Publishing releases

Status: PREPARED, NOT PUBLISHED. astrobaas is not on the registry. The workflow exists (.github/workflows/publish.yml), the package builds, and the tarball has been inspected — what has not happened is the first npm publish, and it should not happen until the repository is public.

---

What publishing fixes, precisely

Three claims in the docs currently carry a caveat. Publishing removes them:

What it does NOT fix. astrobaas init is not a project scaffolder — it writes a .env with a generated AUTH_SECRET. Installing from npm still does not give you a running CMS; you clone the repo for that. Do not let the README imply otherwise, because that is the exact claim this project already had to walk back once.

Order of operations

1. Make the repository public first. An npm package whose repository field points at a private repo cannot be audited by anyone deciding whether to trust it, and the link is the main thing a careful installer checks.
2. Have the CLA gate live (.github/workflows/cla.yml) before either. See LICENSING.md.
3. Then publish, under a dist-tag (below).

Dist-tags: why the first release is not latest

npm install astrobaas resolves the latest tag. Publishing pre-alpha there hands it to everyone who types the obvious command, including people who never read the status line.

So pre-1.0 releases publish under alpha:

npm install astrobaas@alpha     # deliberate
npm install astrobaas           # fails until `latest` exists — which is honest

The workflow defaults to alpha and never moves latest. Promoting a release is a separate, deliberate command:

npm dist-tag add astrobaas@1.0.0 latest

Suggested progression: alpha → beta → latest, moving latest only when TRUTH_PLAN.md has no open items you would be embarrassed to have a stranger find.

How to cut a release

npm version patch          # or minor / major — writes package.json AND tags
git push --follow-tags

The tag push runs the workflow, which re-runs the full gate (build, unit, smoke across all three storage drivers, package build, npm audit) before publishing. A tag whose name disagrees with package.json fails the job rather than shipping a version no tag points at.

Never npm publish from a laptop. It ships whatever is in that working tree.

One-time setup

1. An npm account with 2FA enabled.
2. A granular access token (Access Tokens → Granular), scoped to the astrobaas package, read+write, with an expiry you will renew. A classic automation token works but grants far more than this job needs.
3. Add it to the repository as the secret NPM_TOKEN.

Provenance

The workflow publishes with --provenance, which requires id-token: write and only works from CI. It cryptographically ties the tarball on npm to this repository, this workflow and this commit, and npm shows the link on the package page.

For a package that handles sessions, uploads and payment webhooks, this is worth the two lines of config: it turns “trust the maintainer” into something a stranger can verify.

Publishing is close to irreversible

• A version can be unpublished only within 72 hours.
• After that it is permanent, and the name is taken forever either way.
• A published version cannot be replaced — you can only publish a new one.

So the first publish is worth doing on a quiet afternoon rather than at the end of a long session. Run the workflow manually with dry_run: true first; it packs and validates without publishing, and the default is true precisely so an accidental click cannot ship anything.

What actually ships

Controlled by files in package.json:

pkg/                 built JS + .d.ts for astrobaas/{core,client,plugins}
bin/                 astrobaas, astrobaas-mcp
scripts/setup.mjs
.env.example
LICENSE, README.md   (npm always includes these)

Verified with npm pack --dry-run, which the workflow prints on every run — read it once before the first publish. Source, tests, db.json and uploads are all excluded.

After the first publish

• Remove the “Not on npm yet” note from README.md and the caveat in INTEGRATION.md §4. Leaving a stale caveat is the same failure as a stale claim, in the other direction.
• Update the MCP config example in README.md and AGENTS.md back to npx astrobaas-mcp from the absolute-path workaround.
• Add the alpha install line to the README so people know the tag exists.
• Watch for typosquats. Once a name is popular, astrobass, astro-baas and similar get registered by others. npm will not police this for you.
• Renew the token before it expires, or the first release after expiry fails in a way that looks like a broken workflow.