@smoothbricks/cli 0.1.0 → 0.1.1

package/src/release/__tests__/github-release.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'bun:test';
+import { readFile } from 'node:fs/promises';
+import type { ReleasePackageInfo } from '../core.js';
+import {
+  createOrUpdateGithubRelease,
+  type GithubReleaseWriteShell,
+  nxProjectChangelogArgs,
+  projectChangelogContents,
+} from '../github-release.js';
+
+const stable: ReleasePackageInfo = { name: '@scope/pkg', path: 'packages/pkg', version: '1.2.3' };
+const prerelease: ReleasePackageInfo = { name: '@scope/pkg', path: 'packages/pkg', version: '2.0.0-beta.1' };
+
+describe('GitHub release helpers', () => {
+  it('configures the Nx changelog API for render-only project changelogs', () => {
+    expect(nxProjectChangelogArgs(stable, '@scope/pkg@1.2.2', false)).toEqual({
+      version: '1.2.3',
+      projects: ['@scope/pkg'],
+      gitCommit: false,
+      gitTag: false,
+      gitPush: false,
+      stageChanges: false,
+      createRelease: false,
+      deleteVersionPlans: false,
+      dryRun: false,
+      from: '@scope/pkg@1.2.2',
+    });
+  });
+
+  it('marks the Nx changelog request as a first release when there is no previous tag', () => {
+    expect(nxProjectChangelogArgs(stable, null, true)).toEqual({
+      version: '1.2.3',
+      projects: ['@scope/pkg'],
+      gitCommit: false,
+      gitTag: false,
+      gitPush: false,
+      stageChanges: false,
+      createRelease: false,
+      deleteVersionPlans: false,
+      dryRun: true,
+      firstRelease: true,
+    });
+  });
+
+  it('extracts the generated Nx project changelog body', () => {
+    expect(
+      projectChangelogContents(
+        {
+          projectChangelogs: {
+            '@scope/pkg': { contents: 'generated release notes' },
+          },
+        },
+        '@scope/pkg',
+      ),
+    ).toBe('generated release notes');
+  });
+
+  it('fails when Nx omits the requested project changelog', () => {
+    expect(() => projectChangelogContents({ projectChangelogs: {} }, '@scope/pkg')).toThrow(
+      'Nx did not generate a project changelog for @scope/pkg.',
+    );
+  });
+
+  it('creates a missing stable GitHub Release from the generated notes file', async () => {
+    const shell = new RecordingGithubReleaseShell(false);
+
+    await createOrUpdateGithubRelease(stable, 'stable notes', shell);
+
+    expect(shell.existsQueries).toEqual(['@scope/pkg@1.2.3']);
+    expect(shell.notes).toEqual(['stable notes']);
+    expect(shell.logs).toEqual(['@scope/pkg@1.2.3: creating GitHub Release for @scope/pkg@1.2.3.']);
+    const command = onlyCommand(shell.commands);
+    expect(command.slice(0, 6)).toEqual([
+      'release',
+      'create',
+      '@scope/pkg@1.2.3',
+      '--title',
+      '@scope/pkg@1.2.3',
+      '--notes-file',
+    ]);
+    expect(command).toContain('--verify-tag');
+    expect(command).toContain('--latest=true');
+    expect(command).not.toContain('--prerelease');
+  });
+
+  it('edits an existing prerelease and prevents it from becoming latest', async () => {
+    const shell = new RecordingGithubReleaseShell(true);
+
+    await createOrUpdateGithubRelease(prerelease, 'prerelease notes', shell);
+
+    expect(shell.existsQueries).toEqual(['@scope/pkg@2.0.0-beta.1']);
+    expect(shell.notes).toEqual(['prerelease notes']);
+    expect(shell.logs).toEqual(['@scope/pkg@2.0.0-beta.1: updating GitHub Release for @scope/pkg@2.0.0-beta.1.']);
+    const command = onlyCommand(shell.commands);
+    expect(command.slice(0, 6)).toEqual([
+      'release',
+      'edit',
+      '@scope/pkg@2.0.0-beta.1',
+      '--title',
+      '@scope/pkg@2.0.0-beta.1',
+      '--notes-file',
+    ]);
+    expect(command).toContain('--verify-tag');
+    expect(command).toContain('--latest=false');
+    expect(command).toContain('--prerelease');
+  });
+});
+
+class RecordingGithubReleaseShell implements GithubReleaseWriteShell {
+  readonly existsQueries: string[] = [];
+  readonly commands: string[][] = [];
+  readonly notes: string[] = [];
+  readonly logs: string[] = [];
+
+  constructor(private readonly releaseExists: boolean) {}
+
+  async githubReleaseExists(tag: string): Promise<boolean> {
+    this.existsQueries.push(tag);
+    return this.releaseExists;
+  }
+
+  async runGhRelease(args: string[]): Promise<void> {
+    this.commands.push(args);
+    const notesFileIndex = args.indexOf('--notes-file') + 1;
+    const notesFile = args[notesFileIndex];
+    if (!notesFile) {
+      throw new Error(`Missing --notes-file in gh release command: ${args.join(' ')}`);
+    }
+    this.notes.push(await readFile(notesFile, 'utf8'));
+  }
+
+  log(message: string): void {
+    this.logs.push(message);
+  }
+}
+
+function onlyCommand(commands: string[][]): string[] {
+  expect(commands).toHaveLength(1);
+  const command = commands[0];
+  if (!command) {
+    throw new Error('Expected one gh command.');
+  }
+  return command;
+}

