@rehearsal-db/core 0.1.0-beta.14 → 0.1.0-beta.16

package/src/cli/rehearsal.mjs

@@ -1,972 +0,0 @@
-#!/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 } 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,
-  REHEARSAL_VERSION,
-  renderHumanError,
-  serializeRehearsalError,
-} from "../shared/diagnostics.mjs";
-import { loadRehearsalConfig } 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";
-import { runRehearsalInit } from "./init_command.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 {
-  openRuntimeApplication,
-  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 runSetup = async ({ flags, planOptions }) => {
-  const plan =
-    flags.setupPlan ??
-    (await planRehearsalSetup({
-      projectRoot,
-      configPath: planOptions.configPath,
-      target: flags.target,
-    }));
-  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: [
-      `Review ${result.configurationPath}.`,
-      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.",
-    ].join("\n"),
-  };
-};
-
-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:
-  version                     Print the installed Rehearsal version
-  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
-  open                       Start the runtime and keep the application open
-  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: --help, -h --version, -V --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 === "version" || flags.version) {
-    if (flags.json) {
-      console.log(
-        JSON.stringify(
-          { name: "@rehearsal-db/core", version: REHEARSAL_VERSION },
-          null,
-          2,
-        ),
-      );
-    } else console.log(REHEARSAL_VERSION);
-    return;
-  }
-  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 runRehearsalInit({ projectRoot, 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",
-              `${result.receipt.accessMode === "external" ? "External" : "Temporary"} reader expires: ${result.receipt.expiresAt}`,
-              result.receipt.accessMode === "external"
-                ? "Rehearsal made no source-side changes."
-                : "Rehearsal created only the reviewed temporary source access.",
-              `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 (command === "open") {
-    if (flags.dryRun) {
-      throw new Error("--dry-run is supported only by rehearsal run.");
-    }
-    const data = await openRuntimeApplication({
-      flags,
-      planOptions,
-      onReady: (ready) => {
-        const lines = [
-          `Application: ${ready.url}`,
-          "The verified database runtime stays running and keeps your local changes.",
-          guided
-            ? "Press Ctrl+C to close the app and return here, or Ctrl+Z to exit Rehearsal."
-            : "Press Ctrl+C or Ctrl+Z to close the app. Rehearsal will leave the database runtime running.",
-        ];
-        if (useStyledPrompts(flags)) {
-          prompts.note(lines.join("\n"), "SANDBOX READY");
-        } else if (!flags.json) {
-          console.log(["", "SANDBOX READY", ...lines, ""].join("\n"));
-        }
-      },
-    });
-    if (guided && data.application.stoppedBy === "SIGTSTP") {
-      flags.exitGuidedSession = true;
-    }
-    if (guided) {
-      lastGuidedDetails = [
-        data.started.output,
-        data.verified.output,
-        ...data.preparations.map((preparation) => preparation.output),
-      ]
-        .filter(Boolean)
-        .join("\n");
-    }
-    emit({
-      command,
-      data,
-      flags,
-      render: (result) =>
-        [
-          "SANDBOX APP CLOSED",
-          `Application stopped after ${result.application.stoppedBy}.`,
-          "The database runtime and its local database and Storage changes were preserved.",
-          "Run rehearsal open to return, rehearsal verify to check it, or rehearsal stop to stop the databases.",
-        ].join("\n"),
-    });
-    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: run rehearsal open for hands-on testing, then rehearsal verify.",
-          start:
-            "Next: run rehearsal open for hands-on testing or rehearsal status.",
-          migrate: "Next: run rehearsal verify to prove the current runtime.",
-          reset: "Next: run rehearsal open or rehearsal verify.",
-          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 installExitShortcut = () =>
-      installGuidedExitShortcut(flags, {
-        beforeExit: () => operation?.releaseSync(),
-      });
-    let removeGuidedExitShortcut = installExitShortcut();
-    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;
-        const opensApplication = selected === "open";
-        if (opensApplication) {
-          removeGuidedExitShortcut();
-          removeGuidedExitShortcut = null;
-        }
-        try {
-          await executeCommand({
-            command: selected,
-            flags,
-            planOptions,
-            guided: true,
-          });
-        } finally {
-          if (opensApplication) {
-            removeGuidedExitShortcut = installExitShortcut();
-          }
-        }
-        if (flags.exitGuidedSession) break;
-      }
-    } 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;
-}