Skip to content

Commit bc10e27

Browse files
committed
chore(release): retire local npm publishing
Removes the npm version and publish hooks and release-mark-dev.mjs, refuses a local npm publish from the root, and documents the release channels and the one-time onboarding of a new public package.
1 parent 61567a6 commit bc10e27

6 files changed

Lines changed: 65 additions & 190 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 48 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Use `pnpm build:macos-helper:clean` if a Swift cache was created in another work
6868

6969
## Prepare the npm package
7070

71-
`pnpm publish` and package-manager pack commands run `prepack`, which first checks synchronized MCP
71+
Package-manager pack commands run `prepack`, which first checks synchronized MCP
7272
metadata and then runs `pnpm package:npm`. This is the one completeness-oriented aggregate: it
7373
builds the TypeScript distribution and all four Apple runner targets (into a scratch directory under
7474
`.tmp/` that it removes afterwards, not into `~/.agent-device`), clean-builds the macOS helper,
@@ -83,72 +83,63 @@ so name the version the CI lanes install and the published helper matches the CI
8383
`pnpm package:npm` is a release guard, not a routine development command. Use the specific commands
8484
above while iterating.
8585

86-
### Release the core and public workspace packages together
87-
88-
The root `package.json` owns the release version. Every public workspace package uses that version;
89-
private internal packages stay unpublished. There is one Git tag and GitHub release, `v<version>`,
90-
for the whole release. No changeset files or per-package tags are needed.
91-
92-
From a clean release checkout, bump the version once:
93-
94-
```bash
95-
npm version patch
96-
# or npm version minor / npm version 0.22.0
97-
```
98-
99-
The version hook synchronizes all public workspace manifests and MCP metadata, stages them, and
100-
includes them in npm's version commit and `v<version>` tag. Do not bump plugin versions separately.
101-
102-
Publish and push using the normal npm workflow:
103-
104-
```bash
105-
npm publish && git push && git push --tags
106-
```
107-
108-
The publish hooks prepare and validate every public package before uploading the core, then
109-
publish the remaining workspace packages at the same version. Private packages stay unpublished.
110-
After every package succeeds, the hook commits all public manifests and MCP metadata at the next
111-
`-dev` version. Your `git push` includes that commit; the version bump created the single release
112-
tag. Write one GitHub release covering the core and plugins.
113-
114-
After setting the version, preview the full release with `npm publish --dry-run`. It builds and
115-
checks the packages without uploading them, changing versions, or creating commits. The dry-run
116-
publish hook makes no additional registry requests. Dependency installation during preparation
117-
still requires registry access unless the dependencies are cached. Publishing requires npm registry access for
118-
`agent-device` and the `@agent-device` scope.
119-
120-
If core publication succeeds but a later package fails, run `pnpm release:publish` to finish the
121-
release. It skips versions already published and commits the development marker once every package
122-
succeeds. Plain `npm publish` cannot retry an already-published core version.
123-
If every upload succeeds but development-marker synchronization or its Git commit fails, fix the
124-
reported error and run `pnpm release:mark-dev` to finish any interrupted version synchronization, then commit the
125-
changed public manifests and `server.json` before pushing. No package needs republishing.
126-
127-
Use `npm pack` to build and validate a development-version package locally. The normal npm and
128-
pnpm publishers repack the prepared files when uploading; the checks validate package contents,
129-
not the byte identity of the uploaded archive.
86+
### Release through the Release workflow
87+
88+
Every npm publish runs in `.github/workflows/release.yml`, through npm trusted publishing: no npm
89+
token or one-time password is involved, and every version carries provenance. A local
90+
`npm publish` from the repository root refuses to run.
91+
92+
The core and every public workspace package release together at one version. Private packages
93+
stay unpublished. There are three channels:
94+
95+
- **Nightly** (`npm install -g agent-device@nightly`): every few hours the workflow checks `main`.
96+
It publishes `X.Y.Z-nightly.<YYYYMMDD>.<run>` under the `nightly` dist-tag when `main`'s HEAD has
97+
changed since the last nightly, its CI passed, and no nightly shipped that UTC day. It then tags
98+
the commit `v<nightly version>`. To publish one now, run **Release** with `channel: nightly`.
99+
- **Stable** (`latest`): run **Release** with `channel: stable`. It promotes the latest nightly's
100+
commit, by default as the `X.Y.Z` that nightly previewed. Set `version` to release it under
101+
another number. The run tags that commit `vX.Y.Z` and starts the stable run on the tag. The stable
102+
run waits for approval in the `release` environment, then publishes the packages, drafts the GitHub
103+
release with generated notes, attaches the iOS runner and Android helper assets, publishes the
104+
release and the MCP Registry entry, and commits `main`'s next `-dev` version. Pushing a `vX.Y.Z`
105+
tag yourself starts the same stable run for that commit.
106+
- **Dry run**: a pull request that changes release tooling builds and verifies every package with a
107+
nightly version, and publishes nothing.
108+
109+
To retry a failed run, re-run its failed jobs. The publisher skips package versions that are already
110+
on npm, so a partial publish completes on the next attempt. To preview the packages locally, run
111+
`pnpm release:prepare`. It builds, verifies, and packs every public package into `.tmp/release`.
130112

