Secure npm publication

@vevedh/qform-builder-layer is always published from the verified tarball created under .artifacts/. The publication wrapper rejects unapproved direct publication.

Requirements

• Node.js >= 22.14.0;
• Bun >= 1.3.0;
• publish access to the npm @vevedh scope;
• a clean Git working tree for a real publication;
• a regenerated and validated bun.lock;
• completed Playwright baselines and documentation screenshots.

The manual accessibility review remains mandatory only for promotion to 1.0.0-rc.1; it does not block npm publication of source version 0.1.33.

Never store an npm token in .npmrc, .env or any tracked file. Use npm login, a CI secret provider or trusted publishing.

1. Regenerate the lockfile

bun install
bun run lockfile:check

The publication command stops when the lockfile does not exactly cover package.json dependencies.

2. Verify the M0 reference

bun run m0:check
bun run security:workspace:check

These checks cover:

• npm metadata;
• the public README;
• publication scripts;
• Git and npm exclusions;
• the absence of credentials from the committed .npmrc.

3. Run the preflight

bun run npm:publish:check

This command runs quality checks, creates the npm tarball and verifies its manifest and SHA-256 digest.

4. Simulate publication

bun run npm:publish:dry-run

The default dist-tag for the 0.x series is next. An explicit tag can be supplied:

bun run npm:publish:dry-run -- --tag latest

5. Publish

Reference Windows 11 workstation

The maintainer reference workstation uses Windows 11, Visual Studio Code and PowerShell 7, with Docker Desktop installed. npm publication runs on the Windows host; Docker Desktop is not required for this operation.

After applying a patch archive, review and commit the source changes before starting a real publication:

git status --short
git diff --check
git add .
git commit -m "chore(release): prepare @vevedh/qform-builder-layer@0.1.33"
git status --short

The final command must print nothing. The wrapper now performs this check before long builds and tests and prints the same workflow when it detects a dirty tree. Do not bypass the guard or use git reset --hard / git clean -fd to discard unreviewed changes.

Real publication requires an exact package and version confirmation.

Bash or Zsh:

export NPM_PUBLISH_CONFIRM="@vevedh/qform-builder-layer@0.1.33"
bun run npm:publish

PowerShell:

$env:NPM_PUBLISH_CONFIRM = '@vevedh/qform-builder-layer@0.1.33'
bun run npm:publish

The wrapper:

1. immediately requires a clean Git working tree for a real publication;
2. verifies confidential workspace exclusions;
3. reruns release:publish:check, the fully automated publication gate;
4. checks the tarball identity and SHA-256 digest;
5. ensures the version is not already published;
6. publishes with --access public and the selected dist-tag.

release:candidate:check remains separate: it extends release:publish:check, creates the evidence ledger and then requires the human review before promotion to 1.0.0-rc.1. Never fabricate release/manual-accessibility-review.json merely to publish a 0.x version.

npm resolution on Windows

The wrapper never spawns npm.cmd directly because Node.js 22 with NVM for Windows can return EINVAL for that batch wrapper. It resolves the npm JavaScript CLI and executes it through node.exe, in this order:

1. QFORM_NPM_CLI_JS when explicitly configured;
2. npm_execpath only when it actually ends in npm-cli.js;
3. node_modules/npm/bin/npm-cli.js next to process.execPath.

The same adapter is used for npm pack, npm whoami, npm view and npm publish. Validate it independently with:

bun run npm:command:check
npm whoami

For a non-standard npm installation:

$env:QFORM_NPM_CLI_JS = "C:\path\to\node_modules\npm\bin\npm-cli.js"
bun run npm:command:check

Never point this variable at npm.cmd. Registry, TLS, proxy and authentication failures from npm view remain blocking; only an explicit E404 means that the version is not published yet.

Confidential local files

.gitignore covers environment files, keys, certificates, secret directories and local working context. When one of these files is already tracked by Git, remove it from the index only:

bun run sensitive:untrack
git status --short
git commit -m "chore(release): untrack local maintenance context"

The command does not delete files from disk: it only removes them from the Git index. The equivalent manual fix is:

git rm -r --cached --ignore-unmatch \
  AGENTS.md PROMPT_CONTEXT.md ANALYSE_STRUCTURE_REUTILISATION.md patch-memory

Review the diff before committing the change.