package/src/release/__tests__/helpers/fixture-repo.ts

@@ -0,0 +1,113 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { $ } from 'bun';
+import type { GitReleaseTagInfo } from '../../core.js';
+
+export async function withFixtureRepo(fn: (root: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(join(tmpdir(), 'smoo-release-test-'));
+  try {
+    await git(root, ['init', '-b', 'main']);
+    await git(root, ['config', 'user.name', 'Test User']);
+    await git(root, ['config', 'user.email', 'test@example.com']);
+    await fn(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+export async function writeWorkspace(root: string): Promise<void> {
+  await symlink(join(import.meta.dir, '../../../../../../node_modules'), join(root, 'node_modules'), 'dir');
+  await writeFile(
+    join(root, 'package.json'),
+    `${JSON.stringify({ name: 'fixture', private: true, workspaces: ['packages/*'] }, null, 2)}\n`,
+  );
+  await writeFile(
+    join(root, 'nx.json'),
+    `${JSON.stringify({ targetDefaults: { build: { cache: true, outputs: ['{projectRoot}/dist'] } } }, null, 2)}\n`,
+  );
+}
+
+export async function writePackage(root: string, name: string, packagePath: string, version: string): Promise<void> {
+  await mkdir(join(root, packagePath), { recursive: true });
+  await writeFile(join(root, packagePath, 'package.json'), `${JSON.stringify({ name, version }, null, 2)}\n`);
+}
+
+export async function writeBuildablePackage(
+  root: string,
+  name: string,
+  packagePath: string,
+  version = '1.0.0',
+): Promise<void> {
+  await mkdir(join(root, packagePath), { recursive: true });
+  await writeFile(
+    join(root, packagePath, 'package.json'),
+    `${JSON.stringify(
+      {
+        name,
+        version,
+        nx: {
+          targets: {
+            build: {
+              executor: 'nx:run-commands',
+              options: { command: "mkdir -p dist && echo '{}' > dist/index.js", cwd: packagePath },
+            },
+          },
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+export async function git(root: string, args: string[], env?: Record<string, string>): Promise<void> {
+  await $`git ${args}`
+    .cwd(root)
+    .env(env ?? {})
+    .quiet();
+}
+
+export async function gitOutput(root: string, args: string[]): Promise<string> {
+  const result = await $`git ${args}`.cwd(root).quiet();
+  return new TextDecoder().decode(result.stdout).trim();
+}
+
+export async function tag(root: string, tagName: string, date: string): Promise<void> {
+  await git(root, ['tag', '-a', tagName, '-m', tagName], { GIT_COMMITTER_DATE: date });
+}
+
+export 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();
+  return new TextDecoder()
+    .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 };
+    });
+}
+
+export 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;
+}
+
+export 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) {
+    return null;
+  }
+  const parsed = JSON.parse(new TextDecoder().decode(result.stdout));
+  return typeof parsed.version === 'string' ? parsed.version : null;
+}

package/src/release/__tests__/npm-auth.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'bun:test';
+import type { ReleasePackageInfo } from '../core.js';
+import {
+  type NpmPublishDiagnosticShell,
+  npmPublishAuthFailureMarkdown,
+  npmPublishAuthFailureMessage,
+  publishWithAuthDiagnostics,
+} from '../npm-auth.js';
+
+const pkg: Pick<ReleasePackageInfo, 'name' | 'version'> = { name: '@scope/pkg', version: '1.2.3' };
+
+describe('npm publish auth diagnostics', () => {
+  it('explains trusted publishing setup when an existing package publish is unauthenticated', () => {
+    const message = npmPublishAuthFailureMessage(pkg, {
+      useBootstrapToken: false,
+      tokenPresent: true,
+      repository: 'smoothbricks/codebase',
+    });
+    const markdown = npmPublishAuthFailureMarkdown(pkg, {
+      useBootstrapToken: false,
+      tokenPresent: true,
+      repository: 'smoothbricks/codebase',
+    });
+
+    expect(message).toContain('🚨 npm publish authentication failed for @scope/pkg@1.2.3');
+    expect(message).toContain('smoo release trust-publisher');
+    expect(message).toContain('NODE_AUTH_TOKEN/NPM_TOKEN is set but unused');
+    expect(message).toContain('repository: smoothbricks/codebase');
+    expect(message).toContain('workflow: publish.yml');
+    expect(markdown).toContain('## 🚨 npm Publish Authentication Failed');
+    expect(markdown).toContain('Run locally: `smoo release trust-publisher`');
+    expect(markdown).toContain('repository `smoothbricks/codebase` and workflow `publish.yml`');
+  });
+
+  it('explains the bootstrap token path for first package publishes', () => {
+    const message = npmPublishAuthFailureMessage(pkg, { useBootstrapToken: true, tokenPresent: false });
+    const markdown = npmPublishAuthFailureMarkdown(pkg, { useBootstrapToken: true, tokenPresent: false });
+
+    expect(message).toContain('temporary npm automation token');
+    expect(message).toContain('NODE_AUTH_TOKEN/NPM_TOKEN is not set');
+    expect(message).toContain('After the first successful publish, run:');
+    expect(message).toContain('smoo release trust-publisher');
+    expect(markdown).toContain('Add a temporary `NPM_TOKEN` repository secret');
+    expect(markdown).toContain('After the first successful publish, run `smoo release trust-publisher`');
+  });
+
+  it('reports trusted-publishing guidance and writes it to the publish summary after existing package auth failure', async () => {
+    const shell = new RecordingPublishShell({ publishFails: true });
+
+    await expect(
+      publishWithAuthDiagnostics(pkg, shell, {
+        useBootstrapToken: false,
+        tokenPresent: true,
+        repository: 'smoothbricks/codebase',
+      }),
+    ).rejects.toThrow('@scope/pkg@1.2.3: npm publish authentication failed');
+
+    expect(shell.errors).toHaveLength(1);
+    expect(shell.errors[0]).toContain('🚨 npm publish authentication failed for @scope/pkg@1.2.3');
+    expect(shell.errors[0]).toContain('NODE_AUTH_TOKEN/NPM_TOKEN is set but unused');
+    expect(shell.errors[0]).toContain('smoo release trust-publisher');
+    expect(shell.errors[0]).toContain('repository: smoothbricks/codebase');
+    expect(shell.summaries).toHaveLength(1);
+    expect(shell.summaries[0]).toContain('## 🚨 npm Publish Authentication Failed');
+    expect(shell.summaries[0]).toContain('Run locally: `smoo release trust-publisher`');
+    expect(shell.logs).toEqual([]);
+  });
+
+  it('reports bootstrap token guidance and writes it to the publish summary after first-publish auth failure', async () => {
+    const shell = new RecordingPublishShell({ publishFails: true });
+
+    await expect(
+      publishWithAuthDiagnostics(pkg, shell, { useBootstrapToken: true, tokenPresent: false }),
+    ).rejects.toThrow('@scope/pkg@1.2.3: npm publish authentication failed');
+
+    expect(shell.errors).toHaveLength(1);
+    expect(shell.errors[0]).toContain('temporary npm automation token');
+    expect(shell.errors[0]).toContain('NODE_AUTH_TOKEN/NPM_TOKEN is not set');
+    expect(shell.errors[0]).toContain('smoo release trust-publisher');
+    expect(shell.summaries).toHaveLength(1);
+    expect(shell.summaries[0]).toContain('Add a temporary `NPM_TOKEN` repository secret');
+    expect(shell.logs).toEqual([]);
+  });
+
+  it('continues without auth warning when the package version appears on npm after publish failure', async () => {
+    const shell = new RecordingPublishShell({ publishFails: true, versionVisibleAfterFailure: true });
+
+    await publishWithAuthDiagnostics(pkg, shell, { useBootstrapToken: false, tokenPresent: true });
+
+    expect(shell.errors).toEqual([]);
+    expect(shell.summaries).toEqual([]);
+    expect(shell.logs).toEqual(['@scope/pkg@1.2.3: publish result already visible on npm; continuing.']);
+  });
+});
+
+class RecordingPublishShell implements NpmPublishDiagnosticShell {
+  readonly logs: string[] = [];
+  readonly errors: string[] = [];
+  readonly summaries: string[] = [];
+  private readonly publishFails: boolean;
+  private readonly versionVisibleAfterFailure: boolean;
+
+  constructor(options: { publishFails: boolean; versionVisibleAfterFailure?: boolean }) {
+    this.publishFails = options.publishFails;
+    this.versionVisibleAfterFailure = options.versionVisibleAfterFailure === true;
+  }
+
+  async publish(): Promise<void> {
+    if (this.publishFails) {
+      throw new Error('ENEEDAUTH');
+    }
+  }
+
+  async versionExists(): Promise<boolean> {
+    return this.versionVisibleAfterFailure;
+  }
+
+  log(message: string): void {
+    this.logs.push(message);
+  }
+
+  error(message: string): void {
+    this.errors.push(message);
+  }
+
+  async appendSummary(markdown: string): Promise<void> {
+    this.summaries.push(markdown);
+  }
+}

package/src/release/__tests__/orchestration.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'bun:test';
+import type { ReleasePackageInfo, ReleaseTarget } from '../core.js';
+import {
+  completeReleaseAtHead,
+  type ReleaseRepairShell,
+  type ReleaseVersionShell,
+  repairPendingTargets,
+  runReleaseVersion,
+} from '../orchestration.js';
+
+const stable: ReleasePackageInfo = { name: '@scope/stable', path: 'packages/stable', version: '1.0.0' };
+const prerelease: ReleasePackageInfo = {
+  name: '@scope/prerelease',
+  path: 'packages/prerelease',
+  version: '2.0.0-beta.1',
+};
+
+describe('release orchestration', () => {
+  it('repairs an older target with one checkout, one devenv load, npm-only build, and GitHub create calls', async () => {
+    const target = releaseTarget('older-release', [stable, prerelease], [stable], [prerelease]);
+    const shell = new RecordingRepairShell();
+
+    const summaries = await repairPendingTargets(shell, [target], 'restore-ref', false);
+
+    expect(shell.checkouts).toEqual(['older-release', 'restore-ref']);
+    expect(shell.devenvLoads).toBe(1);
+    expect(shell.builds).toEqual([['@scope/stable']]);
+    expect(shell.publishes).toEqual([{ name: '@scope/stable', distTag: 'latest', dryRun: false }]);
+    expect(shell.githubCreates).toEqual([{ name: '@scope/prerelease', dryRun: false }]);
+    expect(shell.pushes).toEqual([['@scope/stable', '@scope/prerelease']]);
+    expect(summaries).toHaveLength(1);
+    expect(summaries[0]?.published.map((pkg) => pkg.name)).toEqual(['@scope/stable']);
+    expect(summaries[0]?.githubReleases.map((pkg) => pkg.name)).toEqual(['@scope/prerelease']);
+  });
+
+  it('skips build and publish for GitHub-only repair targets', async () => {
+    const target = releaseTarget('github-only', [prerelease], [], [prerelease]);
+    const shell = new RecordingRepairShell();
+
+    await repairPendingTargets(shell, [target], 'restore-ref', false);
+
+    expect(shell.builds).toEqual([]);
+    expect(shell.publishes).toEqual([]);
+    expect(shell.githubCreates).toEqual([{ name: '@scope/prerelease', dryRun: false }]);
+  });
+
+  it('publishes a partial HEAD release by building npm-missing packages and creating missing GitHub Releases', async () => {
+    const shell = new RecordingRepairShell({ npmMissing: ['@scope/stable'], githubMissing: ['@scope/prerelease'] });
+
+    const summary = await completeReleaseAtHead(shell, [stable, prerelease], false, true);
+
+    expect(shell.checkouts).toEqual([]);
+    expect(shell.devenvLoads).toBe(0);
+    expect(shell.builds).toEqual([['@scope/stable']]);
+    expect(shell.publishes).toEqual([{ name: '@scope/stable', distTag: 'latest', dryRun: false }]);
+    expect(shell.githubCreates).toEqual([{ name: '@scope/prerelease', dryRun: false }]);
+    expect(summary.published.map((pkg) => pkg.name)).toEqual(['@scope/stable']);
+    expect(summary.alreadyPublished.map((pkg) => pkg.name)).toEqual(['@scope/prerelease']);
+    expect(summary.githubReleases.map((pkg) => pkg.name)).toEqual(['@scope/prerelease']);
+    expect(summary.rerunRequired).toBe(true);
+  });
+
+  it('leaves a complete HEAD release idempotent', async () => {
+    const shell = new RecordingRepairShell();
+
+    const summary = await completeReleaseAtHead(shell, [stable, prerelease], false, false);
+
+    expect(shell.builds).toEqual([]);
+    expect(shell.publishes).toEqual([]);
+    expect(shell.githubCreates).toEqual([]);
+    expect(summary.published).toEqual([]);
+    expect(summary.alreadyPublished.map((pkg) => pkg.name)).toEqual(['@scope/stable', '@scope/prerelease']);
+    expect(summary.githubReleases).toEqual([]);
+  });
+
+  it('does not run Nx versioning when HEAD is already a release target', async () => {
+    const shell = new RecordingVersionShell({ releasePackagesAtHead: [[stable]] });
+
+    const result = await runReleaseVersion(shell, { bump: 'patch', dryRun: false });
+
+    expect(result).toEqual({ mode: 'none', packages: [stable], status: 'already-release-target' });
+    expect(shell.nxRuns).toEqual([]);
+    expect(shell.ensureCalls).toEqual([['@scope/stable']]);
+  });
+
+  it('runs forced Nx versioning for an untagged HEAD and reports a new release commit', async () => {
+    const shell = new RecordingVersionShell({ releasePackagesAtHead: [[], [stable]], heads: ['before', 'after'] });
+
+    const result = await runReleaseVersion(shell, { bump: 'patch', dryRun: false });
+
+    expect(result).toEqual({ mode: 'new', packages: [stable], status: 'new-release' });
+    expect(shell.nxRuns).toEqual([{ bump: 'patch', dryRun: false }]);
+    expect(shell.cleanChecks).toBe(1);
+    expect(shell.ensureCalls).toEqual([['@scope/stable']]);
+  });
+});
+
+function releaseTarget(
+  sha: string,
+  packages: ReleasePackageInfo[],
+  npmPackages: ReleasePackageInfo[],
+  githubPackages: ReleasePackageInfo[],
+): ReleaseTarget<ReleasePackageInfo> {
+  return { sha, timestamp: 1, packages, npmPackages, githubPackages };
+}
+
+class RecordingRepairShell implements ReleaseRepairShell<ReleasePackageInfo> {
+  readonly checkouts: string[] = [];
+  readonly pushes: string[][] = [];
+  readonly builds: string[][] = [];
+  readonly publishes: Array<{ name: string; distTag: string; dryRun: boolean }> = [];
+  readonly githubCreates: Array<{ name: string; dryRun: boolean }> = [];
+  readonly npmQueries: string[][] = [];
+  readonly githubQueries: string[][] = [];
+  devenvLoads = 0;
+  currentRef = 'head';
+  private readonly npmMissing: Set<string>;
+  private readonly githubMissing: Set<string>;
+
+  constructor(options: { npmMissing?: string[]; githubMissing?: string[] } = {}) {
+    this.npmMissing = new Set(options.npmMissing ?? []);
+    this.githubMissing = new Set(options.githubMissing ?? []);
+  }
+
+  async gitHead(): Promise<string> {
+    return this.currentRef;
+  }
+
+  async pushReleaseRefs(packages: ReleasePackageInfo[]): Promise<boolean> {
+    this.pushes.push(packageNames(packages));
+    return true;
+  }
+
+  async listNpmMissingPackages(packages: ReleasePackageInfo[]): Promise<ReleasePackageInfo[]> {
+    this.npmQueries.push(packageNames(packages));
+    return packages.filter((pkg) => this.npmMissing.has(pkg.name));
+  }
+
+  async buildReleaseCandidate(packages: ReleasePackageInfo[]): Promise<void> {
+    this.builds.push(packageNames(packages));
+  }
+
+  async publishPackage(pkg: ReleasePackageInfo, distTag: string, dryRun: boolean): Promise<void> {
+    this.publishes.push({ name: pkg.name, distTag, dryRun });
+  }
+
+  async listGithubMissingPackages(packages: ReleasePackageInfo[]): Promise<ReleasePackageInfo[]> {
+    this.githubQueries.push(packageNames(packages));
+    return packages.filter((pkg) => this.githubMissing.has(pkg.name));
+  }
+
+  async createGithubRelease(pkg: ReleasePackageInfo, dryRun: boolean): Promise<void> {
+    this.githubCreates.push({ name: pkg.name, dryRun });
+  }
+
+  async checkout(ref: string): Promise<void> {
+    this.currentRef = ref;
+    this.checkouts.push(ref);
+  }
+
+  async withDevenvEnv<T>(runWithEnv: () => Promise<T>): Promise<T> {
+    this.devenvLoads += 1;
+    return runWithEnv();
+  }
+}
+
+class RecordingVersionShell implements ReleaseVersionShell<ReleasePackageInfo> {
+  readonly ensureCalls: string[][] = [];
+  readonly nxRuns: Array<{ bump: string; dryRun: boolean }> = [];
+  cleanChecks = 0;
+  private readonly releaseBatches: ReleasePackageInfo[][];
+  private readonly heads: string[];
+
+  constructor(options: { releasePackagesAtHead: ReleasePackageInfo[][]; heads?: string[] }) {
+    this.releaseBatches = [...options.releasePackagesAtHead];
+    this.heads = [...(options.heads ?? [])];
+  }
+
+  async releasePackagesAtHead(): Promise<ReleasePackageInfo[]> {
+    return this.releaseBatches.shift() ?? [];
+  }
+
+  async ensureLocalReleaseTags(packages: ReleasePackageInfo[]): Promise<void> {
+    this.ensureCalls.push(packageNames(packages));
+  }
+
+  async gitHead(): Promise<string> {
+    return this.heads.shift() ?? 'head';
+  }
+
+  async runNxReleaseVersion(bump: string, dryRun: boolean): Promise<void> {
+    this.nxRuns.push({ bump, dryRun });
+  }
+
+  async assertCleanGitTree(): Promise<void> {
+    this.cleanChecks += 1;
+  }
+}
+
+function packageNames(packages: ReleasePackageInfo[]): string[] {
+  return packages.map((pkg) => pkg.name);
+}

package/src/release/__tests__/publish-plan.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'bun:test';
+import type { ReleasePackageInfo } from '../core.js';
+import { planPublishActions } from '../publish-plan.js';
+
+const stable: ReleasePackageInfo = { name: '@scope/stable', path: 'packages/stable', version: '1.0.0' };
+const prerelease: ReleasePackageInfo = {
+  name: '@scope/prerelease',
+  path: 'packages/prerelease',
+  version: '2.0.0-beta.1',
+};
+
+describe('publish plan', () => {
+  it('returns empty actions when durable release state is complete', () => {
+    expect(
+      planPublishActions({
+        releasePackages: [stable, prerelease],
+        npmMissingPackages: [],
+        githubMissingPackages: [],
+      }),
+    ).toEqual({ buildProjects: [], publishPackages: [], githubReleasePackages: [] });
+  });
+
+  it('builds and publishes exactly npm-missing packages', () => {
+    const plan = planPublishActions({
+      releasePackages: [stable, prerelease],
+      npmMissingPackages: [stable],
+      githubMissingPackages: [],
+    });
+
+    expect(plan.buildProjects).toEqual(['@scope/stable']);
+    expect(plan.publishPackages).toEqual([{ pkg: stable, distTag: 'latest' }]);
+    expect(plan.githubReleasePackages).toEqual([]);
+  });
+
+  it('does not build for GitHub-only repair actions', () => {
+    const plan = planPublishActions({
+      releasePackages: [stable, prerelease],
+      npmMissingPackages: [],
+      githubMissingPackages: [prerelease],
+    });
+
+    expect(plan.buildProjects).toEqual([]);
+    expect(plan.publishPackages).toEqual([]);
+    expect(plan.githubReleasePackages).toEqual([prerelease]);
+  });
+
+  it('uses latest for stable packages and next for prerelease packages', () => {
+    const plan = planPublishActions({
+      releasePackages: [stable, prerelease],
+      npmMissingPackages: [stable, prerelease],
+      githubMissingPackages: [],
+    });
+
+    expect(plan.buildProjects).toEqual(['@scope/stable', '@scope/prerelease']);
+    expect(plan.publishPackages).toEqual([
+      { pkg: stable, distTag: 'latest' },
+      { pkg: prerelease, distTag: 'next' },
+    ]);
+    expect(plan.githubReleasePackages).toEqual([]);
+  });
+});