@rehearsal-db/core 0.1.0-beta.13 → 0.1.0-beta.15

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

@@ -0,0 +1,21 @@
+/** Preview or create the project-root Rehearsal configuration. */
+interface InitFlags {
+    readonly configPath: string | undefined;
+    readonly write: boolean;
+}
+interface InitOptions {
+    readonly projectRoot: string;
+    readonly flags: InitFlags;
+}
+export declare const runRehearsalInit: ({ projectRoot, flags }: InitOptions) => Promise<{
+    mode: string;
+    destination: string;
+    detected: import("../project/configuration.mjs").DetectedProject;
+    source: string;
+    availableOptions: {
+        path: string;
+        summary: string;
+    }[];
+    nextAction: string;
+}>;
+export {};

package/dist/src/cli/init_command.mjs

@@ -0,0 +1,90 @@
+/** Preview or create the project-root Rehearsal configuration. */
+import { writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "../project/configuration.mjs";
+const findExistingConfig = async ({ projectRoot, configPath, }) => {
+    try {
+        return await findRehearsalConfigPath({
+            projectRoot,
+            ...(configPath === undefined ? {} : { configPath }),
+        });
+    }
+    catch (error) {
+        if (String(error instanceof Error ? error.message : error).startsWith("No Rehearsal configuration")) {
+            return null;
+        }
+        throw error;
+    }
+};
+export const runRehearsalInit = async ({ projectRoot, flags }) => {
+    const detected = await inspectDetectedProject({ projectRoot });
+    const destination = join(projectRoot, "rehearsal.config.mjs");
+    const existingPath = await findExistingConfig({
+        projectRoot,
+        configPath: flags.configPath,
+    });
+    if (existingPath) {
+        if (flags.write) {
+            throw new Error(`A Rehearsal configuration already exists at ${relative(projectRoot, existingPath)}; Rehearsal will not overwrite it.`);
+        }
+        const loaded = await loadRehearsalConfig({
+            projectRoot,
+            ...(flags.configPath === undefined
+                ? {}
+                : { configPath: flags.configPath }),
+        });
+        let source;
+        if (loaded.config.supabase) {
+            const { api, database, studio } = loaded.config.runtime.ports;
+            if (api === undefined || studio === undefined) {
+                throw new Error("The normalized Supabase configuration is missing its API or Studio port.");
+            }
+            source = renderDetectedConfig(detected, {
+                applicationUrl: loaded.config.runtime.applicationUrl,
+                ports: { api, database, studio },
+            });
+        }
+        else {
+            source = renderDetectedPostgresqlConfig(detected, {
+                applicationUrl: loaded.config.runtime.applicationUrl,
+                databasePort: loaded.config.runtime.ports.database,
+            });
+        }
+        const usesLegacyAuthentication = Boolean(loaded.config.supabase?.serviceEnvironmentFile ||
+            loaded.config.safety.authenticationProviders.length);
+        const availableOptions = loaded.config.supabase && !loaded.config.supabase.authentication
+            ? [
+                {
+                    path: "supabase.authentication",
+                    summary: usesLegacyAuthentication
+                        ? "A declarative Google/GitHub replacement is available; replace the legacy provider fields together after review."
+                        : "Configure local Google or GitHub sign-in with credentials kept outside tracked files.",
+                },
+            ]
+            : [];
+        return {
+            mode: "current-template",
+            destination: relative(projectRoot, existingPath),
+            detected,
+            source,
+            availableOptions,
+            nextAction: "Your existing configuration was not changed. Compare it with this installed-release template to discover new optional keys.",
+        };
+    }
+    const source = detected.hasSupabaseConfig
+        ? renderDetectedConfig(detected)
+        : renderDetectedPostgresqlConfig(detected);
+    if (flags.write) {
+        await writeFile(destination, source, { flag: "wx", mode: 0o600 });
+    }
+    return {
+        mode: flags.write ? "written" : "preview",
+        destination: relative(projectRoot, destination),
+        detected,
+        source,
+        availableOptions: [],
+        nextAction: flags.write
+            ? "Review the generated safety settings and run rehearsal doctor."
+            : "Review this preview, then rerun rehearsal init --write to create it.",
+    };
+};

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

@@ -0,0 +1,157 @@
+/** Project-scoped CLI orchestration that is shared by direct and guided commands. */
+import { summarizeBaselinePreparation } from "../baseline/preparation.mjs";
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import type { RehearsalCleanupPlan } from "../runtime/cleanup.mjs";
+import type { RehearsalCliFlags } from "./arguments.mjs";
+type CleanupStackPlan = Readonly<{
+    digest: string;
+    targets: readonly Readonly<{
+        name: string;
+        configPath: string;
+        plan: RehearsalCleanupPlan;
+    }>[];
+}>;
+type RunManager = (input: {
+    action: "discard";
+    flags: RehearsalCliFlags;
+    configPath?: string;
+    targetName?: string;
+}) => unknown;
+interface ProjectCommandInput {
+    readonly flags: RehearsalCliFlags;
+    readonly planOptions: RehearsalConfigPathOptions;
+}
+export declare const createProjectCommands: ({ projectRoot, runManager, }: {
+    projectRoot: string;
+    runManager: RunManager;
+}) => Readonly<{
+    loadIdentityClaimPlan: ({ flags, planOptions, }: ProjectCommandInput) => Promise<{
+        loaded: Readonly<{
+            config: Readonly<{
+                schemaVersion: 1;
+                project: Readonly<{
+                    name: string;
+                }>;
+                supabase: Readonly<{
+                    workdir: string;
+                    migrationDirectory: string;
+                    rehearsalConfig: string;
+                    runtimeWorkdir: string;
+                    authentication: Readonly<{
+                        enableLocalSignup: true;
+                        environmentFile: string;
+                        providers: readonly Readonly<{
+                            name: "github" | "google";
+                            clientIdEnvironmentVariable: string;
+                            clientSecretEnvironmentVariable: string;
+                            skipNonceCheck: boolean;
+                            emailOptional: boolean;
+                        }>[];
+                    }> | null;
+                    serviceEnvironmentFile: string | null;
+                    serviceEnvironmentVariables: readonly string[];
+                }> | null;
+                postgresql: Readonly<{
+                    migrationDirectory: string;
+                    runtimeWorkdir: string;
+                    image: string;
+                    database: string;
+                    user: string;
+                }> | null;
+                baseline: Readonly<{
+                    artifactDirectory: string;
+                    sanitizationPolicy: string;
+                }>;
+                containerRuntime: Readonly<{
+                    autoStartColima: boolean;
+                }>;
+                cleanup: Readonly<{
+                    retainBaselineGenerations: number;
+                }>;
+                preparation: Readonly<{
+                    sourcePolicy: string;
+                    privacyKey: string;
+                    batchRows: number;
+                    maximumRows: number;
+                    maximumBytes: number;
+                    diskHeadroomBytes: number;
+                }> | null;
+                runtimePolicy: string | null;
+                identityPolicy: string | null;
+                dependentTargets: readonly Readonly<{
+                    name: string;
+                    configPath: string;
+                    prepareCommand: string | null;
+                }>[];
+                application: Readonly<{
+                    startCommand: string;
+                    proofCommand: string;
+                    environmentFile: string;
+                    environmentVariables: Readonly<Record<string, string>>;
+                    readiness: Readonly<{
+                        url: string;
+                        expectedStatus: number;
+                        timeoutSeconds: number;
+                    }> | null;
+                    httpProofs: readonly Readonly<{
+                        name: string;
+                        kind: "positive" | "negative";
+                        url: string;
+                        method: string;
+                        expectedStatus: number;
+                        json: Readonly<{
+                            path: readonly string[];
+                            equals?: unknown;
+                            notEquals?: unknown;
+                            minimumItems?: number;
+                        }> | null;
+                    }>[];
+                    runtimeAdapter: string | null;
+                }>;
+                runtime: Readonly<{
+                    target: "postgresql" | "supabase";
+                    applicationUrl: string;
+                    projectId: string;
+                    ports: Readonly<{
+                        api?: number;
+                        database: number;
+                        studio?: number;
+                    }>;
+                }>;
+                safety: Readonly<{
+                    allowedHosts: readonly string[];
+                    blockedEnvironmentVariables: readonly string[];
+                    authenticationProviders: readonly string[];
+                    hostedAccess: "disabled";
+                    outboundNetwork: "deny";
+                }>;
+                verification: Readonly<{
+                    commands: readonly string[];
+                }>;
+            }>;
+            configPath: string;
+            projectRoot: string;
+            paths: Readonly<{
+                artifactDirectory: string;
+                applicationEnvironment: string;
+                migrationDirectory: string;
+                rehearsalConfig: string | null;
+                runtimeWorkdir: string;
+                serviceEnvironment: string | null;
+                sanitizationPolicy: string;
+                sourcePolicy: string | null;
+                privacyKey: string | null;
+                runtimePolicy: string | null;
+                identityPolicy: string | null;
+                supabaseWorkdir: string | null;
+                runtimeAdapter: string | null;
+            }>;
+        }>;
+        plan: import("../identity/claim.mjs").IdentityClaimPlan;
+    }>;
+    planRuntimeStackCleanup: ({ flags, planOptions, }: ProjectCommandInput) => Promise<RehearsalCleanupPlan | CleanupStackPlan>;
+    runBaselinePreparation: ({ flags, planOptions, }: ProjectCommandInput) => Promise<ReturnType<typeof summarizeBaselinePreparation>>;
+    runCleanup: ({ flags, planOptions, }: ProjectCommandInput) => Promise<unknown>;
+    runSetup: ({ flags, planOptions, }: ProjectCommandInput) => Promise<unknown>;
+}>;
+export {};

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, }) => {
+        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 = flags.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, }) => {
+        if (!flags.recordsPath || !flags.ledgerPath) {
+            throw new Error("baseline prepare requires --records and --ledger input paths.");
+        }
+        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 (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: 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`.
+ */
+export {};