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

package/dist/src/cli/source_commands.mjs

@@ -0,0 +1,299 @@
+/**
+ * CLI orchestration for temporary production-source access and safe baseline
+ * replacement. Domain validation remains in src/source and src/baseline.
+ */
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { activateBaselineGeneration, planBaselineGenerationPrune, planBaselineReplacementPrune, pruneBaselineGenerations, verifyActiveBaseline, } from "../baseline/artifact.mjs";
+import { createPrivacyEngine, readPrivacyKey, } from "../baseline/privacy_engine.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { createSourceAccessPlan, validateSourceAccessPolicy, } from "../source/access.mjs";
+import { streamApprovedSupabaseAssets } from "../source/asset_transfer.mjs";
+import { refreshPostgresqlBaseline } from "../source/baseline.mjs";
+import { resolvePrivacyMappedAssets } from "../source/privacy_paths.mjs";
+import { applyPostgresqlSourceAccess, planPostgresqlSourceAccessRetirement, resolvePostgresqlSourceStatePaths, retirePostgresqlSourceAccess, } from "../source/postgresql_access.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+const parseSourceAccessReceipt = (source) => {
+    const parsed = JSON.parse(source);
+    if (typeof parsed.targetFingerprint !== "string" ||
+        typeof parsed.planDigest !== "string" ||
+        typeof parsed.expiresAt !== "string") {
+        throw new Error("The source-access receipt has an invalid shape.");
+    }
+    return parsed;
+};
+export const loadPreparationContext = async (planOptions) => {
+    const loaded = await loadRehearsalConfig(planOptions);
+    if (!loaded.config.preparation) {
+        throw new Error("Source preparation is not configured. Review docs/standalone-workflow.md, then enable config.preparation.");
+    }
+    if (!loaded.paths.sourcePolicy || !loaded.paths.privacyKey) {
+        throw new Error("Source preparation paths are incomplete.");
+    }
+    const sourcePolicyBytes = await readFile(loaded.paths.sourcePolicy);
+    const sourcePolicy = validateSourceAccessPolicy(JSON.parse(sourcePolicyBytes.toString("utf8")));
+    return { loaded, sourcePolicy, sourcePolicyBytes };
+};
+export const runSourceAccess = async ({ flags, planOptions, }) => {
+    const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+    const plan = createSourceAccessPlan({ policy: sourcePolicy });
+    if (!flags.sourceAccessConfirmation)
+        return { mode: "preview", plan };
+    const applied = await applyPostgresqlSourceAccess({
+        plan,
+        confirmation: flags.sourceAccessConfirmation,
+        projectRoot: loaded.projectRoot,
+        artifactRoot: loaded.paths.artifactDirectory,
+    });
+    return {
+        mode: "written",
+        plan,
+        receipt: applied.receipt,
+        credentialFile: relative(loaded.projectRoot, applied.credentialPath),
+    };
+};
+export const runSourceRetirement = async ({ flags, planOptions, }) => {
+    const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+    const plan = await planPostgresqlSourceAccessRetirement({
+        projectRoot: loaded.projectRoot,
+        artifactRoot: loaded.paths.artifactDirectory,
+        targetFingerprint: sourcePolicy.targetFingerprint,
+    });
+    if (!flags.sourceRetirementConfirmation)
+        return { mode: "preview", plan };
+    await retirePostgresqlSourceAccess({
+        plan,
+        confirmation: flags.sourceRetirementConfirmation,
+        ...(sourcePolicy.administratorEnvironmentVariable
+            ? {
+                administratorEnvironmentVariable: sourcePolicy.administratorEnvironmentVariable,
+            }
+            : {}),
+        projectRoot: loaded.projectRoot,
+        artifactRoot: loaded.paths.artifactDirectory,
+        credentialFile: sourcePolicy.reader.credentialFile,
+    });
+    return { mode: "written", plan };
+};
+const readSourceReaderCredential = async (path) => {
+    const details = await stat(path);
+    if (!details.isFile() || (details.mode & 0o077) !== 0) {
+        throw new Error("Source reader credential must be an owner-only regular file.");
+    }
+    const lines = (await readFile(path, "utf8")).split(/\r?\n/u).filter(Boolean);
+    if (lines.length !== 1 ||
+        !lines[0]?.startsWith("REHEARSAL_SOURCE_DATABASE_URL=")) {
+        throw new Error("Source reader credential file has an invalid shape.");
+    }
+    const value = lines[0].slice("REHEARSAL_SOURCE_DATABASE_URL=".length);
+    if (!value)
+        throw new Error("Source reader credential file is empty.");
+    return value;
+};
+export const runSourceBaselineRefresh = async ({ planOptions, }) => {
+    const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+    const preparation = loaded.config.preparation;
+    const privacyKeyPath = loaded.paths.privacyKey;
+    if (!preparation || !privacyKeyPath) {
+        throw new Error("Source preparation configuration is incomplete.");
+    }
+    const { credentialPath } = resolvePostgresqlSourceStatePaths({
+        projectRoot: loaded.projectRoot,
+        artifactRoot: loaded.paths.artifactDirectory,
+        credentialFile: sourcePolicy.reader.credentialFile,
+    });
+    const [sourceAccessReceipt, privacyPolicyBytes, privacyKey, connectionString,] = await Promise.all([
+        readFile(join(loaded.paths.artifactDirectory, "source-access-receipt.json"), "utf8").then(parseSourceAccessReceipt),
+        readFile(loaded.paths.sanitizationPolicy),
+        readPrivacyKey(privacyKeyPath),
+        readSourceReaderCredential(credentialPath),
+    ]);
+    const privacyPolicy = JSON.parse(privacyPolicyBytes.toString("utf8"));
+    const assetPrivacyEngine = createPrivacyEngine({
+        policy: privacyPolicy,
+        key: privacyKey,
+    });
+    const assetDeclarations = resolvePrivacyMappedAssets({
+        sourcePolicy,
+        privacyPolicy,
+    });
+    return refreshPostgresqlBaseline({
+        connectionString,
+        sourcePolicy,
+        sourceAccessReceipt,
+        privacyPolicyBytes,
+        privacyKey,
+        artifactRoot: loaded.paths.artifactDirectory,
+        migrationDirectory: loaded.paths.migrationDirectory,
+        limits: {
+            batchRows: preparation.batchRows,
+            maximumRows: preparation.maximumRows,
+            maximumBytes: preparation.maximumBytes,
+            diskHeadroomBytes: preparation.diskHeadroomBytes,
+        },
+        assets: sourcePolicy.assetReader
+            ? streamApprovedSupabaseAssets({
+                baseUrl: process.env[sourcePolicy.assetReader.baseUrlEnvironmentVariable] ??
+                    "",
+                token: process.env[sourcePolicy.assetReader.tokenEnvironmentVariable] ??
+                    "",
+                declarations: assetDeclarations,
+                maximumObjects: sourcePolicy.assetReader.maximumObjects,
+                maximumObjectBytes: sourcePolicy.assetReader.maximumObjectBytes,
+                maximumTotalBytes: sourcePolicy.assetReader.maximumTotalBytes,
+                pathMapper: ({ mapping, value }) => assetPrivacyEngine.remapPath({ mapping, value }),
+            })
+            : [],
+    });
+};
+export const buildRefreshWorkflowPlan = async (planOptions) => {
+    const [{ loaded, sourcePolicy, sourcePolicyBytes }, topology] = await Promise.all([
+        loadPreparationContext(planOptions),
+        loadRuntimeTopology(planOptions),
+    ]);
+    const hashFile = async (path) => path
+        ? createHash("sha256")
+            .update(await readFile(path))
+            .digest("hex")
+        : null;
+    const [currentBaseline, sourceAccessReceipt, replacementCleanup, privacyPolicySha256, runtimeConfigurations,] = await Promise.all([
+        verifyActiveBaseline({ artifactRoot: loaded.paths.artifactDirectory }),
+        readFile(join(loaded.paths.artifactDirectory, "source-access-receipt.json"), "utf8").then(parseSourceAccessReceipt),
+        planBaselineReplacementPrune({
+            artifactRoot: loaded.paths.artifactDirectory,
+            retain: loaded.config.cleanup.retainBaselineGenerations,
+        }),
+        hashFile(loaded.paths.sanitizationPolicy),
+        Promise.all(topology.targets.map(async (target) => ({
+            target: target.name,
+            configSha256: await hashFile(target.configPath),
+            runtimePolicySha256: await hashFile(target.paths.runtimePolicy),
+            runtimeAdapterSha256: await hashFile(target.paths.runtimeAdapter),
+            localServiceConfigSha256: await hashFile(target.paths.rehearsalConfig),
+        }))),
+    ]);
+    if (sourceAccessReceipt.targetFingerprint !== sourcePolicy.targetFingerprint ||
+        !/^[a-f0-9]{64}$/u.test(sourceAccessReceipt.planDigest ?? "")) {
+        throw new Error("The source-access receipt does not match the selected refresh policy.");
+    }
+    const sourceReaderExpiry = new Date(sourceAccessReceipt.expiresAt).valueOf();
+    if (!Number.isFinite(sourceReaderExpiry) ||
+        sourceReaderExpiry <= Date.now()) {
+        throw new Error("The temporary source reader has expired. Preview and apply source access again before refreshing.");
+    }
+    const review = {
+        planVersion: 1,
+        operation: "refresh-and-replace-local-copy",
+        currentBaseline: currentBaseline.generationId,
+        source: {
+            targetFingerprint: sourcePolicy.targetFingerprint,
+            accessPlanDigest: sourceAccessReceipt.planDigest,
+            readerExpiresAt: sourceAccessReceipt.expiresAt,
+            sourcePolicySha256: createHash("sha256")
+                .update(sourcePolicyBytes)
+                .digest("hex"),
+            privacyPolicySha256,
+        },
+        runtimeConfigurations,
+        runtimeTargets: topology.targets.map((target) => target.name),
+        dependentPreparations: topology.dependents.flatMap((target) => target.declaration?.prepareCommand
+            ? [{ target: target.name, command: target.declaration.prepareCommand }]
+            : []),
+        retention: {
+            generations: loaded.config.cleanup.retainBaselineGenerations,
+            removeAfterReplacement: replacementCleanup.removedAfterReplacement,
+            keepFromCurrent: replacementCleanup.retainedAfterReplacement,
+        },
+        steps: [
+            "build and verify a new immutable baseline beside the current baseline",
+            "activate the new baseline only after verification",
+            "discard runtime edits and reset the complete local runtime stack",
+            "run configured dependent preparation commands",
+            "remove only the old baseline generations listed in this plan",
+        ],
+    };
+    return {
+        loaded,
+        topology,
+        plan: {
+            review,
+            digest: createHash("sha256")
+                .update(`${JSON.stringify(review, null, "\t")}\n`)
+                .digest("hex"),
+        },
+    };
+};
+export const createRefreshWorkflow = ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment, buildPlan = buildRefreshWorkflowPlan, refreshBaseline = runSourceBaselineRefresh, }) => async ({ flags, planOptions }) => {
+    const context = await buildPlan(planOptions);
+    if (!flags.refreshConfirmation) {
+        return { mode: "preview", plan: context.plan };
+    }
+    if (flags.refreshConfirmation !== context.plan.digest) {
+        throw new Error(`Refresh confirmation does not match this exact plan. Expected ${context.plan.digest}. Nothing changed.`);
+    }
+    let refreshed;
+    let runtime;
+    let preparations = [];
+    try {
+        refreshed = await refreshBaseline({ planOptions });
+        const stack = await runRuntimeStack({
+            command: "reset",
+            flags,
+            planOptions,
+        });
+        runtime = stack.runtime;
+        preparations = prepareDependentTargets({
+            topology: stack.topology,
+            environment: topologyCommandEnvironment(stack.topology),
+        });
+    }
+    catch (error) {
+        if (refreshed) {
+            await activateBaselineGeneration({
+                artifactRoot: context.loaded.paths.artifactDirectory,
+                generationId: context.plan.review.currentBaseline,
+            });
+            try {
+                const rollback = await runRuntimeStack({
+                    command: "reset",
+                    flags,
+                    planOptions,
+                });
+                prepareDependentTargets({
+                    topology: rollback.topology,
+                    environment: topologyCommandEnvironment(rollback.topology),
+                });
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], "The refreshed runtime failed and the previous local runtime could not be restored automatically. The previous immutable baseline is active; run rehearsal reset after correcting the reported problem.");
+            }
+            throw new Error("The refreshed runtime failed verification. Rehearsal restored the previous baseline and local runtime.", { cause: error });
+        }
+        throw error;
+    }
+    let cleanup;
+    try {
+        const result = await pruneBaselineGenerations({
+            artifactRoot: context.loaded.paths.artifactDirectory,
+            retain: context.plan.review.retention.generations,
+            expectedRemoved: context.plan.review.retention.removeAfterReplacement,
+        });
+        cleanup = { state: "complete", removed: result.removed };
+    }
+    catch {
+        const remaining = await planBaselineGenerationPrune({
+            artifactRoot: context.loaded.paths.artifactDirectory,
+            retain: context.plan.review.retention.generations,
+        }).catch(() => ({ removed: [] }));
+        cleanup = { state: "incomplete", remaining: remaining.removed.length };
+    }
+    return {
+        mode: "written",
+        plan: context.plan,
+        refreshed,
+        runtime,
+        preparations,
+        cleanup,
+    };
+};

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

