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

package/dist/src/cli/runtime_action_handlers.mjs

@@ -0,0 +1,201 @@
+/** Database runtime action handlers shared by guided and scripted CLI flows. */
+import * as prompts from "@clack/prompts";
+import { buildApplicationEnvironment, runHttpProofs, startApplicationSession, } from "../application/session.mjs";
+import { exactCommands, renderedCommand, silentCommand, } from "./command_contract.mjs";
+import { topologyCommandEnvironment, topologyEnvironmentFiles, } from "./runtime_commands.mjs";
+import { formatDuration, isHumanTerminal, terminalStyle, useStyledPrompts, } from "./terminal.mjs";
+const RUNTIME_ACTIONS = [
+    "run",
+    "start",
+    "migrate",
+    "reset",
+    "status",
+    "stop",
+    "discard",
+    "verify",
+];
+const isRuntimeAction = (command) => RUNTIME_ACTIONS.includes(command);
+export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prepareDependentTargets, proveRuntimeStack, runRuntimeStack, }) => [
+    {
+        ...exactCommands("runtime-action", RUNTIME_ACTIONS, async () => silentCommand()),
+        matches: ({ command, flags }) => isRuntimeAction(command) && !(command === "run" && flags.dryRun),
+        handle: async ({ command, flags, planOptions, guided, state }) => {
+            if (!isRuntimeAction(command)) {
+                throw new Error(`Unsupported runtime action: ${command}.`);
+            }
+            if (flags.dryRun && command !== "run") {
+                throw new Error("--dry-run is supported only by rehearsal run.");
+            }
+            if (!(await prepareCandidateConfirmation({
+                command,
+                flags,
+                planOptions,
+                session: state,
+            }))) {
+                return silentCommand();
+            }
+            const stack = await runRuntimeStack({
+                command,
+                flags,
+                planOptions,
+                session: state,
+            });
+            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) {
+                state.lastGuidedDetails = [
+                    runtime.output,
+                    ...preparations.map((preparation) => preparation.output),
+                    ...dependentProofs.map((proof) => proof.output),
+                    applicationProof?.output,
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+            }
+            return renderedCommand({
+                data,
+                render: (value) => {
+                    const runtimeResult = "runtime" in value ? value.runtime : value;
+                    const renderedPreparations = "preparations" in value ? value.preparations : [];
+                    const renderedDependentProofs = "dependentProofs" in value ? value.dependentProofs : [];
+                    const renderedApplicationProof = "applicationProof" in value ? value.applicationProof : undefined;
+                    const renderedApplicationReadiness = "applicationReadiness" in value
+                        ? value.applicationReadiness
+                        : undefined;
+                    const renderedHttpProofResults = "httpProofResults" in value ? value.httpProofResults : [];
+                    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)}`,
+                            ...renderedPreparations.map((preparation) => `✓ ${preparation.target} preparation passed: ${preparation.command}`),
+                            ...renderedDependentProofs.map((proof) => `✓ ${proof.target} proof passed: ${proof.command}`),
+                            renderedApplicationProof
+                                ? `✓ Application proof passed: ${renderedApplicationProof.command}`
+                                : null,
+                            renderedApplicationReadiness
+                                ? `✓ Application became ready at ${renderedApplicationReadiness.url}`
+                                : null,
+                            ...renderedHttpProofResults.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.`,
+                        ...renderedPreparations.map((preparation) => `${preparation.target} preparation passed: ${preparation.command}`),
+                        ...renderedDependentProofs.map((proof) => `${proof.target} proof passed: ${proof.command}`),
+                        renderedApplicationProof
+                            ? `Application proof passed: ${renderedApplicationProof.command}`
+                            : null,
+                        renderedApplicationReadiness
+                            ? `Application readiness passed: ${renderedApplicationReadiness.url}`
+                            : null,
+                        ...renderedHttpProofResults.map((proof) => `${proof.kind} HTTP proof passed: ${proof.name}`),
+                        nextAction ? "" : null,
+                        nextAction,
+                    ]
+                        .filter((entry) => entry !== null)
+                        .join("\n");
+                },
+            });
+        },
+    },
+];

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

