Skip to content

Human action 139

Jerry Holland edited this page Nov 14, 2026 · 8 revisions

Set up npm publishing for @holland-vip/causet

Procedure for issue #139. The issue is the record of ownership, status and completion evidence; this page is the execution instruction.

Owner role: the repository owner (jwh3times), who owns the npm account and the holland-vip organization. npm accounts, two-factor authentication, organizations and first publishes belong to a person, so no agent can do these steps.

What is being set up (ADR-0038 §4 and its 2026-09-28 amendment):

Package Scope Contains First published
@holland-vip/causet @holland-vip/ The CLI (cst, with vlab as an alias). Today the JavaScript implementation; later the platform binaries through optionalDependencies Step 3, by hand, from the v0.19.1 release tarball
@holland-vip/causet-win32-x64, @holland-vip/causet-linux-x64-gnu; later -linux-arm64-gnu, -win32-arm64, -linux-x64-musl, -darwin-arm64, -darwin-x64 @holland-vip/ (moves to @causet/ if that organization is ever obtained) One prebuilt cst executable each Step 4, by hand, once from #150's CI artifacts

Update 2026-09-28: npm refused the unscoped name causet (E403 … too similar to existing packages case,faucet), a typosquatting check that no dry run reveals. The package is therefore @holland-vip/causet (ADR-0038, second amendment), first published as v0.19.1. v0.19.0 was never published.

Do not publish placeholders. npm's dispute policy says: "It is against npm's Terms of Use to publish a package, register a username or an organization name simply for the purposes of reserving it for future use."

  • Every first publish here is a real, working package.
  • The scoped platform names need no early claim, because only holland-vip can publish under @holland-vip/.