131113
A public package owns its `files`, published `exports`, license, repository metadata, README,
132114
and `prepack` build (including any prerequisites). Use `publishConfig.exports` for source-only
133115
workspace test exports; pnpm applies the overrides when packing. Keep plugin SDK imports and
134116
bundled workspace helpers in `devDependencies`. Plugins must not depend on the core at runtime
135117
or through a peer dependency. Their factories receive the host from `agent-device`.
136118

137-
When adding a public package, initialize its version from the root `package.json`; subsequent
138-
`npm version` and `release:mark-dev` runs keep it synchronized automatically. An optional plugin
139-
must have no production import from the core build or production dependency in the root manifest.
140-
Run its packed-install smoke before releasing.
119+
When adding a public package, initialize its version from the root `package.json`; the release
120+
workflow stamps the release version into every public package. An optional plugin must have no
121+
production import from the core build or production dependency in the root manifest. Run its
122+
packed-install smoke before releasing. npm can only trust a package that exists, so a maintainer
123+
publishes an empty `0.0.0` placeholder once and grants the trust before the next nightly:
124+
125+
```bash
126+
cd "$(mktemp -d)"
127+
echo '{"name":"@agent-device/<name>","version":"0.0.0","license":"MIT"}' > package.json
128+
npm publish --access public --tag reserved
129+
npm trust github @agent-device/<name> --file release.yml --repository callstack/agent-device \
130+
--environment npm-publish --allow-publish --yes
131+
npm access set mfa=publish @agent-device/<name>
132+
```
141133

142134
### The version on main never equals a published version
143135

144-
`postpublish` runs `release:mark-dev` after all packages publish, moving all public manifests
145-
and synchronized `server.json` to the next patch with a `-dev` prerelease marker (for example
146-
`0.20.11-dev`) and committing that bump as part of the release. The invariant it protects: MCP registry
147-
scanners diff the repository's tool surface per version string, so a released number left on `main`
148-
while `main` keeps changing is indistinguishable from a republished ("rug-pull") version.
149-
`prepublishOnly` and the retry command refuse to publish while the `-dev` marker is
150-
still in place — set the real release version first (for example `npm version patch`, which strips
151-
the prerelease marker), commit, then publish.
136+
`main` carries `X.Y.Z-dev`, naming the release it is building towards. Nightlies preview it as
137+
`X.Y.Z-nightly.*`, and only a stable release publishes `X.Y.Z`. After a stable release, the workflow
138+
moves `main` to the next patch's `-dev` version, unless `main` already builds towards a later
139+
release. To plan a minor or major release, commit the new `-dev` version to `main` (for example
140+
`0.22.0-dev`); nightlies then preview it. The invariant protects MCP Registry scanners, which diff
141+
the repository's tool surface per version string: a released number left on `main` while `main`
142+
keeps changing is indistinguishable from a republished ("rug-pull") version.
152143

