release

# Release Packages Release one or more packages from this monorepo using the scripts in `agent-files/scripts/release/`. ## Permission prompts The following commands need network access, post-install scripts, or the GitHub CLI, so they will trigger a permission prompt (Claude Code) or must be run with `required_permissions: ["all"]` (Cursor): - `pnpm exec zx agent-files/scripts/release/preflight.cjs` (Step 1 — `gh auth status`) - `pnpm exec zx agent-files/scripts/release/changelog.cjs` (Step 7 — GitHub API via `gh`) - `pnpm install --no-frozen-lockfile` (Step 9 — post-install scripts, native deps) - `pnpm exec zx agent-files/scripts/release/create-pr.cjs` (Step 11 — `gh pr create`) All other scripts (`discover`, `set-private`, `pin-deps`, `bump`, `cleanup`) run fine inside the sandbox. ## Package aliases Use these short names in the `--packages` flag. The user may use either aliases or full names. | Alias | Full package name | | ----------------------- | -------------------------------------------------------------- | | `dmk` | `@ledgerhq/device-management-kit` | | `signer-eth` | `@ledgerhq/device-signer-kit-ethereum` | | `signer-btc` | `@ledgerhq/device-signer-kit-bitcoin` | | `signer-sol` | `@ledgerhq/device-signer-kit-solana` | | `signer-aleo` | `@ledgerhq/device-signer-kit-aleo` | | `signer-cosmos` | `@ledgerhq/device-signer-kit-cosmos` | | `signer-hyperliquid` | `@ledgerhq/device-signer-kit-hyperliquid` | | `signer-concordium` | `@ledgerhq/device-signer-kit-concordium` | | `signer-polkadot` | `@ledgerhq/device-signer-kit-polkadot` | | `signer-zcash` | `@ledgerhq/device-signer-kit-zcash` | | `signer-utils` | `@ledgerhq/signer-utils` | | `signer-xrp` | `@ledgerhq/device-signer-kit-xrp` | | `context-module` | `@ledgerhq/context-module` | | `transport-web-hid` | `@ledgerhq/device-transport-kit-web-hid` | | `transport-web-ble` | `@ledgerhq/device-transport-kit-web-ble` | | `transport-rn-ble` | `@ledgerhq/device-transport-kit-react-native-ble` | | `transport-rn-hid` | `@ledgerhq/device-transport-kit-react-native-hid` | | `transport-node-hid` | `@ledgerhq/device-transport-kit-node-hid` | | `transport-mockserver` | `@ledgerhq/device-transport-kit-mockserver` | | `transport-speculos` | `@ledgerhq/device-transport-kit-speculos` | | `mockserver-client` | `@ledgerhq/device-mockserver-client` | | `mockserver-react` | `@ledgerhq/device-mockserver-react` | | `speculos-controller` | `@ledgerhq/speculos-device-controller` | | `keyring-protocol` | `@ledgerhq/device-trusted-app-kit-ledger-keyring-protocol` | | `ledger-wallet` | `@ledgerhq/dmk-ledger-wallet` | | `devtools-core` | `@ledgerhq/device-management-kit-devtools-core` | | `devtools-rozenite` | `@ledgerhq/device-management-kit-devtools-rozenite` | | `devtools-ui` | `@ledgerhq/device-management-kit-devtools-ui` | | `devtools-ws-common` | `@ledgerhq/device-management-kit-devtools-websocket-common` | | `devtools-ws-connector` | `@ledgerhq/device-management-kit-devtools-websocket-connector` | | `devtools-ws-server` | `@ledgerhq/device-management-kit-devtools-websocket-server` | ## Release flow (step by step) All scripts live in `agent-files/scripts/release/` and are run with `pnpm exec zx`. Replace `<PKGS>` with a comma-separated list of aliases (e.g., `dmk,signer-eth`). **Important:** Commit after every step that modifies files. This keeps the release branch bisectable and easy to review. ### Step 1 -- Preflight ```bash pnpm exec zx agent-files/scripts/release/preflight.cjs ``` - If any check fails, fix the issue before proceeding. - This step **MUST** pass before running any other release step. ### Step 2 -- Discover & confirm ```bash pnpm exec zx agent-files/scripts/release/discover.cjs --packages <PKGS> ``` - `--packages` is required. Pass the same comma-separated aliases the user requested (e.g. `signer-sol,signer-eth`). - Parse the JSON output. The script returns `{ releasable, selected }`. - Present two sections to the user, in order: #### a. All releasable packages `releasable[]` lists every package with pending changesets in the repo. Each entry has `name`, `displayName`, `version`, `bump` (highest of major > minor > patch), and `changesets`. ``` | Package | Current version | Bump | Changesets | |---------|----------------|------|------------| | @ledgerhq/device-signer-kit-ethereum | 1.13.0 | minor | long-flies-try, tidy-onions-flow | | @ledgerhq/signer-utils | 1.1.3 | minor | calm-ducks-love | ``` #### b. Packages that will be released in this run `selected[]` is the intersection of `releasable` and the requested aliases. Each row has `from`, `to`, `bump`, `changesets`, and `depsNotReleased` (workspace deps of this package that are NOT in the selected set). ``` | Package | From | To | Bump | Changesets | |---------|------|----|------|------------| | @ledgerhq/device-signer-kit-solana | 1.7.1 | 1.8.0 | minor | heavy-mangos-write, itchy-teams-join, ripe-suits-lie | ``` For each row where `depsNotReleased` is non-empty, add a sub-bullet block immediately below it: > **Signer SOL** has workspace deps that are NOT in this release: > > - @ledgerhq/context-module (dependency) > - @ledgerhq/signer-utils (dependency) > - @ledgerhq/device-management-kit (peerDependency) These deps will be pinned by `pin-deps.cjs` to their currently-published versions — confirm with the user that this is intended. After the table, diff the requested aliases against `selected[].name`. If any requested package did not appear in `selected`, tell the user it has no pending changesets and will be skipped. **Wait for the user to confirm** before proceeding. Do NOT continue until the user explicitly approves. ### Step 3 -- Create release branch ```bash git checkout develop && git pull git checkout -b release ``` ### Step 4 -- Set release scope ```bash pnpm exec zx agent-files/scripts/release/set-private.cjs --packages <PKGS> ``` - Sets `private:false` on target packages, `private:true` on everything else. - Auto-includes dependents of major-bumped packages (creates a patch changeset for them). - Review the JSON summary to confirm the right packages are public. **Commit:** ```bash git add . git commit -m "📦 (release): Set release scope to <packages>" ``` ### Step 5 -- Pin workspace deps ```bash pnpm exec zx agent-files/scripts/release/pin-deps.cjs --packages <PKGS> ``` - Replaces `workspace:^` with `^<version>` for deps pointing to non-released internal packages. - Review the pinned list; deps between released packages stay as `workspace:^`. **Commit:** ```bash git add . git commit -m "🔧 (release): Pin workspace dependencies" ``` ### Step 6 -- Bump versions ```bash pnpm exec zx agent-files/scripts/release/bump.cjs ``` - Reads changesets and applies semver bumps to `package.json`. - Propagates patch bumps to released packages that depend on bumped packages. - Review the bumps summary. Verify versions look correct. **Commit:** ```bash git add . git commit -m "🔖 (release): Bump versions" ``` ### Step 7 -- Generate changelogs ```bash pnpm exec zx agent-files/scripts/release/changelog.cjs ``` - Prepends new entries to each bumped package's `CHANGELOG.md`. - Review a couple of changelogs to confirm formatting. **Commit:** ```bash git add . git commit -m "📝 (release): Generate changelogs" ``` ### Step 8 -- Clean up changesets ```bash pnpm exec zx agent-files/scripts/release/cleanup.cjs ``` - Deletes `.changeset/*.md` files consumed by the release. **Commit:** ```bash git add . git commit -m "🔥 (release): Clean up consumed changesets" ``` ### Step 9 -- Update lockfile ```bash pnpm install --no-frozen-lockfile ``` - The `--no-frozen-lockfile` flag is required because Step 5 pinned workspace deps (replacing `workspace:^` with concrete versions), which makes the existing lockfile out of date. **Commit:** ```bash git add . git commit -m "🔧 (release): Update lockfile" ``` ### Step 10 -- Update the docs version tables Update the version tables in `apps/docs/content/docs/index.mdx` to reflect the new versions of all released packages. - Read the file and locate the library tables (DMK, Signers & Trusted App Kit, Transports, DevTools). - For each released (public) package, find its row in the table and replace the old version number with the new bumped version from Step 6. - Only update rows for packages that were actually released. **Commit:** ```bash git add . git commit -m "📝 (release): Update getting-started versions" ``` ### Step 11 -- Create release PR ```bash pnpm exec zx agent-files/scripts/release/create-pr.cjs ``` - Opens a PR targeting `main` with a version summary body. - Report the PR URL to the user. ### Step 12 -- Verify documentation and README Perform a documentation health check. This step does not block the release but surfaces issues for the user. - **`apps/docs/content/docs/index.mdx`**: Cross-check that every released package now shows its new version in the tables. Report any mismatches. - **`README.md`**: Check that every released package appears in the package inventory tables (around lines 88-153). If a package is missing, warn the user. - **Migration guides**: For any package with a **major** or **minor** bump, check whether a migration guide exists under `apps/docs/content/docs/integration/migrations/`. If none is found, remind the user that a migration guide may be needed. - Report all findings to the user. ## Error handling - If any script fails, read its stderr output and fix the issue before retrying. - If `set-private.cjs` fails on an unknown alias, check the alias table above or `agent-files/scripts/release/config.cjs`. - If `bump.cjs` reports "No changesets found", verify that `.changeset/*.md` files exist for the target packages. - If `create-pr.cjs` fails, ensure `gh` CLI is authenticated (`gh auth status`) and the branch is pushed. - Never force-push or amend commits that have been pushed to a shared branch.