Prerequisites

  • An npm account with two-factor authentication, set to authorization and writes (avatar → Account → Two-Factor Authentication).
  • The npm organization holland-vip, with your account as owner.
  • Node.js 24 or later (the package's engines.node floor since v0.27.0) and npm 11.5.1 or later on the machine you publish from. Check with node --version and npm --version; upgrade with npm install -g npm@latest. Publishing by hand also needs PowerShell 7 and gh signed in.
  • For step 3: the holland-vip-causet-0.19.1.tgz file the agent prepares from the tagged v0.19.1 release, and names on #139, with its SHA-256.
  • For step 4: #150 merged, and its release workflow's platform tarballs available as CI artifacts.

Steps

Steps 3–5 are done (step 5 on 2026-10-13) and stay as the record of the first publishes; what remains is "Until step 6" and step 6.

Step 1: sign in

  1. Run npm login. It opens a browser to authenticate.
  2. Run npm whoami.
    • Expected: your npm username.

Step 2 (optional): the causet organization name

npm hands over a name only on a trademark claim. It may remove an organization that is squatting, meaning one with no packages published "within a reasonable time".

  1. Open https://www.npmjs.com/org/causet and https://www.npmjs.com/~causet in a browser.
  2. If causet is an organization with no packages, you may report suspected squatting to npm support. This is not guaranteed and has no timeline. Nothing below waits on it.

Step 3: first publish of @holland-vip/causet

  1. Check the tarball's SHA-256 against the value the agent posted on #139:

    (Get-FileHash <path>\holland-vip-causet-0.19.1.tgz -Algorithm SHA256).Hash.ToLower()
  2. Publish it:

    npm publish <path>\holland-vip-causet-0.19.1.tgz --access public

    Approve the two-factor prompt.

    • Expected: + @holland-vip/causet@0.19.1.
  3. Verify:

    npm view @holland-vip/causet version dist-tags bin
    • Expected: 0.19.1, latest: 0.19.1, and bin listing both cst and vlab.
  4. Optional smoke test:

    npm install -g @holland-vip/causet
    cst --version
    • Expected: causet 0.19.1. Uninstall afterwards with npm uninstall -g @holland-vip/causet if you don't want it installed.

Step 4 (after #150): first publish of each platform package

  1. From #150's workflow run, download each platform tarball (holland-vip-causet-<platform>-<version>.tgz).
  2. Run npm publish <tarball> --access public for each.
    • Expected: + @holland-vip/causet-<platform>@<version>.

Step 5 (after #150): trusted publishing, then lock down

For @holland-vip/causet and each @holland-vip/causet-<platform>:

  1. Open https://www.npmjs.com/package/<name> → Settings → Trusted Publisher → GitHub Actions, and enter:
    • Organization or user: jwh3times
    • Repository: the repository's name at that time (vcs-lab, or causet after the #159 rename)
    • Workflow filename: the release workflow #150 names (the filename only)
    • Environment: the one #150 names, or none
  2. Save.
    • Expected: the settings show the repository and the workflow.
  3. Under Publishing access, choose Require two-factor authentication and disallow tokens, and save.

From then on, releases publish only from that CI workflow, with npm provenance, and no token exists to leak.

Until step 6: publish each stable version by hand

Added 2026-11-13 (#448). While NPM_PUBLISH is false, npm gets a version only when you publish it. Publish the version promote.yml made stable, from a checkout of main at or after v0.27.2, in PowerShell 7:

  1. npm login, then npm whoami.

    • Expected: your npm username.
  2. Dry run:

    pwsh -File scripts/publish-npm.ps1 -Version <x.y.z> -DryRun
    • Expected: digest ok for the three tarballs, manifest ok, three npm publish --dry-run listings, and Dry run only: nothing was published.
  3. Publish:

    pwsh -File scripts/publish-npm.ps1 -Version <x.y.z>

    Approve npm's prompt in the browser for each package.

    • Expected: + @holland-vip/causet-win32-x64@<x.y.z>, then the Linux package, then + @holland-vip/causet@<x.y.z>.
  4. Wait 15–20 minutes (the registry answers 404 until it serves a new version; never republish), then verify:

    npm view @holland-vip/causet dist-tags
    • Expected: latest: '<x.y.z>'.
  5. Record the version on #139.

The script downloads the release's own tarballs from GitHub, refuses any whose SHA-256 is not the one SHA256SUMS lists, and refuses a main package that does not pin both platform packages at the version. Never run npm publish in the checkout: its package.json pins no platform package, so the package it publishes installs without cst. If a publish fails part way, fix the cause and rerun the same command: versions npm already has are skipped.

Step 6 (after npm/cli#9969 is fixed): turn CI publishing back on

Added 2026-11-12 for #440 (ADR-0048). Since #440 every landing is a version, and NPM_PUBLISH is false (#442) while npm/cli#9969 refuses this repository's trusted publishing. When that issue is fixed:

  1. Decide how promotion moves npm's latest. Trusted publishing covers npm publish only, not npm dist-tag add, which promote.yml runs. Either:
    • a token for dist-tags only: create a granular access token with read and write access to the three @holland-vip packages, store it as the secret NPM_TOKEN of a new environment npm-promote (Settings → Environments → New environment), and check on one package that the "disallow tokens" publishing setting still lets a token move a dist-tag (npm dist-tag add @holland-vip/causet@<a published version> latest with that token, then put latest back). Publishing itself stays token-free; or
    • no token: leave NPM_TOKEN unset and move latest by hand after each promotion (npm dist-tag add <package>@<version> latest for each of the three packages). The promotion run then fails at its npm step after the GitHub release is already the latest, so record which you chose on #139; the agent can make that step skip instead.
  2. Turn it on: gh variable set NPM_PUBLISH --repo jwh3times/causet --body true.
  3. Verify: the next landing's release run publishes every package under next with provenance (the run's "Publish to npm with provenance" step, and npm view @holland-vip/causet dist-tags).

Verification

  • Step 3 passes when npm view @holland-vip/causet version prints 0.19.1 and npm view @holland-vip/causet bin lists cst and vlab.
  • Steps 4–5 pass when, for every package, the trusted publisher names this repository's workflow and publishing access disallows tokens.
  • Partial completion is normal: step 3 now, steps 4–5 after #150. Record what was done on #139.

Failure handling

Error Meaning What to do
E403 … too similar to an existing package npm refuses the name Stop. Record npm's message on #139; the name needs a new owner decision.
E402 Payment Required A scoped publish was missing --access public Rerun that publish with the flag.
E404 on a @holland-vip/… name Your account is not a member of the org with publish rights Check the org's members.
EOTP or an authentication error Two-factor authentication or the login was not completed Run npm login again, then retry.
A trusted-publishing failure in CI The configuration does not match the workflow Check the owner and repository spelling, the exact workflow filename, the environment, and that the workflow grants id-token: write. Never fall back to a token.

Never put an npm token, a recovery code or a one-time password in an issue, a wiki page, a commit or a CI log.

Completion evidence

Record on #139:

  • the published names and versions, with their npm links;
  • for step 5, confirmation (a screenshot or a written statement) that each package's trusted publisher and "disallow tokens" setting are in place.

When steps 3–5 are done, remove the human-action-required label, set the board card to Done, and mark this page's row on Human TODO as done.

Clone this wiki locally