Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 [<tag>]` | 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<version>`, a commit not on `main`, or a version already on npm (see `PUBLISHING.md`) |

| Workspace script (root delegates per-package) | Runs |
| --- | --- |
Expand Down
17 changes: 13 additions & 4 deletions PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<version>`, 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<version>`, 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<version>`.
4. The workflow then installs, builds, and runs `npm publish` for each package over
OIDC. No token needed.

## Requirements baked into the workflow
Expand Down
42 changes: 42 additions & 0 deletions bin/release-preflight
Original file line number Diff line number Diff line change
@@ -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 [<release tag>]
#
# 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<version>, 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"
6 changes: 3 additions & 3 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion packages/ai-claude-compat/package.json
Original file line number Diff line number Diff line change
@@ -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 <env> system-context block, a subagent-as-tool factory, and .claude/ skills/agents loading.",
"license": "MIT",
"type": "module",
Expand Down
4 changes: 2 additions & 2 deletions packages/aitm/package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -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",
Expand Down
178 changes: 178 additions & 0 deletions packages/aitm/test/integration/release-preflight.test.ts
Original file line number Diff line number Diff line change
@@ -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<Registry, string> = {
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');
});
});