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

package/dist/src/cli/project_commands.mjs

@@ -0,0 +1,183 @@
+/** Project-scoped CLI orchestration that is shared by direct and guided commands. */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { applyBaselinePreparation, planBaselinePreparation, summarizeBaselinePreparation, } from "../baseline/preparation.mjs";
+import { createIdentityClaimPlan, validateIdentityPolicy, } from "../identity/claim.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { applyRehearsalSetup, planRehearsalSetup, summarizeRehearsalSetup, } from "../project/setup.mjs";
+import { applyRehearsalCleanup, planRehearsalCleanup, } from "../runtime/cleanup.mjs";
+import { runRehearsalDoctor } from "../runtime/plan.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+const isCleanupStackPlan = (plan) => "targets" in plan;
+export const createProjectCommands = ({ projectRoot, runManager, }) => {
+    const runSetup = async ({ flags, planOptions, session, }) => {
+        const setupTarget = flags.target === "supabase" || flags.target === "postgresql"
+            ? flags.target
+            : undefined;
+        if (flags.target !== undefined && setupTarget === undefined) {
+            throw new Error("--target must be supabase or postgresql.");
+        }
+        const plan = session?.setupPlan ??
+            (await planRehearsalSetup({
+                projectRoot,
+                ...(planOptions.configPath === undefined
+                    ? {}
+                    : { configPath: planOptions.configPath }),
+                ...(setupTarget === undefined ? {} : { target: setupTarget }),
+            }));
+        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, session, }) => {
+        if (!flags.recordsPath || !flags.ledgerPath) {
+            throw new Error("baseline prepare requires --records and --ledger input paths.");
+        }
+        const plan = session?.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, session, }) => {
+        const plan = session?.cleanupPlan ??
+            (await planRuntimeStackCleanup({ flags, planOptions }));
+        if (!flags.write)
+            return { mode: "preview", plan };
+        if (isCleanupStackPlan(plan)) {
+            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,
+            ...(flags.cleanupConfirmation === undefined
+                ? {}
+                : { 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,
+            }),
+        };
+    };
+    return Object.freeze({
+        loadIdentityClaimPlan,
+        planRuntimeStackCleanup,
+        runBaselinePreparation,
+        runCleanup,
+        runSetup,
+    });
+};

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Parse one CLI request, protect project mutations, and delegate to
+ * the typed command registry shared by scripted and guided flows.
+ * Run: `npm run rehearsal -- doctor` or `npm run rehearsal -- explain`.
+ */
+export {};