@@ -0,0 +1,59 @@
+/** Terminal presentation and prompt primitives shared by guided CLI workflows. */
+export interface TerminalFlags {
+    readonly plain?: boolean;
+    readonly json?: boolean;
+}
+export interface ChoiceOption<Value = unknown> {
+    readonly label: string;
+    readonly hint?: string;
+    readonly command?: string;
+    readonly value?: Value;
+}
+interface ValueChoiceOption<Value> extends ChoiceOption<Value> {
+    readonly value: Value;
+}
+type PathValidator = (value: string) => string | undefined;
+export declare const terminalStyle: (flags: TerminalFlags, code: string, value: string) => string;
+export declare const isHumanTerminal: (flags: TerminalFlags) => boolean;
+export declare const useStyledPrompts: (flags: TerminalFlags) => boolean;
+export declare const formatDuration: (durationMs: number) => string;
+export declare const promptForChoice: <Option extends ChoiceOption>({ message, options, flags, optionsAlreadyShown, }: {
+    message: string;
+    options: readonly Option[];
+    flags?: TerminalFlags;
+    optionsAlreadyShown?: boolean;
+}) => Promise<Option | undefined>;
+export declare function promptForConfirmation(message: string, flags: TerminalFlags, options: {
+    cancelValue: null;
+}): Promise<boolean | null>;
+export declare function promptForConfirmation(message: string, flags?: TerminalFlags, options?: {
+    cancelValue?: boolean;
+}): Promise<boolean>;
+export declare const promptForPath: ({ message, defaultValue, optional, flags, validate, }: {
+    message: string;
+    defaultValue?: string;
+    optional?: boolean;
+    flags?: TerminalFlags;
+    validate?: PathValidator;
+}) => Promise<string | undefined>;
+export declare const promptForSelection: <Value>({ message, options, flags, }: {
+    message: string;
+    options: readonly ValueChoiceOption<Value>[];
+    flags?: TerminalFlags;
+}) => Promise<Value | undefined>;
+export declare const promptForDiscoveredPath: ({ message, candidates, optional, flags, }: {
+    message: string;
+    candidates: readonly string[];
+    optional?: boolean;
+    flags?: TerminalFlags;
+}) => Promise<string | undefined>;
+export declare const promptForMultipleChoice: ({ message, options, initialValues, flags, }: {
+    message: string;
+    options: readonly ValueChoiceOption<string>[];
+    initialValues?: readonly string[];
+    flags?: TerminalFlags;
+}) => Promise<string[] | undefined>;
+export declare const installGuidedExitShortcut: (flags: TerminalFlags, { beforeExit }?: {
+    beforeExit?: () => void;
+}) => (() => void);
+export {};