@@ -0,0 +1,269 @@
+/**
+ * CLI orchestration for one or more isolated database runtimes and their
+ * project-owned proof commands.
+ */
+import { holdApplicationSession } from "../application/session.mjs";
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import { buildRehearsalPlan } from "../runtime/plan.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
+import type { InstalledPackageFingerprint } from "../shared/operation_guard.mjs";
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { RehearsalErrorCategory } from "../shared/diagnostics.mjs";
+import type { CliSessionState } from "./command_contract.mjs";
+type RuntimeTopology = Awaited<ReturnType<typeof loadRuntimeTopology>>;
+type RuntimeAction = "run" | "start" | "migrate" | "reset" | "status" | "stop" | "discard" | "verify";
+interface ManagerReceipt {
+    readonly action: RuntimeAction;
+    readonly target: string;
+    readonly durationMs: number;
+    readonly output: string;
+}
+interface RuntimeStackResult {
+    readonly topology: RuntimeTopology;
+    readonly runtime: ManagerReceipt | Readonly<{
+        action: RuntimeAction;
+        durationMs: number;
+        output: string;
+        targets: readonly ManagerReceipt[];
+    }>;
+}
+export declare const buildRuntimeStackPlan: (planOptions: RehearsalConfigPathOptions) => Promise<{
+    config: {
+        schemaVersion: 1;
+        path: string;
+        project: string;
+    };
+    environment: {
+        target: "postgresql" | "supabase";
+        kind: string;
+        applicationUrl: string;
+        projectId: string;
+        ports: Readonly<{
+            api?: number;
+            database: number;
+            studio?: number;
+        }>;
+        hostedAccess: "disabled";
+        outboundNetwork: "deny";
+        authenticationProviders: readonly string[];
+        authenticationCallback: string | null;
+        barriers: string[];
+    };
+    baseline: {
+        rehearsalVersion: string;
+        formatVersion: 1 | 2;
+        generationId: string;
+        createdAt: string | null;
+        migrationCutoff: string;
+        migrationHistorySha256: string;
+        sanitizationPolicySha256: string;
+        dataSha256: string;
+        tableCount: number;
+        rowCount: number;
+        migrationCount: number;
+        verification: string;
+    };
+    migrations: {
+        representedCount: number;
+        candidateCount: number;
+        candidateSha256: string;
+        candidates: {
+            filename: string;
+            sha256: string;
+        }[];
+    };
+    execution: string[];
+    guarantee: string;
+    paths: {
+        artifactDirectory: string;
+        migrationDirectory: string;
+        sanitizationPolicy: string;
+    };
+} | {
+    targets: {
+        name: string;
+        declaration: RuntimeTopologyTarget["declaration"];
+        plan: Awaited<ReturnType<typeof buildRehearsalPlan>>;
+    }[];
+    migrations: {
+        candidateCount: number;
+        candidateSha256: string;
+    };
+    execution: string[];
+    guarantee: string;
+}>;
+export declare const runRuntimeStackDoctor: (planOptions: RehearsalConfigPathOptions) => Promise<{
+    state: string;
+    checks: {
+        id: string;
+        label: string;
+        status: string;
+        detail: string;
+        remediation: string;
+    }[];
+    ambientHostedVariables?: never;
+} | {
+    state: string;
+    checks: ({
+        status: string;
+        detail: unknown;
+        durationMs: number;
+        remediation?: never;
+        id: string;
+        label: string;
+    } | {
+        status: string;
+        detail: string;
+        remediation: string;
+        durationMs: number;
+        id: string;
+        label: string;
+    } | {
+        status: string;
+        detail: string;
+        remediation: string;
+        id: string;
+        label: string;
+    })[];
+    ambientHostedVariables: {
+        presentButQuarantined: string[];
+        note: string;
+    };
+}>;
+export declare const topologyCandidateSummary: (planOptions: RehearsalConfigPathOptions) => Promise<{
+    baselineGenerationId: string;
+    candidateSha256: string;
+    candidateCount: number;
+    candidates: {
+        version: string;
+        name: string;
+        filename: string;
+        sha256: string;
+        status: string;
+        target: string;
+    }[];
+    targets: {
+        name: string;
+        configPath: string;
+        baselineGenerationId: string;
+        candidateSha256: string;
+        candidateCount: number;
+        candidates: readonly {
+            version: string;
+            name: string;
+            filename: string;
+            sha256: string;
+            status: string;
+        }[];
+    }[];
+    topology: Readonly<{
+        projectRoot: string;
+        primary: RuntimeTopologyTarget;
+        dependents: readonly RuntimeTopologyTarget[];
+        targets: readonly RuntimeTopologyTarget[];
+    }>;
+}>;
+export declare const classifyManagerFailure: ({ action, output, inferredCategory, }: {
+    action: RuntimeAction;
+    output: string;
+    inferredCategory: RehearsalErrorCategory;
+}) => RehearsalErrorCategory;
+export declare const parseDockerCapacity: (output: string) => {
+    cpus: number;
+    memoryBytes: number;
+    runningContainers: number;
+    containers: number;
+} | null;
+export declare const parseColimaMemory: (output: string) => {
+    totalBytes: number;
+    availableBytes: number;
+} | null;
+export declare const topologyCommandEnvironment: (topology: RuntimeTopology) => NodeJS.ProcessEnv;
+export declare const topologyEnvironmentFiles: (topology: RuntimeTopology) => Readonly<Record<string, string>> & {
+    readonly primary: string;
+};
+export declare const createRuntimeCommands: ({ packageRoot, projectRoot, managerPath, getActivePackageFingerprint, }: {
+    packageRoot: string;
+    projectRoot: string;
+    managerPath: string;
+    getActivePackageFingerprint: () => InstalledPackageFingerprint | undefined;
+}) => {
+    openRuntimeApplication: ({ flags, planOptions, session: commandSession, onReady, }: {
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+        session: CliSessionState;
+        onReady?: Parameters<typeof holdApplicationSession>[0]["onReady"];
+    }) => Promise<{
+        action: string;
+        started: ManagerReceipt | Readonly<{
+            action: RuntimeAction;
+            durationMs: number;
+            output: string;
+            targets: readonly ManagerReceipt[];
+        }>;
+        verified: ManagerReceipt | Readonly<{
+            action: RuntimeAction;
+            durationMs: number;
+            output: string;
+            targets: readonly ManagerReceipt[];
+        }>;
+        preparations: {
+            command: string;
+            output: string;
+            target: string;
+        }[];
+        application: {
+            command: string;
+            readiness: Readonly<{
+                url: string;
+                status: number;
+            }>;
+            stoppedBy: string;
+            diagnostics: import("../application/session.mjs").ApplicationDiagnostics;
+        };
+    }>;
+    prepareCandidateConfirmation: ({ command, flags, planOptions, session, }: {
+        command: RuntimeAction;
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+        session: CliSessionState;
+    }) => Promise<boolean>;
+    prepareDependentTargets: ({ topology, environment, }: {
+        topology: RuntimeTopology;
+        environment: NodeJS.ProcessEnv;
+    }) => {
+        command: string;
+        output: string;
+        target: string;
+    }[];
+    proveRuntimeStack: ({ topology, planOptions, environment, }: {
+        topology: RuntimeTopology;
+        planOptions: RehearsalConfigPathOptions;
+        environment: NodeJS.ProcessEnv;
+    }) => Promise<{
+        applicationProof: {
+            command: string;
+            output: string;
+        };
+        dependentProofs: {
+            target: string;
+            command: string;
+            output: string;
+        }[];
+    }>;
+    runManager: ({ action, flags, configPath, confirmation, targetName, }: {
+        action: RuntimeAction;
+        flags: RehearsalCliFlags;
+        configPath?: string;
+        confirmation?: string;
+        targetName?: string;
+    }) => ManagerReceipt;
+    runRuntimeStack: ({ command, flags, planOptions, session, }: {
+        command: RuntimeAction;
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+        session: CliSessionState;
+    }) => Promise<RuntimeStackResult>;
+};
+export {};