next preview; pass stable for a latest release. Use when the user asks to publish, release, ship a version, or cut a dev preview.publish-release — preview under the next dist-tag.\npublish-release stable — real release under latest, with a GitHub release.
npm publishing happens only in GitHub Actions. .github/workflows/release.yml authenticates\nvia npm trusted publishing (OIDC), gated behind the release environment's required reviewer.\nThere is no npm token anywhere and no npm session to reuse.
npm publish yourself. It will fail, and it is not the path.npm login or ask the user for an OTP.Two human checkpoints: the user confirms the version before the push, and approves the\ndeployment in GitHub after it. Everything else runs unattended.
\ngit status — clean tree, on main. Stop and ask if not.
git fetch && git status -sb — up to date with origin/main.
git log origin/main..HEAD --oneline — if anything is unpushed, show it and confirm it should ship.
Record whether a dev bun link is active, because §8 branches on it:
readlink ~/.bun/install/global/node_modules/moi-computer\nA path into this repo means a dev link that §8 must restore. No output (it is a real\ndirectory) means an ordinary global install; a missing path means a clean container with\nnothing to put back.
\nDo not check ~/.bun/bin/moi for this. That symlink reads\n../install/global/node_modules/moi-computer/bin/moi.mjs in every case — linked or\ninstalled — so it cannot answer the question §8 asks. Only the level below discriminates.
Both a cloud container and the user's machine run every phase below. The only difference is what\n§8 restores, which is why you captured it here rather than assuming.
\nRead the current state first — do not assume the file is a good starting point:\nnpm view moi-computer dist-tags and the version in package.json.
package.json already holds an X.Y.Z-next.N that sorts above the published\nlatest, increment N. Otherwise start a fresh series at <next patch above latest>-next.0.\nThe next tag has drifted below latest before; a preview that installs older code than\nstable is a bug, so verify the new version sorts above latest before continuing.Do not use npm version — it makes its own commit and tag.
Everything here is read-only with respect to git. It duplicates the CI verify job on purpose:\nfailing here costs nothing, failing after the tag push costs a burned version.
bun install --frozen-lockfile, bun run lint, bun run format:check, bun test.
Pack and inspect. Clear stale tarballs first — they accumulate in the repo root, and a\nbare moi-computer-*.tgz glob that matches more than one file makes tar read the first as\nthe archive and the rest as members to list. Every check then fails against a perfectly good\ntarball. Pin the exact filename instead of globbing:
rm -f moi-computer-*.tgz # before packing, not after\nbun pm pack\nTGZ=$(ls moi-computer-*.tgz) # exactly one now\ntar -tzf \"$TGZ\" | grep -c '^package/dist/' # must be > 0\ntar -tzf \"$TGZ\" | grep -Ei '\\.env|secret' # must be empty\nSkim what is shipping: git log <last tag>..HEAD --oneline. Enough to describe the\nrelease and to know what §6 should poke at. Time-box it — a sanity check, not a QA pass.
Do not globally install the tarball here. It cannot coexist with a running dev server (see\n§6), and §6 smoke-tests the real published package anyway, which is better evidence. Delete the\ntarball once inspected.
\nShow the user, compactly: the version you propose, what is shipping since the last tag, and the\n§2 check results (lint, format, test counts, tarball dist/ count, secrets scan). Then ask\nwhether to bump and push.
There is no smoke output at this point — §2 deliberately skips the global install, and §6 does\nthe smoke against the published package. Do not go looking for it.
\nWait for a real answer. This is the checkpoint that gates the version number.
\n# edit package.json version by hand\ngit commit -am \"Release vX.Y.Z\"\ngit tag vX.Y.Z\ngit push origin main vX.Y.Z # push the tag by name; --tags would push every local tag\nThe commit fires .githooks (oxlint --fix, oxfmt). Normally they touch nothing, since only\npackage.json changed — but if they do reformat files, those changes land in the release commit\nsilently. Check git show --stat HEAD and confirm it is the one-line version bump you expect.
Then surface the approval link and stop. Do not trust --limit 1 on its own: GitHub may not\nhave created the run yet when the push returns, so the newest run can still be the previous\nrelease. Match on the tag:
gh run list --workflow=release.yml --limit 5 \\\n --json databaseId,url,status,headBranch \\\n --jq '.[] | select(.headBranch == \"vX.Y.Z\")'\nIf that comes back empty, wait a few seconds and repeat until the run for your tag appears.\nGive the user that URL and tell them to approve the release environment. One link, one click.
gh run watch <id> --exit-status. It blocks until the user approves, so it can sit for a long\ntime — that is expected, not a hang. If it fails, read the logs before retrying.
Recovery, if verify fails or the run is rejected:
git tag -d vX.Y.Z,\ngit push origin :refs/tags/vX.Y.Z) before re-pushing.gh workflow run release.yml -f tag=vX.Y.Z.npm view moi-computer dist-tags — the intended tag moved, and for a preview confirm\nlatest did not.npm view moi-computer@<version> dist.attestations — trusted publishing attaches provenance\nautomatically; its absence means the publish did not go through OIDC.CONTROL_PORT defaults to\n13059 (server/constants.ts) and server/control.ts binds it unconditionally, so --port\ndoes not let a second instance coexist. (MOI_CONTROL_PORT overrides it, but that is a test\nseam — smoke the real defaults.) Before installing:\nlsof -ti:13059 -ti:13337 — if anything is running, it is almost certainly the user's own\nbun run dev in their terminal. Stop it, and tell the user you stopped it. Do not\nsilently respawn it in §8; a detached agent-owned supervisor is not the same thing and its\noutput goes where they are not looking.bun remove -g moi-computer first. Installing over an existing install fails with\nENOENT/DependencyLoop because the global package.json pins the old range. Despite -g,\nthis still treats the current directory as a project and writes a package.json and\nlockfile there. Run it from the repo root (where both already exist and are git-tracked, so\nstray writes are visible) — never from /tmp or the scratchpad, where it leaves a junk\npackage.json behind that will break bun link in §8.bun install -g moi-computer@<version>, then moi version, moi env, moi start, and\ncurl / and /api/workspaces. Poke at anything §2.3 flagged as new, if it is quick.If this fails, publishing cannot be undone cleanly. Unpublish is only possible within 72 hours\nand breaks anyone who already installed. The realistic remedy is npm deprecate on the bad\nversion plus a follow-up release. Tell the user rather than improvising.
Previews get no GitHub release and no release notes. Skip this entire section for next.
For a stable release:
\n.agents/rules/product-language.md first — the notes are user-facing copy.https://github.com/molefrog/moi/compare/vPREV...vX.Y.Z). Behavior the user can observe,\nnot a file inventory.gh release create vX.Y.Z --title \"vX.Y.Z\" --notes-file <file> --latestAlways run this, including after a failure or an abandoned release.
\nbun remove -g moi-computer, then bun link — both run from\nthe repo root. bun link registers the package in the current directory, so running it\nanywhere else either errors (package.json missing \"name\") or links the wrong thing. These\nare two separate commands with a directory requirement, not one chained sequence; if your\ntooling resets the working directory between calls, set it explicitly for each.\nVerify ~/.bun/install/global/node_modules/moi-computer symlinks back to the repo, and\nmoi version reports X.Y.Z (githash).bun remove -g moi-computer.rm -f moi-computer-*.tgz and rm -rf dist/. A leftover dist/index.html silently shadows\nthe dev client for linked moi runs (server/static.ts); only bun run dev ignores it.bun run dev belongs in their terminal, not in a background process you own.