@smoothbricks/cli 0.1.0 → 0.1.1

package/README.md

@@ -3,9 +3,9 @@
 `@smoothbricks/cli` provides `smoo`, the SmoothBricks monorepo automation CLI. It is the control plane for shared CI,
 release, Git hook, package metadata, and publish validation conventions across SmoothBricks-style repositories.
 
-The tool is intentionally convention-over-configuration. SmoothBricks repos use Nx, Bun, Nix, devenv, and direnv, so
-`smoo` assumes those pieces exist instead of adding another local config file. Repos should be made correct by running
-the mutating initialization path, then kept correct by the read-only validation path.
+The tool is intentionally convention-over-configuration. SmoothBricks repos use [Nx], [Bun], [Nix], [devenv], and
+[direnv], so `smoo` assumes those pieces exist instead of adding another local config file. Repos should be made correct
+by running the mutating initialization path, then kept correct by the read-only validation path.
 
 ## Install
 
@@ -28,19 +28,20 @@ directly. Published installs use the package binary in `bin/smoo`, which imports
 
 ```bash
 smoo monorepo init [--runtime-only] [--sync-runtime]
-smoo monorepo validate
+smoo monorepo validate [--fail-fast] [--only-if-new-workspace-package]
 smoo monorepo update
 smoo monorepo check
 smoo monorepo diff
 smoo monorepo validate-commit-msg <commit-msg-file>
 smoo monorepo sync-bun-lockfile-versions
-smoo monorepo list-public-projects
+smoo monorepo list-release-packages [--fail-empty] [--github-output <path>]
 smoo monorepo validate-public-tags
-smoo monorepo release-state
 
-smoo release version --bump <auto|patch|minor|major|prerelease> [--dry-run]
-smoo release publish --bump <auto|patch|minor|major|prerelease> [--tag <tag>] [--npm-tag <tag>] [--dry-run]
-smoo release github-release --tags <tags> --bump <auto|patch|minor|major|prerelease> [--tag <tag>] [--npm-tag <tag>] [--dry-run]
+smoo release npm-status
+smoo release repair-pending [--dry-run]
+smoo release version --bump <auto|patch|minor|major|prerelease> [--dry-run] [--github-output <path>]
+smoo release publish --bump <auto|patch|minor|major|prerelease> [--dry-run]
+smoo release retag-unpublished <tag...> [--to <ref>] [--push] [--dispatch] [--remote <remote>] [--branch <branch>] [--dry-run]
 smoo release trust-publisher [--dry-run] [--otp <code>] [--skip-login]
 
 smoo github-ci cleanup-cache
@@ -55,12 +56,13 @@ only reporting drift.
 
 It currently:
 
-- Updates managed CI, release, hook, and formatting files.
+- Updates managed CI, release, hook, and formatting files. The publish workflow is only written when the repo has owned
+  release packages.
 - Ensures the local `tooling/smoo` source shim is executable when present.
 - Synchronizes root runtime versions inside devenv, or when `--sync-runtime` is passed.
-- Applies publish metadata defaults to `npm:public` packages.
+- Applies safe publish metadata defaults to `npm:public` packages without inferring package ownership.
 - Normalizes internal workspace dependency ranges to `workspace:*`.
-- Runs `sherif --fix --select highest` for broad monorepo package hygiene.
+- Runs [`sherif --fix --select highest`][sherif] for broad monorepo package hygiene.
 - Normalizes conditional export ordering so `types` comes first and `default` comes last.
 - Adds `src` to package `files` when development-only exports intentionally point at source files.
 
@@ -86,24 +88,32 @@ It checks:
 - Managed file drift.
 - Root package policy.
 - Root Bun type version matches the Bun package manager version.
-- Nx release policy.
+- Nx release policy, including project package release tags, project-level GitHub Release changelogs, and the temporary
+  Bun lockfile versionActions hook.
+- `bun.lock` workspace versions match package manifests.
 - Public package tag policy.
 - Public package metadata.
 - Workspace dependency ranges.
-- `sherif` package hygiene.
-- Packed public package artifacts with `publint`.
-- Packed public package type resolution with the `attw` CLI.
+- [`sherif`] package hygiene, with warnings treated as validation failures.
+- Packed public package artifacts with [`publint`].
+- Packed public package type resolution with the [`attw`][are-the-types-wrong] CLI.
+
+The packed-package checks validate what [npm] users will install, not only the source tree. `smoo` packs each
+`npm:public` package with [Bun], runs [`publint`] on the tarball, then runs [`attw`][are-the-types-wrong] on the same
+tarball.
 
-The packed-package checks validate what npm users will install, not only the source tree. `smoo` packs each `npm:public`
-package with Bun, runs `publint` on the tarball, then runs `attw` on the same tarball.
+The [`attw`][are-the-types-wrong] check uses the `node16` profile and ignores the CJS-to-ESM warning. SmoothBricks
+packages are [ESM]-first, so [CommonJS] consumers can use dynamic import. Node 10-only subpath failures are
+intentionally ignored because [Node.js] 10 is not part of the supported package contract.
 
-The `attw` check uses the `node16` profile and ignores the CJS-to-ESM warning. SmoothBricks packages are ESM-first, so
-CommonJS consumers can use dynamic import. Node 10-only subpath failures are intentionally ignored because Node 10 is
-not part of the supported package contract.
+`smoo monorepo validate --only-if-new-workspace-package` first checks the staged git diff for newly added workspace
+package manifests. If none are staged, it exits successfully without running the full validator. The generated
+pre-commit hook uses this mode so adding a package rechecks conditional managed files, including whether the publish
+workflow is now required, without making every commit pay for full validation.
 
 ## Publishable Packages
 
-Publishability is declared with an Nx tag:
+Publishability is declared with an [Nx] tag:
 
 ```json
 {
@@ -113,23 +123,39 @@ Publishability is declared with an Nx tag:
 }
 ```
 
-This tag is the source of truth for release selection, metadata validation, and publish artifact validation. `smoo`
-never relies on a second hardcoded package list.
+This tag is the source of truth for public npm metadata and publish artifact validation. Release selection adds one more
+convention: a package is released by the current repository only when its `repository.url` exactly matches the root
+`package.json` `repository.url`. Equivalent-but-different spellings, such as `git+https` vs SSH for the same GitHub
+repo, fail validation because ownership should be explicit and visually obvious. This lets a workspace mirror public
+packages from another repository without publishing them from the mirror.
 
 Rules:
 
-- Publishable packages must not be private.
-- Private packages must not have `npm:public`.
-- Every non-private workspace package must have `npm:public`.
+- `npm:public` packages must not be `private: true`.
+- `private: true` packages must not have `npm:public`.
 - Public packages must define license metadata.
 - Public packages must publish with `publishConfig.access = "public"`.
-- Public package repositories must point at the root repo and include `repository.directory`.
+- Public packages must define `repository.type`, `repository.url`, and `repository.directory`.
 - Public packages must define `files`.
 - Public library packages must define `types`.
 - Public packages must define either `exports` or `bin`.
 
-`smoo monorepo init` fixes the metadata that can be derived from the root package. For example, it copies the root
-license and repository URL, then sets each package's `repository.directory` from its workspace path.
+Owned public packages may inherit the root license when the root license is not `UNLICENSED`. Mirrored public packages
+must carry their own license. `smoo monorepo init` does not copy the root `repository.url` into packages; a missing
+package `repository.url` is a validation failure so new packages must consciously choose whether they are owned by the
+current repository or mirrored from another one. Init still sets `publishConfig.access = "public"`, repository type,
+repository directory, export ordering, and source-file publish entries when those can be derived safely.
+
+`smoo monorepo list-release-packages` prints the comma-separated package names that are both `npm:public` and owned by
+the current repository. Release commands, trusted-publisher setup, and the managed publish workflow use this owned
+release package list instead of every public package in the workspace.
+
+For [GitHub Actions], `smoo monorepo list-release-packages --fail-empty --github-output "$GITHUB_OUTPUT"` appends the
+`projects=<package-list>` output expected by the managed publish workflow and fails with a clear error when no owned
+release packages exist.
+
+`smoo release npm-status` shows whether each owned release package's current `name@version` already exists on npm. It is
+an npm registry check, not a full release workflow status check.
 
 ## Managed Files
 
@@ -137,15 +163,18 @@ license and repository URL, then sets each package's `repository.directory` from
 
 Managed files include:
 
-- `.git-format-staged.yml`
+- [`.git-format-staged.yml`][git-format-staged]
 - Git hook scripts under `tooling/git-hooks`
-- direnv/GitHub Actions bootstrap scripts under `tooling/direnv`
-- GitHub Actions workflows under `.github/workflows`
-- Local composite GitHub Actions under `.github/actions`
+- [direnv]/[GitHub Actions] bootstrap scripts under `tooling/direnv`
+- [GitHub Actions] workflows under `.github/workflows`
+- Local composite [GitHub Actions] under `.github/actions`
 
 When a managed target is a symlink, `smoo` leaves it alone. SmoothBricks uses symlinks back to `packages/cli/managed` so
 changes to the CLI package are tested immediately. Downstream repos receive ordinary committed copies.
 
+The publish workflow is conditional. Repositories with no owned release packages skip `.github/workflows/publish.yml` in
+`init`, `check`, and `diff`; adding a new owned package makes the workflow required on the next validation run.
+
 Use:
 
 ```bash
