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

package/dist/src/baseline/schema_snapshot.mjs

@@ -0,0 +1,79 @@
+/**
+ * Purpose: Capture and compare bounded, data-free PostgreSQL public-schema
+ * snapshots for a local Rehearsal runtime. Do not run directly.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { basename, join, resolve, sep } from "node:path";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
+const maximumSchemaBytes = 64 * 1024 * 1024;
+const assertArtifactRoot = (artifactRoot) => {
+    const resolved = resolve(artifactRoot);
+    if (basename(resolved) !== ".rehearsal" || resolved === sep) {
+        throw new Error(`Refusing an unsafe Rehearsal artifact root: ${artifactRoot}`);
+    }
+    return resolved;
+};
+export const assertProductionSchemaDump = (schemaSql) => {
+    if (typeof schemaSql !== "string" || schemaSql.length === 0) {
+        throw new Error("The Rehearsal production schema snapshot is empty.");
+    }
+    if (Buffer.byteLength(schemaSql) > maximumSchemaBytes) {
+        throw new Error("The Rehearsal production schema snapshot is too large.");
+    }
+    if (!schemaSql.includes('CREATE SCHEMA IF NOT EXISTS "public";')) {
+        throw new Error("The Rehearsal production schema snapshot does not define public.");
+    }
+    if (/^COPY\s|^\\connect\s|^CREATE DATABASE\s/mu.test(schemaSql)) {
+        throw new Error("The Rehearsal production schema snapshot contains data or database switching commands.");
+    }
+    return schemaSql;
+};
+const comparableSchemaDump = (schemaSql) => assertProductionSchemaDump(schemaSql)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+    const checkConstraint = line.match(/^(\s*CONSTRAINT "[^"]+" CHECK ).*(,?)$/u);
+    return checkConstraint
+        ? `${checkConstraint[1]}<database-normalized-expression>${checkConstraint[2]}`
+        : line;
+})
+    .join("\n");
+export const compareProductionSchemaDumps = ({ expected, actual, }) => {
+    const expectedComparable = comparableSchemaDump(expected);
+    const actualComparable = comparableSchemaDump(actual);
+    if (expectedComparable !== actualComparable) {
+        throw new Error("The local Rehearsal public schema does not structurally match the production snapshot.");
+    }
+    return createHash("sha256").update(actualComparable).digest("hex");
+};
+export const captureSupabasePublicSchema = async ({ repositoryRoot, artifactRoot, arguments_, }) => {
+    const root = assertArtifactRoot(artifactRoot);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const temporaryDirectory = await mkdtemp(join(root, ".schema-capture-"));
+    const destination = join(temporaryDirectory, "production-schema.sql");
+    try {
+        const result = spawnSync("supabase", [...arguments_, "--schema", "public", "--file", destination], {
+            cwd: repositoryRoot,
+            env: createCleanProcessEnvironment(),
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        if (result.error || result.status !== 0) {
+            throw new Error("The exact Rehearsal schema snapshot could not be captured.", { cause: result.error });
+        }
+        await chmod(destination, 0o600);
+        return assertProductionSchemaDump(await readFile(destination, "utf8"));
+    }
+    finally {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+};
+export const captureLocalPublicSchema = ({ repositoryRoot, artifactRoot, workdir, }) => captureSupabasePublicSchema({
+    repositoryRoot,
+    artifactRoot,
+    arguments_: ["db", "dump", "--local", "--workdir", workdir],
+});

package/dist/src/cli/application_command_handlers.d.mts

@@ -0,0 +1,8 @@
+/** Persistent application-session command handler. */
+import type { CommandDefinition } from "./command_contract.mjs";
+import type { createRuntimeCommands } from "./runtime_commands.mjs";
+type RuntimeCommands = ReturnType<typeof createRuntimeCommands>;
+export declare const createApplicationCommandHandlers: ({ openRuntimeApplication, }: {
+    openRuntimeApplication: RuntimeCommands["openRuntimeApplication"];
+}) => readonly CommandDefinition[];
+export {};