package/dist/src/cli/rehearsal.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Parse one CLI request, protect project mutations, and delegate to
+ * the typed command registry shared by scripted and guided flows.
+ * Run: `npm run rehearsal -- doctor` or `npm run rehearsal -- explain`.
+ */
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import * as prompts from "@clack/prompts";
+import { normalizeRehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
+import { acquireProjectOperation, assertInstalledPackageFingerprint, createInstalledPackageFingerprint, } from "../shared/operation_guard.mjs";
+import { commandMutatesProject, parseArguments, resetGuidedFlags, } from "./arguments.mjs";
+import { usage } from "./basic_command_handlers.mjs";
+import { createCliCommandRegistry } from "./cli_commands.mjs";
+import { createCliSessionState, resetCommandSessionState, } from "./command_contract.mjs";
+import { createCommandEmitter } from "./command_output.mjs";
+import { createGuidedHome } from "./guided.mjs";
+import { createProjectCommands } from "./project_commands.mjs";
+import { buildRuntimeStackPlan, createRuntimeCommands, runRuntimeStackDoctor, topologyCandidateSummary, topologyCommandEnvironment, } from "./runtime_commands.mjs";
+import { buildRefreshWorkflowPlan, createRefreshWorkflow, } from "./source_commands.mjs";
+import { installGuidedExitShortcut, useStyledPrompts } from "./terminal.mjs";
+const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
+const projectRoot = process.cwd();
+const managerPath = join(packageRoot, "dist/scripts/runtime/manage_database.mjs");
+const state = createCliSessionState();
+let activePackageFingerprint = null;
+const runtimeCommands = createRuntimeCommands({
+    packageRoot,
+    projectRoot,
+    managerPath,
+    getActivePackageFingerprint: () => activePackageFingerprint ?? undefined,
+});
+const projectCommands = createProjectCommands({
+    projectRoot,
+    runManager: runtimeCommands.runManager,
+});
+const runRefreshWorkflow = createRefreshWorkflow({
+    runRuntimeStack: runtimeCommands.runRuntimeStack,
+    prepareDependentTargets: runtimeCommands.prepareDependentTargets,
+    topologyCommandEnvironment,
+});
+const commandRegistry = createCliCommandRegistry({
+    projectRoot,
+    projectCommands,
+    runtimeCommands,
+    runRefreshWorkflow,
+});
+const emitCommand = createCommandEmitter({
+    startedAt: new Date(),
+    startedMs: performance.now(),
+});
+const runGuidedHome = createGuidedHome({
+    projectRoot,
+    topologyCandidateSummary,
+    buildRefreshWorkflowPlan,
+    planRuntimeStackCleanup: projectCommands.planRuntimeStackCleanup,
+    getLastGuidedDetails: () => state.lastGuidedDetails,
+    session: state,
+});
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+const executeCommand = async ({ command, flags, planOptions, guided, }) => {
+    const result = await commandRegistry.execute({
+        command,
+        flags,
+        planOptions,
+        guided,
+        state,
+    });
+    if (!result) {
+        throw new Error(`Unknown Rehearsal command: ${command}.\n\n${usage()}`);
+    }
+    const exitCode = emitCommand({ command, flags, result });
+    if (exitCode !== undefined)
+        process.exitCode = exitCode;
+};
+const main = async () => {
+    const { flags, positionals } = parseArguments(process.argv.slice(2));
+    const command = positionals.join(" ") || "help";
+    const planOptions = {
+        projectRoot,
+        ...(flags.configPath === undefined ? {} : { 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);
+                resetCommandSessionState(state);
+                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: errorMessage(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;
+}

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

@@ -0,0 +1,299 @@
+/**
+ * Human-readable CLI output. These functions are intentionally pure so the
+ * command and guided workflow modules can focus on orchestration.
+ */
+import type { SourceAccessPlan } from "../source/access.mjs";
+import type { IdentityClaimPlan } from "../identity/claim.mjs";
+type Verbosity = "normal" | "verbose";
+type RenderFlags = Readonly<{
+    plain?: boolean;
+    json?: boolean;
+}>;
+type RenderMode = "preview" | "written";
+interface RenderMigration {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly status?: string;
+}
+interface RenderEnvironment {
+    readonly kind: string;
+    readonly hostedAccess: string;
+    readonly outboundNetwork: string;
+    readonly authenticationProviders: readonly string[];
+    readonly authenticationCallback: string | null;
+    readonly barriers: readonly string[];
+}
+interface RenderBaselineSummary {
+    readonly generationId: string;
+    readonly tableCount: number;
+    readonly rowCount: number;
+    readonly verification: string;
+}
+interface RenderMigrationSummary {
+    readonly candidates: readonly RenderMigration[];
+    readonly candidateSha256: string;
+    readonly candidateCount: number;
+    readonly representedCount: number;
+}
+interface RenderSinglePlan {
+    readonly environment: RenderEnvironment;
+    readonly baseline: RenderBaselineSummary;
+    readonly migrations: RenderMigrationSummary;
+    readonly execution: readonly string[];
+    readonly guarantee: string;
+}
+interface RenderStackTarget {
+    readonly name: string;
+    readonly plan: {
+        readonly config: {
+            readonly project: string;
+        };
+        readonly environment: RenderEnvironment;
+        readonly baseline: RenderBaselineSummary;
+        readonly migrations: Pick<RenderMigrationSummary, "candidates">;
+    };
+}
+interface RenderStackPlan {
+    readonly targets: readonly RenderStackTarget[];
+    readonly migrations: Pick<RenderMigrationSummary, "candidateSha256" | "candidateCount">;
+    readonly execution: readonly string[];
+    readonly guarantee: string;
+}
+interface ReadinessCheck {
+    readonly id: string;
+    readonly label: string;
+    readonly status: "pass" | "fail";
+    readonly detail: string;
+    readonly remediation?: string;
+}
+interface ReadinessReport {
+    readonly state: string;
+    readonly checks: readonly ReadinessCheck[];
+    readonly ambientHostedVariables?: {
+        readonly presentButQuarantined: readonly string[];
+    };
+}
+interface RenderTable {
+    readonly name: string;
+    readonly rowCount: number;
+    readonly columns: readonly string[];
+}
+interface CandidateSummary {
+    readonly baselineGenerationId: string;
+    readonly candidates: readonly RenderMigration[];
+    readonly candidateSha256: string;
+    readonly candidateCount: number;
+    readonly targets?: readonly {
+        readonly name: string;
+        readonly baselineGenerationId: string;
+        readonly candidates: readonly RenderMigration[];
+    }[];
+}
+interface CleanupImage {
+    readonly bytes: number;
+    readonly tags: readonly string[];
+}
+interface CleanupTargetPlan {
+    readonly project: string;
+    readonly projectId: string;
+    readonly baselines: {
+        readonly available: boolean;
+        readonly removed: readonly string[];
+        readonly retained: readonly string[];
+    };
+    readonly runtime: {
+        readonly included: boolean;
+        readonly detected: boolean;
+    };
+    readonly images: {
+        readonly requested: boolean;
+        readonly inspected: boolean;
+        readonly candidates: readonly CleanupImage[];
+    };
+}
+interface AppliedCleanup {
+    readonly baselines: {
+        readonly removed: readonly string[];
+    };
+    readonly runtimeRemoved: boolean;
+    readonly imagesRemoved: readonly string[];
+}
+interface CleanupResult {
+    readonly mode: RenderMode;
+    readonly plan: (CleanupTargetPlan & {
+        readonly digest: string;
+        readonly docker: {
+            readonly resources: readonly unknown[];
+            readonly disk: {
+                readonly usedBytes: number;
+                readonly totalBytes: number;
+                readonly availableBytes: number;
+                readonly usedPercent: number;
+            } | null;
+        };
+    }) | {
+        readonly targets: readonly {
+            readonly name: string;
+            readonly plan: CleanupTargetPlan;
+        }[];
+        readonly digest: string;
+    };
+    readonly applied?: AppliedCleanup | {
+        readonly targets: readonly {
+            readonly name: string;
+            readonly applied: AppliedCleanup;
+        }[];
+    };
+}
+interface RefreshPlan {
+    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[];
+    };
+}
+interface SourceRetirementPlan {
+    readonly digest: string;
+    readonly review: {
+        readonly targetFingerprint: string;
+        readonly readerRole: string;
+        readonly exportSchema: string;
+        readonly accessMode: "managed" | "external";
+        readonly views: readonly string[];
+    };
+}
+export declare const renderPlan: (plan: RenderSinglePlan | RenderStackPlan, verbosity: Verbosity) => string;
+export declare const renderDoctor: (doctor: ReadinessReport, verbosity: Verbosity) => string;
+export declare const renderBaseline: (baseline: {
+    rehearsalVersion: string;
+    generationId: string;
+    createdAt?: string | null;
+    formatVersion: number;
+    tableCount: number;
+    rowCount: number;
+    migrationCount: number;
+    migrationCutoff: string;
+    dataSha256: string;
+    sanitizationPolicySha256: string;
+    verification: string;
+}) => string;
+export declare const renderMigrations: (inspection: {
+    baselineGenerationId: string;
+    baselineCutoff: string;
+    candidateSha256: string;
+    migrations: readonly (RenderMigration & {
+        status: string;
+    })[];
+}, verbosity: Verbosity) => string;
+export declare const renderCandidates: (summary: CandidateSummary, verbosity: Verbosity) => string;
+export declare const renderInit: (result: {
+    mode: RenderMode;
+    destination: string;
+    detected: {
+        packageManager: string;
+        hasSupabaseConfig: boolean;
+        hasMigrations: boolean;
+    };
+    availableOptions?: readonly {
+        path: string;
+        summary: string;
+    }[];
+    source?: string | null;
+    nextAction: string;
+}) => string;
+export declare const renderSetup: (result: {
+    mode: RenderMode;
+    project: string;
+    configurationPath: string;
+    configurationAction: "create" | "update" | "unchanged";
+    rootConfigGenerationSkipped?: boolean;
+    target: "postgresql" | "supabase";
+    projectId: string;
+    applicationUrl: string;
+    ports: Readonly<Record<string, number>> & {
+        readonly database: number;
+    };
+    files: readonly {
+        action: "create" | "update" | "unchanged";
+        path: string;
+    }[];
+    safety: readonly string[];
+    readiness?: ReadinessReport;
+    nextAction: string;
+}) => string;
+export declare const renderBaselinePreparation: (result: {
+    mode: RenderMode;
+    destination: string;
+    rowCount: number;
+    recordsPath: string;
+    migrationCount: number;
+    migrationCutoff: string;
+    tables: readonly RenderTable[];
+    nextAction: string;
+}, flags?: RenderFlags) => string;
+export declare const renderBaselineInputInspection: (result: {
+    rowCount: number;
+    recordsPath: string;
+    migrationCount: number;
+    migrationCutoff: string;
+    ledgerPath: string;
+    assetsPath?: string;
+    assetCount: number;
+    tables: readonly RenderTable[];
+}, flags?: RenderFlags) => string;
+export declare const renderSupportReport: (report: {
+    rehearsalVersion: string;
+    system: {
+        platform: string;
+        architecture: string;
+        release: string;
+        node: string;
+    };
+    tools: Record<"npm" | "supabase" | "dockerClient" | "dockerServer", {
+        status: string;
+        version?: string;
+    }>;
+    readiness: {
+        state: string;
+        checks: readonly Omit<ReadinessCheck, "detail">[];
+        quarantinedHostedVariableCount: number;
+    };
+    supportUrl: string;
+}) => string;
+export declare const formatBytes: (bytes: number) => string;
+export declare const renderCleanup: (result: CleanupResult) => string;
+export declare const renderSourceAccessPlan: (plan: SourceAccessPlan) => string;
+export declare const renderRefreshWorkflow: ({ mode, plan, refreshed, runtime, cleanup, }: {
+    mode: RenderMode;
+    plan: RefreshPlan;
+    refreshed?: {
+        generationId: string;
+    };
+    runtime?: {
+        targets?: readonly unknown[];
+    };
+    cleanup?: {
+        state: "complete";
+        removed: readonly string[];
+    } | {
+        state: string;
+        remaining: number;
+    };
+}) => string;
+export declare const renderSourceRetirement: ({ mode, plan, }: {
+    mode: RenderMode;
+    plan: SourceRetirementPlan;
+}) => string;
+export declare const renderIdentityPlan: ({ mode, plan, }: {
+    mode: RenderMode;
+    plan: IdentityClaimPlan;
+}) => string;
+export {};