@@ -158,8 +187,12 @@ smoo monorepo diff
 
 ## Git Hooks
 
-The generated pre-commit hook runs `git-format-staged` from the repository root with `tooling`, `node_modules/.bin`, and
-the devenv profile on `PATH`.
+The generated pre-commit hook runs [`git-format-staged`][git-format-staged] from the repository root with `tooling`,
+`node_modules/.bin`, and the [devenv] profile on `PATH`.
+
+After formatting, the hook runs `smoo monorepo validate --fail-fast --only-if-new-workspace-package`. This keeps normal
+commits fast while still catching incomplete package setup and conditional managed-file drift when a new workspace
+package manifest is staged.
 
 The generated commit-msg hook delegates conventional commit validation to:
 
@@ -171,21 +204,22 @@ This keeps hook behavior consistent with CI and avoids duplicating commit messag
 
 ## GitHub Actions
 
-The generated workflows keep readable YAML and named top-level steps, while larger logic lives in `smoo` commands,
-post-checkout composite actions, or the small pre-smoo bootstrap script. Checkout stays inline in each workflow because
-repository-local composite actions do not exist until `actions/checkout` has populated the working tree.
+The generated [GitHub Actions] workflows keep readable YAML and named top-level steps, while larger logic lives in
+`smoo` commands, post-checkout composite actions, or the small pre-smoo bootstrap script. Checkout stays inline in each
+workflow because repository-local composite actions do not exist until `actions/checkout` has populated the working
+tree.
 