package/dist/src/cli/application_command_handlers.mjs

@@ -0,0 +1,52 @@
+/** Persistent application-session command handler. */
+import * as prompts from "@clack/prompts";
+import { exactCommands, renderedCommand } from "./command_contract.mjs";
+import { useStyledPrompts } from "./terminal.mjs";
+export const createApplicationCommandHandlers = ({ openRuntimeApplication, }) => [
+    exactCommands("open", ["open"], async ({ flags, planOptions, guided, state }) => {
+        if (flags.dryRun) {
+            throw new Error("--dry-run is supported only by rehearsal run.");
+        }
+        const data = await openRuntimeApplication({
+            flags,
+            planOptions,
+            session: state,
+            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) {
+            state.lastGuidedDetails = [
+                data.started.output,
+                data.verified.output,
+                ...data.preparations.map((preparation) => preparation.output),
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        return renderedCommand({
+            data,
+            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"),
+        });
+    }),
+];

package/dist/src/cli/arguments.d.mts

@@ -0,0 +1,38 @@
+/** Parse and classify the stable Rehearsal command-line contract. */
+export type RehearsalVerbosity = "normal" | "verbose" | "debug";
+export interface RehearsalCliFlags {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+    verbosity: RehearsalVerbosity;
+    dryRun: boolean;
+    write: boolean;
+    plain: boolean;
+    configPath: string | undefined;
+    confirmation: string | undefined;
+    recordsPath: string | undefined;
+    ledgerPath: string | undefined;
+    assetsPath: string | undefined;
+    target: string | undefined;
+    includeRuntime: boolean;
+    includeImages: boolean;
+    cleanupConfirmation: string | undefined;
+    sourceAccessConfirmation: string | undefined;
+    sourceRetirementConfirmation: string | undefined;
+    refreshConfirmation: string | undefined;
+    identityConfirmation: string | undefined;
+    identityName: string | undefined;
+    exitGuidedSession: boolean;
+    guided: boolean;
+}
+export interface ParsedArguments {
+    flags: RehearsalCliFlags;
+    positionals: string[];
+}
+export declare const parseArguments: (arguments_: readonly string[]) => ParsedArguments;
+export declare const resetGuidedFlags: (flags: RehearsalCliFlags) => void;
+export declare const commandMutatesProject: ({ command, flags, guided, }: {
+    command: string;
+    flags: RehearsalCliFlags;
+    guided: boolean;
+}) => boolean;

package/dist/src/cli/arguments.mjs

@@ -0,0 +1,128 @@
+/** Parse and classify the stable Rehearsal command-line contract. */
+export const parseArguments = (arguments_) => {
+    const flags = {
+        json: false,
+        help: false,
+        version: false,
+        verbosity: "normal",
+        dryRun: false,
+        write: false,
+        plain: false,
+        configPath: undefined,
+        confirmation: undefined,
+        recordsPath: undefined,
+        ledgerPath: undefined,
+        assetsPath: undefined,
+        target: undefined,
+        includeRuntime: false,
+        includeImages: false,
+        cleanupConfirmation: undefined,
+        sourceAccessConfirmation: undefined,
+        sourceRetirementConfirmation: undefined,
+        refreshConfirmation: undefined,
+        identityConfirmation: undefined,
+        identityName: undefined,
+        exitGuidedSession: false,
+        guided: false,
+    };
+    const positionals = [];
+    for (const argument of arguments_) {
+        if (argument === "--json")
+            flags.json = true;
+        else if (argument === "--help" || argument === "-h")
+            flags.help = true;
+        else if (argument === "--version" || argument === "-V")
+            flags.version = true;
+        else if (argument === "--verbose")
+            flags.verbosity = "verbose";
+        else if (argument === "--debug")
+            flags.verbosity = "debug";
+        else if (argument === "--dry-run")
+            flags.dryRun = true;
+        else if (argument === "--write")
+            flags.write = true;
+        else if (argument === "--plain")
+            flags.plain = true;
+        else if (argument.startsWith("--config="))
+            flags.configPath = argument.slice("--config=".length);
+        else if (argument.startsWith("--confirm-candidates="))
+            flags.confirmation = argument.slice("--confirm-candidates=".length);
+        else if (argument.startsWith("--confirm-cleanup="))
+            flags.cleanupConfirmation = argument.slice("--confirm-cleanup=".length);
+        else if (argument.startsWith("--confirm-source-access="))
+            flags.sourceAccessConfirmation = argument.slice("--confirm-source-access=".length);
+        else if (argument.startsWith("--confirm-source-retirement="))
+            flags.sourceRetirementConfirmation = argument.slice("--confirm-source-retirement=".length);
+        else if (argument.startsWith("--confirm-refresh="))
+            flags.refreshConfirmation = argument.slice("--confirm-refresh=".length);
+        else if (argument.startsWith("--confirm-identity="))
+            flags.identityConfirmation = argument.slice("--confirm-identity=".length);
+        else if (argument.startsWith("--identity="))
+            flags.identityName = argument.slice("--identity=".length);
+        else if (argument.startsWith("--records="))
+            flags.recordsPath = argument.slice("--records=".length);
+        else if (argument.startsWith("--ledger="))
+            flags.ledgerPath = argument.slice("--ledger=".length);
+        else if (argument.startsWith("--assets="))
+            flags.assetsPath = argument.slice("--assets=".length);
+        else if (argument.startsWith("--target="))
+            flags.target = argument.slice("--target=".length);
+        else if (argument === "--include-runtime")
+            flags.includeRuntime = true;
+        else if (argument === "--include-images")
+            flags.includeImages = true;
+        else if (argument.startsWith("--"))
+            throw new Error(`Unknown Rehearsal option: ${argument}.`);
+        else
+            positionals.push(argument);
+    }
+    return { flags, positionals };
+};
+export const resetGuidedFlags = (flags) => {
+    Object.assign(flags, {
+        dryRun: false,
+        write: false,
+        confirmation: undefined,
+        recordsPath: undefined,
+        ledgerPath: undefined,
+        assetsPath: undefined,
+        target: undefined,
+        includeRuntime: false,
+        includeImages: false,
+        cleanupConfirmation: undefined,
+        sourceAccessConfirmation: undefined,
+        sourceRetirementConfirmation: undefined,
+        refreshConfirmation: undefined,
+        identityConfirmation: undefined,
+        identityName: undefined,
+        exitGuidedSession: false,
+    });
+};
+export const commandMutatesProject = ({ command, flags, guided, }) => {
+    if (guided)
+        return true;
+    if (["setup", "init", "baseline prepare", "privacy key"].includes(command))
+        return flags.write;
+    if (command === "cleanup")
+        return flags.write;
+    if (command === "source apply")
+        return Boolean(flags.sourceAccessConfirmation);
+    if (command === "source retire")
+        return Boolean(flags.sourceRetirementConfirmation);
+    if (command === "refresh")
+        return Boolean(flags.refreshConfirmation);
+    if (command === "identity claim")
+        return Boolean(flags.identityConfirmation);
+    if (command === "run")
+        return !flags.dryRun;
+    return [
+        "baseline create",
+        "baseline refresh",
+        "open",
+        "start",
+        "migrate",
+        "reset",
+        "stop",
+        "discard",
+    ].includes(command);
+};

package/dist/src/cli/basic_command_handlers.d.mts

@@ -0,0 +1,4 @@
+/** Stable version and help handlers with no project-side effects. */
+import type { CommandDefinition } from "./command_contract.mjs";
+export declare const usage: () => string;
+export declare const createBasicCommandHandlers: () => readonly CommandDefinition[];

package/dist/src/cli/basic_command_handlers.mjs

@@ -0,0 +1,56 @@
+/** Stable version and help handlers with no project-side effects. */
+import { REHEARSAL_VERSION } from "../shared/diagnostics.mjs";
+import { exactCommands, textCommand } from "./command_contract.mjs";
+export 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>`;
+export const createBasicCommandHandlers = () => [
+    {
+        id: "version",
+        matches: ({ command, flags }) => command === "version" || flags.version,
+        handle: async ({ flags }) => textCommand(flags.json
+            ? JSON.stringify({ name: "@rehearsal-db/core", version: REHEARSAL_VERSION }, null, 2)
+            : REHEARSAL_VERSION),
+    },
+    {
+        ...exactCommands("help", ["help"], async () => textCommand(usage())),
+        matches: ({ command, flags }) => command === "help" || flags.help,
+    },
+];

package/dist/src/cli/cli_commands.d.mts

@@ -0,0 +1,14 @@
+/** Assemble the CLI command families into one ordered typed registry. */
+import type { createProjectCommands } from "./project_commands.mjs";
+import type { createRuntimeCommands } from "./runtime_commands.mjs";
+import type { createRefreshWorkflow } from "./source_commands.mjs";
+type ProjectCommands = ReturnType<typeof createProjectCommands>;
+type RuntimeCommands = ReturnType<typeof createRuntimeCommands>;
+type RefreshWorkflow = ReturnType<typeof createRefreshWorkflow>;
+export declare const createCliCommandRegistry: ({ projectRoot, projectCommands, runtimeCommands, runRefreshWorkflow, }: {
+    projectRoot: string;
+    projectCommands: ProjectCommands;
+    runtimeCommands: RuntimeCommands;
+    runRefreshWorkflow: RefreshWorkflow;
+}) => import("./command_registry.mjs").CommandRegistry;
+export {};

package/dist/src/cli/cli_commands.mjs

@@ -0,0 +1,32 @@
+/** Assemble the CLI command families into one ordered typed registry. */
+import { createApplicationCommandHandlers } from "./application_command_handlers.mjs";
+import { createBasicCommandHandlers } from "./basic_command_handlers.mjs";
+import { createCommandRegistry } from "./command_registry.mjs";
+import { createIdentityCommandHandlers } from "./identity_command_handlers.mjs";
+import { createInspectionCommandHandlers } from "./inspection_command_handlers.mjs";
+import { createProjectCommandHandlers } from "./project_command_handlers.mjs";
+import { createRuntimeActionHandlers } from "./runtime_action_handlers.mjs";
+import { createSourceCommandHandlers } from "./source_command_handlers.mjs";
+export const createCliCommandRegistry = ({ projectRoot, projectCommands, runtimeCommands, runRefreshWorkflow, }) => createCommandRegistry([
+    ...createBasicCommandHandlers(),
+    ...createProjectCommandHandlers({
+        projectRoot,
+        runSetup: projectCommands.runSetup,
+        runBaselinePreparation: projectCommands.runBaselinePreparation,
+        runCleanup: projectCommands.runCleanup,
+    }),
+    ...createSourceCommandHandlers({ runRefreshWorkflow }),
+    ...createIdentityCommandHandlers({
+        loadIdentityClaimPlan: projectCommands.loadIdentityClaimPlan,
+    }),
+    ...createInspectionCommandHandlers(),
+    ...createApplicationCommandHandlers({
+        openRuntimeApplication: runtimeCommands.openRuntimeApplication,
+    }),
+    ...createRuntimeActionHandlers({
+        prepareCandidateConfirmation: runtimeCommands.prepareCandidateConfirmation,
+        prepareDependentTargets: runtimeCommands.prepareDependentTargets,
+        proveRuntimeStack: runtimeCommands.proveRuntimeStack,
+        runRuntimeStack: runtimeCommands.runRuntimeStack,
+    }),
+]);

package/dist/src/cli/command_contract.d.mts

@@ -0,0 +1,57 @@
+/** Typed contracts shared by CLI command handlers and the process entry point. */
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import type { RehearsalStatus } from "../shared/diagnostics.mjs";
+import type { RehearsalCliFlags, RehearsalVerbosity } from "./arguments.mjs";
+export interface CliSessionState {
+    lastGuidedDetails: string | undefined;
+    runtimeTopology: unknown | undefined;
+    targetConfirmations: unknown | undefined;
+    setupPlan: unknown | undefined;
+    preparationPlan: unknown | undefined;
+    cleanupPlan: unknown | undefined;
+}
+export declare const createCliSessionState: () => CliSessionState;
+export declare const resetCommandSessionState: (state: CliSessionState) => void;
+export interface CommandContext {
+    readonly command: string;
+    readonly flags: RehearsalCliFlags;
+    readonly planOptions: RehearsalConfigPathOptions;
+    readonly guided: boolean;
+    readonly state: CliSessionState;
+}
+export interface RenderedCommandResult {
+    readonly kind: "rendered";
+    readonly data: unknown;
+    readonly status: RehearsalStatus;
+    readonly render: (verbosity: RehearsalVerbosity) => string;
+    readonly exitCode?: number;
+}
+export interface TextCommandResult {
+    readonly kind: "text";
+    readonly output: string;
+    readonly exitCode?: number;
+}
+export interface SilentCommandResult {
+    readonly kind: "silent";
+    readonly exitCode?: number;
+}
+export type CommandResult = RenderedCommandResult | TextCommandResult | SilentCommandResult;
+export type CommandHandler = (context: CommandContext) => Promise<CommandResult>;
+export interface CommandDefinition {
+    readonly id: string;
+    readonly matches: (context: CommandContext) => boolean;
+    readonly handle: CommandHandler;
+}
+export declare const renderedCommand: <Data>({ data, render, status, exitCode, }: {
+    data: Data;
+    render: (data: Data, verbosity: RehearsalVerbosity) => string;
+    status?: RehearsalStatus;
+    exitCode?: number;
+}) => RenderedCommandResult;
+export declare const textCommand: (output: string, options?: {
+    exitCode?: number;
+}) => TextCommandResult;
+export declare const silentCommand: (options?: {
+    exitCode?: number;
+}) => SilentCommandResult;
+export declare const exactCommands: (id: string, commands: readonly string[], handle: CommandHandler) => CommandDefinition;

package/dist/src/cli/command_contract.mjs

@@ -0,0 +1,39 @@
+/** Typed contracts shared by CLI command handlers and the process entry point. */
+export const createCliSessionState = () => ({
+    lastGuidedDetails: undefined,
+    runtimeTopology: undefined,
+    targetConfirmations: undefined,
+    setupPlan: undefined,
+    preparationPlan: undefined,
+    cleanupPlan: undefined,
+});
+export const resetCommandSessionState = (state) => {
+    Object.assign(state, {
+        runtimeTopology: undefined,
+        targetConfirmations: undefined,
+        setupPlan: undefined,
+        preparationPlan: undefined,
+        cleanupPlan: undefined,
+    });
+};
+export const renderedCommand = ({ data, render, status = "success", exitCode, }) => ({
+    kind: "rendered",
+    data,
+    status,
+    render: (verbosity) => render(data, verbosity),
+    ...(exitCode === undefined ? {} : { exitCode }),
+});
+export const textCommand = (output, options = {}) => ({
+    kind: "text",
+    output,
+    ...(options.exitCode === undefined ? {} : { exitCode: options.exitCode }),
+});
+export const silentCommand = (options = {}) => ({
+    kind: "silent",
+    ...(options.exitCode === undefined ? {} : { exitCode: options.exitCode }),
+});
+export const exactCommands = (id, commands, handle) => ({
+    id,
+    matches: ({ command }) => commands.includes(command),
+    handle,
+});

package/dist/src/cli/command_output.d.mts

@@ -0,0 +1,12 @@
+/** Emit the stable JSON envelope or human result for a typed command result. */
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { CommandResult } from "./command_contract.mjs";
+export declare const createCommandEmitter: ({ startedAt, startedMs, write, }: {
+    startedAt: Date;
+    startedMs: number;
+    write?: (output: string) => void;
+}) => ({ command, flags, result, }: {
+    command: string;
+    flags: RehearsalCliFlags;
+    result: CommandResult;
+}) => number | undefined;

package/dist/src/cli/command_output.mjs

@@ -0,0 +1,20 @@
+/** Emit the stable JSON envelope or human result for a typed command result. */
+import { performance } from "node:perf_hooks";
+import { createRehearsalResult } from "../shared/diagnostics.mjs";
+export const createCommandEmitter = ({ startedAt, startedMs, write = console.log, }) => ({ command, flags, result, }) => {
+    if (result.kind === "text")
+        write(result.output);
+    if (result.kind === "rendered") {
+        const envelope = createRehearsalResult({
+            command,
+            status: result.status,
+            data: result.data,
+            startedAt,
+            durationMs: Math.round((performance.now() - startedMs) * 100) / 100,
+        });
+        write(flags.json
+            ? JSON.stringify(envelope, null, 2)
+            : result.render(flags.verbosity));
+    }
+    return result.exitCode;
+};

package/dist/src/cli/command_registry.d.mts

@@ -0,0 +1,7 @@
+/** Resolve one CLI request to exactly one typed command handler. */
+import type { CommandContext, CommandDefinition, CommandResult } from "./command_contract.mjs";
+export interface CommandRegistry {
+    readonly ids: readonly string[];
+    execute(context: CommandContext): Promise<CommandResult | null>;
+}
+export declare const createCommandRegistry: (definitions: readonly CommandDefinition[]) => CommandRegistry;

package/dist/src/cli/command_registry.mjs

@@ -0,0 +1,14 @@
+/** Resolve one CLI request to exactly one typed command handler. */
+export const createCommandRegistry = (definitions) => {
+    const ids = definitions.map(({ id }) => id);
+    if (new Set(ids).size !== ids.length) {
+        throw new Error("CLI command registry IDs must be unique.");
+    }
+    return Object.freeze({
+        ids: Object.freeze(ids),
+        async execute(context) {
+            const definition = definitions.find((candidate) => candidate.matches(context));
+            return definition ? definition.handle(context) : null;
+        },
+    });
+};

package/dist/src/cli/guided.d.mts

@@ -0,0 +1,53 @@
+/**
+ * State-aware interactive home screen and first-run flows.
+ */
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { CliSessionState } from "./command_contract.mjs";
+import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
+import type { RehearsalCleanupPlan } from "../runtime/cleanup.mjs";
+interface TopologySummary {
+    readonly topology: {
+        readonly dependents: readonly unknown[];
+        readonly targets: readonly RuntimeTopologyTarget[];
+    };
+}
+type GuidedCleanupPlan = RehearsalCleanupPlan | Readonly<{
+    digest: string;
+    targets: readonly Readonly<{
+        name: string;
+        plan: RehearsalCleanupPlan;
+    }>[];
+}>;
+interface GuidedRefreshPlan {
+    readonly digest: string;
+    readonly review: {
+        readonly currentBaseline: string;
+        readonly source: {
+            readonly readerExpiresAt: string;
+        };
+        readonly runtimeTargets: readonly string[];
+        readonly retention: {
+            readonly generations: number;
+            readonly removeAfterReplacement: readonly string[];
+        };
+        readonly steps: readonly string[];
+    };
+}
+export declare const createGuidedHome: ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, session, }: {
+    projectRoot: string;
+    topologyCandidateSummary: (options: RehearsalConfigPathOptions) => Promise<TopologySummary>;
+    buildRefreshWorkflowPlan: (options: RehearsalConfigPathOptions) => Promise<{
+        plan: GuidedRefreshPlan;
+    }>;
+    planRuntimeStackCleanup: (input: {
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+    }) => Promise<GuidedCleanupPlan>;
+    getLastGuidedDetails: () => string | undefined;
+    session: CliSessionState;
+}) => ({ flags, planOptions, }: {
+    flags: RehearsalCliFlags;
+    planOptions: RehearsalConfigPathOptions;
+}) => Promise<string | null>;
+export {};