diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2ddc631..452d7f5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -35,6 +35,9 @@ jobs: timeout-minutes: 10 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + # The preflight checks the commit is on main, which needs the history and origin/main. + fetch-depth: 0 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7 with: @@ -50,6 +53,14 @@ jobs: - name: upgrade npm run: npm install -g npm@11.5.2 + # Refuse before anything is built: a version already on npm can never ship again, so a + # missed bump, packages out of lockstep, a tag that is not the version, or a commit that is + # not on main stops the release here instead of at the registry. See PUBLISHING.md. + - name: preflight + env: + TAG: ${{ github.event.release.tag_name }} + run: bin/release-preflight "$TAG" + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 with: bun-version: latest diff --git a/CLAUDE.md b/CLAUDE.md index 692a41c..242232f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,7 @@ Instructions for Claude when editing `aitm` source. Not for end users. | TypeScript | `^7.0.2`, `strict: true` | | AI SDK | `ai` `^7.0.170`, `ToolLoopAgent` (v7; the AI SDK 5 name `experimental_Agent` survives only as an alias export of it, `ToolLoopAgent as Experimental_Agent`); MCP client `@ai-sdk/mcp` `^2.0.97` | | Lint/format | Biome 2.6.4 — `bun run lint` = `biome check .` | -| Packages | `@developerz.ai/aitm` 0.0.56 + `@developerz.ai/ai-claude-compat` 0.0.56; aitm pins compat EXACTLY, versions move in lockstep | +| Packages | `@developerz.ai/aitm` + `@developerz.ai/ai-claude-compat`, always the same version; aitm pins compat EXACTLY, versions move in lockstep (`bin/release-preflight` refuses a release otherwise) | ## Commands | `bin/` command | Runs | @@ -34,6 +34,7 @@ Instructions for Claude when editing `aitm` source. Not for end users. | `bin/setup` | `bun install && npm run build -w @developerz.ai/ai-claude-compat` | | `bin/dev` | `bun packages/aitm/scripts/debug-start.ts` — dogfood aitm on a throwaway repo | | `bin/stop` | No-op (nothing detected to stop) | +| `bin/release-preflight []` | Run by `release.yml` before it builds: refuses packages out of lockstep, a pin that is not the version, a tag that is not `v`, a commit not on `main`, or a version already on npm (see `PUBLISHING.md`) | | Workspace script (root delegates per-package) | Runs | | --- | --- | diff --git a/PUBLISHING.md b/PUBLISHING.md index d259b59..4e31b2f 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -44,11 +44,20 @@ On npmjs.com, for **each** package: ## Ongoing releases (automated) -1. Bump the version in **both** `package.json` files (keep them in lockstep — - `aitm` pins `ai-claude-compat` to an exact version). -2. Commit, then publish a GitHub Release (or run the `release` workflow via +1. **The bump is the first step of every release, in a pull request to `main`.** + Set the same new version in **both** `package.json` files, set `aitm`'s pin on + `@developerz.ai/ai-claude-compat` to that exact version, and run `bun install` + so `bun.lock` records it. npm versions are immutable: a version that is already + published can never ship again, so a release without a bump cannot work. +2. Once that is merged, publish a GitHub Release whose tag is `v`, on a + commit on `main` (or run the `release` workflow from `main` via **Actions → release → Run workflow**). -3. The workflow installs, builds, and runs `npm publish` for each package over +3. The workflow runs `bin/release-preflight` before it builds anything. It refuses + packages out of lockstep, a pin that is not the version, a tag that is not + `v`, a commit that is not on `main`, or a version already on npm, and + says which. Anything but a clear "not found" from the registry is a refusal too. + You can run it locally first: `bin/release-preflight v`. +4. The workflow then installs, builds, and runs `npm publish` for each package over OIDC. No token needed. ## Requirements baked into the workflow diff --git a/bin/release-preflight b/bin/release-preflight new file mode 100755 index 0000000..4506adb --- /dev/null +++ b/bin/release-preflight @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +# Release preflight: refuse a release before anything is built, not late at the registry. npm +# versions are immutable, so a version that is already published can never ship again. +# +# bin/release-preflight [] +# +# Refuses when the two packages are out of lockstep, when aitm's pin on ai-claude-compat is not that +# version, when a release tag is given and is not v, when the commit is not on main, or when +# either package is already on npm at that version. Anything but a clear "not found" from the +# registry is a refusal too, so a registry outage cannot wave a release through. +set -euo pipefail +cd "$(dirname "$0")/.." + +fail() { + echo "::error::release preflight: $1" + exit 1 +} + +manifest() { node -p "require('./packages/$1/package.json')$2"; } + +compat=$(manifest ai-claude-compat .version) +aitm=$(manifest aitm .version) +pin=$(manifest aitm ".dependencies['@developerz.ai/ai-claude-compat']") + +[ "$compat" = "$aitm" ] || fail "the packages are out of lockstep: ai-claude-compat is $compat, aitm is $aitm" +[ "$pin" = "$compat" ] || fail "aitm pins ai-claude-compat $pin, but ai-claude-compat is $compat" + +tag=${1:-} +if [ -n "$tag" ] && [ "$tag" != "v$aitm" ]; then + fail "the release tag $tag does not match the packages' version v$aitm" +fi + +git merge-base --is-ancestor HEAD origin/main 2>/dev/null || fail "the commit being released is not on main" + +for pkg in @developerz.ai/ai-claude-compat @developerz.ai/aitm; do + if out=$(npm view "$pkg@$aitm" version 2>&1); then + fail "$pkg@$aitm is already on npm, and npm versions are immutable: bump both package.json files first (PUBLISHING.md)" + fi + grep -q 'E404' <<<"$out" || fail "could not check whether $pkg@$aitm is on npm: $(tail -n 1 <<<"$out")" +done + +echo "release preflight: v$aitm is unpublished, in lockstep, and on main" diff --git a/bun.lock b/bun.lock index 494b1b9..eaeb635 100644 --- a/bun.lock +++ b/bun.lock @@ -14,7 +14,7 @@ }, "packages/ai-claude-compat": { "name": "@developerz.ai/ai-claude-compat", - "version": "0.0.56", + "version": "0.0.57", "dependencies": { "ai": "^7.0.170", "execa": "^10.2.1", @@ -23,13 +23,13 @@ }, "packages/aitm": { "name": "@developerz.ai/aitm", - "version": "0.0.56", + "version": "0.0.57", "bin": { "aitm": "./dist/cli/cli.js", }, "dependencies": { "@ai-sdk/mcp": "^2.0.97", - "@developerz.ai/ai-claude-compat": "0.0.56", + "@developerz.ai/ai-claude-compat": "0.0.57", "@openrouter/ai-sdk-provider": "^3.1.0", "ai": "^7.0.170", "execa": "^10.2.1", diff --git a/packages/ai-claude-compat/package.json b/packages/ai-claude-compat/package.json index e5c5ae4..3593af2 100644 --- a/packages/ai-claude-compat/package.json +++ b/packages/ai-claude-compat/package.json @@ -1,6 +1,6 @@ { "name": "@developerz.ai/ai-claude-compat", - "version": "0.0.56", + "version": "0.0.57", "description": "Claude-Code-style agent primitives for the Vercel AI SDK: FS/bash tools, an system-context block, a subagent-as-tool factory, and .claude/ skills/agents loading.", "license": "MIT", "type": "module", diff --git a/packages/aitm/package.json b/packages/aitm/package.json index 9ae263e..ca6e921 100644 --- a/packages/aitm/package.json +++ b/packages/aitm/package.json @@ -1,6 +1,6 @@ { "name": "@developerz.ai/aitm", - "version": "0.0.56", + "version": "0.0.57", "description": "Autonomous task orchestrator. Goal in, merged PRs out.", "license": "MIT", "type": "module", @@ -44,7 +44,7 @@ }, "dependencies": { "@ai-sdk/mcp": "^2.0.97", - "@developerz.ai/ai-claude-compat": "0.0.56", + "@developerz.ai/ai-claude-compat": "0.0.57", "@openrouter/ai-sdk-provider": "^3.1.0", "ai": "^7.0.170", "execa": "^10.2.1", diff --git a/packages/aitm/test/integration/release-preflight.test.ts b/packages/aitm/test/integration/release-preflight.test.ts new file mode 100644 index 0000000..ce6acad --- /dev/null +++ b/packages/aitm/test/integration/release-preflight.test.ts @@ -0,0 +1,178 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { + chmodSync, + copyFileSync, + mkdirSync, + mkdtempSync, + readFileSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { describe, it } from 'node:test'; +import { fileURLToPath } from 'node:url'; + +/** + * A release is refused before anything is built, or it fails late at the registry. + * + * The defect this guards: both manifests carried the version already on npm, so every publish + * from `main` was refused by the registry, at the very end of the release, and `main` could never + * ship. npm versions are immutable, so the only fix is a bump. `bin/release-preflight` makes the + * release workflow refuse first and say why: the packages out of lockstep, the pin not matching, + * a tag that is not the version, a commit that is not on `main`, or a version already published. + * A registry it cannot reach is a refusal too, never a pass. + * + * The script is the artifact under test: it runs for real, in a throwaway repository, with a stub + * `npm` on PATH standing in for the registry. + */ + +const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url)); +const SCRIPT = 'bin/release-preflight'; + +type Registry = 'published' | 'missing' | 'down'; + +interface Fixture { + compat?: string; + aitm?: string; + pin?: string; + onMain?: boolean; +} + +function git(cwd: string, ...args: string[]): void { + const proc = spawnSync( + 'git', + ['-c', 'user.name=t', '-c', 'user.email=t@example.invalid', ...args], + { + cwd, + }, + ); + assert.equal(proc.status, 0, `git ${args.join(' ')}: ${proc.stderr?.toString()}`); +} + +/** A throwaway repository holding the real script, two manifests and an `origin/main`. */ +function fixture({ + compat = '0.0.57', + aitm = '0.0.57', + pin = aitm, + onMain = true, +}: Fixture): string { + const root = mkdtempSync(join(tmpdir(), 'aitm-preflight-')); + mkdirSync(join(root, 'bin')); + copyFileSync(join(REPO_ROOT, SCRIPT), join(root, SCRIPT)); + chmodSync(join(root, SCRIPT), 0o755); + for (const [dir, manifest] of [ + ['ai-claude-compat', { name: '@developerz.ai/ai-claude-compat', version: compat }], + [ + 'aitm', + { + name: '@developerz.ai/aitm', + version: aitm, + dependencies: { '@developerz.ai/ai-claude-compat': pin }, + }, + ], + ] as const) { + mkdirSync(join(root, 'packages', dir), { recursive: true }); + writeFileSync(join(root, 'packages', dir, 'package.json'), JSON.stringify(manifest)); + } + git(root, 'init', '-q', '-b', 'main'); + git(root, 'add', '-A'); + git(root, 'commit', '-q', '-m', 'release'); + git(root, 'update-ref', 'refs/remotes/origin/main', 'HEAD'); + if (!onMain) git(root, 'commit', '-q', '--allow-empty', '-m', 'not on main'); + return root; +} + +/** A stub `npm` whose `view` answers like the registry in the given state. */ +function stubNpm(registry: Registry): string { + const dir = mkdtempSync(join(tmpdir(), 'aitm-preflight-npm-')); + const answers: Record = { + published: 'echo "$2" | sed "s/.*@//"; exit 0', + missing: 'echo "npm error code E404" >&2; exit 1', + down: 'echo "npm error code ECONNREFUSED" >&2; exit 1', + }; + writeFileSync(join(dir, 'npm'), `#!/usr/bin/env bash\n${answers[registry]}\n`); + chmodSync(join(dir, 'npm'), 0o755); + return dir; +} + +function preflight(root: string, registry: Registry, tag?: string) { + // The stub goes first so it shadows any real npm; the inherited PATH supplies node, git and bash + // (under Bun, process.execPath is bun, not node, so it cannot stand in for node's directory). + const path = [stubNpm(registry), process.env.PATH ?? '/usr/bin:/bin'].join(':'); + const proc = spawnSync('bash', [join(root, SCRIPT), ...(tag === undefined ? [] : [tag])], { + cwd: root, + env: { PATH: path, HOME: root }, + }); + return { status: proc.status, out: `${proc.stdout?.toString()}${proc.stderr?.toString()}` }; +} + +describe('the release preflight', () => { + it('passes an unpublished version in lockstep, on main', () => { + const run = preflight(fixture({}), 'missing'); + assert.equal(run.status, 0, run.out); + assert.match(run.out, /v0\.0\.57 is unpublished, in lockstep, and on main/); + }); + + it('passes a release tag that is the version', () => { + const run = preflight(fixture({}), 'missing', 'v0.0.57'); + assert.equal(run.status, 0, run.out); + }); + + it('refuses a version already on npm', () => { + const run = preflight(fixture({}), 'published'); + assert.equal(run.status, 1); + assert.match(run.out, /already on npm, and npm versions are immutable/); + }); + + it('refuses when the registry cannot be asked, instead of passing', () => { + const run = preflight(fixture({}), 'down'); + assert.equal(run.status, 1); + assert.match(run.out, /could not check whether .* is on npm/); + }); + + it('refuses packages out of lockstep', () => { + const run = preflight(fixture({ compat: '0.0.56' }), 'missing'); + assert.equal(run.status, 1); + assert.match(run.out, /out of lockstep/); + }); + + it('refuses a pin that is not the version', () => { + const run = preflight(fixture({ pin: '0.0.56' }), 'missing'); + assert.equal(run.status, 1); + assert.match(run.out, /aitm pins ai-claude-compat 0\.0\.56/); + }); + + it('refuses a release tag that is not the version', () => { + const run = preflight(fixture({}), 'missing', 'v0.0.56'); + assert.equal(run.status, 1); + assert.match(run.out, /release tag v0\.0\.56 does not match/); + }); + + it('refuses a commit that is not on main', () => { + const run = preflight(fixture({ onMain: false }), 'missing'); + assert.equal(run.status, 1); + assert.match(run.out, /not on main/); + }); +}); + +describe('the tree the release is cut from', () => { + it('keeps both packages in lockstep, with aitm pinning that exact version', () => { + const read = (dir: string) => + JSON.parse(readFileSync(join(REPO_ROOT, 'packages', dir, 'package.json'), 'utf8')); + const compat = read('ai-claude-compat'); + const aitm = read('aitm'); + assert.equal(aitm.version, compat.version); + assert.equal(aitm.dependencies['@developerz.ai/ai-claude-compat'], compat.version); + }); + + it('runs the preflight before it publishes anything, with the history it needs', () => { + const workflow = readFileSync(join(REPO_ROOT, '.github/workflows/release.yml'), 'utf8'); + const preflightAt = workflow.indexOf(SCRIPT); + // The publish STEP, not a mention of it: the npm-upgrade comment above names `npm publish` too. + const publishAt = workflow.indexOf('run: npm publish'); + assert.ok(preflightAt > 0, 'the release workflow does not run the preflight'); + assert.ok(publishAt > preflightAt, 'the release workflow publishes before the preflight runs'); + assert.match(workflow, /fetch-depth: 0/, 'the checkout needs full history to see origin/main'); + }); +});