package/dist/src/cli/terminal.mjs

@@ -0,0 +1,230 @@
+/** Terminal presentation and prompt primitives shared by guided CLI workflows. */
+import { createInterface } from "node:readline/promises";
+import * as prompts from "@clack/prompts";
+const useColor = (flags) => !flags.plain &&
+    process.stdout.isTTY &&
+    process.env.NO_COLOR === undefined &&
+    process.env.TERM !== "dumb";
+export const terminalStyle = (flags, code, value) => (useColor(flags) ? `\u001B[${code}m${value}\u001B[0m` : value);
+export const isHumanTerminal = (flags) => !flags.json && process.stdin.isTTY && process.stdout.isTTY;
+export const useStyledPrompts = (flags) => isHumanTerminal(flags) && useColor(flags);
+export const formatDuration = (durationMs) => durationMs < 1_000
+    ? `${Math.round(durationMs)}ms`
+    : `${(durationMs / 1_000).toFixed(1)}s`;
+export const promptForChoice = async ({ message, options, flags = {}, optionsAlreadyShown = false, }) => {
+    if (useStyledPrompts(flags)) {
+        const selected = await prompts.select({
+            message,
+            maxItems: options.length,
+            options: options.map((option, index) => ({
+                value: index,
+                label: option.label,
+                ...(option.hint === undefined ? {} : { hint: option.hint }),
+            })),
+        });
+        return prompts.isCancel(selected)
+            ? options.find((option) => option.command === "exit")
+            : options[selected];
+    }
+    if (!optionsAlreadyShown) {
+        console.log([
+            "",
+            ...options.map((option, index) => `  ${index === 0 ? "›" : " "} ${index + 1}. ${option.label}${option.hint ? ` — ${option.hint}` : ""}`),
+            "",
+        ].join("\n"));
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        while (true) {
+            const answer = (await prompt.question(`${message} [1]: `)).trim();
+            const selected = answer === "" ? 1 : Number(answer);
+            if (Number.isInteger(selected) &&
+                selected >= 1 &&
+                selected <= options.length) {
+                return options[selected - 1];
+            }
+            console.log(`Choose a number from 1 to ${options.length}.`);
+        }
+    }
+    finally {
+        prompt.close();
+    }
+};
+export async function promptForConfirmation(message, flags = {}, { cancelValue = false } = {}) {
+    if (useStyledPrompts(flags)) {
+        const accepted = await prompts.confirm({ message, initialValue: false });
+        return prompts.isCancel(accepted) ? cancelValue : accepted;
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await prompt.question(`${message} (y/N) `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        prompt.close();
+    }
+}
+export const promptForPath = async ({ message, defaultValue, optional = false, flags = {}, validate, }) => {
+    if (useStyledPrompts(flags)) {
+        const answer = await prompts.text({
+            message,
+            placeholder: defaultValue ?? (optional ? "Leave blank for none" : ""),
+            ...(defaultValue === undefined ? {} : { defaultValue }),
+            validate: (value) => {
+                const resolved = String(value || defaultValue || "").trim();
+                if (!optional && !resolved)
+                    return "Enter a value.";
+                return resolved && validate ? validate(resolved) : undefined;
+            },
+        });
+        if (prompts.isCancel(answer))
+            return undefined;
+        return String(answer || defaultValue || "").trim() || undefined;
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        while (true) {
+            const suffix = defaultValue
+                ? ` [${defaultValue}]`
+                : optional
+                    ? ""
+                    : " (required)";
+            const answer = (await prompt.question(`${message}${suffix}: `)).trim();
+            const value = answer || defaultValue || "";
+            const invalid = value && validate ? validate(value) : undefined;
+            if (invalid) {
+                console.log(invalid);
+                continue;
+            }
+            if (value || optional)
+                return value || undefined;
+            console.log("Enter a project-relative path.");
+        }
+    }
+    finally {
+        prompt.close();
+    }
+};
+export const promptForSelection = async ({ message, options, flags = {}, }) => {
+    const selected = await promptForChoice({ message, options, flags });
+    return selected?.value;
+};
+export const promptForDiscoveredPath = async ({ message, candidates, optional = false, flags = {}, }) => {
+    if (candidates.length === 0)
+        return promptForPath({ message, optional, flags });
+    const noneValue = "\0none";
+    const manualValue = "\0manual";
+    const selected = await promptForSelection({
+        message,
+        flags,
+        options: [
+            ...(optional
+                ? [
+                    {
+                        label: "No storage assets",
+                        hint: "Continue without an asset manifest",
+                        value: noneValue,
+                    },
+                ]
+                : []),
+            ...candidates.map((path) => ({ label: path, value: path })),
+            { label: "Enter another path", value: manualValue },
+        ],
+    });
+    if (!selected || selected === noneValue)
+        return undefined;
+    if (selected !== manualValue)
+        return selected;
+    return promptForPath({ message, optional, flags });
+};
+export const promptForMultipleChoice = async ({ message, options, initialValues = [], flags = {}, }) => {
+    if (useStyledPrompts(flags)) {
+        const selected = await prompts.multiselect({
+            message,
+            options: options.map((option) => ({
+                value: option.value,
+                label: option.label,
+                ...(option.hint === undefined ? {} : { hint: option.hint }),
+            })),
+            initialValues: [...initialValues],
+            required: false,
+        });
+        return prompts.isCancel(selected) ? undefined : selected;
+    }
+    const initial = new Set(initialValues);
+    console.log("");
+    console.log(message);
+    for (const [index, option] of options.entries()) {
+        console.log(`  ${index + 1}. ${option.label}${initial.has(option.value) ? " (suggested)" : ""}`);
+    }
+    const defaultNumbers = options
+        .map((option, index) => (initial.has(option.value) ? index + 1 : undefined))
+        .filter(Boolean)
+        .join(",");
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        while (true) {
+            const suffix = defaultNumbers ? ` [${defaultNumbers}]` : " [none]";
+            const answer = (await prompt.question(`Choose comma-separated numbers, all, or none${suffix}: `))
+                .trim()
+                .toLowerCase();
+            if (!answer)
+                return [...initialValues];
+            if (answer === "none")
+                return [];
+            if (answer === "all")
+                return options.map((option) => option.value);
+            const indexes = answer.split(",").map((value) => Number(value.trim()));
+            if (indexes.length > 0 &&
+                indexes.every((index) => Number.isInteger(index) && index >= 1 && index <= options.length)) {
+                return [...new Set(indexes)].map((index) => options[index - 1].value);
+            }
+            console.log(`Choose numbers from 1 to ${options.length}, all, or none.`);
+        }
+    }
+    finally {
+        prompt.close();
+    }
+};
+export const installGuidedExitShortcut = (flags, { beforeExit } = {}) => {
+    let exiting = false;
+    const exit = () => {
+        if (exiting)
+            return;
+        exiting = true;
+        if (process.stdin.isTTY && process.stdin.isRaw)
+            process.stdin.setRawMode(false);
+        beforeExit?.();
+        process.stdout.write("\u001B[?25h");
+        if (useStyledPrompts(flags))
+            prompts.outro("Rehearsal exited.");
+        else
+            console.log("\nRehearsal exited.");
+        process.exit(0);
+    };
+    const onInput = (chunk) => {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (bytes.includes(0x1a))
+            exit();
+    };
+    process.stdin.prependListener("data", onInput);
+    process.prependListener("SIGTSTP", exit);
+    return () => {
+        process.stdin.removeListener("data", onInput);
+        process.removeListener("SIGTSTP", exit);
+    };
+};