@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/cli/commands/publish/alpha.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Alpha-helper tests — v2/PUBLILO_CLI.md Phase 3 payoff.
+ *
+ * The pure functions in alpha.ts (parsePackageSpec, stripAlphaSuffix,
+ * isAlphaVersion, pickNextAlphaN, decideAlphaSkip) need no I/O to
+ * exercise. The impure wrappers (nextAlphaNumber, alphaSkipDecision)
+ * just glue npm view + git log onto the pure inputs, so testing the
+ * pure layer covers the real logic.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  decideAlphaSkip,
+  isAlphaVersion,
+  parsePackageSpec,
+  pickNextAlphaN,
+  stripAlphaSuffix,
+} from './alpha';
+
+describe('parsePackageSpec', () => {
+  test('parses scoped name@version', () => {
+    expect(parsePackageSpec('@celilo/e2e@0.7.14-alpha.3')).toEqual({
+      name: '@celilo/e2e',
+      version: '0.7.14-alpha.3',
+    });
+  });
+
+  test('parses unscoped name@version', () => {
+    expect(parsePackageSpec('lodash@4.17.21')).toEqual({
+      name: 'lodash',
+      version: '4.17.21',
+    });
+  });
+
+  test('throws when no @ separator beyond an initial scope @', () => {
+    expect(() => parsePackageSpec('@celilo/e2e')).toThrow('Invalid package spec');
+    expect(() => parsePackageSpec('lodash')).toThrow('Invalid package spec');
+  });
+
+  test('uses the LAST @ as the separator (scoped names contain another)', () => {
+    // @scope/name@1.0.0-pre@special — last @ before version wins. (Not a
+    // realistic form, but documents the contract.)
+    expect(parsePackageSpec('@a/b@1.0.0-pre@x')).toEqual({
+      name: '@a/b@1.0.0-pre',
+      version: 'x',
+    });
+  });
+});
+
+describe('stripAlphaSuffix', () => {
+  test('removes -alpha.N suffix', () => {
+    expect(stripAlphaSuffix('0.7.14-alpha.3')).toBe('0.7.14');
+    expect(stripAlphaSuffix('1.0.0-alpha.0')).toBe('1.0.0');
+    expect(stripAlphaSuffix('10.20.30-alpha.999')).toBe('10.20.30');
+  });
+
+  test('leaves real versions alone', () => {
+    expect(stripAlphaSuffix('0.7.14')).toBe('0.7.14');
+    expect(stripAlphaSuffix('1.0.0')).toBe('1.0.0');
+  });
+
+  test('leaves other pre-releases alone (only -alpha.N matches)', () => {
+    expect(stripAlphaSuffix('1.0.0-beta.0')).toBe('1.0.0-beta.0');
+    expect(stripAlphaSuffix('1.0.0-rc.1')).toBe('1.0.0-rc.1');
+    expect(stripAlphaSuffix('1.0.0-alpha')).toBe('1.0.0-alpha'); // no .N
+  });
+});
+
+describe('isAlphaVersion', () => {
+  test('identifies -alpha.N', () => {
+    expect(isAlphaVersion('0.7.14-alpha.0')).toBe(true);
+    expect(isAlphaVersion('0.7.14-alpha.3')).toBe(true);
+    expect(isAlphaVersion('1.0.0-alpha.999')).toBe(true);
+  });
+
+  test('rejects other forms', () => {
+    expect(isAlphaVersion('0.7.14')).toBe(false);
+    expect(isAlphaVersion('0.7.14-beta.0')).toBe(false);
+    expect(isAlphaVersion('0.7.14-alpha')).toBe(false); // no .N
+  });
+});
+
+describe('pickNextAlphaN', () => {
+  test('returns 0 when no alphas exist for the target core', () => {
+    expect(pickNextAlphaN([], '0.7.14')).toBe(0);
+    expect(pickNextAlphaN(['0.7.13', '0.7.14', '0.7.15'], '0.7.14')).toBe(0);
+  });
+
+  test('returns max+1 when alphas exist', () => {
+    expect(pickNextAlphaN(['0.7.14-alpha.0'], '0.7.14')).toBe(1);
+    expect(pickNextAlphaN(['0.7.14-alpha.0', '0.7.14-alpha.1'], '0.7.14')).toBe(2);
+    expect(pickNextAlphaN(['0.7.14-alpha.0', '0.7.14-alpha.1', '0.7.14-alpha.5'], '0.7.14')).toBe(
+      6,
+    );
+  });
+
+  test('ignores alphas of other cores', () => {
+    expect(pickNextAlphaN(['0.7.13-alpha.99', '0.7.14-alpha.0', '0.7.15-alpha.10'], '0.7.14')).toBe(
+      1,
+    );
+  });
+
+  test("ignores versions that aren't -alpha.N", () => {
+    expect(
+      pickNextAlphaN(['0.7.14', '0.7.14-beta.0', '0.7.14-rc.5', '0.7.14-alpha.2'], '0.7.14'),
+    ).toBe(3);
+  });
+
+  test('handles gaps (uses max, not min-gap)', () => {
+    // Operator manually published 0.7.14-alpha.3 and 0.7.14-alpha.7 —
+    // next is 8, NOT 4. Avoid reusing numbers, ever.
+    expect(pickNextAlphaN(['0.7.14-alpha.3', '0.7.14-alpha.7'], '0.7.14')).toBe(8);
+  });
+
+  test('regex-escapes dots in the semver core', () => {
+    // If we didn't escape, "0.7.14" would match "0X7X14" too. Verify
+    // the escape works by feeding noise that would match a non-escaped
+    // pattern.
+    expect(pickNextAlphaN(['0X7X14-alpha.0'], '0.7.14')).toBe(0);
+  });
+});
+
+describe('decideAlphaSkip', () => {
+  test('publishes the first alpha (N=0)', () => {
+    expect(
+      decideAlphaSkip({
+        nextN: 0,
+        priorGitHead: '',
+        priorHeadReachable: false,
+        sourceChangedSincePrior: false,
+        priorVersion: '',
+      }),
+    ).toEqual({ skip: false });
+  });
+
+  test('publishes when prior alpha has no gitHead', () => {
+    const decision = decideAlphaSkip({
+      nextN: 3,
+      priorGitHead: '',
+      priorHeadReachable: false,
+      sourceChangedSincePrior: false,
+      priorVersion: '0.7.14-alpha.2',
+    });
+    expect(decision.skip).toBe(false);
+    expect(decision.reason).toContain('no gitHead on 0.7.14-alpha.2');
+  });
+
+  test('publishes when prior gitHead is unreachable', () => {
+    const decision = decideAlphaSkip({
+      nextN: 3,
+      priorGitHead: 'deadbeef1234',
+      priorHeadReachable: false,
+      sourceChangedSincePrior: false,
+      priorVersion: '0.7.14-alpha.2',
+    });
+    expect(decision.skip).toBe(false);
+    expect(decision.reason).toContain('deadbeef unreachable');
+  });
+
+  test('publishes when source changed since prior alpha', () => {
+    const decision = decideAlphaSkip({
+      nextN: 3,
+      priorGitHead: 'abcdef1234567890',
+      priorHeadReachable: true,
+      sourceChangedSincePrior: true,
+      priorVersion: '0.7.14-alpha.2',
+    });
+    expect(decision).toEqual({ skip: false });
+  });
+
+  test('skips when prior alpha exists and source is unchanged', () => {
+    const decision = decideAlphaSkip({
+      nextN: 3,
+      priorGitHead: 'abcdef1234567890',
+      priorHeadReachable: true,
+      sourceChangedSincePrior: false,
+      priorVersion: '0.7.14-alpha.2',
+    });
+    expect(decision.skip).toBe(true);
+    if (decision.skip) {
+      expect(decision.reason).toContain('no source changes since 0.7.14-alpha.2');
+      expect(decision.reason).toContain('gitHead abcdef12');
+    }
+  });
+});

