@smoothbricks/cli 0.1.1 → 0.3.0

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'bun:test';
-import type { ReleasePackageInfo, ReleaseTarget } from '../core.js';
+import { type ReleasePackageInfo, type ReleaseTarget, releaseTag } from '../core.js';
 import {
+  bumpStableReleaseToNext,
   completeReleaseAtHead,
   type ReleaseRepairShell,
   type ReleaseVersionShell,
@@ -8,9 +9,15 @@ import {
   runReleaseVersion,
 } from '../orchestration.js';
 
-const stable: ReleasePackageInfo = { name: '@scope/stable', path: 'packages/stable', version: '1.0.0' };
+const stable: ReleasePackageInfo = {
+  name: '@scope/stable',
+  projectName: 'stable',
+  path: 'packages/stable',
+  version: '1.0.0',
+};
 const prerelease: ReleasePackageInfo = {
   name: '@scope/prerelease',
+  projectName: 'prerelease',
   path: 'packages/prerelease',
   version: '2.0.0-beta.1',
 };
@@ -27,7 +34,7 @@ describe('release orchestration', () => {
     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(shell.pushes).toEqual([['stable@1.0.0', 'prerelease@2.0.0-beta.1']]);
     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']);
@@ -44,6 +51,33 @@ describe('release orchestration', () => {
     expect(shell.githubCreates).toEqual([{ name: '@scope/prerelease', dryRun: false }]);
   });
 
+  it('dry-run repair reports planned targets without checkout, devenv, build, publish, or GitHub calls', async () => {
+    const target = releaseTarget('github-only', [prerelease], [], [prerelease]);
+    const shell = new RecordingRepairShell();
+
+    const summaries = await repairPendingTargets(shell, [target], 'restore-ref', true);
+
+    expect(shell.checkouts).toEqual([]);
+    expect(shell.devenvLoads).toBe(0);
+    expect(shell.builds).toEqual([]);
+    expect(shell.publishes).toEqual([]);
+    expect(shell.githubCreates).toEqual([]);
+    expect(summaries).toEqual([
+      {
+        sha: 'github-only',
+        dryRun: true,
+        packages: [prerelease],
+        pushed: false,
+        published: [],
+        alreadyPublished: [prerelease],
+        githubReleases: [],
+        githubReleaseLinks: [],
+        rerunRequired: false,
+        noRelease: 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'] });
 
@@ -54,9 +88,13 @@ describe('release orchestration', () => {
     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([['stable@1.0.0', 'prerelease@2.0.0-beta.1']]);
     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.githubReleaseLinks).toEqual([
+      { pkg: prerelease, url: 'https://github.test/prerelease@2.0.0-beta.1' },
+    ]);
     expect(summary.rerunRequired).toBe(true);
   });
 
@@ -71,6 +109,7 @@ describe('release orchestration', () => {
     expect(summary.published).toEqual([]);
     expect(summary.alreadyPublished.map((pkg) => pkg.name)).toEqual(['@scope/stable', '@scope/prerelease']);
     expect(summary.githubReleases).toEqual([]);
+    expect(summary.githubReleaseLinks).toEqual([]);
   });
 
   it('does not run Nx versioning when HEAD is already a release target', async () => {
@@ -84,15 +123,79 @@ describe('release orchestration', () => {
   });
 
   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 shell = new RecordingVersionShell({
+      releasePackagesAtHead: [[], [stable]],
+      releaseVersionPackages: [stable, prerelease],
+      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.nxRuns).toEqual([{ packages: ['@scope/stable', '@scope/prerelease'], bump: 'patch', dryRun: false }]);
     expect(shell.cleanChecks).toBe(1);
     expect(shell.ensureCalls).toEqual([['@scope/stable']]);
   });
+
+  it('skips auto Nx versioning when no package-local candidates exist', async () => {
+    const shell = new RecordingVersionShell({ releasePackagesAtHead: [[]], releaseVersionPackages: [] });
+
+    const result = await runReleaseVersion(shell, { bump: 'auto', dryRun: false });
+
+    expect(result).toEqual({ mode: 'none', packages: [], status: 'no-release-needed' });
+    expect(shell.nxRuns).toEqual([]);
+    expect(shell.cleanChecks).toBe(0);
+    expect(shell.ensureCalls).toEqual([]);
+  });
+
+  it('runs auto Nx versioning only for selected package-local candidates', async () => {
+    const shell = new RecordingVersionShell({
+      releasePackagesAtHead: [[], [stable]],
+      releaseVersionPackages: [stable],
+      heads: ['before', 'after'],
+    });
+
+    const result = await runReleaseVersion(shell, { bump: 'auto', dryRun: false });
+
+    expect(result).toEqual({ mode: 'new', packages: [stable], status: 'new-release' });
+    expect(shell.nxRuns).toEqual([{ packages: ['@scope/stable'], bump: 'auto', dryRun: false }]);
+  });
+
+  it('reports dry-run version packages resolved by Nx without creating a release mode', async () => {
+    const preview = { ...stable, version: '1.1.0' };
+    const shell = new RecordingVersionShell({ releasePackagesAtHead: [[]], releaseVersionPackages: [stable], preview });
+
+    const result = await runReleaseVersion(shell, { bump: 'auto', dryRun: true });
+
+    expect(result).toEqual({ mode: 'none', packages: [preview], status: 'dry-run' });
+    expect(shell.nxRuns).toEqual([{ packages: ['@scope/stable'], bump: 'auto', dryRun: true }]);
+  });
+
+  it('bumps stable release packages to next after publish completion', async () => {
+    const shell = new RecordingNextShell();
+
+    const bumped = await bumpStableReleaseToNext(shell, [stable, prerelease], false, false);
+
+    expect(bumped.map((pkg) => pkg.name)).toEqual(['@scope/stable']);
+    expect(shell.bumped).toEqual([['@scope/stable']]);
+  });
+
+  it('does not bump prerelease-only or dry-run publishes to next', async () => {
+    const shell = new RecordingNextShell();
+
+    await expect(bumpStableReleaseToNext(shell, [prerelease], false, false)).resolves.toEqual([]);
+    await expect(bumpStableReleaseToNext(shell, [stable], true, false)).resolves.toEqual([]);
+
+    expect(shell.bumped).toEqual([]);
+  });
+
+  it('does not bump stable packages to next when newer branch commits remain', async () => {
+    const shell = new RecordingNextShell();
+
+    await expect(bumpStableReleaseToNext(shell, [stable], false, true)).resolves.toEqual([]);
+
+    expect(shell.bumped).toEqual([]);
+  });
 });
 
 function releaseTarget(
@@ -127,7 +230,7 @@ class RecordingRepairShell implements ReleaseRepairShell<ReleasePackageInfo> {
   }
 
   async pushReleaseRefs(packages: ReleasePackageInfo[]): Promise<boolean> {
-    this.pushes.push(packageNames(packages));
+    this.pushes.push(packages.map((pkg) => releaseTag(pkg)));
     return true;
   }
 
@@ -149,8 +252,9 @@ class RecordingRepairShell implements ReleaseRepairShell<ReleasePackageInfo> {
     return packages.filter((pkg) => this.githubMissing.has(pkg.name));
   }
 
-  async createGithubRelease(pkg: ReleasePackageInfo, dryRun: boolean): Promise<void> {
+  async createGithubRelease(pkg: ReleasePackageInfo, dryRun: boolean): Promise<string | null> {
     this.githubCreates.push({ name: pkg.name, dryRun });
+    return dryRun ? null : `https://github.test/${releaseTag(pkg)}`;
   }
 
   async checkout(ref: string): Promise<void> {
@@ -166,20 +270,33 @@ class RecordingRepairShell implements ReleaseRepairShell<ReleasePackageInfo> {
 
 class RecordingVersionShell implements ReleaseVersionShell<ReleasePackageInfo> {
   readonly ensureCalls: string[][] = [];
-  readonly nxRuns: Array<{ bump: string; dryRun: boolean }> = [];
+  readonly nxRuns: Array<{ packages: string[]; bump: string; dryRun: boolean }> = [];
   cleanChecks = 0;
   private readonly releaseBatches: ReleasePackageInfo[][];
+  private readonly versionPackages: ReleasePackageInfo[];
   private readonly heads: string[];
-
-  constructor(options: { releasePackagesAtHead: ReleasePackageInfo[][]; heads?: string[] }) {
+  private readonly preview: ReleasePackageInfo[];
+
+  constructor(options: {
+    releasePackagesAtHead: ReleasePackageInfo[][];
+    releaseVersionPackages?: ReleasePackageInfo[];
+    heads?: string[];
+    preview?: ReleasePackageInfo | ReleasePackageInfo[];
+  }) {
     this.releaseBatches = [...options.releasePackagesAtHead];
+    this.versionPackages = options.releaseVersionPackages ?? [stable, prerelease];
     this.heads = [...(options.heads ?? [])];
+    this.preview = Array.isArray(options.preview) ? options.preview : options.preview ? [options.preview] : [];
   }
 
   async releasePackagesAtHead(): Promise<ReleasePackageInfo[]> {
     return this.releaseBatches.shift() ?? [];
   }
 
+  async releaseVersionPackages(): Promise<ReleasePackageInfo[]> {
+    return this.versionPackages;
+  }
+
   async ensureLocalReleaseTags(packages: ReleasePackageInfo[]): Promise<void> {
     this.ensureCalls.push(packageNames(packages));
   }
@@ -188,8 +305,13 @@ class RecordingVersionShell implements ReleaseVersionShell<ReleasePackageInfo> {
     return this.heads.shift() ?? 'head';
   }
 
-  async runNxReleaseVersion(bump: string, dryRun: boolean): Promise<void> {
-    this.nxRuns.push({ bump, dryRun });
+  async runNxReleaseVersion(
+    packages: ReleasePackageInfo[],
+    bump: string,
+    dryRun: boolean,
+  ): Promise<ReleasePackageInfo[]> {
+    this.nxRuns.push({ packages: packageNames(packages), bump, dryRun });
+    return this.preview;
   }
 
   async assertCleanGitTree(): Promise<void> {
@@ -197,6 +319,14 @@ class RecordingVersionShell implements ReleaseVersionShell<ReleasePackageInfo> {
   }
 }
 
+class RecordingNextShell {
+  readonly bumped: string[][] = [];
+
+  async bumpStablePackagesToNext(packages: ReleasePackageInfo[]): Promise<void> {
+    this.bumped.push(packageNames(packages));
+  }
+}
+
 function packageNames(packages: ReleasePackageInfo[]): string[] {
   return packages.map((pkg) => pkg.name);
 }

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

@@ -2,9 +2,15 @@ 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 stable: ReleasePackageInfo = {
+  name: '@scope/stable',
+  projectName: 'stable',
+  path: 'packages/stable',
+  version: '1.0.0',
+};
 const prerelease: ReleasePackageInfo = {
   name: '@scope/prerelease',
+  projectName: 'prerelease',
   path: 'packages/prerelease',
   version: '2.0.0-beta.1',
 };
@@ -27,7 +33,7 @@ describe('publish plan', () => {
       githubMissingPackages: [],
     });
 
-    expect(plan.buildProjects).toEqual(['@scope/stable']);
+    expect(plan.buildProjects).toEqual(['stable']);
     expect(plan.publishPackages).toEqual([{ pkg: stable, distTag: 'latest' }]);
     expect(plan.githubReleasePackages).toEqual([]);
   });
@@ -51,7 +57,7 @@ describe('publish plan', () => {
       githubMissingPackages: [],
     });
 
-    expect(plan.buildProjects).toEqual(['@scope/stable', '@scope/prerelease']);
+    expect(plan.buildProjects).toEqual(['stable', 'prerelease']);
     expect(plan.publishPackages).toEqual([
       { pkg: stable, distTag: 'latest' },
       { pkg: prerelease, distTag: 'next' },

package/src/release/__tests__/retag-unpublished.test.ts

@@ -7,31 +7,31 @@ import {
   retagUnpublished,
 } from '../retag-unpublished.js';
 
-const pkg: ReleasePackageInfo = { name: '@scope/pkg', path: 'packages/pkg', version: '1.2.3' };
+const pkg: ReleasePackageInfo = { name: '@scope/pkg', projectName: 'pkg', path: 'packages/pkg', version: '1.2.3' };
 
 describe('retag unpublished releases', () => {
   it('moves unpublished owned tags, pushes with a remote lease, and dispatches publish auto', async () => {
     const shell = new RecordingRetagShell({
       versionAtRef: '1.2.3',
-      remoteTagObjects: new Map([['@scope/pkg@1.2.3', 'old-tag-object']]),
+      remoteTagObjects: new Map([['pkg@1.2.3', 'old-tag-object']]),
       dispatchSha: 'target-sha',
     });
 
     const updates = await retagUnpublished(shell, retagOptions({ push: true, dispatch: true }));
 
-    expect(updates).toEqual([{ tag: '@scope/pkg@1.2.3', pkg, expectedRemoteObject: 'old-tag-object' }]);
-    expect(shell.movedTags).toEqual([{ tag: '@scope/pkg@1.2.3', ref: 'HEAD' }]);
-    expect(shell.pushed).toEqual([[{ tag: '@scope/pkg@1.2.3', expectedRemoteObject: 'old-tag-object' }]]);
+    expect(updates).toEqual([{ tag: 'pkg@1.2.3', pkg, expectedRemoteObject: 'old-tag-object' }]);
+    expect(shell.movedTags).toEqual([{ tag: 'pkg@1.2.3', ref: 'HEAD' }]);
+    expect(shell.pushed).toEqual([[{ tag: 'pkg@1.2.3', expectedRemoteObject: 'old-tag-object' }]]);
     expect(shell.dispatched).toEqual([{ workflow: 'publish.yml', branch: 'main' }]);
     expect(shell.dispatchRefLookups).toEqual(['main']);
-    expect(shell.remoteTagLookups).toEqual(['@scope/pkg@1.2.3']);
+    expect(shell.remoteTagLookups).toEqual(['pkg@1.2.3']);
   });
 
   it('rejects tags whose package version already exists on npm', async () => {
     const shell = new RecordingRetagShell({ versionAtRef: '1.2.3', npmPublished: true });
 
     await expect(retagUnpublished(shell, retagOptions())).rejects.toThrow(
-      'Cannot retag @scope/pkg@1.2.3: @scope/pkg@1.2.3 already exists on npm.',
+      'Cannot retag pkg@1.2.3: @scope/pkg@1.2.3 already exists on npm.',
     );
 
     expect(shell.movedTags).toEqual([]);
@@ -42,7 +42,7 @@ describe('retag unpublished releases', () => {
     const shell = new RecordingRetagShell({ versionAtRef: '1.2.4' });
 
     await expect(retagUnpublished(shell, retagOptions())).rejects.toThrow(
-      'Release tag @scope/pkg@1.2.3 cannot move to HEAD: packages/pkg/package.json has version 1.2.4, expected 1.2.3.',
+      'Release tag pkg@1.2.3 cannot move to HEAD: packages/pkg/package.json has version 1.2.4, expected 1.2.3.',
     );
   });
 
@@ -66,7 +66,7 @@ describe('retag unpublished releases', () => {
     expect(shell.movedTags).toEqual([]);
     expect(shell.pushed).toEqual([]);
     expect(shell.dispatched).toEqual([]);
-    expect(shell.logs).toContain('Would move @scope/pkg@1.2.3 to HEAD (target-sha).');
+    expect(shell.logs).toContain('Would move pkg@1.2.3 to HEAD (target-sha).');
     expect(shell.logs).toContain('Would push 1 retagged release tag.');
     expect(shell.logs).toContain('Would dispatch publish.yml on main with bump=auto.');
   });
@@ -74,7 +74,7 @@ describe('retag unpublished releases', () => {
 
 function retagOptions(overrides: Partial<RetagUnpublishedOptions> = {}): RetagUnpublishedOptions {
   return {
-    tags: ['@scope/pkg@1.2.3'],
+    tags: ['pkg@1.2.3'],
     toRef: 'HEAD',
     push: false,
     dispatch: false,

package/src/release/__tests__/trust-publisher.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'bun:test';
+import type { BootstrapNpmPackagesOptions } from '../bootstrap-npm-packages.js';
+import type { ReleasePackageInfo } from '../core.js';
+import {
+  configureTrustedPublishers,
+  parseTrustedPublishers,
+  type TrustedPublisher,
+  type TrustPublisherShell,
+} from '../index.js';
+
+const stable: ReleasePackageInfo = {
+  name: '@scope/stable',
+  projectName: 'stable',
+  path: 'packages/stable',
+  version: '1.2.3',
+};
+const missing: ReleasePackageInfo = {
+  name: '@scope/missing',
+  projectName: 'missing',
+  path: 'packages/missing',
+  version: '2.0.0',
+};
+
+describe('trusted publisher setup', () => {
+  it('bootstraps missing npm packages before configuring trust', async () => {
+    const shell = new RecordingTrustPublisherShell({ packages: [stable, missing], existing: [stable.name] });
+
+    await configureTrustedPublishers(shell, { bootstrap: true, skipLogin: false });
+
+    expect(shell.events).toEqual([
+      'bootstrap:false:false',
+      `exists:${stable.name}`,
+      `exists:${missing.name}`,
+      `list:${stable.name}`,
+      `trust:${stable.name}:false`,
+      `list:${missing.name}`,
+      `trust:${missing.name}:false`,
+    ]);
+  });
+
+  it('directs missing packages to trust-publisher --bootstrap', async () => {
+    const shell = new RecordingTrustPublisherShell({ packages: [missing], existing: [] });
+
+    await expect(configureTrustedPublishers(shell, {})).rejects.toThrow(
+      'Run smoo release trust-publisher --bootstrap locally',
+    );
+    expect(shell.events).toEqual([`exists:${missing.name}`]);
+  });
+
+  it('does not pre-login before trust operations', async () => {
+    const shell = new RecordingTrustPublisherShell({ packages: [stable], existing: [stable.name] });
+
+    await configureTrustedPublishers(shell, { bootstrap: true });
+
+    expect(shell.events).toEqual([
+      'bootstrap:false:false',
+      `exists:${stable.name}`,
+      `list:${stable.name}`,
+      `trust:${stable.name}:false`,
+    ]);
+  });
+
+  it('skips packages with matching trusted publishers', async () => {
+    const shell = new RecordingTrustPublisherShell({
+      packages: [stable],
+      existing: [stable.name],
+      trustedPublishers: {
+        [stable.name]: [{ id: 'trusted-1', type: 'github', file: 'publish.yml', repository: 'scope/repo' }],
+      },
+    });
+
+    await configureTrustedPublishers(shell, { skipLogin: true });
+
+    expect(shell.events).toEqual([`exists:${stable.name}`, `list:${stable.name}`]);
+    expect(shell.logs).toContain(`${stable.name}: npm trusted publisher is already configured; skipping.`);
+  });
+
+  it('rejects mismatched trusted publishers', async () => {
+    const shell = new RecordingTrustPublisherShell({
+      packages: [stable],
+      existing: [stable.name],
+      trustedPublishers: {
+        [stable.name]: [{ id: 'trusted-1', type: 'github', file: 'other.yml', repository: 'scope/repo' }],
+      },
+    });
+
+    await expect(configureTrustedPublishers(shell, { skipLogin: true })).rejects.toThrow(
+      'npm trusted publisher exists but does not match',
+    );
+    expect(shell.events).toEqual([`exists:${stable.name}`, `list:${stable.name}`]);
+  });
+
+  it('configures only selected packages', async () => {
+    const shell = new RecordingTrustPublisherShell({
+      packages: [stable, missing],
+      existing: [stable.name, missing.name],
+    });
+
+    await configureTrustedPublishers(shell, { skipLogin: true, packages: [missing.name] });
+
+    expect(shell.events).toEqual([`exists:${missing.name}`, `list:${missing.name}`, `trust:${missing.name}:false`]);
+  });
+
+  it('parses empty npm trust list output as no trusted publishers', () => {
+    expect(parseTrustedPublishers('', stable.name)).toEqual([]);
+    expect(parseTrustedPublishers('null', stable.name)).toEqual([]);
+  });
+});
+
+class RecordingTrustPublisherShell implements TrustPublisherShell<ReleasePackageInfo> {
+  readonly repository = 'scope/repo';
+  readonly workflow = 'publish.yml';
+  readonly events: string[] = [];
+  readonly logs: string[] = [];
+  readonly errors: string[] = [];
+  private readonly packages: ReleasePackageInfo[];
+  private readonly existing: Set<string>;
+  private readonly trustedPublisherByPackage: Record<string, TrustedPublisher[]>;
+
+  constructor(options: {
+    packages: ReleasePackageInfo[];
+    existing: string[];
+    trustedPublishers?: Record<string, TrustedPublisher[]>;
+  }) {
+    this.packages = options.packages;
+    this.existing = new Set(options.existing);
+    this.trustedPublisherByPackage = options.trustedPublishers ?? {};
+  }
+
+  listReleasePackages(): ReleasePackageInfo[] {
+    return this.packages;
+  }
+
+  async packageExists(name: string): Promise<boolean> {
+    this.events.push(`exists:${name}`);
+    return this.existing.has(name);
+  }
+
+  async bootstrapNpmPackages(options: BootstrapNpmPackagesOptions): Promise<ReleasePackageInfo[]> {
+    this.events.push(`bootstrap:${options.dryRun}:${options.skipLogin}`);
+    const missingPackages = this.packages.filter((pkg) => !this.existing.has(pkg.name));
+    for (const pkg of missingPackages) {
+      this.existing.add(pkg.name);
+    }
+    return missingPackages;
+  }
+
+  async trustPublisher(pkg: ReleasePackageInfo, dryRun: boolean): Promise<'configured' | 'already-configured'> {
+    this.events.push(`trust:${pkg.name}:${dryRun}`);
+    return 'configured';
+  }
+
+  async trustedPublishers(pkg: ReleasePackageInfo): Promise<TrustedPublisher[]> {
+    this.events.push(`list:${pkg.name}`);
+    return this.trustedPublisherByPackage[pkg.name] ?? [];
+  }
+
+  log(message: string): void {
+    this.logs.push(message);
+  }
+
+  error(message: string): void {
+    this.errors.push(message);
+  }
+}

package/src/release/bootstrap-npm-packages.ts

@@ -0,0 +1,88 @@
+import type { ReleasePackageInfo } from './core.js';
+
+export const NPM_BOOTSTRAP_VERSION = '0.0.0-bootstrap.0';
+export const NPM_BOOTSTRAP_DIST_TAG = 'bootstrap';
+
+export interface BootstrapNpmPackagesOptions {
+  dryRun: boolean;
+  skipLogin: boolean;
+  packages: string[];
+  otp?: string;
+}
+
+export interface BootstrapNpmPackagesShell<Package extends ReleasePackageInfo = ReleasePackageInfo> {
+  listReleasePackages(): Package[];
+  packageExists(name: string): Promise<boolean>;
+  login(): Promise<void>;
+  publishPlaceholder(pkg: Package, env?: Record<string, string>): Promise<void>;
+  promptOtp(packageName: string): Promise<string>;
+  log(message: string): void;
+}
+
+export async function bootstrapNpmPackages<Package extends ReleasePackageInfo>(
+  shell: BootstrapNpmPackagesShell<Package>,
+  options: BootstrapNpmPackagesOptions,
+): Promise<Package[]> {
+  const packages = selectedReleasePackages(shell.listReleasePackages(), options.packages);
+  if (packages.length === 0) {
+    throw new Error('No owned release packages found.');
+  }
+
+  const missing: Package[] = [];
+  for (const pkg of packages) {
+    if (await shell.packageExists(pkg.name)) {
+      shell.log(`${pkg.name}: already exists on npm; skipping placeholder bootstrap.`);
+    } else {
+      missing.push(pkg);
+    }
+  }
+
+  if (missing.length === 0) {
+    shell.log('All selected owned release packages already exist on npm.');
+    return [];
+  }
+
+  shell.log(
+    `Bootstrap npm placeholders (${NPM_BOOTSTRAP_VERSION}, dist-tag ${NPM_BOOTSTRAP_DIST_TAG}): ${missing
+      .map((pkg) => pkg.name)
+      .join(', ')}`,
+  );
+  if (options.dryRun) {
+    return missing;
+  }
+
+  if (!options.skipLogin) {
+    await shell.login();
+  }
+  for (const pkg of missing) {
+    shell.log(`${pkg.name}: publishing npm placeholder.`);
+    const otp = options.otp ?? (await shell.promptOtp(pkg.name));
+    await shell.publishPlaceholder(pkg, { NPM_CONFIG_OTP: otp });
+  }
+  shell.log('Bootstrap complete. Run smoo release trust-publisher before the first CI publish.');
+  return missing;
+}
+
+function selectedReleasePackages<Package extends ReleasePackageInfo>(
+  packages: Package[],
+  selections: string[],
+): Package[] {
+  if (selections.length === 0) {
+    return packages;
+  }
+  const byName = new Map(packages.map((pkg) => [pkg.name, pkg]));
+  const selected: Package[] = [];
+  const unknown: string[] = [];
+  for (const name of selections) {
+    const pkg = byName.get(name);
+    if (pkg) {
+      selected.push(pkg);
+    } else {
+      unknown.push(name);
+    }
+  }
+  if (unknown.length > 0) {
+    throw new Error(`Unknown owned release package selection: ${unknown.join(', ')}`);
+  }
+  return selected;
+}