@celilo/cli 0.3.30 → 0.4.0-alpha.1

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

@@ -0,0 +1,238 @@
+/**
+ * Preflight checks for `celilo publish` — dirty-tree, workspace
+ * stale-version, module stale-manifest. Builds a single
+ * `PreflightReport` so the planner can decide which gates apply for
+ * the current mode (alpha skips workspace + module stale; promote
+ * skips workspace stale; normal enforces all three).
+ *
+ * Also owns `--release-touch`: the auto-fix path for the
+ * release-only-drift case where source changed but manifest.yml
+ * didn't. Touch + commit + continue is automated when the publisher
+ * just hits Enter through it; otherwise --release-touch by itself
+ * touches and exits.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { checkModuleStale } from '../../../services/module-validator/git-hygiene';
+import {
+  PACKAGES,
+  REPO_ROOT,
+  isAncestor,
+  isPublished,
+  lastCommitTouching,
+  listModuleDirs,
+  readPkg,
+} from './helpers';
+import type { ModuleStaleIssue, PreflightReport, StalenessIssue } from './types';
+
+/**
+ * Detect "I bumped source but forgot to bump the version." If a package's
+ * current version is already on npm AND there are commits touching the
+ * package's source after the last commit that touched its package.json,
+ * the publish would silently skip — which is exactly how a feature add
+ * never makes it to npm.
+ *
+ * False positives: a commit that bumps a dependency in package.json
+ * (without changing the "version" field) resets staleness even though the
+ * version is still stale relative to the last bump. Acceptable for v1 —
+ * the common case (forget-to-bump after a feature commit) is caught.
+ */
+export function checkStaleVersion(pkg: string): StalenessIssue | null {
+  const { name, version } = readPkg(pkg);
+  if (!name || !version) return null;
+  if (!isPublished(name, version)) return null;
+  const lastPkgJson = lastCommitTouching([`${pkg}/package.json`]);
+  const lastSrc = lastCommitTouching([
+    pkg,
+    `:(exclude)${pkg}/package.json`,
+    `:(exclude)${pkg}/node_modules`,
+  ]);
+  if (!lastPkgJson || !lastSrc) return null;
+  if (lastSrc === lastPkgJson) return null;
+  if (!isAncestor(lastPkgJson, lastSrc)) return null;
+  return {
+    name,
+    pkg,
+    version,
+    lastSrcCommit: lastSrc,
+    lastPkgJsonCommit: lastPkgJson,
+  };
+}
+
+/**
+ * Run every precondition that can fail a publish, accumulating all
+ * issues into a single report. Used both by --dry-run (report-only) and
+ * by the normal publish flow (where it's the gate before any side
+ * effects run).
+ *
+ * Replaces the old "abort-on-first-failure per phase" pattern that made
+ * fresh releases require N round-trips when N modules drifted.
+ */
+export function runPreflight(): PreflightReport {
+  const dirtyOutput = execSync('git status --porcelain', {
+    encoding: 'utf-8',
+    cwd: REPO_ROOT,
+  }).trim();
+
+  const workspaceStale: StalenessIssue[] = [];
+  for (const pkg of PACKAGES) {
+    const issue = checkStaleVersion(pkg);
+    if (issue) workspaceStale.push(issue);
+  }
+
+  const moduleStale: ModuleStaleIssue[] = [];
+  for (const dir of listModuleDirs()) {
+    const issue = checkModuleStale(dir);
+    if (issue) {
+      moduleStale.push({
+        moduleDir: issue.moduleDir,
+        lastSrcCommit: issue.lastSrcCommit,
+        lastManifestCommit: issue.lastManifestCommit,
+      });
+    }
+  }
+
+  return {
+    dirty: dirtyOutput.length > 0,
+    dirtyOutput,
+    workspaceStale,
+    moduleStale,
+  };
+}
+
+/**
+ * Print a human-readable preflight report. Returns true if any issue is
+ * blocking (i.e. publish would fail without --allow-stale).
+ */
+export function printPreflightReport(report: PreflightReport): boolean {
+  let anyIssue = false;
+
+  if (report.dirty) {
+    anyIssue = true;
+    console.error('\n✗ Working tree has uncommitted changes:\n');
+    console.error(execSync('git status --short', { encoding: 'utf-8', cwd: REPO_ROOT }));
+    console.error('  fix: commit or stash, then re-run.');
+  }
+
+  if (report.workspaceStale.length > 0) {
+    anyIssue = true;
+    console.error('\n✗ Stale-version drift on workspace packages:\n');
+    for (const i of report.workspaceStale) {
+      console.error(`  ${i.name}@${i.version} is on npm, but commits touching ${i.pkg} landed`);
+      console.error(`  after the last ${i.pkg}/package.json change.`);
+      console.error(`    src commit:        ${i.lastSrcCommit.slice(0, 12)}`);
+      console.error(`    package.json commit: ${i.lastPkgJsonCommit.slice(0, 12)}`);
+      console.error(`    fix: bump ${i.pkg}/package.json#version, commit, re-run.`);
+      console.error();
+    }
+  }
+
+  if (report.moduleStale.length > 0) {
+    anyIssue = true;
+    console.error('\n✗ Stale-manifest drift on celilo modules:\n');
+    for (const i of report.moduleStale) {
+      const rel = relative(REPO_ROOT, i.moduleDir);
+      console.error(`  ${rel}: src committed after manifest.yml`);
+      console.error(`    src commit:          ${i.lastSrcCommit.slice(0, 12)}`);
+      console.error(`    manifest.yml commit: ${i.lastManifestCommit.slice(0, 12)}`);
+    }
+    console.error(
+      '    fix: bump manifest.yml#version (semver change), or run\n' +
+        '         `bun run publish --release-touch` to auto-touch all drifted\n' +
+        "         manifests with today's date (release-only — auto-revision\n" +
+        '         picks the next +N).',
+    );
+    console.error();
+  }
+
+  if (!anyIssue) {
+    console.log('✓ Preflight clean: no dirty tree, no stale workspace versions, no stale modules.');
+  } else {
+    console.error('Pass --allow-stale to publish anyway (the prior versions stay on npm).');
+  }
+
+  return anyIssue;
+}
+
+/**
+ * Append (or refresh) a `# released: <ISO timestamp>` trailing comment on
+ * the given manifest.yml. Always produces a fresh diff (timestamps are
+ * unique per second), so the resulting commit always advances past any
+ * source commit on the same day.
+ */
+export function touchManifestRelease(manifestPath: string): void {
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const original = readFileSync(manifestPath, 'utf-8');
+  const lines = original.split('\n');
+  const cleaned: string[] = [];
+  for (const line of lines) {
+    if (line.match(/^#\s*released:/)) continue;
+    cleaned.push(line);
+  }
+  while (cleaned.length > 0 && cleaned[cleaned.length - 1].trim() === '') {
+    cleaned.pop();
+  }
+  cleaned.push(`# released: ${now}`);
+  cleaned.push('');
+  writeFileSync(manifestPath, cleaned.join('\n'));
+}
+
+/**
+ * Apply --release-touch: rewrite every drifted manifest.yml with today's
+ * release marker. Doesn't commit — operator reviews `git diff` and
+ * commits explicitly so the touch lands as a documented release event,
+ * not as a silent script side-effect.
+ */
+export function applyReleaseTouch(issues: ModuleStaleIssue[]): void {
+  if (issues.length === 0) {
+    console.log('No module drift to touch — nothing to do.');
+    return;
+  }
+  console.log(`\nTouching ${issues.length} drifted manifest(s):`);
+  for (const i of issues) {
+    const manifestPath = join(i.moduleDir, 'manifest.yml');
+    touchManifestRelease(manifestPath);
+    console.log(`  ✎ ${relative(REPO_ROOT, manifestPath)}`);
+  }
+  console.log('\nReview with `git diff modules/`, commit, then re-run `bun run publish`.');
+}
+
+/**
+ * Auto-cascade for the common case: only modules drifted. Touches +
+ * commits + returns true if the operator approved continuing. Returns
+ * false if they aborted (caller should exit). Throws on git failure.
+ *
+ * Confirmation is gated by `autoYes` — when -y is set, the cascade
+ * runs without prompting. When false, the caller already prompted.
+ */
+export function autoTouchAndCommit(
+  report: PreflightReport,
+  spawnSyncFn: typeof spawnSync = spawnSync,
+): { ok: boolean; recheck: PreflightReport | null } {
+  applyReleaseTouch(report.moduleStale);
+  const manifestPaths = report.moduleStale.map((i) => join(i.moduleDir, 'manifest.yml'));
+  const stageResult = spawnSyncFn('git', ['add', '--', ...manifestPaths], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+  if (stageResult.status !== 0) {
+    console.error('git add failed; resolve manually and re-run.');
+    return { ok: false, recheck: null };
+  }
+  const commitMessage = `modules: release-touch drifted manifests (${report.moduleStale
+    .map((i) => relative(REPO_ROOT, i.moduleDir).replace('modules/', ''))
+    .join(', ')})`;
+  const commitResult = spawnSyncFn('git', ['commit', '-m', commitMessage], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+  if (commitResult.status !== 0) {
+    console.error('git commit failed; resolve manually and re-run.');
+    return { ok: false, recheck: null };
+  }
+
+  const recheck = runPreflight();
+  return { ok: true, recheck };
+}

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

@@ -0,0 +1,264 @@
+/**
+ * Type definitions for `celilo publish` — the planner/executor split per
+ * v2/PUBLILO_CLI.md Phase 2.
+ *
+ * The umbrella `PublishPlan` enumerates everything a publish run intends
+ * to do. It's produced by the pure planner (`plan.ts`) and consumed by
+ * the executor (`execute.ts`). The planner takes its inputs from
+ * discovery + flag parsing; the executor only mutates state described in
+ * the plan. Dry-run is "build plan, print it, exit"; a real publish is
+ * "build plan, confirm, execute."
+ */
+
+/**
+ * Subset of the npm package.json shape we touch. Kept narrow so the
+ * planner can't accidentally rely on fields not part of the contract.
+ */
+export interface PackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+}
+
+/**
+ * Single workspace package → npm-version mapping. Built once at the top
+ * of a publish run from each package's package.json#version. In alpha
+ * mode it gets tightened to the alpha versions before being threaded
+ * through to the workspace-dep rewriter, so cross-package alpha pins
+ * resolve to the alpha line.
+ */
+export type WorkspaceVersionMap = Map<string, string>;
+
+/**
+ * What kind of publish run is this? Most per-package decisions
+ * (preflight gating, version rewrite, bun publish flags, post-publish
+ * verification expectations) flow from this single discriminator.
+ *
+ * - `normal`:  bump real semver, publish to `@latest`, run Phase 2/3/4.
+ * - `alpha`:   publish `X.Y.Z-alpha.N` to the `@alpha` dist-tag. Skip
+ *              Phase 2 (consumer pins opt in via `@alpha` manually).
+ *              Phase 3 only runs when `trackAlpha`. Phase 4 only when
+ *              `alphaModules`.
+ * - `promote`: graduate a specific alpha to its base real version (e.g.
+ *              `@celilo/e2e@0.7.14-alpha.3` → `@celilo/e2e@0.7.14`).
+ *              Single package; Phase 2/3/4 run normally — this IS a
+ *              real release.
+ */
+export type PublishMode =
+  | { kind: 'normal' }
+  | { kind: 'alpha'; trackAlpha: boolean; alphaModules: boolean }
+  | { kind: 'promote'; target: { name: string; version: string } };
+
+/**
+ * Parsed top-level flag bundle. Produced by `parseOptions` and threaded
+ * into the planner. Doesn't include flag-validation errors — those bail
+ * out before reaching here.
+ */
+export interface PublishOptions {
+  allowStale: boolean;
+  autoYes: boolean;
+  mode: PublishMode;
+}
+
+/**
+ * One workspace package source committing past its package.json version.
+ * Surfaced by `checkStaleVersion` during preflight; blocks a normal
+ * publish unless --allow-stale.
+ */
+export interface StalenessIssue {
+  name: string;
+  pkg: string;
+  version: string;
+  lastSrcCommit: string;
+  lastPkgJsonCommit: string;
+}
+
+/**
+ * Module source committed past its manifest.yml. Surfaced by
+ * `checkModuleStale` during preflight; blocks a normal publish unless
+ * --allow-stale or `bun run publish --release-touch`.
+ */
+export interface ModuleStaleIssue {
+  moduleDir: string;
+  lastSrcCommit: string;
+  lastManifestCommit: string;
+}
+
+/**
+ * Snapshot of everything preflight learned about the working tree.
+ * Built once at the top of the run and threaded into the planner.
+ */
+export interface PreflightReport {
+  dirty: boolean;
+  dirtyOutput: string;
+  workspaceStale: StalenessIssue[];
+  moduleStale: ModuleStaleIssue[];
+}
+
+/**
+ * Single workspace:^ → explicit-pin rewrite recorded by
+ * `rewriteWorkspaceDeps`. Used by the executor for both the actual
+ * package.json mutation and the post-publish verification step.
+ */
+export interface WorkspaceRewrite {
+  depName: string;
+  bucket: string;
+  oldSpec: string;
+  newSpec: string;
+}
+
+/**
+ * Optional knobs for the package.json rewriter. Lifecycle: the planner
+ * decides which to set per package (per-mode), the executor applies them
+ * to the live file just before `bun publish` and restores from the
+ * captured `original` after.
+ */
+export interface RewriteOptions {
+  /**
+   * Force the package's `version` field to this value before publish.
+   * Used by --alpha (sets `X.Y.Z-alpha.N`) and --promote (forces the
+   * base `X.Y.Z` even if source disagrees).
+   */
+  targetVersion?: string;
+  /**
+   * Pin workspace deps to exact versions instead of `^`/`~`. Required for
+   * --alpha mode: pre-release semver excludes pre-release versions from
+   * caret ranges, so the only way to keep alpha consumers resolvable is
+   * to pin to the exact alpha that was just published.
+   */
+  exactPins?: boolean;
+  /**
+   * Stamp a `gitHead` field on the published package.json so future
+   * `--alpha` runs can detect "no source change since prior alpha" and
+   * skip. bun publish doesn't populate gitHead automatically.
+   */
+  gitHead?: string;
+}
+
+/**
+ * Per-package pre-publish work. Currently only `@celilo/e2e` triggers
+ * any of these (it ships netapps + registry server + caches inside its
+ * tarball), but the plan still enumerates them so dry-run can show
+ * what extra work the publish entails.
+ */
+export type PrePublishHookKind =
+  | 'registryServerBundle'
+  | 'rebuildE2eNetapps'
+  | 'stageE2ePublishCaches';
+
+/**
+ * Single workspace package planned to publish (or explicitly skip) in
+ * this run. The plan is built before any side effects so the dry-run
+ * can faithfully describe what `bun publish` would do.
+ */
+export interface WorkspaceItem {
+  /** Workspace path relative to REPO_ROOT (e.g. 'packages/e2e'). */
+  pkg: string;
+  /** npm package name (e.g. '@celilo/e2e'). */
+  name: string;
+  /** Version currently in this package's package.json. */
+  baseVersion: string;
+  /**
+   * What this run will publish. Same as `baseVersion` for normal mode,
+   * `X.Y.Z-alpha.N` for alpha mode, base-stripped for promote mode.
+   */
+  versionToPublish: string;
+  /** npm dist-tag override (only `'alpha'` for alpha mode; undefined → `@latest`). */
+  tag?: 'alpha';
+  /**
+   * Rewrite recipe applied to the package's package.json immediately
+   * before `bun publish`. Restored from `originalPackageJson` after.
+   */
+  rewriteOptions: RewriteOptions;
+  /** Pre-publish work to do (netapp rebuild, cache staging, etc.). */
+  hooks: PrePublishHookKind[];
+  /**
+   * If set, this package is explicitly NOT publishing this run (already
+   * on npm, source unchanged since prior alpha, etc.). The reason
+   * appears in the dry-run plan and the post-run summary.
+   */
+  skipReason?: string;
+}
+
+/**
+ * Pin update planned for a single consumer package.json. Generated by
+ * walking the in-repo modules/, apps/, packages/, and any
+ * EXTERNAL_PROJECT_PATHS, matching `@celilo/*` deps to current npm
+ * latests. Produced in `--normal` and `--promote` modes; skipped in
+ * `--alpha` (consumers opt into the @alpha tag manually).
+ */
+export interface ConsumerPinItem {
+  /** Absolute path to the package.json. */
+  filePath: string;
+  /** What this run will rewrite in that file. */
+  updates: Array<{
+    bucket: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+    depName: string;
+    oldSpec: string;
+    newSpec: string;
+  }>;
+}
+
+/**
+ * Single managed package planned to be force-pinned (or update-pulled)
+ * in bun's global install. `target` is the version we expect after the
+ * operation; `installed` is what's there now.
+ */
+export interface GlobalUpdateItem {
+  name: string;
+  installed: string | null;
+  target: string;
+  /**
+   * If true, the executor will run `bun add -g <name>@<target>` — force-
+   * pin to an exact version. Used for packages we just published this
+   * run (so the global ends up on the precise version, not whatever
+   * @latest resolves to a moment later).
+   *
+   * If false, the executor runs `bun update -g <name>` — chase whatever
+   * `@latest` is now. Used for managed packages that we didn't publish
+   * this run but might still be drifting in the global install.
+   */
+  forcePin: boolean;
+}
+
+/**
+ * Single module planned to publish to the celilo registry. Phase 4 is
+ * the slimmest phase: revision selection and tarball construction live
+ * inside `celilo module publish` itself, so the plan only needs to
+ * enumerate the directories.
+ */
+export interface ModuleItem {
+  moduleDir: string;
+}
+
+/**
+ * Umbrella plan — the central data structure of Phase 2 of the publish
+ * CLI refactor (v2/PUBLILO_CLI.md). One plan covers all four phases of
+ * a publish run; the executor consumes it top-to-bottom.
+ */
+export interface PublishPlan {
+  mode: PublishMode;
+  options: PublishOptions;
+  preflight: PreflightReport;
+  /** Workspace npm publishes — Phase 1 of the publish flow. */
+  workspace: WorkspaceItem[];
+  /** Consumer package.json pin bumps — Phase 2. */
+  consumerPins: ConsumerPinItem[];
+  /** bun global install force-pins / refreshes — Phase 3. */
+  globalUpdate: GlobalUpdateItem[];
+  /** Modules to publish to the celilo registry — Phase 4. */
+  modulePublish: ModuleItem[];
+}
+
+/**
+ * Aggregated outcome of a publish run. Mirrors the prior
+ * `runPublishPhase` return shape so the post-run summary can keep
+ * reporting the same way (published list + skipped list).
+ */
+export interface PublishResult {
+  published: Array<{ name: string; version: string }>;
+  skipped: string[];
+}