Development Commands

Run these commands from the repository root unless a section says otherwise.

Repository Setup

npm ci runs the native installation hook, which builds the bundled OpenSSL source when no prebuild matches. That build needs the platform C/C++ toolchain, Perl, and make on Unix-like systems, or Perl, NMake, and Visual Studio Build Tools on Windows.

RPM-based distributions such as Fedora, RHEL, and openSUSE need several separate Perl core packages installed first, or npm ci fails while configuring OpenSSL. Install them before the first npm ci; see Perl Packages On RPM Distributions for the list and what each package is needed for. Debian and Ubuntu ship these modules with perl itself.

Install the Node.js workspaces and build the native addon when needed:

npm ci

Use npm ci --ignore-scripts when a workflow needs JavaScript dependencies but must not run the native installation hook.

Native Package

# Run the complete native test suite.
npm test

# Run one native test.
npx mocha packages/native-with-source/tests/SimpleTextUsageTest.js --timeout 15000

# Check formatting.
npm run test:codestyle

# Build a native prebuild with node-pre-gyp.
npm run package

# Produce slim and source-capable native publication tarballs.
npm pack --workspace=@muhammara/native-core
npm pack --workspace=@muhammara/native-with-source
npm pack --workspace=@muhammara/native

# Execute documentation examples.
npm run test:docs

Fuzzing

npm run fuzz --workspace=@muhammara/native-with-source runs a mutation fuzzer against the native addon; build it with AddressSanitizer and UndefinedBehaviorSanitizer first so memory errors are reported where they happen. packages/native-with-source/fuzz/README.md lists the targets, the options, and how to turn a finding into a regression test. The sanitizer job in ci-native.yml runs a short fixed-seed pass on every change. The Wasm build is fuzzed separately; see the Wasm development guide.

Documentation

Create a Python virtual environment and install the native site's pinned documentation dependencies:

python -m venv .docs-venv
source .docs-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r packages/native/docs/requirements.txt

On Windows PowerShell, activate the environment with:

.docs-venv\Scripts\Activate.ps1

Generate references and work with the native MkDocs site:

# Generate API reference pages.
npm run docs:generate

# Build the site.
npm run docs:build

# Build strictly and fail on warnings.
npm run docs:check

# Serve with live reload at http://127.0.0.1:8000/.
npm run docs:serve

Never commit the generated site/ output.

The native Read the Docs project uses packages/native/.readthedocs.yaml. Configure the project to use that file rather than the repository root.

Release Tags

Normal package tags trigger validation and publication. The package version must match the version in the tag. A native release builds its prebuilds once, then publishes @muhammara/native-core, then @muhammara/native-with-source, before the smaller prebuilt-only @muhammara/native package. After all three npm publishes succeed, the workflow creates the GitHub release and uploads its prebuilds. Native packages use npm trusted publishing through GitHub Actions OIDC and do not require an npm token.

Before the first native release, configure npm trusted publishers for all three scoped native packages. Each publisher must trust this repository's native release workflow and its release environment. After the first successful replacement release, deprecate every published unscoped version without publishing another muhammara package:

npm deprecate 'muhammara@*' 'Deprecated: use @muhammara/native for prebuilt binaries or @muhammara/native-with-source for local builds.'

# Native release example.
git tag native-v7.0.0
git push origin native-v7.0.0

The release body is generated at build time by .github/scripts/release-notes.mjs. It copies the ## [<version>] section of CHANGELOG.md, so that section must exist before the tag is pushed; the workflow fails before anything is published when it is missing. Below the changelog, the notes list the pull requests merged since the previous native-v tag with the issues they close, every contributor, the contributors whose first commit on the default branch is part of the release, and a compare link. Documentation tags and the tags of the other package are never picked as the previous tag. The same notes can be reproduced for a published release:

# Print the release notes of a tag. GITHUB_TOKEN raises the API rate limit.
node .github/scripts/release-notes.mjs CHANGELOG.md native-v native-v7.0.0

After successful publication, the workflows automatically create matching native-doc-v<version> documentation tag. A later documentation-only correction can be tagged without rebuilding or publishing a package:

git tag native-doc-v7.0.0.1
git push origin native-doc-v7.0.0.1

Documentation tags trigger only the documentation workflow.