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.

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

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

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

git checkout develop && git pull
git checkout -b release

Step 4 -- Set release scope

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:

git add .
git commit -m "📦 (release): Set release scope to <packages>"

Step 5 -- Pin workspace deps

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:

git add .
git commit -m "🔧 (release): Pin workspace dependencies"

Step 6 -- Bump versions

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:

git add .
git commit -m "🔖 (release): Bump versions"

Step 7 -- Generate changelogs

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:

git add .
git commit -m "📝 (release): Generate changelogs"

Step 8 -- Clean up changesets

pnpm exec zx agent-files/scripts/release/cleanup.cjs

• Deletes .changeset/*.md files consumed by the release.

Commit:

git add .
git commit -m "🔥 (release): Clean up consumed changesets"

Step 9 -- Update lockfile

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:

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:

git add .
git commit -m "📝 (release): Update getting-started versions"

Step 11 -- Create release PR

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.