@smoothbricks/cli 0.1.0 → 0.1.1

package/src/release/index.ts

@@ -1,26 +1,47 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { appendFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { Writable } from 'node:stream';
 import { $ } from 'bun';
+import { withDevenvEnv } from '../lib/devenv.js';
+import { isRecord, stringProperty } from '../lib/json.js';
 import { decode, run, runStatus } from '../lib/run.js';
-import { listPublicPackages, readPackageJson, repositoryInfo } from '../lib/workspace.js';
+import { listReleasePackages, readPackageJson, repositoryInfo } from '../lib/workspace.js';
+import { readPackedPackageJson, validatePackedWorkspaceDependencies } from '../monorepo/packed-manifest.js';
+import {
+  type ReleaseTagRecord as CoreReleaseTagRecord,
+  type ReleaseTarget as CoreReleaseTarget,
+  collectOwnedReleaseTagRecords,
+  type GitReleaseTagInfo,
+  pendingReleaseTargets,
+  releaseTag,
+} from './core.js';
+import { createOrUpdateGithubRelease, renderNxProjectChangelogContents } from './github-release.js';
+import { publishWithAuthDiagnostics } from './npm-auth.js';
+import {
+  completeReleaseAtHead as completeReleaseAtHeadWithShell,
+  type ReleaseCompletionShell,
+  type ReleaseSummary,
+  type ReleaseVersionMode,
+  repairPendingTargets,
+  runReleaseVersion,
+} from './orchestration.js';
+import { type RetagUnpublishedTagUpdate, retagUnpublished } from './retag-unpublished.js';
 
 export interface ReleaseVersionOptions {
   bump: string;
   dryRun?: boolean;
+  githubOutput?: string;
 }
 
 export interface ReleasePublishOptions {
   bump: string;
-  tag?: string;
-  npmTag?: string;
   dryRun?: boolean;
 }
 
-export interface ReleaseGithubOptions extends ReleasePublishOptions {
-  tags?: string;
+export interface ReleaseRepairPendingOptions {
+  dryRun?: boolean;
 }
 
 export interface ReleaseTrustPublisherOptions {
@@ -29,90 +50,98 @@ export interface ReleaseTrustPublisherOptions {
   skipLogin?: boolean;
 }
 
+export interface ReleaseRetagUnpublishedOptions {
+  tags: string[];
+  to?: string;
+  push?: boolean;
+  dispatch?: boolean;
+  dryRun?: boolean;
+  remote?: string;
+  branch?: string;
+}
+
 export async function releaseVersion(root: string, options: ReleaseVersionOptions): Promise<void> {
   const bump = releaseBumpArg(options.bump);
-  const projects = listPublicPackages(root)
-    .map((pkg) => pkg.name)
-    .join(',');
-  const state = await getReleaseState(root);
-  if (state.allPublished) {
-    console.log('Current package versions are already published; skipping version bump.');
-    return;
-  }
-
-  const headBeforeVersioning = await gitHead(root);
-
-  // Nx owns local release mutation: package versions, bun.lock updates, the
-  // release commit, and annotated tags. smoo owns the remote push so retries do
-  // not push an older checkout when Nx skips the release commit.
-  const nxArgs = ['release', 'version'];
-  if (bump !== 'auto') {
-    nxArgs.push(bump);
-  }
-  nxArgs.push(`--projects=${projects}`, '--git-commit=true', '--git-tag=true', '--git-push=false');
-  if (options.dryRun) {
-    nxArgs.push('--dryRun');
-  }
-  await run('nx', nxArgs, root);
-  if (!options.dryRun) {
-    // Guard against future Nx/config regressions that leave release files, such
-    // as bun.lock, outside the release commit after tagging/pushing.
-    await assertCleanGitTree(root);
-    const headAfterVersioning = await gitHead(root);
-    if (headAfterVersioning === headBeforeVersioning) {
-      console.log('Nx did not create a release commit; skipping git push.');
-      return;
-    }
-    await pushReleaseCommit(root);
+  const packages = releasePackages(root);
+  const projects = releasePackageProjects(packages);
+  const result = await runReleaseVersion(
+    {
+      releasePackagesAtHead: () => releasePackagesAtHead(root, packages),
+      ensureLocalReleaseTags: (releasePackages) => ensureLocalReleaseTags(root, releasePackages),
+      gitHead: () => gitHead(root),
+      runNxReleaseVersion: (releaseBump, dryRun) => runNxReleaseVersion(root, projects, releaseBump, dryRun),
+      assertCleanGitTree: () => assertCleanGitTree(root),
+    },
+    { bump, dryRun: options.dryRun === true },
+  );
+  if (result.status === 'already-release-target') {
+    console.log('HEAD is already a release target; publish will complete any missing durable state.');
+  } else if (result.status === 'no-release-needed') {
+    console.log('Nx did not create a release commit; no release needed.');
   }
+  await writeReleaseGithubOutput(options.githubOutput, result.packages, result.mode);
 }
 
 export async function releasePublish(root: string, options: ReleasePublishOptions): Promise<void> {
-  const tag = releaseNpmTagArg(options);
-  const unpublishedPackages = await listUnpublishedPackages(root);
-  if (unpublishedPackages.length === 0) {
-    console.log('Current package versions are already published; skipping npm publish.');
-    return;
-  }
-  // npm package versions are immutable. Publishing only missing name@version
-  // pairs makes auth/network retries idempotent after a partial publish failure.
-  for (const pkg of unpublishedPackages) {
-    await publishPackedPackage(root, pkg, tag, options.dryRun === true);
+  const bump = releaseBumpArg(options.bump);
+  const packages = await releasePackagesAtHead(root, releasePackages(root));
+  if (packages.length === 0) {
+    if (bump === 'auto') {
+      console.log('No release tags found at HEAD; no release to publish.');
+      const summary: ReleaseSummary<ReleasePackage> = {
+        sha: await gitHead(root),
+        dryRun: options.dryRun === true,
+        packages,
+        pushed: false,
+        published: [],
+        alreadyPublished: [],
+        githubReleases: [],
+        rerunRequired: false,
+        noRelease: true,
+      };
+      await writeReleaseSummary(summary);
+      return;
+    }
+    throw new Error('No release tags found at HEAD for current package versions. Run smoo release version first.');
   }
+  const summary = await completeReleaseAtHeadWithShell(
+    releaseCompletionShell(root),
+    packages,
+    options.dryRun === true,
+    await newerCommitsRemain(root),
+  );
+  await writeReleaseSummary(summary);
 }
 
-export async function releaseGithubRelease(root: string, options: ReleaseGithubOptions): Promise<void> {
-  if (options.dryRun) {
-    console.log('Dry run; skipping GitHub Release creation.');
-    return;
-  }
-  const npmTag = releaseNpmTagArg(options);
-  const tags = options.tags ? options.tags.split(/\s+/).filter(Boolean) : await gitTagsAtHead(root);
-  if (tags.length === 0) {
-    throw new Error('No release tags found. Pass --tags or run from a tagged release commit.');
-  }
-  const latestFlag = npmTag === 'latest' ? 'true' : 'false';
-  for (const tag of tags) {
-    const exists = (await runStatus('gh', ['release', 'view', tag], root, true)) === 0;
-    if (exists) {
-      await run('gh', ['release', 'edit', tag, '--title', tag, `--latest=${latestFlag}`], root);
-    } else {
-      await run('gh', ['release', 'create', tag, '--title', tag, '--generate-notes', `--latest=${latestFlag}`], root);
-    }
-  }
+export async function releaseRepairPending(root: string, options: ReleaseRepairPendingOptions): Promise<void> {
+  const branch = await releaseBranch(root);
+  const remote = await releaseRemote(root, branch);
+  console.log(`Repair pending releases: fetching ${remote}/${branch} and tags.`);
+  await fetchReleaseRefs(root, remote, branch);
+  const remoteRef = `${remote}/${branch}`;
+  const restoreRef = (await gitRefExists(root, remoteRef)) ? remoteRef : await gitHead(root);
+  console.log(`Repair pending releases: planning from ${restoreRef}.`);
+  const targets = await listPendingReleaseTargets(root, restoreRef);
+  console.log(
+    targets.length === 0
+      ? 'Repair pending releases: no pending durable state repairs found.'
+      : `Repair pending releases: ${targets.length} release target${targets.length === 1 ? '' : 's'} need repair.`,
+  );
+  const summaries = await repairPendingTargets(releaseRepairShell(root), targets, restoreRef, options.dryRun === true);
+  await writeRepairSummary(summaries, options.dryRun === true);
 }
 
 export async function releaseTrustPublisher(root: string, options: ReleaseTrustPublisherOptions): Promise<void> {
   const repository = githubRepositoryFromRootPackage(root);
   const workflow = 'publish.yml';
-  const packages = listPublicPackages(root);
+  const packages = listReleasePackages(root);
   if (packages.length === 0) {
-    throw new Error('No npm:public packages found.');
+    throw new Error('No owned release packages found.');
   }
 
   if (!options.dryRun) {
     const packageStates = await Promise.all(
-      packages.map(async (pkg) => ((await npmPackageExists(pkg.name)) ? null : pkg.name)),
+      packages.map(async (pkg) => ((await npmPackageExists(root, pkg.name)) ? null : pkg.name)),
     );
     const missingPackages = packageStates.filter((name): name is string => name !== null);
     if (missingPackages.length > 0) {
@@ -128,17 +157,57 @@ export async function releaseTrustPublisher(root: string, options: ReleaseTrustP
     await runLatestNpm(root, ['login', '--auth-type=web']);
   }
 
+  const failedPackages: string[] = [];
   for (const pkg of packages) {
     console.log(`${pkg.name}: trusting GitHub Actions ${repository}/${workflow}`);
     const args = ['trust', 'github', pkg.name, '--file', workflow, '--repo', repository, '--yes'];
     if (options.dryRun) {
       args.push('--dry-run');
     }
-    const otp = options.dryRun ? undefined : (options.otp ?? (await promptForNpmOtp(pkg.name)));
-    await runLatestNpm(root, args, otp ? { NPM_CONFIG_OTP: otp } : undefined);
+    while (true) {
+      const otp = options.dryRun ? undefined : (options.otp ?? (await promptForNpmOtp(pkg.name)));
+      try {
+        await runLatestNpm(root, args, otp ? { NPM_CONFIG_OTP: otp } : undefined);
+        break;
+      } catch (error) {
+        console.error(`${pkg.name}: npm trusted publisher setup failed.`);
+        console.error(error instanceof Error ? error.message : String(error));
+        if (!options.dryRun) {
+          console.error('npm OTP codes are single-use. Generate a fresh OTP before retrying this package.');
+        }
+        if (options.otp || options.dryRun) {
+          failedPackages.push(pkg.name);
+          break;
+        }
+        console.error('Retrying this package. Press Ctrl-C to stop.');
+      }
+    }
+  }
+  if (failedPackages.length > 0) {
+    console.error(`Trusted publishing was not configured for: ${failedPackages.join(', ')}`);
+    if (options.otp) {
+      console.error('Rerun smoo release trust-publisher without --otp to enter a fresh OTP for each failed package.');
+    }
   }
 }
 
+export async function releaseRetagUnpublished(root: string, options: ReleaseRetagUnpublishedOptions): Promise<void> {
+  const toRef = options.to ?? 'HEAD';
+  const dispatch = options.dispatch === true;
+  const push = options.push === true || dispatch;
+  const branch = options.branch ?? (await releaseBranch(root));
+  const remote = options.remote ?? (push ? await releaseRemote(root, branch) : 'origin');
+  await retagUnpublished(releaseRetagShell(root, remote), {
+    tags: options.tags,
+    toRef,
+    push,
+    dispatch,
+    dryRun: options.dryRun === true,
+    branch,
+    workflow: 'publish.yml',
+  });
+}
+
 export async function printReleaseState(root: string): Promise<void> {
   console.log(JSON.stringify(await getReleaseState(root), null, 2));
 }
@@ -148,34 +217,45 @@ interface ReleaseState {
   allPublished: boolean;
 }
 
-type PublicPackage = ReturnType<typeof listPublicPackages>[number];
+type ReleasePackage = ReturnType<typeof listReleasePackages>[number];
+
+type ReleaseTarget = CoreReleaseTarget<ReleasePackage>;
+type ReleaseTagRecord = CoreReleaseTagRecord<ReleasePackage>;
 
 async function getReleaseState(root: string): Promise<ReleaseState> {
-  const packages = listPublicPackages(root);
+  return getReleaseStateForPackages(root, listReleasePackages(root));
+}
+
+async function getReleaseStateForPackages(root: string, packages: ReleasePackage[]): Promise<ReleaseState> {
   const states = await Promise.all(
     packages.map(async (pkg) => {
-      const published = await npmVersionExists(pkg.name, pkg.version);
+      const published = await npmVersionExists(root, pkg.name, pkg.version);
       return { name: pkg.name, version: pkg.version, published };
     }),
   );
   return { packages: states, allPublished: states.every((state) => state.published) };
 }
 
-async function listUnpublishedPackages(root: string): Promise<PublicPackage[]> {
-  const packages = listPublicPackages(root);
+async function listUnpublishedPackages(root: string, packages: ReleasePackage[]): Promise<ReleasePackage[]> {
   const states = await Promise.all(
-    packages.map(async (pkg) => ({ pkg, published: await npmVersionExists(pkg.name, pkg.version) })),
+    packages.map(async (pkg) => ({ pkg, published: await npmVersionExists(root, pkg.name, pkg.version) })),
   );
   return states.filter((state) => !state.published).map((state) => state.pkg);
 }
 
-async function publishPackedPackage(root: string, pkg: PublicPackage, tag: string, dryRun: boolean): Promise<void> {
+async function publishPackedPackage(
+  root: string,
+  pkg: ReleasePackage,
+  tag: string,
+  dryRun: boolean,
+  useBootstrapToken: boolean,
+): Promise<void> {
   const tempDir = await mkdtemp(join(tmpdir(), 'smoo-publish-'));
   const tarball = join(tempDir, `${safeTarballPrefix(pkg.name)}-${pkg.version}.tgz`);
   try {
     console.log(`${pkg.name}@${pkg.version}: packing with bun pm pack`);
     await run('bun', ['pm', 'pack', '--filename', tarball, '--ignore-scripts', '--quiet'], join(root, pkg.path));
-    await assertNoWorkspaceProtocolInTarball(root, tarball, pkg);
+    await assertPackedWorkspaceDependencies(root, tarball, pkg);
     // npm CLI owns authentication here: trusted publishing OIDC when configured,
     // or the temporary NODE_AUTH_TOKEN bootstrap path below before trust exists.
     // Bun still produces the tarball so workspace:* dependencies are resolved the
@@ -184,39 +264,146 @@ async function publishPackedPackage(root: string, pkg: PublicPackage, tag: strin
     if (dryRun) {
       args.push('--dry-run');
     }
-    await runLatestNpmPublish(root, args);
+    await publishWithAuthDiagnostics(
+      pkg,
+      {
+        publish: () => runLatestNpmPublish(root, args, useBootstrapToken),
+        versionExists: () => npmVersionExists(root, pkg.name, pkg.version),
+        log: (message) => console.log(message),
+        error: (message) => console.error(message),
+        appendSummary: async (markdown) => {
+          const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+          if (summaryPath) {
+            await appendFile(summaryPath, `${markdown}\n\n`);
+          }
+        },
+      },
+      {
+        useBootstrapToken,
+        tokenPresent: npmAuthTokenPresent(),
+        repository: githubRepositoryFromRootPackage(root),
+      },
+    );
   } finally {
     await rm(tempDir, { recursive: true, force: true });
   }
 }
 
+function npmAuthTokenPresent(): boolean {
+  return Boolean(process.env.NODE_AUTH_TOKEN || process.env.NPM_TOKEN || process.env.NPM_CONFIG_USERCONFIG);
+}
+
 function safeTarballPrefix(name: string): string {
   return name.replace(/^@/, '').replace(/[^a-zA-Z0-9._-]+/g, '-');
 }
 
-async function assertNoWorkspaceProtocolInTarball(root: string, tarball: string, pkg: PublicPackage): Promise<void> {
-  const result = await $`tar -xOf ${tarball} package/package.json`.cwd(root).quiet().nothrow();
+async function assertPackedWorkspaceDependencies(root: string, tarball: string, pkg: ReleasePackage): Promise<void> {
+  const manifest = await readPackedPackageJson(root, tarball, pkg.name);
+  const failures = validatePackedWorkspaceDependencies(root, pkg, manifest);
+  if (failures.length > 0) {
+    throw new Error(failures.join('\n'));
+  }
+}
+
+function releasePackages(root: string): ReleasePackage[] {
+  const packages = listReleasePackages(root);
+  if (packages.length === 0) {
+    throw new Error('No owned release packages found.');
+  }
+  return packages;
+}
+
+function releasePackageProjects(packages: ReleasePackage[]): string {
+  return packages.map((pkg) => pkg.name).join(',');
+}
+
+async function runNxReleaseVersion(root: string, projects: string, bump: string, dryRun: boolean): Promise<void> {
+  // Nx owns local release mutation: package versions, bun.lock updates, the
+  // release commit, and annotated tags. smoo owns remote publication after the
+  // workflow validates the exact release commit Nx produced.
+  const nxArgs = ['release', 'version'];
+  if (bump !== 'auto') {
+    nxArgs.push(bump);
+  }
+  nxArgs.push(`--projects=${projects}`, '--git-commit=true', '--git-tag=true', '--git-push=false');
+  if (dryRun) {
+    nxArgs.push('--dry-run');
+  }
+  await run('nx', nxArgs, root);
+}
+
+async function releasePackagesAtHead(root: string, packages: ReleasePackage[]): Promise<ReleasePackage[]> {
+  return releasePackagesAtRef(root, packages, 'HEAD');
+}
+
+async function writeReleaseGithubOutput(
+  outputPath: string | undefined,
+  packages: ReleasePackage[],
+  mode: ReleaseVersionMode,
+): Promise<void> {
+  if (!outputPath) {
+    return;
+  }
+  await appendFile(outputPath, `mode=${mode}\nprojects=${releasePackageProjects(packages)}\n`);
+}
+
+async function releasePackagesAtRef(root: string, packages: ReleasePackage[], ref: string): Promise<ReleasePackage[]> {
+  const packagesAtRef = await Promise.all(packages.map(async (pkg) => releasePackageAtRef(root, pkg, ref)));
+  const presentPackages = packagesAtRef.filter((pkg): pkg is ReleasePackage => pkg !== null);
+  const tags = new Set(await gitTagsAtRef(root, ref));
+  const taggedPackages = presentPackages.filter((pkg) => tags.has(releaseTag(pkg)));
+  if (taggedPackages.length > 0) {
+    return taggedPackages;
+  }
+  if (!(await isNxReleaseCommit(root, ref))) {
+    return [];
+  }
+  return releasePackagesChangedAtRef(root, presentPackages, ref);
+}
+
+async function releasePackageAtRef(root: string, pkg: ReleasePackage, ref: string): Promise<ReleasePackage | null> {
+  const version = await packageVersionAtRef(root, pkg.path, ref);
+  return version ? { ...pkg, version } : null;
+}
+
+async function packageVersionAtRef(root: string, packagePath: string, ref: string): Promise<string | null> {
+  const result = await $`git show ${`${ref}:${packagePath}/package.json`}`.cwd(root).quiet().nothrow();
   if (result.exitCode !== 0) {
-    throw new Error(`${pkg.name}: unable to inspect packed package.json before publish.`);
+    return null;
   }
-  const manifest = decode(result.stdout);
-  if (manifest.includes('workspace:')) {
-    throw new Error(`${pkg.name}: packed package.json still contains workspace: dependency references.`);
+  try {
+    const parsed = JSON.parse(decode(result.stdout));
+    return isRecord(parsed) ? stringProperty(parsed, 'version') : null;
+  } catch {
+    return null;
   }
 }
 
-async function npmVersionExists(name: string, version: string): Promise<boolean> {
-  const result = await $`bun pm view ${`${name}@${version}`} version`.cwd(process.cwd()).quiet().nothrow();
-  return result.exitCode === 0 && decode(result.stdout).trim() === version;
+async function isNxReleaseCommit(root: string, ref: string): Promise<boolean> {
+  const result = await $`git show -s --format=%s ${ref}`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0 && decode(result.stdout).trim() === 'chore(release): publish';
 }
 
-async function npmPackageExists(name: string): Promise<boolean> {
-  const result = await $`bun pm view ${name} name`.cwd(process.cwd()).quiet().nothrow();
-  return result.exitCode === 0;
+async function releasePackagesChangedAtRef(
+  root: string,
+  packages: ReleasePackage[],
+  ref: string,
+): Promise<ReleasePackage[]> {
+  if (!(await gitRefExists(root, `${ref}^`))) {
+    return packages;
+  }
+  const changed: ReleasePackage[] = [];
+  for (const pkg of packages) {
+    const previousVersion = await packageVersionAtRef(root, pkg.path, `${ref}^`);
+    if (previousVersion !== pkg.version) {
+      changed.push(pkg);
+    }
+  }
+  return changed;
 }
 
-async function gitTagsAtHead(root: string): Promise<string[]> {
-  const result = await $`git tag --points-at HEAD`.cwd(root).quiet().nothrow();
+async function gitTagsAtRef(root: string, ref: string): Promise<string[]> {
+  const result = await $`git tag --points-at ${ref}`.cwd(root).quiet().nothrow();
   if (result.exitCode !== 0) {
     return [];
   }
@@ -226,6 +413,375 @@ async function gitTagsAtHead(root: string): Promise<string[]> {
     .filter(Boolean);
 }
 
+async function previousReleaseTag(root: string, pkg: ReleasePackage, currentTag: string): Promise<string | null> {
+  const result = await $`git tag --list ${`${pkg.name}@*`} --sort=-v:refname --merged ${currentTag}`
+    .cwd(root)
+    .quiet()
+    .nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error(`Unable to list release tags for ${pkg.name}.`);
+  }
+  return (
+    decode(result.stdout)
+      .split('\n')
+      .map((tag) => tag.trim())
+      .find((tag) => tag && tag !== currentTag) ?? null
+  );
+}
+
+async function ensureLocalReleaseTags(root: string, packages: ReleasePackage[]): Promise<void> {
+  for (const pkg of packages) {
+    const tag = releaseTag(pkg);
+    if (await gitRefExists(root, `refs/tags/${tag}`)) {
+      if (!(await gitTagPointsAt(root, tag, 'HEAD'))) {
+        throw new Error(`Release tag ${tag} exists but does not point at HEAD.`);
+      }
+      continue;
+    }
+    await run('git', ['tag', '-a', tag, '-m', tag, 'HEAD'], root);
+  }
+}
+
+async function pushReleaseRefs(root: string, packages: ReleasePackage[]): Promise<boolean> {
+  const branch = await releaseBranch(root);
+  const remote = await releaseRemote(root, branch);
+  await fetchReleaseRefs(root, remote, branch);
+  await ensureLocalReleaseTags(root, packages);
+  const refspecs: string[] = [];
+  const remoteRef = `${remote}/${branch}`;
+  const head = await gitHead(root);
+  if (!(await gitRefExists(root, remoteRef)) || !(await gitIsAncestor(root, head, remoteRef))) {
+    refspecs.push(`HEAD:refs/heads/${branch}`);
+  }
+  for (const pkg of packages) {
+    const tag = releaseTag(pkg);
+    if (!(await remoteReleaseTagExists(root, remote, tag))) {
+      refspecs.push(`refs/tags/${tag}:refs/tags/${tag}`);
+    }
+  }
+  if (refspecs.length === 0) {
+    console.log('Release branch and tags are already present on the remote.');
+    return false;
+  }
+  await run('git', ['push', '--atomic', remote, ...refspecs], root);
+  return true;
+}
+
+function releaseCompletionShell(root: string): ReleaseCompletionShell<ReleasePackage> {
+  return {
+    gitHead: () => gitHead(root),
+    pushReleaseRefs: (packages) => pushReleaseRefs(root, packages),
+    listNpmMissingPackages: (packages) => listUnpublishedPackages(root, packages),
+    buildReleaseCandidate: (packages) => buildReleaseCandidate(root, packages),
+    publishPackage: async (pkg, distTag, dryRun) => {
+      const packageExists = dryRun ? true : await npmPackageExists(root, pkg.name);
+      await publishPackedPackage(root, pkg, distTag, dryRun, !dryRun && !packageExists);
+    },
+    listGithubMissingPackages: (packages) => listMissingGithubReleasePackages(root, packages),
+    createGithubRelease: (pkg, dryRun) => createGithubRelease(root, pkg, dryRun),
+  };
+}
+
+function releaseRepairShell(root: string): ReleaseCompletionShell<ReleasePackage> & {
+  checkout(ref: string): Promise<void>;
+  withDevenvEnv<T>(runWithEnv: () => Promise<T>): Promise<T>;
+  beforeRepairTarget(target: ReleaseTarget): void;
+  afterRepairTarget(target: ReleaseTarget): void;
+} {
+  return {
+    ...releaseCompletionShell(root),
+    checkout: (ref) => run('git', ['switch', '--detach', ref], root),
+    withDevenvEnv: (runWithEnv) => withDevenvEnv(root, runWithEnv),
+    beforeRepairTarget: (target) => {
+      console.log(`::group::Repair pending release ${target.sha.slice(0, 12)} (${packageSummary(target.packages)})`);
+    },
+    afterRepairTarget: () => {
+      console.log('::endgroup::');
+    },
+  };
+}
+
+function releaseRetagShell(root: string, remote: string) {
+  return {
+    listReleasePackages: () => releasePackages(root),
+    resolveRef: (ref: string) => gitSha(root, ref),
+    resolveDispatchRef: (branch: string) => remoteBranchSha(root, remote, branch),
+    packageVersionAtRef: (packagePath: string, ref: string) => packageVersionAtRef(root, packagePath, ref),
+    npmVersionExists: (name: string, version: string) => npmVersionExists(root, name, version),
+    githubReleaseExists: (tag: string) => githubReleaseExists(root, tag),
+    remoteTagObject: (tag: string) => remoteReleaseTagObject(root, remote, tag),
+    createOrMoveTag: (tag: string, ref: string) => run('git', ['tag', '-fa', tag, '-m', tag, ref], root),
+    pushTags: (updates: RetagUnpublishedTagUpdate<ReleasePackage>[]) => pushRetaggedReleaseTags(root, remote, updates),
+    dispatchPublishWorkflow: (workflow: string, branch: string) =>
+      run('gh', ['workflow', 'run', workflow, '--ref', branch, '-f', 'bump=auto', '-f', 'dry_run=false'], root),
+    log: (message: string) => console.log(message),
+  };
+}
+
+async function listPendingReleaseTargets(root: string, ref: string): Promise<ReleaseTarget[]> {
+  const head = await gitHead(root);
+  return pendingReleaseTargets(await listOwnedReleaseTagRecords(root, ref), head);
+}
+
+async function listOwnedReleaseTagRecords(root: string, ref: string): Promise<ReleaseTagRecord[]> {
+  const tags = await gitReleaseTagsByCreatorDate(root);
+  console.log(`Repair pending releases: scanning ${tags.length} local tag${tags.length === 1 ? '' : 's'}.`);
+  return collectOwnedReleaseTagRecords(releasePackages(root), ref, {
+    listReleaseTagsByCreatorDate: async () => tags,
+    isAncestor: (ancestor, descendant) => gitIsAncestor(root, ancestor, descendant),
+    packageVersionAtRef: (packagePath, tagRef) => packageVersionAtRef(root, packagePath, tagRef),
+    durableTagState: (pkg, tag) => durableReleaseTagState(root, pkg, tag),
+  });
+}
+
+async function durableReleaseTagState(root: string, pkg: Pick<ReleasePackage, 'name' | 'version'>, tag: string) {
+  const packageVersion = `${pkg.name}@${pkg.version}`;
+  const start = Date.now();
+  console.log(`${packageVersion}: checking durable state (npm + GitHub Release ${tag}).`);
+  const [npmPublished, githubReleasePresent] = await Promise.all([
+    npmVersionExists(root, pkg.name, pkg.version),
+    githubReleaseExists(root, tag),
+  ]);
+  console.log(
+    `${packageVersion}: durable state npm=${yesNo(npmPublished)} github=${yesNo(githubReleasePresent)} (${Date.now() - start}ms).`,
+  );
+  return { npmPublished, githubReleaseExists: githubReleasePresent };
+}
+
+async function gitReleaseTagsByCreatorDate(root: string): Promise<GitReleaseTagInfo[]> {
+  const result =
+    await $`git for-each-ref --sort=-creatordate --format=${'%(refname:short)%09%(creatordate:unix)%09%(*objectname)%09%(objectname)'} refs/tags`
+      .cwd(root)
+      .quiet()
+      .nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error('Unable to list release tags by creator date.');
+  }
+  return decode(result.stdout)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [name, timestampText, peeledSha, objectSha] = line.split('\t');
+      const timestamp = Number(timestampText);
+      const sha = peeledSha || objectSha;
+      if (!name || !sha || !Number.isSafeInteger(timestamp)) {
+        throw new Error(`Unable to parse release tag ref: ${line}`);
+      }
+      return { name, sha, timestamp };
+    });
+}
+
+async function buildReleaseCandidate(root: string, packages: ReleasePackage[]): Promise<void> {
+  await run('nx', ['run-many', '-t', 'build', `--projects=${releasePackageProjects(packages)}`], root);
+}
+
+async function listMissingGithubReleasePackages(root: string, packages: ReleasePackage[]): Promise<ReleasePackage[]> {
+  return (
+    await Promise.all(packages.map(async (pkg) => ((await githubReleaseExists(root, releaseTag(pkg))) ? null : pkg)))
+  ).filter((pkg): pkg is ReleasePackage => pkg !== null);
+}
+
+async function createGithubRelease(root: string, pkg: ReleasePackage, dryRun: boolean): Promise<void> {
+  const currentTag = releaseTag(pkg);
+  console.log(`${pkg.name}@${pkg.version}: rendering GitHub Release notes for ${currentTag}.`);
+  console.log(`GitHub release auth: ${envPresence('GH_TOKEN')}, ${envPresence('GITHUB_TOKEN')}.`);
+  if (!dryRun) {
+    await assertRemoteTagExists(root, currentTag);
+  }
+  const previousTag = await previousReleaseTag(root, pkg, currentTag);
+  if (dryRun) {
+    await renderNxProjectChangelogContents({ root, pkg, previousTag, dryRun });
+    return;
+  }
+  const contents = await renderNxProjectChangelogContents({ root, pkg, previousTag, dryRun });
+  await createOrUpdateGithubRelease(pkg, contents, {
+    githubReleaseExists: (tag) => githubReleaseExists(root, tag),
+    runGhRelease: (args) => run('gh', args, root),
+    log: (message) => console.log(message),
+  });
+}
+
+function envPresence(name: string): string {
+  return `${name}=${process.env[name] ? 'present' : 'missing'}`;
+}
+
+function yesNo(value: boolean): string {
+  return value ? 'yes' : 'no';
+}
+
+async function newerCommitsRemain(root: string): Promise<boolean> {
+  const branch = await releaseBranch(root);
+  const remote = await releaseRemote(root, branch);
+  await fetchReleaseRefs(root, remote, branch);
+  const remoteRef = `${remote}/${branch}`;
+  if (!(await gitRefExists(root, remoteRef))) {
+    return false;
+  }
+  const head = await gitHead(root);
+  return head !== (await gitSha(root, remoteRef)) && (await gitIsAncestor(root, head, remoteRef));
+}
+
+async function writeReleaseSummary(summary: ReleaseSummary<ReleasePackage>): Promise<void> {
+  const shortSha = summary.sha.slice(0, 12);
+  const lines = [
+    '## Release Summary',
+    '',
+    `- Commit: \`${shortSha}\``,
+    `- Mode: ${summary.dryRun ? 'dry run' : 'release'}`,
+  ];
+  if (summary.noRelease) {
+    lines.push('- Result: no release tags found at HEAD');
+  } else {
+    lines.push(`- Packages: ${packageSummary(summary.packages)}`);
+    lines.push(`- Git refs pushed: ${summary.pushed ? 'yes' : 'already current'}`);
+    lines.push(`- npm published: ${packageSummary(summary.published)}`);
+    lines.push(`- npm already published: ${packageSummary(summary.alreadyPublished)}`);
+    lines.push(`- GitHub Releases created/updated: ${packageSummary(summary.githubReleases)}`);
+  }
+  if (summary.rerunRequired) {
+    const message = 'A previous incomplete release was repaired; newer commits remain. Run Publish again.';
+    console.log(`::warning::${message}`);
+    lines.push(`- Warning: ${message}`);
+  }
+  const text = `${lines.join('\n')}\n`;
+  console.log(text.trimEnd());
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    await appendFile(summaryPath, `${text}\n`);
+  }
+}
+
+async function writeRepairSummary(summaries: Array<ReleaseSummary<ReleasePackage>>, dryRun: boolean): Promise<void> {
+  const lines = ['## Pending Release Repair', '', `- Mode: ${dryRun ? 'dry run' : 'release'}`];
+  if (summaries.length === 0) {
+    lines.push('- Result: no pending releases needed repair');
+  } else {
+    for (const summary of summaries) {
+      lines.push(`- Repaired \`${summary.sha.slice(0, 12)}\`: ${packageSummary(summary.packages)}`);
+    }
+  }
+  const text = `${lines.join('\n')}\n`;
+  console.log(text.trimEnd());
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    await appendFile(summaryPath, `${text}\n`);
+  }
+}
+
+function packageSummary(packages: ReleasePackage[]): string {
+  if (packages.length === 0) {
+    return 'none';
+  }
+  return packages.map((pkg) => `${pkg.name}@${pkg.version}`).join(', ');
+}
+
+async function fetchReleaseRefs(root: string, remote: string, branch: string): Promise<void> {
+  await run('git', ['fetch', '--tags', remote, branch], root);
+}
+
+async function gitRefExists(root: string, ref: string): Promise<boolean> {
+  const result = await $`git rev-parse --verify ${ref}`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0;
+}
+
+async function gitIsAncestor(root: string, ancestor: string, descendant: string): Promise<boolean> {
+  const result = await $`git merge-base --is-ancestor ${ancestor} ${descendant}`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0;
+}
+
+async function gitSha(root: string, ref: string): Promise<string> {
+  const result = await $`git rev-parse ${ref}`.cwd(root).quiet().nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error(`Unable to resolve git ref ${ref}.`);
+  }
+  return decode(result.stdout).trim();
+}
+
+async function gitTagPointsAt(root: string, tag: string, ref: string): Promise<boolean> {
+  return (await gitCommitForTag(root, tag)) === (await gitSha(root, ref));
+}
+
+async function gitCommitForTag(root: string, tag: string): Promise<string> {
+  const result = await $`git rev-list -n 1 ${tag}`.cwd(root).quiet().nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error(`Unable to resolve release tag ${tag}.`);
+  }
+  return decode(result.stdout).trim();
+}
+
+async function remoteReleaseTagExists(root: string, remote: string, tag: string): Promise<boolean> {
+  const result = await $`git ls-remote --exit-code --tags ${remote} ${`refs/tags/${tag}`}`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0;
+}
+
+async function remoteReleaseTagObject(root: string, remote: string, tag: string): Promise<string | null> {
+  const result = await $`git ls-remote --exit-code --tags ${remote} ${`refs/tags/${tag}`}`.cwd(root).quiet().nothrow();
+  if (result.exitCode === 2) {
+    return null;
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(`Unable to inspect remote release tag ${tag} on ${remote}.`);
+  }
+  const [object] = decode(result.stdout).trim().split('\t');
+  if (!object) {
+    throw new Error(`Unable to parse remote release tag ${tag} on ${remote}.`);
+  }
+  return object;
+}
+
+async function remoteBranchSha(root: string, remote: string, branch: string): Promise<string | null> {
+  const result = await $`git ls-remote --exit-code --heads ${remote} ${`refs/heads/${branch}`}`
+    .cwd(root)
+    .quiet()
+    .nothrow();
+  if (result.exitCode === 2) {
+    return null;
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(`Unable to inspect remote branch ${branch} on ${remote}.`);
+  }
+  const [sha] = decode(result.stdout).trim().split('\t');
+  if (!sha) {
+    throw new Error(`Unable to parse remote branch ${branch} on ${remote}.`);
+  }
+  return sha;
+}
+
+async function pushRetaggedReleaseTags(
+  root: string,
+  remote: string,
+  updates: Array<RetagUnpublishedTagUpdate<ReleasePackage>>,
+): Promise<void> {
+  const leases = updates.map(
+    (update) => `--force-with-lease=refs/tags/${update.tag}:${update.expectedRemoteObject ?? ''}`,
+  );
+  const refspecs = updates.map((update) => `refs/tags/${update.tag}:refs/tags/${update.tag}`);
+  await run('git', ['push', '--atomic', ...leases, remote, ...refspecs], root);
+}
+
+async function githubReleaseExists(root: string, tag: string): Promise<boolean> {
+  return (await runStatus('gh', ['release', 'view', tag, '--json', 'tagName'], root, true)) === 0;
+}
+
+async function assertRemoteTagExists(root: string, tag: string): Promise<void> {
+  const branch = await releaseBranch(root);
+  const remote = await releaseRemote(root, branch);
+  if (!(await remoteReleaseTagExists(root, remote, tag))) {
+    throw new Error(`Release tag ${tag} is not present on remote ${remote}. Run smoo release version first.`);
+  }
+}
+
+async function npmVersionExists(root: string, name: string, version: string): Promise<boolean> {
+  const result = await $`bun pm view ${`${name}@${version}`} version`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0 && decode(result.stdout).trim() === version;
+}
+
+async function npmPackageExists(root: string, name: string): Promise<boolean> {
+  const result = await $`bun pm view ${name} name`.cwd(root).quiet().nothrow();
+  return result.exitCode === 0;
+}
+
 async function assertCleanGitTree(root: string): Promise<void> {
   const result = await $`git status --porcelain --untracked-files=no`.cwd(root).quiet().nothrow();
   if (result.exitCode !== 0) {
@@ -245,12 +801,6 @@ async function gitHead(root: string): Promise<string> {
   return decode(result.stdout).trim();
 }
 
-async function pushReleaseCommit(root: string): Promise<void> {
-  const branch = await releaseBranch(root);
-  const remote = await releaseRemote(root, branch);
-  await run('git', ['push', '--follow-tags', '--atomic', remote, `HEAD:refs/heads/${branch}`], root);
-}
-
 async function releaseBranch(root: string): Promise<string> {
   const githubBranch = process.env.GITHUB_REF_NAME?.trim();
   if (githubBranch) {
@@ -304,19 +854,6 @@ function releaseBumpArg(bump = 'auto'): string {
   return bump;
 }
 
-function releaseNpmTagArg(options: ReleasePublishOptions): string {
-  const bump = releaseBumpArg(options.bump);
-  const derivedTag = bump === 'prerelease' ? 'next' : 'latest';
-  const explicitTag = options.tag ?? options.npmTag;
-  if (!explicitTag) {
-    return derivedTag;
-  }
-  if (explicitTag !== derivedTag) {
-    throw new Error(`--bump ${bump} publishes with npm dist-tag ${derivedTag}, not ${explicitTag}.`);
-  }
-  return explicitTag;
-}
-
 function githubRepositoryFromRootPackage(root: string): string {
   const pkg = readPackageJson(join(root, 'package.json'));
   const repository = pkg ? repositoryInfo(pkg.json) : null;
@@ -350,9 +887,18 @@ async function runLatestNpm(root: string, npmArgs: string[], env?: Record<string
   await run('nix', ['shell', 'nixpkgs#nodejs_latest', '-c', 'npm', ...npmArgs], root, env);
 }
 
-async function runLatestNpmPublish(root: string, npmArgs: string[]): Promise<void> {
+async function runLatestNpmPublish(root: string, npmArgs: string[], useBootstrapToken: boolean): Promise<void> {
+  if (!useBootstrapToken) {
+    await runLatestNpm(root, npmArgs, { NODE_AUTH_TOKEN: '', NPM_TOKEN: '' });
+    return;
+  }
   const token = process.env.NODE_AUTH_TOKEN || process.env.NPM_TOKEN;
   if (!token || process.env.NPM_CONFIG_USERCONFIG) {
+    if (!token && !process.env.NPM_CONFIG_USERCONFIG) {
+      throw new Error(
+        'First publish for a package requires NODE_AUTH_TOKEN or NPM_TOKEN until trusted publishing exists.',
+      );
+    }
     await runLatestNpm(root, npmArgs);
     return;
   }