Repository navigation
Human action 139
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-vipcan publish under@holland-vip/.
- 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.nodefloor since v0.27.0) and npm 11.5.1 or later on the machine you publish from. Check withnode --versionandnpm --version; upgrade withnpm install -g npm@latest. Publishing by hand also needs PowerShell 7 andghsigned in. - For step 3: the
holland-vip-causet-0.19.1.tgzfile 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 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.
- Run
npm login. It opens a browser to authenticate. - Run
npm whoami.- Expected: your npm username.
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".
- Open
https://www.npmjs.com/org/causetandhttps://www.npmjs.com/~causetin a browser. - If
causetis 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.
-
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()
-
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.
-
Expected:
-
Verify:
npm view @holland-vip/causet version dist-tags bin
-
Expected:
0.19.1,latest: 0.19.1, andbinlisting bothcstandvlab.
-
Expected:
-
Optional smoke test:
npm install -g @holland-vip/causet cst --version
-
Expected:
causet 0.19.1. Uninstall afterwards withnpm uninstall -g @holland-vip/causetif you don't want it installed.
-
Expected:
- From #150's workflow run, download each platform tarball
(
holland-vip-causet-<platform>-<version>.tgz). - Run
npm publish <tarball> --access publicfor each.-
Expected:
+ @holland-vip/causet-<platform>@<version>.
-
Expected:
For @holland-vip/causet and each @holland-vip/causet-<platform>:
- 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, orcausetafter the #159 rename) - Workflow filename: the release workflow #150 names (the filename only)
- Environment: the one #150 names, or none
-
Organization or user:
- Save.
- Expected: the settings show the repository and the workflow.
- 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.
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:
-
npm login, thennpm whoami.- Expected: your npm username.
-
Dry run:
pwsh -File scripts/publish-npm.ps1 -Version <x.y.z> -DryRun
-
Expected:
digest okfor the three tarballs,manifest ok, threenpm publish --dry-runlistings, andDry run only: nothing was published.
-
Expected:
-
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>.
-
Expected:
-
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>'.
-
Expected:
-
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.
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:
-
Decide how promotion moves npm's
latest. Trusted publishing coversnpm publishonly, notnpm dist-tag add, whichpromote.ymlruns. Either:-
a token for dist-tags only: create a granular access token with read and write access to
the three
@holland-vippackages, store it as the secretNPM_TOKENof a new environmentnpm-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> latestwith that token, then putlatestback). Publishing itself stays token-free; or -
no token: leave
NPM_TOKENunset and movelatestby hand after each promotion (npm dist-tag add <package>@<version> latestfor 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.
-
a token for dist-tags only: create a granular access token with read and write access to
the three
-
Turn it on:
gh variable set NPM_PUBLISH --repo jwh3times/causet --body true. -
Verify: the next landing's release run publishes every package under
nextwith provenance (the run's "Publish to npm with provenance" step, andnpm view @holland-vip/causet dist-tags).
-
Step 3 passes when
npm view @holland-vip/causet versionprints0.19.1andnpm view @holland-vip/causet binlistscstandvlab. - 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.
| 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.
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.