@rehearsal-db/core 0.1.0-beta.8 → 0.1.0-beta.9

package/src/cli/rehearsal.mjs

@@ -0,0 +1,933 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Run the versioned, project-configured Rehearsal developer CLI for
+ * initialization, readiness, planning, inspection, and verified local execution.
+ * Run: `npm run rehearsal -- doctor` or `npm run rehearsal -- explain`.
+ */
+
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { performance } from "node:perf_hooks";
+import { parseEnv } from "node:util";
+import { fileURLToPath } from "node:url";
+import * as prompts from "@clack/prompts";
+import {
+  createRehearsalResult,
+  normalizeRehearsalError,
+  renderHumanError,
+  serializeRehearsalError,
+} from "../shared/diagnostics.mjs";
+import {
+  inspectDetectedProject,
+  findRehearsalConfigPath,
+  loadRehearsalConfig,
+  renderDetectedConfig,
+} from "../project/configuration.mjs";
+import {
+  inspectRehearsalBaseline,
+  inspectRehearsalMigrations,
+  runRehearsalDoctor,
+} from "../runtime/plan.mjs";
+import { createSyntheticBaselineFromFiles } from "../baseline/builder.mjs";
+import {
+  applyBaselinePreparation,
+  inspectBaselineInputFiles,
+  planBaselinePreparation,
+  summarizeBaselinePreparation,
+} from "../baseline/preparation.mjs";
+import {
+  applyRehearsalSetup,
+  planRehearsalSetup,
+  summarizeRehearsalSetup,
+} from "../project/setup.mjs";
+import { formatCount } from "../shared/human_output.mjs";
+import { collectRehearsalSupportReport } from "../project/support_report.mjs";
+import {
+  applyRehearsalCleanup,
+  planRehearsalCleanup,
+} from "../runtime/cleanup.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+import { createPrivacyKey } from "../baseline/privacy_engine.mjs";
+import { createSourceAccessPlan } from "../source/access.mjs";
+import {
+  buildApplicationEnvironment,
+  runHttpProofs,
+  startApplicationSession,
+} from "../application/session.mjs";
+import {
+  applyIdentityClaim,
+  createIdentityClaimPlan,
+  validateIdentityPolicy,
+} from "../identity/claim.mjs";
+import { createSupabaseStorageTransfer } from "../identity/storage.mjs";
+import {
+  acquireProjectOperation,
+  assertInstalledPackageFingerprint,
+  createInstalledPackageFingerprint,
+} from "../shared/operation_guard.mjs";
+import {
+  commandMutatesProject,
+  parseArguments,
+  resetGuidedFlags,
+} from "./arguments.mjs";
+import {
+  formatDuration,
+  installGuidedExitShortcut,
+  isHumanTerminal,
+  terminalStyle,
+  useStyledPrompts,
+} from "./terminal.mjs";
+import { createGuidedHome } from "./guided.mjs";
+import {
+  buildRefreshWorkflowPlan,
+  createRefreshWorkflow,
+  loadPreparationContext,
+  runSourceAccess,
+  runSourceBaselineRefresh,
+  runSourceRetirement,
+} from "./source_commands.mjs";
+import {
+  buildRuntimeStackPlan,
+  createRuntimeCommands,
+  runRuntimeStackDoctor,
+  topologyCandidateSummary,
+  topologyCommandEnvironment,
+  topologyEnvironmentFiles,
+} from "./runtime_commands.mjs";
+import {
+  renderBaseline,
+  renderBaselineInputInspection,
+  renderBaselinePreparation,
+  renderCandidates,
+  renderCleanup,
+  renderDoctor,
+  formatBytes,
+  renderIdentityPlan,
+  renderInit,
+  renderMigrations,
+  renderPlan,
+  renderRefreshWorkflow,
+  renderSetup,
+  renderSourceAccessPlan,
+  renderSourceRetirement,
+  renderSupportReport,
+} from "./renderers.mjs";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+const projectRoot = process.cwd();
+let activePackageFingerprint = null;
+const commandStartedAt = new Date();
+const commandStartedMs = performance.now();
+const managerPath = join(packageRoot, "scripts/runtime/manage_database.mjs");
+let lastGuidedDetails;
+
+const {
+  prepareCandidateConfirmation,
+  prepareDependentTargets,
+  proveRuntimeStack,
+  runManager,
+  runRuntimeStack,
+} = createRuntimeCommands({
+  packageRoot,
+  projectRoot,
+  managerPath,
+  getActivePackageFingerprint: () => activePackageFingerprint,
+});
+
+const emit = ({ command, data, flags, render, status = "success" }) => {
+  const result = createRehearsalResult({
+    command,
+    status,
+    data,
+    startedAt: commandStartedAt,
+    durationMs: Math.round((performance.now() - commandStartedMs) * 100) / 100,
+  });
+  if (flags.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(render(data, flags.verbosity));
+};
+
+const runInit = async ({ flags }) => {
+  const detected = await inspectDetectedProject({ projectRoot });
+  const source = renderDetectedConfig(detected);
+  const destination = join(projectRoot, "rehearsal.config.mjs");
+  let existingPath = null;
+  try {
+    existingPath = await findRehearsalConfigPath({ projectRoot });
+  } catch (error) {
+    if (
+      !String(error?.message ?? error).startsWith("No Rehearsal configuration")
+    ) {
+      throw error;
+    }
+  }
+  if (existingPath) {
+    if (flags.write) {
+      throw new Error(
+        `A Rehearsal configuration already exists at ${relative(projectRoot, existingPath)}; Rehearsal will not overwrite it.`,
+      );
+    }
+    return {
+      mode: "existing",
+      destination: relative(projectRoot, existingPath),
+      detected,
+      source: "",
+      nextAction:
+        "Review the existing configuration, then run rehearsal doctor.",
+    };
+  }
+  if (flags.write)
+    await writeFile(destination, source, { flag: "wx", mode: 0o600 });
+  return {
+    mode: flags.write ? "written" : "preview",
+    destination: relative(projectRoot, destination),
+    detected,
+    source,
+    nextAction: flags.write
+      ? "Review the generated safety settings and run rehearsal doctor."
+      : "Review this preview, then rerun rehearsal init --write to create it.",
+  };
+};
+
+const runSetup = async ({ flags, planOptions }) => {
+  const plan =
+    flags.setupPlan ??
+    (await planRehearsalSetup({
+      projectRoot,
+      target: flags.target ?? "supabase",
+    }));
+  if (flags.write) await applyRehearsalSetup(plan);
+  const result = summarizeRehearsalSetup(plan, {
+    mode: flags.write ? "written" : "preview",
+  });
+  if (!flags.write) return result;
+  const readiness = await runRehearsalDoctor(planOptions);
+  const needsBaselinePolicy = readiness.checks.some(
+    (check) => check.id === "sanitization-policy" && check.status === "fail",
+  );
+  return {
+    ...result,
+    readiness,
+    nextAction:
+      readiness.state === "READY"
+        ? "Next: run rehearsal explain to review the migration plan."
+        : needsBaselinePolicy
+          ? flags.guided
+            ? "Next: choose Prepare the script to create a reviewable policy draft."
+            : "Next: run rehearsal again and choose Prepare a reviewable baseline policy draft."
+          : "Next: complete the remaining readiness items shown above.",
+  };
+};
+
+const runBaselinePreparation = async ({ flags, planOptions }) => {
+  const plan =
+    flags.preparationPlan ??
+    (await planBaselinePreparation({
+      ...planOptions,
+      recordsPath: flags.recordsPath,
+      ledgerPath: flags.ledgerPath,
+    }));
+  if (flags.write) await applyBaselinePreparation(plan);
+  const result = summarizeBaselinePreparation(plan, {
+    mode: flags.write ? "written" : "preview",
+  });
+  return flags.guided && flags.write
+    ? {
+        ...result,
+        nextAction:
+          "Next: choose Review the script to classify every column interactively.",
+      }
+    : result;
+};
+
+const planRuntimeStackCleanup = async ({ flags, planOptions }) => {
+  const topology = await loadRuntimeTopology(planOptions);
+  const targets = [];
+  for (const target of topology.targets) {
+    targets.push({
+      name: target.name,
+      configPath: target.configPath,
+      plan: await planRehearsalCleanup({
+        projectRoot: topology.projectRoot,
+        configPath: target.configPath,
+        includeRuntime: flags.includeRuntime,
+        includeImages: flags.includeImages && target.primary,
+      }),
+    });
+  }
+  if (targets.length === 1) return targets[0].plan;
+  return {
+    digest: createHash("sha256")
+      .update(
+        JSON.stringify(
+          targets.map((target) => ({
+            name: target.name,
+            digest: target.plan.digest,
+          })),
+        ),
+      )
+      .digest("hex"),
+    targets,
+  };
+};
+
+const runCleanup = async ({ flags, planOptions }) => {
+  const plan =
+    flags.cleanupPlan ??
+    (await planRuntimeStackCleanup({ flags, planOptions }));
+  if (!flags.write) return { mode: "preview", plan };
+  if (plan.targets) {
+    if (flags.cleanupConfirmation !== plan.digest) {
+      throw new Error(
+        "Cleanup requires the exact --confirm-cleanup digest from a fresh preview. Nothing was removed.",
+      );
+    }
+    for (const target of plan.targets) {
+      const refreshed = await planRehearsalCleanup({
+        projectRoot,
+        configPath: target.configPath,
+        includeRuntime: target.plan.runtime.included,
+        includeImages: target.plan.images.requested,
+      });
+      if (refreshed.digest !== target.plan.digest) {
+        throw new Error(
+          `Cleanup targets changed for ${target.name} after the preview. Nothing was removed; preview the cleanup again.`,
+        );
+      }
+    }
+    const appliedTargets = [];
+    for (const target of plan.targets) {
+      appliedTargets.push({
+        name: target.name,
+        applied: await applyRehearsalCleanup({
+          plan: target.plan,
+          confirmation: target.plan.digest,
+          projectRoot,
+          configPath: target.configPath,
+          removeRuntime: async () => {
+            runManager({
+              action: "discard",
+              flags,
+              configPath: target.configPath,
+              targetName: target.name,
+            });
+          },
+        }),
+      });
+    }
+    return {
+      mode: "written",
+      plan,
+      applied: { targets: appliedTargets },
+    };
+  }
+  const applied = await applyRehearsalCleanup({
+    plan,
+    confirmation: flags.cleanupConfirmation,
+    ...planOptions,
+    removeRuntime: async () => {
+      runManager({ action: "discard", flags });
+    },
+  });
+  return { mode: "written", plan, applied };
+};
+
+const loadIdentityClaimPlan = async ({ flags, planOptions }) => {
+  const loaded = await loadRehearsalConfig(planOptions);
+  if (!loaded.paths.identityPolicy) {
+    throw new Error("No config.identityPolicy is configured.");
+  }
+  if (!flags.identityName) {
+    throw new Error("Choose a declared identity with --identity=<name>.");
+  }
+  const policy = validateIdentityPolicy(
+    JSON.parse(await readFile(loaded.paths.identityPolicy, "utf8")),
+  );
+  return {
+    loaded,
+    plan: createIdentityClaimPlan({
+      policy,
+      name: flags.identityName,
+    }),
+  };
+};
+
+const usage = () => `Usage: rehearsal <command> [options]
+
+Commands:
+  guide                       Open the interactive, state-aware home screen
+  setup [--target=] [--write] Preview or create safe first-run scaffolding
+  init [--write]              Preview or explicitly write safe starter config
+  baseline prepare --records= --ledger= [--write] Create a fail-closed policy draft
+  baseline create --records= --ledger= [--assets=] Create a baseline from safe local inputs
+  privacy key [--write]       Preview or create the owner-only pseudonym key
+  source plan                 Preview exact, temporary source access
+  source apply --confirm-source-access= Apply the reviewed source-access plan
+  source retire [--confirm-source-retirement=] Preview or retire exact source access
+  baseline refresh            Replace only the baseline from a reviewed source
+  refresh [--confirm-refresh=] Replace the database copy, reset locally, and remove old copies
+  identity plan --identity=   Preview an approved local identity association
+  identity claim --identity= --confirm-identity= Apply the exact local association
+  doctor                     Check whether Rehearsal is safe and ready
+  support                    Print a safe, copy-ready support report
+  explain                    Show the immutable execution plan
+  run --dry-run              Alias the exact explain plan without mutations
+  run --confirm-candidates=  Execute reset, migration, and verification locally
+  candidates                 Show the exact pending migration digest
+  inspect baseline           Show verified baseline provenance
+  inspect migrations         Classify represented, applied, and candidate migrations
+  start                      Start an existing verified local runtime
+  migrate --confirm-candidates= Apply the exact candidate suffix without resetting
+  reset                      Restore and verify the immutable local baseline
+  status                     Report the disposable local runtime state
+  stop                       Stop only this project's local runtime
+  discard                    Remove only this project's disposable runtime
+  cleanup [--include-runtime] [--include-images] [--write] [--confirm-cleanup=]
+                             Preview or apply conservative disk cleanup
+  verify                     Verify the current local Rehearsal runtime
+
+Options: --json --verbose --debug --plain --config=<path> --target=supabase|postgresql
+         --confirm-source-access=<digest> --confirm-source-retirement=<digest>
+         --confirm-refresh=<digest>`;
+
+const runRefreshWorkflow = createRefreshWorkflow({
+  runRuntimeStack,
+  prepareDependentTargets,
+  topologyCommandEnvironment,
+});
+
+const runGuidedHome = createGuidedHome({
+  projectRoot,
+  topologyCandidateSummary,
+  buildRefreshWorkflowPlan,
+  planRuntimeStackCleanup,
+  getLastGuidedDetails: () => lastGuidedDetails,
+});
+
+const executeCommand = async ({ command, flags, planOptions, guided }) => {
+  if (command === "help" || flags.help) {
+    console.log(usage());
+    return;
+  }
+  if (command === "setup") {
+    const data = await runSetup({ flags, planOptions });
+    emit({ command, data, flags, render: renderSetup });
+    return;
+  }
+  if (command === "init") {
+    const data = await runInit({ flags });
+    emit({ command, data, flags, render: renderInit });
+    return;
+  }
+  if (command === "baseline prepare") {
+    const data = await runBaselinePreparation({ flags, planOptions });
+    emit({
+      command,
+      data,
+      flags,
+      render: (result) => renderBaselinePreparation(result, flags),
+    });
+    return;
+  }
+  if (command === "baseline create") {
+    await inspectBaselineInputFiles({
+      ...planOptions,
+      recordsPath: flags.recordsPath,
+      ledgerPath: flags.ledgerPath,
+      assetsPath: flags.assetsPath,
+    });
+    const data = await createSyntheticBaselineFromFiles({
+      ...planOptions,
+      recordsPath: flags.recordsPath,
+      ledgerPath: flags.ledgerPath,
+      assetsPath: flags.assetsPath,
+    });
+    emit({
+      command,
+      data,
+      flags,
+      render: (baseline) =>
+        [
+          `Activated synthetic baseline ${baseline.generationId}: ${formatCount(baseline.rowCount, "row")} across ${formatCount(baseline.tableCount, "table")}; ${formatCount(baseline.migrationCount, "migration")} through ${baseline.migrationCutoff}.`,
+          "",
+          flags.guided
+            ? "Next: choose Run a rehearsal when you are ready."
+            : "Next: run rehearsal doctor to check readiness.",
+        ].join("\n"),
+    });
+    return;
+  }
+  if (command === "privacy key") {
+    const { loaded } = await loadPreparationContext(planOptions);
+    const data = flags.write
+      ? {
+          mode: "written",
+          path: relative(loaded.projectRoot, loaded.paths.privacyKey),
+          ...(await createPrivacyKey(loaded.paths.privacyKey)),
+        }
+      : {
+          mode: "preview",
+          path: relative(loaded.projectRoot, loaded.paths.privacyKey),
+        };
+    emit({
+      command,
+      data,
+      flags,
+      render: (result) =>
+        result.mode === "preview"
+          ? `PRIVACY KEY — PREVIEW\n\nWould create ${result.path} with owner-only permissions.\nNothing was written. Rerun with --write after reviewing the path.`
+          : `Created owner-only privacy key at ${result.path}.\nFingerprint: ${result.fingerprint}\nThe key is excluded from source control and must not be shared.`,
+    });
+    return;
+  }
+  if (command === "source plan") {
+    const { sourcePolicy } = await loadPreparationContext(planOptions);
+    const data = createSourceAccessPlan({ policy: sourcePolicy });
+    emit({ command, data, flags, render: renderSourceAccessPlan });
+    return;
+  }
+  if (command === "source apply") {
+    const data = await runSourceAccess({ flags, planOptions });
+    emit({
+      command,
+      data,
+      flags,
+      render: (result) =>
+        result.mode === "preview"
+          ? renderSourceAccessPlan(result.plan)
+          : [
+              "SOURCE ACCESS — READY",
+              `Temporary reader expires: ${result.receipt.expiresAt}`,
+              `Local credential: ${result.credentialFile}`,
+              "",
+              "Next: run rehearsal baseline refresh, then retire source access.",
+            ].join("\n"),
+    });
+    return;
+  }
+  if (command === "source retire") {
+    const data = await runSourceRetirement({ flags, planOptions });
+    emit({ command, data, flags, render: renderSourceRetirement });
+    return;
+  }
+  if (command === "baseline refresh") {
+    const data = await runSourceBaselineRefresh({ planOptions });
+    emit({
+      command,
+      data,
+      flags,
+      render: (result) =>
+        [
+          `Activated refreshed baseline ${result.generationId}.`,
+          `${formatCount(result.manifest.rowCount, "sanitized row")} across ${formatCount(Object.keys(result.manifest.tableCounts).length, "table")}.`,
+          `Source estimate: ${formatCount(result.estimate.rows, "row")}, ${formatBytes(result.estimate.bytes)}.`,
+          "",
+          "Next: run rehearsal source retire, then rehearsal doctor.",
+        ].join("\n"),
+    });
+    return;
+  }
+  if (command === "refresh") {
+    const data = await runRefreshWorkflow({ flags, planOptions });
+    emit({ command, data, flags, render: renderRefreshWorkflow });
+    return;
+  }
+  if (command === "identity plan" || command === "identity claim") {
+    const { loaded, plan } = await loadIdentityClaimPlan({
+      flags,
+      planOptions,
+    });
+    if (command === "identity plan" || !flags.identityConfirmation) {
+      emit({
+        command,
+        data: { mode: "preview", plan },
+        flags,
+        render: renderIdentityPlan,
+      });
+      return;
+    }
+    const runtimeEnvironment = parseEnv(
+      await readFile(loaded.paths.applicationEnvironment, "utf8"),
+    );
+    if (!runtimeEnvironment.DATABASE_URL) {
+      throw new Error("The local runtime environment has no DATABASE_URL.");
+    }
+    const result = await applyIdentityClaim({
+      plan,
+      confirmation: flags.identityConfirmation,
+      connectionString: runtimeEnvironment.DATABASE_URL,
+      storageTransfer: plan.identity.assets.some((asset) => asset.rewritePath)
+        ? createSupabaseStorageTransfer({
+            url: runtimeEnvironment.SUPABASE_URL,
+            serviceRoleKey: runtimeEnvironment.SUPABASE_SERVICE_ROLE_KEY,
+          })
+        : undefined,
+    });
+    emit({
+      command,
+      data: { mode: "written", plan, result },
+      flags,
+      render: renderIdentityPlan,
+    });
+    return;
+  }
+  if (command === "doctor") {
+    const data = await runRuntimeStackDoctor(planOptions);
+    emit({
+      command,
+      data,
+      flags,
+      render: renderDoctor,
+      status: data.state === "READY" ? "success" : "not_ready",
+    });
+    if (data.state !== "READY" && !guided) process.exitCode = 1;
+    return;
+  }
+  if (command === "support") {
+    const data = await collectRehearsalSupportReport(planOptions, {
+      runDoctor: async (options) => {
+        const report = await runRuntimeStackDoctor(options);
+        const targetAliases = new Map();
+        const aliasFor = (name) => {
+          if (!targetAliases.has(name)) {
+            targetAliases.set(name, `runtime-${targetAliases.size + 1}`);
+          }
+          return targetAliases.get(name);
+        };
+        return {
+          ...report,
+          checks: report.checks.map((check) => {
+            const separator = check.id.indexOf(":");
+            if (separator === -1) return check;
+            const target = check.id.slice(0, separator);
+            const alias = aliasFor(target);
+            return {
+              ...check,
+              id: `${alias}:${check.id.slice(separator + 1)}`,
+              label: check.label.replace(`${target}:`, `${alias}:`),
+            };
+          }),
+        };
+      },
+    });
+    emit({ command, data, flags, render: renderSupportReport });
+    return;
+  }
+  if (command === "cleanup") {
+    const data = await runCleanup({ flags, planOptions });
+    emit({ command, data, flags, render: renderCleanup });
+    return;
+  }
+  if (command === "explain" || (command === "run" && flags.dryRun)) {
+    const data = await buildRuntimeStackPlan(planOptions);
+    emit({ command, data, flags, render: renderPlan });
+    return;
+  }
+  if (command === "inspect baseline") {
+    const data = await inspectRehearsalBaseline(planOptions);
+    emit({ command, data, flags, render: renderBaseline });
+    return;
+  }
+  if (command === "inspect migrations") {
+    const data = await inspectRehearsalMigrations(planOptions);
+    emit({ command, data, flags, render: renderMigrations });
+    return;
+  }
+  if (command === "candidates") {
+    const { topology: _topology, ...data } =
+      await topologyCandidateSummary(planOptions);
+    emit({ command, data, flags, render: renderCandidates });
+    return;
+  }
+  if (
+    [
+      "run",
+      "start",
+      "migrate",
+      "reset",
+      "status",
+      "stop",
+      "discard",
+      "verify",
+    ].includes(command)
+  ) {
+    if (flags.dryRun && command !== "run") {
+      throw new Error("--dry-run is supported only by rehearsal run.");
+    }
+    if (
+      !(await prepareCandidateConfirmation({ command, flags, planOptions }))
+    ) {
+      return;
+    }
+    const stack = await runRuntimeStack({ command, flags, planOptions });
+    const { runtime, topology } = stack;
+    const stackEnvironment = topologyCommandEnvironment(topology);
+    const preparations = ["run", "reset", "migrate"].includes(command)
+      ? prepareDependentTargets({
+          topology,
+          environment: stackEnvironment,
+        })
+      : [];
+    let applicationProof;
+    let dependentProofs = [];
+    let httpProofResults = [];
+    let applicationReadiness;
+    if (command === "run") {
+      const applicationConfig = topology.primary.config.application;
+      const mappedApplicationEnvironment = Object.keys(
+        applicationConfig.environmentVariables,
+      ).length
+        ? await buildApplicationEnvironment({
+            files: topologyEnvironmentFiles(topology),
+            mappings: applicationConfig.environmentVariables,
+          })
+        : {};
+      const proofEnvironment = {
+        ...stackEnvironment,
+        ...mappedApplicationEnvironment,
+      };
+      const proofLabel =
+        topology.targets.length > 1
+          ? "project-owned dependent and application proofs"
+          : "project-owned application proof";
+      const proofSpinner = useStyledPrompts(flags) ? prompts.spinner() : null;
+      if (proofSpinner) {
+        proofSpinner.start(`Running the ${proofLabel}.`);
+      } else if (isHumanTerminal(flags)) {
+        console.log(
+          `${terminalStyle(flags, "36", "→")} Running the ${proofLabel}.`,
+        );
+      }
+      let applicationSession;
+      try {
+        if (applicationConfig.readiness) {
+          applicationSession = await startApplicationSession({
+            command: applicationConfig.startCommand,
+            cwd: topology.projectRoot,
+            files: topologyEnvironmentFiles(topology),
+            mappings: applicationConfig.environmentVariables,
+            readiness: applicationConfig.readiness,
+          });
+          applicationReadiness = applicationSession.ready;
+        }
+        ({ applicationProof, dependentProofs } = await proveRuntimeStack({
+          topology,
+          planOptions,
+          environment: proofEnvironment,
+        }));
+        if (applicationConfig.httpProofs.length) {
+          httpProofResults = await runHttpProofs({
+            checks: applicationConfig.httpProofs,
+          });
+        }
+      } catch (error) {
+        if (proofSpinner) proofSpinner.stop("A project proof failed.");
+        throw error;
+      } finally {
+        await applicationSession?.stop();
+      }
+      if (proofSpinner) {
+        proofSpinner.stop("Project proofs passed.");
+      } else if (isHumanTerminal(flags)) {
+        console.log(
+          `${terminalStyle(flags, "32", "✓")} Project proofs passed.`,
+        );
+      }
+    }
+    const data =
+      command === "run"
+        ? {
+            runtime,
+            preparations,
+            dependentProofs,
+            applicationProof,
+            applicationReadiness,
+            httpProofResults,
+          }
+        : preparations.length
+          ? { ...runtime, preparations }
+          : runtime;
+    if (guided) {
+      lastGuidedDetails = [
+        runtime.output,
+        ...preparations.map((preparation) => preparation.output),
+        ...dependentProofs.map((proof) => proof.output),
+        applicationProof?.output,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    }
+    emit({
+      command,
+      data,
+      flags,
+      render: (value) => {
+        const runtimeResult = value.runtime ?? value;
+        const nextAction = {
+          run: "Next: exercise the local application, then run rehearsal verify.",
+          start:
+            "Next: exercise the local application or run rehearsal status.",
+          migrate: "Next: run rehearsal verify to prove the current runtime.",
+          reset: "Next: run rehearsal verify or continue testing locally.",
+          status: "Next: run rehearsal verify, reset, stop, or discard.",
+          stop: "Next: run rehearsal start when you want to resume.",
+          discard:
+            "The disposable runtime was removed; the immutable baseline remains.",
+          verify:
+            "Next: continue testing, reset to the baseline, or stop the runtime.",
+        }[runtimeResult.action];
+        if (guided) {
+          const title =
+            runtimeResult.action === "run"
+              ? "REHEARSAL PASSED"
+              : "ACTION COMPLETE";
+          return [
+            title,
+            `✓ ${runtimeResult.action} completed in ${formatDuration(runtimeResult.durationMs)}`,
+            ...(value.preparations ?? []).map(
+              (preparation) =>
+                `✓ ${preparation.target} preparation passed: ${preparation.command}`,
+            ),
+            ...(value.dependentProofs ?? []).map(
+              (proof) => `✓ ${proof.target} proof passed: ${proof.command}`,
+            ),
+            value.applicationProof
+              ? `✓ Application proof passed: ${value.applicationProof.command}`
+              : null,
+            value.applicationReadiness
+              ? `✓ Application became ready at ${value.applicationReadiness.url}`
+              : null,
+            ...(value.httpProofResults ?? []).map(
+              (proof) => `✓ ${proof.kind} HTTP proof passed: ${proof.name}`,
+            ),
+            "",
+            "Technical output is available from Show details in the guide.",
+          ]
+            .filter(Boolean)
+            .join("\n");
+        }
+        return [
+          runtimeResult.output ||
+            `Rehearsal ${runtimeResult.action} completed.`,
+          ...(value.preparations ?? []).map(
+            (preparation) =>
+              `${preparation.target} preparation passed: ${preparation.command}`,
+          ),
+          ...(value.dependentProofs ?? []).map(
+            (proof) => `${proof.target} proof passed: ${proof.command}`,
+          ),
+          value.applicationProof
+            ? `Application proof passed: ${value.applicationProof.command}`
+            : null,
+          value.applicationReadiness
+            ? `Application readiness passed: ${value.applicationReadiness.url}`
+            : null,
+          ...(value.httpProofResults ?? []).map(
+            (proof) => `${proof.kind} HTTP proof passed: ${proof.name}`,
+          ),
+          nextAction ? "" : null,
+          nextAction,
+        ]
+          .filter((entry) => entry !== null)
+          .join("\n");
+      },
+    });
+    return;
+  }
+  throw new Error(`Unknown Rehearsal command: ${command}.\n\n${usage()}`);
+};
+
+const main = async () => {
+  const { flags, positionals } = parseArguments(process.argv.slice(2));
+  const command = positionals.join(" ") || "help";
+  const planOptions = {
+    projectRoot,
+    configPath: flags.configPath,
+  };
+  const wantsAutomaticGuide =
+    positionals.length === 0 &&
+    !flags.help &&
+    !flags.json &&
+    process.stdin.isTTY &&
+    process.stdout.isTTY;
+  const guided = command === "guide" || wantsAutomaticGuide;
+  const mutating = commandMutatesProject({ command, flags, guided });
+  const operation = mutating
+    ? await acquireProjectOperation({ projectRoot, command })
+    : null;
+  if (operation) {
+    activePackageFingerprint = createInstalledPackageFingerprint({
+      packageRoot,
+    });
+  }
+  try {
+    if (!guided) {
+      await executeCommand({ command, flags, planOptions, guided: false });
+      return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      throw new Error(
+        "The guided home screen requires an interactive terminal. Run rehearsal --help to list scriptable commands.",
+      );
+    }
+    flags.guided = true;
+    const removeGuidedExitShortcut = installGuidedExitShortcut(flags, {
+      beforeExit: () => operation?.releaseSync(),
+    });
+    if (useStyledPrompts(flags)) {
+      prompts.intro("REHEARSAL · Safe local migration testing");
+    }
+    try {
+      while (true) {
+        resetGuidedFlags(flags);
+        const selected = await runGuidedHome({ flags, planOptions });
+        if (!selected) break;
+        if (selected === "home") continue;
+        await executeCommand({
+          command: selected,
+          flags,
+          planOptions,
+          guided: true,
+        });
+      }
+    } finally {
+      removeGuidedExitShortcut();
+    }
+    if (useStyledPrompts(flags)) {
+      prompts.outro("See you at the next rehearsal.");
+    } else {
+      console.log("See you at the next rehearsal.");
+    }
+  } finally {
+    if (operation) {
+      try {
+        assertInstalledPackageFingerprint({
+          packageRoot,
+          expected: activePackageFingerprint,
+        });
+      } finally {
+        activePackageFingerprint = null;
+        await operation.release();
+      }
+    }
+  }
+};
+
+try {
+  await main();
+} catch (error) {
+  const failure = normalizeRehearsalError(error, {
+    expected: "a safe, versioned, local-only Rehearsal operation",
+    actual: String(error?.message ?? error),
+    refused: "No further Rehearsal action was performed.",
+    suggestions: ["Run rehearsal doctor for actionable readiness checks."],
+  });
+  const wantsJson = process.argv.includes("--json");
+  const debug = process.argv.includes("--debug");
+  if (wantsJson)
+    console.log(
+      JSON.stringify(serializeRehearsalError(failure, { debug }), null, 2),
+    );
+  else console.error(renderHumanError(failure, { debug }));
+  process.exitCode = failure.exitCode;
+}