@@ -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
7272metadata and then runs ` pnpm package:npm ` . This is the one completeness-oriented aggregate: it
7373builds 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
8484above 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
131113A public package owns its ` files ` , published ` exports ` , license, repository metadata, README,
132114and ` prepack ` build (including any prerequisites). Use ` publishConfig.exports ` for source-only
133115workspace test exports; pnpm applies the overrides when packing. Keep plugin SDK imports and
134116bundled workspace helpers in ` devDependencies ` . Plugins must not depend on the core at runtime
135117or 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
0 commit comments