-CI uses explicit lint, test, and build phases. The publish workflow does the same before running release commands so
-GitHub output remains readable even though Nx release also has its own `preVersionCommand` safety net.
+CI uses explicit lint, test, and build phases. The publish workflow does the same after versioning so GitHub output
+stays readable and validation happens on the exact release commit.
 
-CI status deeplinks depend on GitHub's top-level job step anchors. The generated CI workflow keeps `# Step N` comments
-next to each top-level step, and the `smoo github-ci nx-smart --step <number>` values for lint, test, and build must
-stay synchronized with those comments. Composite action internals do not change the top-level step numbers.
+CI status deeplinks depend on [GitHub Actions]' top-level job step anchors. The generated CI workflow keeps `# Step N`
+comments next to each top-level step, and the `smoo github-ci nx-smart --step <number>` values for lint, test, and build
+must stay synchronized with those comments. Composite action internals do not change the top-level step numbers.
 
 Managed CI setup is split across local composite actions:
 
-- `setup-devenv` installs Nix, restores the Nix cache segment, imports the store NAR, restores `.devenv`/`.direnv` only
-  after an exact Nix cache hit, enables Cachix, installs devenv, restores `node_modules`, and builds the shell.
+- `setup-devenv` installs [Nix], restores the Nix cache segment, imports the store NAR, restores `.devenv`/`.direnv`
+  only after an exact Nix cache hit, enables [Cachix], installs [devenv], restores `node_modules`, and builds the shell.
 - `save-nix-devenv` runs under `always()`, calls `smoo github-ci cleanup-cache`, and explicitly saves cache segments
   only when cleanup reports `cache-ready=true`.
 - `cache-nix-devenv` is the shared restore/save primitive for the separate `nix` and `devenv` cache segments.