153144
### Released-surface baselines roll forward on publish
154145

‎package.json‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -122,8 +122,6 @@
122122
"build:package": "pnpm build && pnpm package:xcuitest && pnpm build:macos-helper:clean && pnpm prepare:publish-assets",
123123
"package:npm": "pnpm build:package && pnpm check:package",
124124
"release:prepare": "rm -rf .tmp/release && pnpm check:mcp-metadata && pnpm build:package && pnpm check:package -- --pack-destination .tmp/release && node scripts/release-workspace.mjs pack",
125-
"release:publish": "node scripts/release-mark-dev.mjs --check-release-version && pnpm release:prepare && node scripts/release-workspace.mjs publish",
126-
"release:mark-dev": "node scripts/release-mark-dev.mjs",
127125
"ad": "node bin/agent-device.mjs",
128126
"bench:help-conformance": "node scripts/help-conformance-bench.mjs",
129127
"maestro:conformance": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/maestro-conformance/format-generated-json.test.mjs packages/maestro/test/conformance/verify.test.ts packages/maestro/test/conformance/differential/engine-process.test.ts packages/maestro/test/conformance/differential/report-output.test.ts packages/maestro/test/conformance/differential/run.test.ts packages/maestro/test/conformance/differential/invariants.test.ts",
@@ -173,7 +171,6 @@
173171
"check:quick": "pnpm lint && pnpm typecheck",
174172
"sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
175173
"check:mcp-metadata": "node scripts/sync-mcp-metadata.mjs --check",
176-
"version": "node scripts/release-workspace.mjs sync --stage && pnpm sync:mcp-metadata && git add server.json",
177174
"check:tooling": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm check:layering && pnpm depgraph:test && pnpm check:gate-manifest:test && pnpm check:gate-manifest && pnpm check:production-exports && pnpm check:tmpdir-leaks:test && pnpm check:xctest-selection && pnpm check:packaged-runner-swift && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files && pnpm check:package",
178175
"check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
179176
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
@@ -214,8 +211,7 @@
214211
"test:replay:macos": "node --experimental-strip-types src/bin.ts test test/integration/replays/macos",
215212
"test:replay:linux": "node --experimental-strip-types src/bin.ts test test/integration/replays/linux",
216213
"test:linux:command-evidence": "node --experimental-strip-types test/integration/linux-e2e/live-runner.ts",
217-
"postpublish": "node scripts/release-workspace.mjs publish",
218-
"prepublishOnly": "node scripts/release-mark-dev.mjs --check-release-version"
214+
"prepublishOnly": "echo 'agent-device publishes from .github/workflows/release.yml; see CONTRIBUTING.md.' >&2 && exit 1"
219215
},
220216
"files": [
221217
"bin",

‎packages/host-kit/src/internal/version.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ test('isNewerVersion orders releases numerically per segment', () => {
138138
});
139139

140140
test('isNewerVersion ranks a release above the prerelease of the same base', () => {
141-
// main carries `-dev` between releases (scripts/release-mark-dev.mjs): a released client meeting
141+
// main carries `-dev` between releases (scripts/release-version.mjs): a released client meeting
142142
// a `-dev` daemon of the same base is the upgrade, and the reverse is the downgrade.
143143
assert.equal(isNewerVersion('0.21.13', '0.21.13-dev'), true);
144144
assert.equal(isNewerVersion('0.21.13-dev', '0.21.13'), false);

‎scripts/release-mark-dev.mjs‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

‎scripts/release-workspace.mjs‎

Lines changed: 4 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,8 @@ import path from 'node:path';
44

55
const root = process.cwd();
66
const [command, ...options] = process.argv.slice(2);
7-
if (
8-
!['sync', 'check', 'pack', 'publish'].includes(command) ||
9-
options.some((option) => option !== '--stage')
10-
) {
11-
throw new Error('Usage: node scripts/release-workspace.mjs <sync|check|pack|publish> [--stage]');
7+
if (!['sync', 'pack'].includes(command) || options.length > 0) {
8+
throw new Error('Usage: node scripts/release-workspace.mjs <sync|pack>');
129
}
1310
const packages = JSON.parse(
1411
execFileSync('pnpm', ['list', '--recursive', '--depth', '-1', '--json'], {
@@ -34,12 +31,11 @@ if (command === 'sync') {
3431
for (const pkg of publicPackages) {
3532
if (pkg.manifest.version !== version) {
3633
throw new Error(
37-
`${pkg.manifest.name}@${pkg.manifest.version} must match agent-device@${version}. Run npm version first.`,
34+
`${pkg.manifest.name}@${pkg.manifest.version} must match agent-device@${version}. Run release-version.mjs stamp first.`,
3835
);
3936
}
4037
}
41-
if (command === 'pack') packWorkspacePackages();
42-
if (command === 'publish') publishWorkspacePackages();
38+
packWorkspacePackages();
4339
}
4440

4541
function syncVersions() {
@@ -48,12 +44,6 @@ function syncVersions() {
4844
pkg.manifest.version = version;
4945
fs.writeFileSync(pkg.manifestPath, `${JSON.stringify(pkg.manifest, null, 2)}\n`);
5046
}
51-
if (options.includes('--stage')) {
52-
execFileSync('git', ['add', '--', ...publicPackages.map((pkg) => pkg.manifestPath)], {
53-
cwd: root,
54-
stdio: 'inherit',
55-
});
56-
}
5747
}
5848

5949
function packWorkspacePackages() {
@@ -101,41 +91,3 @@ function checkPackedIdentity(packed, name) {
10191
throw new Error('Packed package identity differs from the synchronized public package.');
10292
}
10393
}
104-
105-
function publishWorkspacePackages() {
106-
if (process.env.npm_config_dry_run === 'true') {
107-
if (process.env.npm_lifecycle_event !== 'postpublish') {
108-
throw new Error(
109-
'Use npm publish --dry-run to preview a release; the retry command publishes.',
110-
);
111-
}
112-
return;
113-
}
114-
const args = [
115-
'--recursive',
116-
'--include-workspace-root',
117-
'publish',
118-
'--access',
119-
'public',
120-
'--no-git-checks',
121-
'--ignore-scripts',
122-
];
123-
if (process.env.npm_lifecycle_event === 'postpublish') {
124-
args.push('--filter', `!${rootPackage.manifest.name}`);
125-
}
126-
execFileSync('pnpm', args, { cwd: root, stdio: 'inherit' });
127-
execFileSync(process.execPath, ['scripts/release-mark-dev.mjs'], { cwd: root, stdio: 'inherit' });
128-
execFileSync(
129-
'git',
130-
[
131-
'commit',
132-
'--only',
133-
'-m',
134-
`chore: mark ${version} as released`,
135-
'--',
136-
...publicPackages.map((pkg) => pkg.manifestPath),
137-
path.join(root, 'server.json'),
138-
],
139-
{ cwd: root, stdio: 'inherit' },
140-
);
141-
}

‎website/docs/docs/installation.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,17 @@ agent-device --version
5555

5656
Set `AGENT_DEVICE_NO_UPDATE_NOTIFIER=1` to disable the notice.
5757

58+
## Nightly builds
59+
60+
Nightly builds publish the latest `main` once a day, after its CI passes:
61+
62+
```bash
63+
npm install -g agent-device@nightly
64+
```
65+
66+
A nightly install's update notice suggests the newest nightly. To return to stable releases, install
67+
`agent-device@latest`.
68+
5869
## Without installing
5970

6071
```bash

0 commit comments

Comments
 (0)