@celilo/cli 0.3.30 → 0.4.0-alpha.0

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

@@ -0,0 +1,365 @@
+/**
+ * `celilo publish` entry point — thin orchestration over the
+ * planner/executor split (v2/PUBLILO_CLI.md Phase 2).
+ *
+ *   parse args  →  preflight  →  build plan  →  display  →  confirm  →  execute
+ *
+ * Each per-phase planner and executor lives in its own module
+ * (workspace.ts, consumer-pins.ts, global-install.ts,
+ * module-registry.ts); this file just wires them together and owns the
+ * top-level flag parsing + dry-run / release-touch / promote special
+ * paths.
+ *
+ * Both `celilo publish ...` (via the CLI dispatcher) and
+ * `bun run publish ...` (via the legacy shim at scripts/publish.ts)
+ * call `main()` here with their argv slice.
+ *
+ * Usage:
+ *   celilo publish                                  # publish (preflight first)
+ *   celilo publish --dry-run                        # preflight + plan, no changes
+ *   celilo publish --release-touch                  # auto-fix module stale-drift
+ *   celilo publish --allow-stale                    # skip stale-version safeguards
+ *   celilo publish -y / --yes                       # auto-confirm prompts
+ *   celilo publish --alpha                          # X.Y.Z-alpha.N to @alpha
+ *   celilo publish --alpha --track-alpha            # also force-pin alphas globally
+ *   celilo publish --alpha --alpha-modules          # also publish module +N
+ *   celilo publish --promote <pkg>@<alpha-version>  # graduate alpha to real
+ */
+
+import { execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import {
+  alphaSkipDecision,
+  isAlphaVersion,
+  nextAlphaNumber,
+  parsePackageSpec,
+  stripAlphaSuffix,
+} from './alpha';
+import {
+  applyPendingChangesets,
+  listPendingChangesets,
+  printPendingChangesets,
+} from './changesets';
+import { executePlan } from './execute';
+import { PACKAGES, REPO_ROOT, isPublished, readPkg } from './helpers';
+import { displayPlan, planPublish } from './plan';
+import {
+  applyReleaseTouch,
+  autoTouchAndCommit,
+  printPreflightReport,
+  runPreflight,
+} from './preflight';
+import type { PublishMode, PublishOptions } from './types';
+
+// ─── Confirm helper ────────────────────────────────────────────────
+
+// Set once at main() entry from the resolved argv. Module-scoped because
+// confirm() is called from a dozen places and threading the flag through
+// each path adds noise without lifting any decisions.
+let autoYes = false;
+
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) =>
+    rl.question(question, (a) => {
+      rl.close();
+      res(a);
+    }),
+  );
+}
+
+/**
+ * `-y` / `--yes` auto-confirms every prompt. Doesn't bypass the
+ * dirty-tree check or the stale-version safeguard — those are real
+ * gates, not just confirmations.
+ */
+async function confirm(question: string): Promise<boolean> {
+  if (autoYes) {
+    process.stdout.write(`${question}y  (auto-confirmed via -y)\n`);
+    return true;
+  }
+  const reply = await prompt(question);
+  return /^[Yy]$/.test(reply.trim());
+}
+
+// ─── Flag parsing ──────────────────────────────────────────────────
+
+interface ParsedFlags {
+  options: PublishOptions;
+  dryRun: boolean;
+  releaseTouch: boolean;
+  /**
+   * Suppresses the pending-changesets prompt at the top of normal-mode
+   * publishes. Use when there are unapplied changesets but the
+   * operator wants to ship what's in source right now (or pre-applied
+   * the bumps via `bunx changeset version` themselves). The flag has
+   * no effect in alpha or promote mode — those skip changesets
+   * categorically.
+   */
+  skipChangesets: boolean;
+}
+
+export function parseOptions(argv: string[]): ParsedFlags {
+  function takeFlagValue(flag: string): string | null {
+    const i = argv.indexOf(flag);
+    if (i < 0) return null;
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('-')) {
+      console.error(`✗ ${flag} requires a value (e.g. ${flag} @celilo/e2e@0.7.14-alpha.3)`);
+      process.exit(1);
+    }
+    return value;
+  }
+
+  const allowStale = argv.includes('--allow-stale');
+  const yes = argv.includes('-y') || argv.includes('--yes');
+  const dryRun = argv.includes('--dry-run') || argv.includes('-n');
+  const releaseTouch = argv.includes('--release-touch');
+  const alphaFlag = argv.includes('--alpha');
+  const trackAlphaFlag = argv.includes('--track-alpha');
+  const alphaModulesFlag = argv.includes('--alpha-modules');
+  const skipChangesets = argv.includes('--skip-changesets');
+  const promoteArg = takeFlagValue('--promote');
+
+  if (alphaFlag && promoteArg) {
+    console.error('✗ --alpha and --promote are mutually exclusive.');
+    process.exit(1);
+  }
+  if (trackAlphaFlag && !alphaFlag) {
+    console.error('✗ --track-alpha requires --alpha.');
+    process.exit(1);
+  }
+  if (alphaModulesFlag && !alphaFlag) {
+    console.error('✗ --alpha-modules requires --alpha.');
+    process.exit(1);
+  }
+  if (releaseTouch && (alphaFlag || promoteArg)) {
+    console.error('✗ --release-touch cannot be combined with --alpha or --promote.');
+    process.exit(1);
+  }
+
+  const mode: PublishMode = promoteArg
+    ? { kind: 'promote', target: parsePackageSpec(promoteArg) }
+    : alphaFlag
+      ? { kind: 'alpha', trackAlpha: trackAlphaFlag, alphaModules: alphaModulesFlag }
+      : { kind: 'normal' };
+
+  if (mode.kind === 'promote' && !isAlphaVersion(mode.target.version)) {
+    console.error(
+      `✗ --promote target "${mode.target.name}@${mode.target.version}" is not an alpha (no -alpha.N suffix).`,
+    );
+    process.exit(1);
+  }
+
+  return {
+    options: { allowStale, autoYes: yes, mode },
+    dryRun,
+    releaseTouch,
+    skipChangesets,
+  };
+}
+
+// ─── Special-case handlers ─────────────────────────────────────────
+
+async function handleDryRun(opts: PublishOptions): Promise<never> {
+  const report = runPreflight();
+  // Match the mode-aware blocking logic the real publish uses.
+  const skipWorkspaceStale = opts.mode.kind !== 'normal';
+  const skipModuleStale = opts.mode.kind === 'alpha';
+  printPreflightReport(report);
+
+  if (opts.mode.kind === 'alpha') {
+    console.log('\nAlpha publish plan:');
+    for (const pkg of PACKAGES) {
+      const { name, version } = readPkg(pkg);
+      if (!name || !version) continue;
+      const n = nextAlphaNumber(name, version);
+      const decision = alphaSkipDecision(pkg, name, version, n);
+      const note = decision.skip ? `  [skip: ${decision.reason}]` : '';
+      console.log(`  ${name.padEnd(32)} ${version} → ${version}-alpha.${n}  (${pkg})${note}`);
+    }
+  } else if (opts.mode.kind === 'promote') {
+    const base = stripAlphaSuffix(opts.mode.target.version);
+    console.log(
+      `\nPromote plan:\n  ${opts.mode.target.name.padEnd(32)} ${opts.mode.target.version} → ${base}`,
+    );
+  }
+
+  const anyIssue =
+    report.dirty ||
+    (!skipWorkspaceStale && report.workspaceStale.length > 0) ||
+    (!skipModuleStale && report.moduleStale.length > 0);
+  process.exit(anyIssue ? 1 : 0);
+}
+
+async function handleReleaseTouch(): Promise<never> {
+  const report = runPreflight();
+  if (report.dirty) {
+    console.error(
+      '✗ Working tree is dirty — refusing to touch manifests on top of uncommitted work.',
+    );
+    console.error('  Commit or stash first, then re-run --release-touch.\n');
+    console.error(execSync('git status --short', { encoding: 'utf-8', cwd: REPO_ROOT }));
+    process.exit(1);
+  }
+  if (report.workspaceStale.length > 0) {
+    console.error(
+      "✗ Workspace package(s) need real version bumps — these can't be release-touched:",
+    );
+    for (const i of report.workspaceStale) {
+      console.error(`    ${i.name}@${i.version}  (bump ${i.pkg}/package.json)`);
+    }
+    console.error(
+      '\n  Bump those manually, commit, then re-run --release-touch (or just `bun run publish`).',
+    );
+    process.exit(1);
+  }
+  applyReleaseTouch(report.moduleStale);
+  process.exit(0);
+}
+
+// ─── Main ──────────────────────────────────────────────────────────
+
+export async function main(argv: string[]): Promise<void> {
+  // process.chdir matches the prior script-scope behavior: many helpers
+  // run `git`, `bun`, `npm` as subprocesses without a cwd, relying on
+  // the publisher being at the monorepo root.
+  process.chdir(REPO_ROOT);
+
+  const { options, dryRun, releaseTouch, skipChangesets } = parseOptions(argv);
+  autoYes = options.autoYes;
+
+  if (dryRun) return handleDryRun(options);
+  if (releaseTouch) return handleReleaseTouch();
+
+  // Promote requires the alpha to actually exist on npm — otherwise
+  // there's nothing to graduate.
+  if (options.mode.kind === 'promote') {
+    if (!isPublished(options.mode.target.name, options.mode.target.version)) {
+      console.error(
+        `✗ Cannot promote: ${options.mode.target.name}@${options.mode.target.version} is not on npm.`,
+      );
+      process.exit(1);
+    }
+  }
+
+  // Preflight cascade: if only module manifests drifted (the common
+  // case), offer to auto-touch + commit + continue. For anything else,
+  // print and exit.
+  const preflight = runPreflight();
+  const skipWorkspaceStale = options.mode.kind !== 'normal';
+  const skipModuleStale = options.mode.kind === 'alpha';
+  const blocking =
+    preflight.dirty ||
+    (!skipWorkspaceStale && preflight.workspaceStale.length > 0) ||
+    (!skipModuleStale && preflight.moduleStale.length > 0);
+
+  if (blocking && !options.allowStale) {
+    const onlyModuleDrift =
+      !skipModuleStale &&
+      !preflight.dirty &&
+      preflight.workspaceStale.length === 0 &&
+      preflight.moduleStale.length > 0;
+
+    if (onlyModuleDrift) {
+      printPreflightReport(preflight);
+      const proceed = await confirm(
+        '\nAuto-touch the drifted manifests, commit, and continue with publish? [y/N] ',
+      );
+      if (!proceed) {
+        console.log(
+          '\nAborted. Run `bun run publish --release-touch` to touch without publishing.',
+        );
+        process.exit(1);
+      }
+      const { ok, recheck } = autoTouchAndCommit(preflight);
+      if (!ok) process.exit(1);
+      if (
+        recheck &&
+        (recheck.dirty || recheck.workspaceStale.length > 0 || recheck.moduleStale.length > 0)
+      ) {
+        console.error('\n✗ Preflight still has issues after auto-touch:');
+        printPreflightReport(recheck);
+        process.exit(1);
+      }
+      console.log(
+        `\n✓ Touched and committed ${preflight.moduleStale.length} manifest(s). Continuing with publish.\n`,
+      );
+    } else {
+      printPreflightReport(preflight);
+      process.exit(1);
+    }
+  } else if (blocking && options.allowStale) {
+    console.warn('\n⚠ Preflight issues detected; publishing anyway (--allow-stale):');
+    printPreflightReport(preflight);
+  }
+
+  // Changesets — Phase 4 of v2/PUBLILO_CLI.md. Only applies in normal
+  // mode: alpha publishes are throwaway prereleases (applying changesets
+  // would burn them on alpha publishes), and promote graduates an
+  // existing alpha rather than producing a new version. The
+  // --skip-changesets flag is the manual escape hatch.
+  if (options.mode.kind === 'normal' && !skipChangesets) {
+    const pending = listPendingChangesets();
+    if (pending.length > 0) {
+      printPendingChangesets(pending);
+      const apply = await confirm(
+        '\nApply changesets (bump versions, update changelogs, commit), then continue with publish? [Y/n] ',
+      );
+      if (!apply) {
+        console.log(
+          '\nAborted. Run with --skip-changesets to publish current package.json versions instead.',
+        );
+        process.exit(1);
+      }
+      try {
+        applyPendingChangesets(pending.length);
+      } catch (err) {
+        console.error(`\n✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+      // Re-run preflight on the post-bump tree so we don't proceed
+      // with an unexpected state (e.g. changeset version left
+      // something dirty that wasn't picked up by our git-add).
+      const recheck = runPreflight();
+      if (recheck.dirty) {
+        console.error('\n✗ Tree is dirty after applying changesets:');
+        printPreflightReport(recheck);
+        process.exit(1);
+      }
+      console.log(`\n✓ Applied ${pending.length} changeset(s). Continuing with publish.\n`);
+    }
+  }
+
+  const plan = planPublish(options);
+  displayPlan(plan);
+
+  // Alpha mode might have auto-skipped every package — bail before
+  // prompting for confirmation we don't need.
+  if (options.mode.kind === 'alpha' && plan.workspace.every((p) => p.skipReason !== undefined)) {
+    console.log('All packages skipped (no source changes since last alpha). Nothing to do.');
+    return;
+  }
+
+  if (!(await confirm('Proceed? [y/N] '))) {
+    console.log('Aborted.');
+    process.exit(0);
+  }
+
+  const result = await executePlan({ plan, confirm });
+
+  console.log('\n──────────────────────────────────────────────');
+  console.log(' Publish summary');
+  console.log('──────────────────────────────────────────────');
+  if (result.published.length) {
+    console.log('Published:');
+    for (const p of result.published) console.log(`  ✓ ${p.name}@${p.version}`);
+  }
+  if (result.skipped.length) {
+    console.log('Skipped:');
+    for (const s of result.skipped) console.log(`  - ${s}`);
+  }
+  if (!result.published.length && !result.skipped.length) {
+    console.log('Nothing to do.');
+  }
+}

package/src/cli/commands/publish/module-registry.test.ts

@@ -0,0 +1,40 @@
+/**
+ * Module-registry planner test — Phase 4 is the slimmest publish
+ * phase (revision selection lives inside `celilo module publish`),
+ * so the planner is a thin wrap around `listModuleDirs`. We test
+ * the pure inner `mapModuleDirsToItems` directly so the test surface
+ * doesn't need to mock `./helpers` — mocking that path leaks to
+ * unrelated tests via bun:test's process-global mock.module.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mapModuleDirsToItems } from './module-registry';
+
+describe('mapModuleDirsToItems', () => {
+  test('empty input → empty plan', () => {
+    expect(mapModuleDirsToItems([])).toEqual([]);
+  });
+
+  test('wraps each discovered module dir in a ModuleItem', () => {
+    expect(
+      mapModuleDirsToItems([
+        '/repo/modules/caddy',
+        '/repo/modules/homebridge',
+        '/repo/modules/dns-external',
+      ]),
+    ).toEqual([
+      { moduleDir: '/repo/modules/caddy' },
+      { moduleDir: '/repo/modules/homebridge' },
+      { moduleDir: '/repo/modules/dns-external' },
+    ]);
+  });
+
+  test('preserves input order', () => {
+    const result = mapModuleDirsToItems(['/repo/modules/z', '/repo/modules/a', '/repo/modules/m']);
+    expect(result.map((m) => m.moduleDir)).toEqual([
+      '/repo/modules/z',
+      '/repo/modules/a',
+      '/repo/modules/m',
+    ]);
+  });
+});

package/src/cli/commands/publish/module-registry.ts

@@ -0,0 +1,64 @@
+/**
+ * Module registry publish — Phase 4 of `celilo publish`.
+ *
+ * Phase 4 is the slimmest phase: revision selection and tarball
+ * construction live inside `celilo module publish` itself, so the plan
+ * only enumerates which module directories to ship. The executor
+ * shells out to a single `celilo module publish <dirs...>` invocation
+ * (using the local source, not the global install, so this script
+ * always runs the just-built CLI from this repo).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { REPO_ROOT, listModuleDirs } from './helpers';
+import type { ModuleItem } from './types';
+
+// ─── Planner ───────────────────────────────────────────────────────
+
+/**
+ * Pure wrapper: turn a list of module directories into the
+ * corresponding `ModuleItem[]`. Exists so the test surface can
+ * exercise the wrapping contract without mocking `listModuleDirs`
+ * (which lives in helpers.ts and is process-globally referenced by
+ * other modules — mocking it would leak to unrelated tests).
+ */
+export function mapModuleDirsToItems(dirs: string[]): ModuleItem[] {
+  return dirs.map((moduleDir) => ({ moduleDir }));
+}
+
+export function planModulePublish(): ModuleItem[] {
+  return mapModuleDirsToItems(listModuleDirs());
+}
+
+// ─── Executor ──────────────────────────────────────────────────────
+
+export function executeModulePublish(items: ModuleItem[], opts: { allowStale: boolean }): void {
+  if (items.length === 0) {
+    console.log('\nNo modules with manifest.yml found — skipping module-publish phase.');
+    return;
+  }
+
+  const modulesRoot = join(REPO_ROOT, 'modules');
+  if (!existsSync(modulesRoot)) {
+    console.log('\nNo modules/ directory at repo root — skipping module-publish phase.');
+    return;
+  }
+
+  console.log('\n──────────────────────────────────────────────');
+  console.log(' Publishing modules to celilo registry');
+  console.log('──────────────────────────────────────────────');
+  for (const m of items) console.log(`  ${relative(REPO_ROOT, m.moduleDir)}`);
+  console.log();
+
+  const cliEntry = join(REPO_ROOT, 'apps', 'celilo', 'src', 'cli', 'index.ts');
+  const args = ['run', cliEntry, 'module', 'publish', ...items.map((m) => m.moduleDir)];
+  if (opts.allowStale) args.push('--allow-stale');
+
+  const r = spawnSync('bun', args, { cwd: REPO_ROOT, stdio: 'inherit' });
+  if (r.status !== 0) {
+    console.error(`\n✗ Module publish failed (exit ${r.status}). Aborting.`);
+    process.exit(r.status ?? 1);
+  }
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Umbrella planner — composes the per-phase planners into a single
+ * `PublishPlan`.
+ *
+ * The planner is the value-add of v2/PUBLILO_CLI.md Phase 2: it does
+ * all the world-reads (npm view, git log, fs walks) and produces a
+ * typed description of every side effect the executor will perform.
+ * Dry-run prints the plan and exits; a real publish confirms the plan
+ * and hands it to the executor.
+ *
+ * Per-phase planners are imported lazily where needed so unit tests
+ * can mock individual phases without dragging in the others' I/O.
+ */
+
+import { planConsumerPins } from './consumer-pins';
+import { planGlobalUpdate } from './global-install';
+import { PACKAGES, buildWorkspaceVersionMap, currentGitHead } from './helpers';
+import { planModulePublish } from './module-registry';
+import { runPreflight } from './preflight';
+import type { PublishOptions, PublishPlan } from './types';
+import { planWorkspace } from './workspace';
+
+/**
+ * Build the full publish plan. Reads from the world (preflight, npm,
+ * git, fs); doesn't mutate.
+ *
+ * Phase gating per the spec:
+ * - normal:  all four phases planned.
+ * - alpha:   workspace planned; consumer pins SKIPPED (consumers
+ *            opt into @alpha manually); global update SKIPPED unless
+ *            --track-alpha; module publish SKIPPED unless
+ *            --alpha-modules.
+ * - promote: all four phases planned — this IS a real release.
+ *
+ * In alpha mode the consumer-pin / global-update / module-publish
+ * planners are simply not invoked, so their items stay empty in the
+ * returned plan. The executor reads the same flag combination to know
+ * which phases to actually run; the empty-list contract means "nothing
+ * to do here" either way.
+ */
+export function planPublish(opts: PublishOptions): PublishPlan {
+  const preflight = runPreflight();
+  const baseWorkspaceVersions = buildWorkspaceVersionMap();
+  const gitHead = currentGitHead();
+
+  const workspaceResult = planWorkspace({
+    mode: opts.mode,
+    packages: PACKAGES,
+    baseWorkspaceVersions,
+    gitHead,
+  });
+
+  // PROJECTED publish list — what executeWorkspace would land on
+  // npm if no per-package skips happen at execution time. Used to
+  // seed the global-update plan with force-pin targets.
+  const projectedPublishes = workspaceResult.items
+    .filter((item) => !item.skipReason)
+    .map((item) => ({ name: item.name, version: item.versionToPublish }));
+
+  const runPhase2 = opts.mode.kind !== 'alpha';
+  const runPhase3 = opts.mode.kind !== 'alpha' || opts.mode.trackAlpha;
+  const runPhase4 =
+    opts.mode.kind === 'normal' ||
+    opts.mode.kind === 'promote' ||
+    (opts.mode.kind === 'alpha' && opts.mode.alphaModules);
+
+  return {
+    mode: opts.mode,
+    options: opts,
+    preflight,
+    workspace: workspaceResult.items,
+    consumerPins: runPhase2 ? planConsumerPins() : [],
+    globalUpdate: runPhase3
+      ? planGlobalUpdate({
+          justPublished: projectedPublishes,
+          trackAlpha: opts.mode.kind === 'alpha' && opts.mode.trackAlpha,
+        })
+      : [],
+    modulePublish: runPhase4 ? planModulePublish() : [],
+  };
+}
+
+/**
+ * Print the plan for the operator. Called before any side effects (in
+ * both --dry-run and real publish), so confirmation is informed.
+ */
+export function displayPlan(plan: PublishPlan): void {
+  const mode = plan.mode;
+  const planLabel =
+    mode.kind === 'alpha'
+      ? 'Alpha publish plan'
+      : mode.kind === 'promote'
+        ? 'Promote plan'
+        : 'Publish plan';
+  console.log(`${planLabel} (in this order):\n`);
+  for (const p of plan.workspace) {
+    const arrow =
+      mode.kind === 'promote'
+        ? `${mode.target.version} → ${p.versionToPublish}`
+        : p.versionToPublish === p.baseVersion
+          ? p.versionToPublish
+          : `${p.baseVersion} → ${p.versionToPublish}`;
+    const note = p.skipReason ? `  [skip: ${p.skipReason}]` : '';
+    console.log(`  ${p.name.padEnd(32)} ${arrow}  (${p.pkg})${note}`);
+  }
+  console.log();
+}