@@ -208,64 +242,132 @@ The bootstrap script is intentionally small. It only handles work required befor
 
 ## Releases
 
-Release commands wrap Nx release but keep SmoothBricks policy in one place.
+Release commands wrap [Nx Release][nx-release] but keep SmoothBricks policy in one place.
 
 Versioning:
 
-- `--bump auto` uses Nx conventional-commit versioning.
+- `--bump auto` uses [Nx Release][nx-release] [Conventional Commits] versioning.
 - `--bump patch|minor|major|prerelease` forces the release specifier.
-- Release projects are discovered from `npm:public` packages.
-- Nx release config must use `currentVersionResolver: "git-tag"` with `fallbackCurrentVersionResolver: "disk"`.
-  Conventional-commit versioning requires git tags as the primary source, while the disk fallback supports initial
-  releases before package tags exist.
-- `smoo release version` lets Nx own local package versioning, `bun.lock` updates, the release commit, and annotated
-  tags. smoo records `HEAD` before and after Nx runs, then pushes with `git push --follow-tags --atomic` only if Nx
-  created a new release commit. This keeps the release commit and tags atomic without pushing an older checkout on
-  retries where Nx has nothing new to commit.
-- Reruns call Nx versioning again rather than repairing tags in `smoo`. Nx's git-tag current-version resolver plus disk
-  fallback handles already-tagged releases and first releases before package tags exist; smoo skips the remote push when
-  Nx leaves `HEAD` unchanged.
+- Release packages are discovered from `npm:public` packages whose `repository.url` exactly matches the root package.
+- [Nx Release][nx-release] config must use `currentVersionResolver: "git-tag"` with
+  `fallbackCurrentVersionResolver: "disk"`. Conventional-commit versioning requires git tags as the primary source,
+  while the disk fallback supports initial releases before package tags exist.
+- [Nx Release][nx-release] config must use `versionActions: "@smoothbricks/cli/nx-version-actions"`. This wraps Nx's JS
+  version actions and temporarily syncs `bun.lock` workspace versions after Nx runs `bun install --lockfile-only`.
+- [Nx Release][nx-release] `preVersionCommand` is intentionally not used. smoo builds exactly the packages that still
+  need npm publish immediately before packing them, while the managed workflow separately builds, lints, tests, and
+  validates newly created release commits.
+- `smoo release repair-pending` runs before the normal publish flow. It repairs older remote release tags whose npm
+  package version or GitHub Release is missing, while leaving the current `HEAD` release target to `version` and
+  `publish`.
+- `smoo release version` selects the current release target before validation by running [Nx Release][nx-release]
+  versioning. npm registry state is not used to decide whether versioning should run. If `HEAD` is already a release
+  target, versioning returns `mode=none` and leaves idempotent completion to `smoo release publish`.
+- `smoo release version --github-output "$GITHUB_OUTPUT"` appends `mode=new|none` and `projects=<comma-list>`. The
+  managed publish workflow uses `mode != "none"` to build, lint, test, and validate exactly the commit that
+  `smoo release publish` will publish. The validation and publish step names include the selected mode so the [GitHub
+  Actions] run shows whether it is creating a new release or recording a no-op.
+- Explicit bumps are mandatory when `HEAD` is not already a release target: after pending releases are repaired,
+  `bump=patch|minor|major|prerelease` must make Nx create a new release commit. smoo fails if Nx returns without moving
+  `HEAD`; `auto` may no-op when there are no releasable conventional commits.
+- `--dry-run` previews versioning and completion without pushing refs, publishing npm packages, or writing GitHub
+  Releases.
+- The `nx-version-actions` hook is a temporary Bun workaround. Bun currently leaves `bun.lock` workspace versions stale
+  after package manifest bumps, and `bun pm pack` rewrites `workspace:*` dependencies using those stale lockfile
+  versions. Keep the hook until supported Bun versions resolve these issues:
+  [oven-sh/bun#18906](https://github.com/oven-sh/bun/issues/18906),
+  [oven-sh/bun#20477](https://github.com/oven-sh/bun/issues/20477), and
+  [oven-sh/bun#20829](https://github.com/oven-sh/bun/issues/20829).
+- Package release tags must use `{projectName}@{version}`. smoo derives release package/version pairs from that tag
+  shape and recreates missing local tags for Nx release commits before repairing remote state.
+- `smoo release retag-unpublished <tag...>` is a break-glass recovery command for the case where Nx already committed a
+  version bump but npm publish failed before the package version became durable. It moves exact owned release tags to
+  `HEAD` by default without bumping package manifests again. It refuses to move a tag when `package@version` already
+  exists on npm, when the GitHub Release exists, or when the target ref's package manifest does not contain the tagged
+  version. Pass `--push` to update remote tags with `--force-with-lease`; pass `--dispatch` to also start `publish.yml`
+  with `bump=auto`. Dispatch validates that the target ref is already the remote branch head so the workflow will
+  publish the same commit that was retagged.
+
+### Repair Process
+
+`repair-pending` is tag-driven, not history-driven. It starts from fetched remote release tags because those tags are
+the durable record that a package version was selected for release. It only checks npm and GitHub Release state to
+decide which tags still need work; it does not walk normal commits looking for release-shaped changes.
+
+1. Collect owned release tags from the fetched remote tag set, sorted newest-first by annotated tag `creatordate`. Only
+   tags matching owned package release names are considered, and each tag is peeled to the commit it releases.
+2. Classify each owned release tag before grouping by commit. A tag needs npm repair when `package@version` is missing
+   from npm, and it needs GitHub repair when the GitHub Release for that tag is missing. Tags needing neither are
+   filtered out immediately.
+3. Group only repair-needed tags by peeled commit. Empty commits disappear because their tags were already complete.
+   Exclude `HEAD` because the current release target is handled by `smoo release version` and `smoo release publish`,
+   not by the older-release repair loop.
+4. Sort the remaining repair commits oldest-to-newest. Only after this sorted non-HEAD repair list exists does smoo
+   start checking out commits.
+5. For each repair commit, check out the commit once and load that checkout's direnv environment once. If any grouped
+   tag still needs npm publish, run `nx run-many -t build --projects=<comma-separated npm-missing packages>` once, then
+   publish those packages using the npm dist-tag implied by each package version. If the commit only needs GitHub
+   Releases, skip the build. Finally, create the missing GitHub Releases for the grouped tags that need them.
+
+Pending release state should be a suffix of the release-target timeline because `repair-pending` runs before every
+publish. Once a complete release target is reached, older targets are assumed complete; an observed gap in repair state
+violates the workflow invariant and should fail loudly instead of silently repairing history out of order.
 
 Publishing:
 
 - `prerelease` publishes with npm dist-tag `next`.
 - Stable bumps publish with npm dist-tag `latest`.
-- Conflicting explicit dist-tags are rejected.
-- `smoo release publish` checks every current `name@version` for `npm:public` packages before publishing. Already
-  published versions are skipped, so reruns after auth or network failures retry only the package versions npm does not
-  have yet.
+- `smoo release publish` pushes missing branch/tag refs, publishes missing npm versions, creates or updates GitHub
+  Releases, and writes a GitHub Step Summary. Already published npm versions are skipped, so reruns after auth or
+  network failures retry only the package versions npm does not have yet.
+- npm registry state gates publish idempotency only. It decides which already-versioned package tarballs still need to
+  be published during a real release retry, not whether versioning should run or whether the workflow has a release to
+  publish.
+- Before npm publish, smoo runs `nx run-many -t build --projects=<comma-separated npm-missing packages>` for exactly the
+  packages whose `name@version` is not on npm yet. Nx cache makes this cheap when the managed workflow already built the
+  same projects, and it keeps reruns self-sufficient when repairing a previously selected `HEAD` release target.
 - Publish uses `bun pm pack` to create package tarballs, then publishes those tarballs with latest npm CLI and
-  `--provenance`. Bun pack resolves internal `workspace:*` dependency ranges to real versions in the tarball manifest;
-  smoo fails before publish if a packed manifest still contains `workspace:`.
-- npm CLI owns publish authentication. When trusted publishing is configured, npm uses GitHub Actions OIDC from the
-  workflow's `id-token: write` permission. Before trusted publishing exists, the managed workflow passes
-  `secrets.NPM_TOKEN` as `NODE_AUTH_TOKEN` and smoo writes a temporary npm user config for bootstrap publishing.
-- `smoo release trust-publisher` configures npm trusted publishing for every `npm:public` package. It uses the root
-  `package.json` `repository.url` as the GitHub `owner/repo`, uses `publish.yml` as the trusted workflow, and runs
-  `npm trust` through `nix shell nixpkgs#nodejs_latest` because the Lambda-pinned Node 24/npm toolchain may lag the npm
-  CLI feature. By default it runs `npm login --auth-type=web` first so npm can open a browser login; pass `--skip-login`
-  when the current npm session is already authenticated. Packages must already exist on npm before trust can be
-  configured. npm may still require operation-level 2FA for `npm trust`; smoo prompts for a hidden OTP per package, or
-  you can pass `--otp <code>` for non-interactive use.
+  `--provenance`. Each package uses the npm dist-tag implied by its own version (`next` for prereleases, `latest` for
+  stable versions). Bun pack resolves internal `workspace:*` dependency ranges to real versions in the tarball manifest;
+  smoo fails before publish if a packed manifest still contains `workspace:` or if an internal dependency does not match
+  the current workspace package version.
+- [npm CLI][npm] owns publish authentication. Existing packages use [trusted publishing][npm-trusted-publishing] with
+  [GitHub Actions OIDC][github-actions-oidc] from the workflow's `id-token: write` permission. Package names that do not
+  exist on npm yet use `secrets.NPM_TOKEN` as `NODE_AUTH_TOKEN` for the first publish, because trusted publishing can
+  only be configured after the package exists. Once `smoo release trust-publisher` succeeds for a package, future
+  publishes for that package use OIDC even if the bootstrap token is still present in repository secrets.
+- `smoo release trust-publisher` configures [npm trusted publishing][npm-trusted-publishing] for every owned release
+  package. It uses the root `package.json` `repository.url` as the GitHub `owner/repo`, uses `publish.yml` as the
+  trusted workflow, and runs `npm trust` through `nix shell nixpkgs#nodejs_latest` because the Lambda-pinned Node 24/npm
+  toolchain may lag the npm CLI feature. By default it runs `npm login --auth-type=web` first so npm can open a browser
+  login; pass `--skip-login` when the current npm session is already authenticated. Packages must already exist on npm
+  before trust can be configured. npm may still require operation-level 2FA for `npm trust`; smoo prompts for a hidden
+  OTP per package, or you can pass `--otp <code>` for non-interactive use.
 
 GitHub Releases:
 
-- `smoo release github-release` creates or updates releases for the selected tags.
-- `latest` status follows the derived npm dist-tag.
+- `smoo release publish` delegates to `nx release changelog` once per owned package whose current package release tag is
+  at `HEAD`, passing that package's version explicitly for independent releases after npm publish succeeds.
+- Nx project changelogs are configured to create or update GitHub Releases, not local changelog files.
+- Generated release notes are package-scoped Conventional Commit changelogs. Init defaults author rendering and GitHub
+  username lookup on, while validation allows repos to override those render options.
 
-The release flow is designed to be rerun after partial failure. Nx owns local version/tag behavior, `smoo` owns the
-guarded atomic git push, and npm registry state makes publishing idempotent across retries.
+The release flow is designed to be rerun after partial failure. Nx owns local version/tag behavior, while smoo derives
+durable completion state from the remote branch, release tags, npm registry versions, and GitHub Releases. Repeated
+Publish runs converge without self-spawning another workflow run.
 
 ## Why This Shape
 
 The important design goal is one source of truth per convention:
 
-- Nx `npm:public` tags decide what is publishable.
+- [Nx] `npm:public` tags decide what has a public npm package contract.
+- Matching root/package `repository.url` values decide which public packages are released by the current repo.
 - Managed files decide what generated CI and hooks should look like.
-- Root package metadata provides defaults for public packages.
+- Root package metadata provides defaults only for owned public packages.
 - Actual workspace package names decide which dependency ranges become `workspace:*`.
-- `sherif` handles broad package hygiene.
-- `publint` and `attw` validate real packed artifacts.
+- Package manifests decide Bun lockfile workspace versions until Bun stops leaving them stale during releases.
+- [`sherif`] handles broad package hygiene.
+- [`publint`] and [`attw`][are-the-types-wrong] validate real packed artifacts.
 
 This keeps `smoo` small where external tools already do the job, but keeps SmoothBricks-specific policy native where
 generic tools do not know the repo contract. In particular, `sherif` is useful for package hygiene, but it does not know
@@ -287,3 +389,26 @@ If validating packages with Zig build steps from outside the devenv shell, add Z
 ```bash
 nix shell nixpkgs#zig -c nx run-many -t build --projects=<public-projects>
 ```
+
+## Links
+
+[are-the-types-wrong]: https://github.com/arethetypeswrong/arethetypeswrong.github.io/tree/main/packages/cli
+[Bun]: https://bun.sh/
+[Cachix]: https://www.cachix.org/
+[CommonJS]: https://nodejs.org/api/modules.html
+[Conventional Commits]: https://www.conventionalcommits.org/
+[devenv]: https://devenv.sh/
+[direnv]: https://direnv.net/
+[ESM]: https://nodejs.org/api/esm.html
+[git-format-staged]: https://github.com/smoothbricks/git-format-staged
+[GitHub Actions]: https://docs.github.com/actions
+[github-actions-oidc]:
+  https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+[Nix]: https://nixos.org/
+[Node.js]: https://nodejs.org/
+[npm]: https://www.npmjs.com/
+[npm-trusted-publishing]: https://docs.npmjs.com/trusted-publishers
+[Nx]: https://nx.dev/
+[nx-release]: https://nx.dev/features/manage-releases
+[`publint`]: https://publint.dev/
+[`sherif`]: https://github.com/QuiiBz/sherif

package/dist/cli.js

@@ -32,6 +32,7 @@ function buildProgram() {
     monorepo
         .command('validate')
         .option('--fail-fast', 'stop after the first failing validation pack')
+        .option('--only-if-new-workspace-package', 'skip validation unless a new workspace package manifest is staged')
         .action(async (options) => {
         const { validateMonorepo } = await import('./monorepo/index.js');
         await validateMonorepo(await findRepoRoot(), options);
@@ -56,51 +57,80 @@ function buildProgram() {
         const { syncBunLockfileVersions } = await import('./monorepo/index.js');
         syncBunLockfileVersions(await findRepoRoot());
     });
-    monorepo.command('list-public-projects').action(async () => {
-        const { listPublicProjects } = await import('./monorepo/index.js');
-        console.log(listPublicProjects(await findRepoRoot()));
+    monorepo
+        .command('list-release-packages')
+        .option('--fail-empty', 'fail when no owned release packages are found')
+        .option('--github-output <path>', 'append projects=<packages> to a GitHub Actions output file')
+        .action(async (options) => {
+        const { listReleasePackagesForNx } = await import('./monorepo/index.js');
+        const packages = listReleasePackagesForNx(await findRepoRoot(), options);
+        if (!options.githubOutput) {
+            console.log(packages);
+        }
     });
     monorepo.command('validate-public-tags').action(async () => {
         const { validatePublicPackageTags } = await import('./monorepo/index.js');
         validatePublicPackageTags(await findRepoRoot());
     });
-    monorepo.command('release-state').action(async () => {
+    const release = program.command('release').description('Version, publish, and create GitHub Releases');
+    release.command('npm-status').action(async () => {
         const { printReleaseState } = await import('./release/index.js');
         await printReleaseState(await findRepoRoot());
     });
-    const release = program.command('release').description('Version, publish, and create GitHub Releases');
+    release
+        .command('repair-pending')
+        .description('Repair incomplete older release commits before releasing the current HEAD')
+        .option('--dry-run [dryRun]', 'run without pushing, publishing, or writing GitHub Releases')
+        .action(async (options) => {
+        const { releaseRepairPending } = await import('./release/index.js');
+        await releaseRepairPending(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
+    });
     release
         .command('version')
         .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-        .option('--dry-run [dryRun]', 'run without writing versions, tags, or pushes')
+        .option('--dry-run [dryRun]', 'run without writing versions or tags')
+        .option('--github-output <path>', 'append mode=<mode> and projects=<packages> to a GitHub Actions output file')
         .action(async (options) => {
         const { releaseVersion } = await import('./release/index.js');
-        await releaseVersion(await findRepoRoot(), { bump: options.bump, dryRun: booleanOption(options.dryRun) });
+        await releaseVersion(await findRepoRoot(), {
+            bump: options.bump,
+            dryRun: booleanOption(options.dryRun),
+            githubOutput: options.githubOutput,
+        });
     });
     release
         .command('publish')
         .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-        .option('--tag <tag>', 'explicit npm dist-tag; must match bump-derived tag')
-        .option('--npm-tag <npmTag>', 'explicit npm dist-tag; must match bump-derived tag')
-        .option('--dry-run [dryRun]', 'run without publishing')
+        .option('--dry-run [dryRun]', 'run without pushing, publishing, or writing GitHub Releases')
         .action(async (options) => {
         const { releasePublish } = await import('./release/index.js');
         await releasePublish(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
     });
     release
-        .command('github-release')
-        .option('--tags <tags>', 'space-separated release tags')
-        .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-        .option('--tag <tag>', 'explicit npm dist-tag; must match bump-derived tag')
-        .option('--npm-tag <npmTag>', 'explicit npm dist-tag; must match bump-derived tag')
-        .option('--dry-run [dryRun]', 'skip GitHub Release writes')
-        .action(async (options) => {
-        const { releaseGithubRelease } = await import('./release/index.js');
-        await releaseGithubRelease(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
+        .command('retag-unpublished')
+        .description('Move unpublished owned release tags to a later commit without bumping versions')
+        .argument('<tag...>', 'owned release tags to move, for example @scope/pkg@1.2.3')
+        .option('--to <ref>', 'commit or ref to move tags to', 'HEAD')
+        .option('--push', 'push moved tags with force-with-lease')
+        .option('--dispatch', 'push moved tags and start publish.yml with bump=auto')
+        .option('--remote <remote>', 'git remote used for pushed tags')
+        .option('--branch <branch>', 'branch used for publish workflow dispatch')
+        .option('--dry-run [dryRun]', 'validate and print the retag operation without mutating refs')
+        .action(async (tags, options) => {
+        const { releaseRetagUnpublished } = await import('./release/index.js');
+        await releaseRetagUnpublished(await findRepoRoot(), {
+            tags,
+            to: options.to,
+            push: options.push === true,
+            dispatch: options.dispatch === true,
+            remote: options.remote,
+            branch: options.branch,
+            dryRun: booleanOption(options.dryRun),
+        });
     });
     release
         .command('trust-publisher')
-        .description('Configure npm trusted publishing for public packages')
+        .description('Configure npm trusted publishing for owned release packages')
         .option('--dry-run [dryRun]', 'show npm trust changes without saving them')
         .option('--otp <otp>', 'npm one-time password for trust operations')
         .option('--skip-login', 'skip npm browser login before configuring trust')

package/dist/lib/devenv.d.ts

@@ -0,0 +1,6 @@
+type EnvSnapshot = Record<string, string>;
+export declare function withDevenvEnv<T>(root: string, runWithEnv: () => Promise<T>): Promise<T>;
+export declare function parseNulEnv(bytes: Uint8Array): EnvSnapshot;
+export declare function mergeDevenvEnv(baseEnv: EnvSnapshot, devenvEnv: EnvSnapshot): EnvSnapshot;
+export {};
+//# sourceMappingURL=devenv.d.ts.map

package/dist/lib/devenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devenv.d.ts","sourceRoot":"","sources":["../../src/lib/devenv.ts"],"names":[],"mappings":"AAMA,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1C,wBAAsB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS7F;AAmBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAoB1D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,GAAG,WAAW,CAExF"}