package/src/cli/commands/publish/alpha.ts

@@ -0,0 +1,226 @@
+/**
+ * Alpha-tagging logic — `--alpha` publish + `--promote` graduation.
+ *
+ * The semantics live in `v2/FIRST_PUBLILO_ALPHA_TAGGING.md`; this
+ * module is the implementation surface those flags drive. Per
+ * v2/PUBLILO_CLI.md Phase 3, the alpha-specific helpers live here
+ * (not in helpers.ts) so it's clear where to look when extending the
+ * model — e.g. to add `--beta` once `v2/BUILD_BUS.md`'s validation
+ * signal lands.
+ *
+ * Two-layer design for testability:
+ *
+ *   pure:    pickNextAlphaN, decideAlphaSkip — operate on inputs the
+ *            caller has already fetched. Unit-tested directly without
+ *            spawning npm or git.
+ *   impure:  nextAlphaNumber, alphaSkipDecision — thin wrappers that
+ *            fetch from npm/git and delegate to the pure helpers. The
+ *            planner uses these; tests mock them at the import
+ *            boundary (the workspace.test.ts pattern).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { REPO_ROOT } from './helpers';
+
+/** npm dist-tag used by `--alpha` publishes. */
+export const ALPHA_TAG = 'alpha';
+
+// ─── Pure helpers ──────────────────────────────────────────────────
+
+/**
+ * Parse `<name>@<version>` — handles scoped names where the package
+ * name itself starts with `@` (e.g. `@celilo/e2e@0.7.14-alpha.3`).
+ * Pure — used by both --promote parsing and any test fixture that
+ * needs to round-trip a spec string.
+ */
+export function parsePackageSpec(spec: string): { name: string; version: string } {
+  const lastAt = spec.lastIndexOf('@');
+  if (lastAt <= 0) {
+    throw new Error(`Invalid package spec "${spec}". Expected "<name>@<version>".`);
+  }
+  return {
+    name: spec.slice(0, lastAt),
+    version: spec.slice(lastAt + 1),
+  };
+}
+
+export function stripAlphaSuffix(version: string): string {
+  return version.replace(/-alpha\.\d+$/, '');
+}
+
+export function isAlphaVersion(version: string): boolean {
+  return /-alpha\.\d+$/.test(version);
+}
+
+/**
+ * Pure inner of `nextAlphaNumber`. Given the full list of versions
+ * for a package (whatever `npm view <name> versions --json` returned)
+ * and a target semver core, returns the next alpha N to ship.
+ *
+ * - No existing `X.Y.Z-alpha.*` → 0
+ * - Existing `X.Y.Z-alpha.0`, `X.Y.Z-alpha.1`, `X.Y.Z-alpha.3` → 4
+ *   (gaps in the sequence don't matter; we want max+1, not min-gap)
+ * - Versions outside the target X.Y.Z are ignored.
+ */
+export function pickNextAlphaN(versions: string[], semverCore: string): number {
+  const re = new RegExp(`^${semverCore.replace(/\./g, '\\.')}-alpha\\.(\\d+)$`);
+  let max = -1;
+  for (const v of versions) {
+    const m = v.match(re);
+    if (m) {
+      const n = Number.parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return max + 1;
+}
+
+/**
+ * Inputs the alpha-skip decision actually depends on. Lifted out as a
+ * type so the pure decideAlphaSkip can be tested without mocking npm
+ * or git: callers construct one of these, the function returns the
+ * decision.
+ */
+export interface AlphaSkipInputs {
+  /** Next alpha number we'd ship (0 means no prior alpha exists). */
+  nextN: number;
+  /**
+   * `gitHead` recorded on the prior alpha's package.json. Empty string
+   * when npm returned nothing — we stamp gitHead ourselves on every
+   * alpha publish, but pre-feature alphas (or hand-published ones) may
+   * not have it.
+   */
+  priorGitHead: string;
+  /**
+   * Was the prior gitHead reachable in the current git history? When
+   * false (history rewritten, shallow clone, etc.), the planner can't
+   * tell whether the source moved — defaults to "publish to be safe."
+   */
+  priorHeadReachable: boolean;
+  /**
+   * Whether any commits between priorGitHead..HEAD touched this
+   * package's source. Only meaningful when priorHeadReachable is true.
+   */
+  sourceChangedSincePrior: boolean;
+  /** Tag of the prior version (e.g. "0.7.14-alpha.3"). Used in skip reason text. */
+  priorVersion: string;
+}
+
+export type AlphaSkipDecision = { skip: false; reason?: string } | { skip: true; reason: string };
+
+/**
+ * Pure decision function. Given the inputs the planner has gathered,
+ * decide whether this package should skip its alpha publish this run.
+ *
+ * Conservative bias: any signal we can't read cleanly defaults to
+ * publish. Specifically:
+ *   - N === 0 (no prior alpha) → publish (nothing to compare to).
+ *   - priorGitHead is empty → publish (can't tell if source changed).
+ *   - priorHead unreachable → publish (history likely got rewritten).
+ *   - sourceChanged → publish.
+ *   - everything else → skip (clean diff against prior alpha).
+ */
+export function decideAlphaSkip(inputs: AlphaSkipInputs): AlphaSkipDecision {
+  if (inputs.nextN === 0) return { skip: false };
+  if (!inputs.priorGitHead) {
+    return { skip: false, reason: `no gitHead on ${inputs.priorVersion}; publishing` };
+  }
+  if (!inputs.priorHeadReachable) {
+    return {
+      skip: false,
+      reason: `prior gitHead ${inputs.priorGitHead.slice(0, 8)} unreachable; publishing`,
+    };
+  }
+  if (inputs.sourceChangedSincePrior) {
+    return { skip: false };
+  }
+  return {
+    skip: true,
+    reason: `no source changes since ${inputs.priorVersion} (gitHead ${inputs.priorGitHead.slice(0, 8)})`,
+  };
+}
+
+// ─── Impure wrappers (npm + git I/O) ───────────────────────────────
+
+/**
+ * Next alpha number for `<semverCore>-alpha.N` on npm. Returns 0 if no
+ * alphas exist for this core (or the package isn't on npm yet). Matches
+ * the spec: N auto-increments per X.Y.Z, resets when the publisher bumps
+ * the core.
+ */
+export function nextAlphaNumber(name: string, semverCore: string): number {
+  const r = spawnSync('npm', ['view', name, 'versions', '--json'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  if (r.status !== 0) return 0;
+  let versions: string[];
+  try {
+    const parsed = JSON.parse(r.stdout || '[]');
+    versions = Array.isArray(parsed) ? parsed : [String(parsed)];
+  } catch {
+    return 0;
+  }
+  return pickNextAlphaN(versions, semverCore);
+}
+
+/**
+ * Did this package's source change since the last alpha publish?
+ *
+ * Reads the prior alpha's `gitHead` (stamped onto package.json by the
+ * executor during prior publishes) and asks git whether any commits
+ * between that head and current HEAD touched this package's source.
+ * Delegates the actual decision to `decideAlphaSkip` so the logic can
+ * be unit-tested without spawning anything.
+ */
+export function alphaSkipDecision(
+  pkg: string,
+  name: string,
+  semverCore: string,
+  nextN: number,
+): AlphaSkipDecision {
+  if (nextN === 0)
+    return decideAlphaSkip({
+      nextN,
+      priorGitHead: '',
+      priorHeadReachable: false,
+      sourceChangedSincePrior: false,
+      priorVersion: '',
+    });
+
+  const priorVersion = `${semverCore}-alpha.${nextN - 1}`;
+  const r = spawnSync('npm', ['view', `${name}@${priorVersion}`, 'gitHead'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  // `npm view` couldn't reach the registry / version — bias to publish.
+  if (r.status !== 0) return { skip: false };
+
+  const priorGitHead = r.stdout.trim();
+  if (!priorGitHead) {
+    return decideAlphaSkip({
+      nextN,
+      priorGitHead: '',
+      priorHeadReachable: false,
+      sourceChangedSincePrior: false,
+      priorVersion,
+    });
+  }
+
+  const log = spawnSync(
+    'git',
+    ['log', '--format=%H', `${priorGitHead}..HEAD`, '--', pkg, `:(exclude)${pkg}/node_modules`],
+    { cwd: REPO_ROOT, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' },
+  );
+
+  const priorHeadReachable = log.status === 0;
+  const sourceChangedSincePrior = priorHeadReachable && log.stdout.trim() !== '';
+
+  return decideAlphaSkip({
+    nextN,
+    priorGitHead,
+    priorHeadReachable,
+    sourceChangedSincePrior,
+    priorVersion,
+  });
+}

package/src/cli/commands/publish/changesets.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Changesets integration tests — covers the pure helpers in
+ * changesets.ts. The impure pieces (running `bunx changeset version`,
+ * doing git commits) are thin wrappers around well-tested external
+ * tools; we don't unit-test those.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { filterChangesetEntries, parseGitStatusFiles } from './changesets';
+
+describe('filterChangesetEntries', () => {
+  test('returns nothing for an empty dir', () => {
+    expect(filterChangesetEntries([])).toEqual([]);
+  });
+
+  test('returns only .md files', () => {
+    expect(
+      filterChangesetEntries([
+        'fancy-tigers-jump.md',
+        'config.json',
+        '.DS_Store',
+        'noisy-cats-walk.md',
+      ]),
+    ).toEqual(['fancy-tigers-jump.md', 'noisy-cats-walk.md']);
+  });
+
+  test('excludes README.md (the default scaffolding doc)', () => {
+    expect(filterChangesetEntries(['README.md', 'happy-birds-sing.md'])).toEqual([
+      'happy-birds-sing.md',
+    ]);
+  });
+
+  test('excludes config.json regardless of extension filtering', () => {
+    // config.json doesn't end in .md so it's already excluded by the
+    // extension filter; this test documents that the extension check
+    // alone is sufficient — no special-case needed for config.json.
+    expect(filterChangesetEntries(['config.json'])).toEqual([]);
+  });
+
+  test('preserves input order (changesets has no inherent ordering)', () => {
+    expect(filterChangesetEntries(['z-z-z.md', 'a-a-a.md', 'm-m-m.md'])).toEqual([
+      'z-z-z.md',
+      'a-a-a.md',
+      'm-m-m.md',
+    ]);
+  });
+});
+
+describe('parseGitStatusFiles', () => {
+  test('returns empty for empty input', () => {
+    expect(parseGitStatusFiles('')).toEqual([]);
+    expect(parseGitStatusFiles('\n\n')).toEqual([]);
+  });
+
+  test('parses modified and untracked entries (XY-space-path format)', () => {
+    const output = [
+      ' M packages/cli-display/package.json',
+      ' M packages/event-bus/package.json',
+      'A  packages/cli-display/CHANGELOG.md',
+      '?? .changeset/quick-flowers-jump.md',
+    ].join('\n');
+
+    expect(parseGitStatusFiles(output)).toEqual([
+      'packages/cli-display/package.json',
+      'packages/event-bus/package.json',
+      'packages/cli-display/CHANGELOG.md',
+      '.changeset/quick-flowers-jump.md',
+    ]);
+  });
+
+  test('handles deletions (changeset version removes consumed changesets)', () => {
+    const output = [' D .changeset/old-bumpy-cats.md', 'D  .changeset/consumed.md'].join('\n');
+
+    expect(parseGitStatusFiles(output)).toEqual([
+      '.changeset/old-bumpy-cats.md',
+      '.changeset/consumed.md',
+    ]);
+  });
+
+  test('handles renames (uses destination path)', () => {
+    const output = 'R  old/path.md -> new/path.md';
+    expect(parseGitStatusFiles(output)).toEqual(['new/path.md']);
+  });
+
+  test('ignores blank lines', () => {
+    const output = [' M foo.txt', '', '  ', ' M bar.txt'].join('\n');
+    expect(parseGitStatusFiles(output)).toEqual(['foo.txt', 'bar.txt']);
+  });
+});

package/src/cli/commands/publish/changesets.ts

@@ -0,0 +1,144 @@
+/**
+ * @changesets/cli integration — v2/PUBLILO_CLI.md Phase 4.
+ *
+ * Changesets is the "what versions does this publish produce" piece
+ * of the workflow. During dev, the operator runs `bun changeset` to
+ * record a pending bump as a markdown file under `.changeset/`. At
+ * publish time, `celilo publish` finds those pending changesets and
+ * runs `bunx changeset version` to apply the bumps (writes new
+ * versions to each affected package.json, generates / updates
+ * CHANGELOG.md, deletes the consumed changesets), then commits the
+ * resulting diff. The downstream workspace publisher reads from
+ * package.json as before — it doesn't need to know changesets exist.
+ *
+ * Falls back to "operator manually bumped package.json" when there
+ * are no pending changesets — preserving the muscle memory operators
+ * built during the pre-changesets era. The `--skip-changesets` flag
+ * is the escape hatch for cases where pending changesets exist but
+ * the operator wants to publish what's in source right now.
+ *
+ * Skipped entirely in alpha mode (alphas are throwaway pre-releases;
+ * applying changesets would burn them on alpha publishes) and in
+ * promote mode (promote is graduating an existing alpha, not bumping
+ * to a new version).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { REPO_ROOT } from './helpers';
+
+/**
+ * Pure: given a directory listing of `.changeset/`, return the
+ * filenames that represent actual pending changesets. Filters out
+ * `README.md` and `config.json` (the changesets default scaffolding)
+ * and anything that isn't a markdown file.
+ *
+ * Exposed for unit testing — `listPendingChangesets` is the disk
+ * wrapper.
+ */
+export function filterChangesetEntries(filenames: string[]): string[] {
+  return filenames.filter((f) => f.endsWith('.md') && f !== 'README.md');
+}
+
+/**
+ * List pending changesets. Returns absolute paths to the markdown
+ * files under `.changeset/` that represent actual unapplied bumps.
+ */
+export function listPendingChangesets(): string[] {
+  const dir = join(REPO_ROOT, '.changeset');
+  if (!existsSync(dir)) return [];
+  return filterChangesetEntries(readdirSync(dir)).map((f) => join(dir, f));
+}
+
+/**
+ * Parse `git status --porcelain` output into a list of file paths.
+ * Used to figure out exactly which files `bunx changeset version`
+ * touched so we can git-add them specifically (per CLAUDE.md's
+ * "prefer adding specific files by name" guidance).
+ *
+ * Pure — exposed so the test suite can exercise the parser without
+ * a real git invocation.
+ */
+export function parseGitStatusFiles(porcelainOutput: string): string[] {
+  const files: string[] = [];
+  for (const line of porcelainOutput.split('\n')) {
+    if (!line.trim()) continue;
+    // Porcelain format: "XY <path>" where XY is two-char status,
+    // followed by a space, followed by the path. Renamed entries
+    // use " -> " separator; for our purposes we only care about
+    // the destination side, which is what changeset version emits
+    // in the new-file case anyway.
+    const match = line.match(/^.{2}\s+(.+?)(?:\s+->\s+(.+))?$/);
+    if (!match) continue;
+    files.push(match[2] ?? match[1]);
+  }
+  return files;
+}
+
+/**
+ * Apply pending changesets:
+ *   1. Run `bunx changeset version` to bump every affected
+ *      package.json + write CHANGELOG.md + delete consumed
+ *      .changeset/*.md files.
+ *   2. Stage every file the previous step changed (parsed from
+ *      `git status --porcelain`).
+ *   3. Commit with a message naming the count.
+ *
+ * Throws on any failure; the caller decides what to do (typically:
+ * exit non-zero).
+ */
+export function applyPendingChangesets(pendingCount: number): void {
+  const versionResult = spawnSync('bunx', ['changeset', 'version'], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+  if (versionResult.status !== 0) {
+    throw new Error(`bunx changeset version failed (exit ${versionResult.status})`);
+  }
+
+  // Find every file changeset touched and stage it specifically.
+  const statusResult = spawnSync('git', ['status', '--porcelain'], {
+    cwd: REPO_ROOT,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  if (statusResult.status !== 0) {
+    throw new Error(`git status failed after changeset version (exit ${statusResult.status})`);
+  }
+  const changedFiles = parseGitStatusFiles(statusResult.stdout ?? '');
+  if (changedFiles.length === 0) {
+    // `bunx changeset version` ran but didn't change anything — possible
+    // if the changesets resolved to no-ops. Nothing to commit.
+    console.log('changeset version produced no changes — nothing to commit.');
+    return;
+  }
+
+  const addResult = spawnSync('git', ['add', '--', ...changedFiles], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+  if (addResult.status !== 0) {
+    throw new Error(`git add failed after changeset version (exit ${addResult.status})`);
+  }
+
+  const message = `publish: apply ${pendingCount} pending changeset${pendingCount === 1 ? '' : 's'}`;
+  const commitResult = spawnSync('git', ['commit', '-m', message], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+  if (commitResult.status !== 0) {
+    throw new Error(`git commit failed after changeset version (exit ${commitResult.status})`);
+  }
+}
+
+/**
+ * Display the pending changesets to the operator before prompting
+ * for approval. Shows relative paths (less noise than absolute).
+ */
+export function printPendingChangesets(paths: string[]): void {
+  console.log(`\n${paths.length} pending changeset${paths.length === 1 ? '' : 's'} found:`);
+  for (const p of paths) {
+    console.log(`  ${relative(REPO_ROOT, p)}`);
+  }
+}