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

package/dist/src/project/configuration.mjs

@@ -0,0 +1,958 @@
+/**
+ * Purpose: Load and strictly validate the versioned, project-owned Rehearsal
+ * configuration contract. Do not run directly; this module is reusable script
+ * infrastructure.
+ */
+import { access, readFile, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveRuntimeTarget } from "../targets/target.mjs";
+export const REHEARSAL_CONFIG_VERSION = 1;
+export const REHEARSAL_DEFAULTS = Object.freeze({
+    baseline: Object.freeze({ artifactDirectory: ".rehearsal" }),
+    containerRuntime: Object.freeze({ autoStartColima: true }),
+    cleanup: Object.freeze({ retainBaselineGenerations: 2 }),
+    runtime: Object.freeze({
+        applicationUrl: "http://localhost:5175",
+        projectId: "rehearsal-local",
+    }),
+    safety: Object.freeze({
+        allowedHosts: Object.freeze(["127.0.0.1", "::1", "localhost"]),
+        blockedEnvironmentVariables: Object.freeze([
+            "DATABASE_URL",
+            "PGHOST",
+            "PGPASSWORD",
+            "PGPORT",
+            "PGUSER",
+            "SUPABASE_ACCESS_TOKEN",
+            "SUPABASE_DB_PASSWORD",
+            "SUPABASE_PROJECT_ID",
+        ]),
+        hostedAccess: "disabled",
+        outboundNetwork: "deny",
+    }),
+});
+const CONFIG_FILENAMES = Object.freeze([
+    "rehearsal.config.mjs",
+    "rehearsal.config.js",
+    "rehearsal.config.ts",
+    join("infrastructure", "rehearsal", "rehearsal.config.mjs"),
+    join("infrastructure", "rehearsal", "rehearsal.config.ts"),
+]);
+const LOOPBACK_HOSTS = new Set(REHEARSAL_DEFAULTS.safety.allowedHosts);
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}$/u;
+const DATABASE_IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]{0,62}$/u;
+const POSTGRES_IMAGE_PATTERN = /^postgres:\d+(?:\.\d+)?-alpine$/u;
+const SAFE_COMMAND_PATTERN = /^[^\n\r\0]+$/u;
+const ENVIRONMENT_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
+const ENVIRONMENT_REFERENCE_PATTERN = /^[a-z0-9][a-z0-9-]*:[A-Z][A-Z0-9_]*$/u;
+const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
+const hasErrorCode = (error, code) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code;
+const isPlainObject = (value) => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype;
+const assertPlainObject = (value, path) => {
+    if (!isPlainObject(value)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    return value;
+};
+const assertKnownKeys = (value, keys, path) => {
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key)) {
+            throw new Error(`Unknown Rehearsal configuration property: ${path}.${key}.`);
+        }
+    }
+};
+const assertNonEmptyString = (value, path) => {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${path} must be a non-empty string.`);
+    }
+    return value.trim();
+};
+const assertRelativePath = (value, path) => {
+    const normalized = assertNonEmptyString(value, path);
+    if (isAbsolute(normalized) || normalized.split(/[\\/]/u).includes("..")) {
+        throw new Error(`${path} must stay inside the project root.`);
+    }
+    return normalized;
+};
+const assertCommand = (value, path) => {
+    const command = assertNonEmptyString(value, path);
+    if (!SAFE_COMMAND_PATTERN.test(command)) {
+        throw new Error(`${path} contains an unsafe control character.`);
+    }
+    return command;
+};
+const assertPort = (value, path) => {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 1024 ||
+        value > 65_535) {
+        throw new Error(`${path} must be a non-privileged TCP port.`);
+    }
+    return value;
+};
+const assertBoolean = (value, path) => {
+    if (typeof value !== "boolean") {
+        throw new Error(`${path} must be true or false.`);
+    }
+    return value;
+};
+const assertPositiveInteger = (value, path) => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${path} must be a positive integer.`);
+    }
+    return value;
+};
+const assertHttpStatus = (value, path) => {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 100 ||
+        value > 599) {
+        throw new Error(`${path} must be an HTTP status.`);
+    }
+    return value;
+};
+const assertStringArray = (value, path) => {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.some((entry) => typeof entry !== "string" || !entry.trim())) {
+        throw new Error(`${path} must be a non-empty string array.`);
+    }
+    return [...new Set(value.map((entry) => entry.trim()))];
+};
+const normalizeApplicationEnvironmentMappings = (value = {}) => {
+    const mappings = assertPlainObject(value, "config.application.environmentVariables");
+    return Object.freeze(Object.fromEntries(Object.entries(mappings).map(([key, reference]) => {
+        if (!ENVIRONMENT_KEY_PATTERN.test(key)) {
+            throw new Error(`config.application.environmentVariables.${key} is not a safe environment variable name.`);
+        }
+        if (typeof reference !== "string" ||
+            !ENVIRONMENT_REFERENCE_PATTERN.test(reference)) {
+            throw new Error(`config.application.environmentVariables.${key} must reference target:VARIABLE, such as primary:DATABASE_URL.`);
+        }
+        return [key, reference];
+    })));
+};
+const assertLoopbackUrl = (value, path, allowedHosts) => {
+    let parsed;
+    try {
+        parsed = new URL(assertNonEmptyString(value, path));
+    }
+    catch {
+        throw new Error(`${path} must be a valid loopback URL.`);
+    }
+    if (!allowedHosts.includes(parsed.hostname) ||
+        !LOOPBACK_HOSTS.has(parsed.hostname)) {
+        throw new Error(`${path} must use an explicitly allowed loopback host.`);
+    }
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+        throw new Error(`${path} must use HTTP or HTTPS.`);
+    }
+    return parsed.toString().replace(/\/$/u, "");
+};
+const normalizeConfig = (input) => {
+    const root = assertPlainObject(input, "config");
+    assertKnownKeys(root, [
+        "schemaVersion",
+        "project",
+        "supabase",
+        "postgresql",
+        "baseline",
+        "containerRuntime",
+        "cleanup",
+        "preparation",
+        "runtimePolicy",
+        "identityPolicy",
+        "dependentTargets",
+        "application",
+        "runtime",
+        "safety",
+        "verification",
+    ], "config");
+    if (root.schemaVersion !== REHEARSAL_CONFIG_VERSION) {
+        throw new Error(`Unsupported Rehearsal configuration version: ${String(root.schemaVersion)}. Expected ${REHEARSAL_CONFIG_VERSION}.`);
+    }
+    const project = assertPlainObject(root.project, "config.project");
+    assertKnownKeys(project, ["name"], "config.project");
+    const projectName = assertNonEmptyString(project.name, "config.project.name");
+    if (!IDENTIFIER_PATTERN.test(projectName)) {
+        throw new Error("config.project.name must contain only lowercase letters, digits, and hyphens.");
+    }
+    const runtime = assertPlainObject(root.runtime ?? {}, "config.runtime");
+    const runtimeTarget = resolveRuntimeTarget(runtime.target).id;
+    const supabase = runtimeTarget === "supabase"
+        ? assertPlainObject(root.supabase, "config.supabase")
+        : null;
+    const postgresql = runtimeTarget === "postgresql"
+        ? assertPlainObject(root.postgresql, "config.postgresql")
+        : null;
+    if (runtimeTarget === "supabase" && root.postgresql !== undefined) {
+        throw new Error("config.postgresql is not allowed when config.runtime.target is supabase.");
+    }
+    if (runtimeTarget === "postgresql" && root.supabase !== undefined) {
+        throw new Error("config.supabase is not allowed when config.runtime.target is postgresql.");
+    }
+    if (supabase) {
+        assertKnownKeys(supabase, [
+            "workdir",
+            "migrationDirectory",
+            "rehearsalConfig",
+            "runtimeWorkdir",
+            "authentication",
+            "serviceEnvironmentFile",
+            "serviceEnvironmentVariables",
+        ], "config.supabase");
+    }
+    if (postgresql) {
+        assertKnownKeys(postgresql, ["migrationDirectory", "runtimeWorkdir", "image", "database", "user"], "config.postgresql");
+    }
+    const baseline = assertPlainObject(root.baseline, "config.baseline");
+    assertKnownKeys(baseline, ["artifactDirectory", "sanitizationPolicy"], "config.baseline");
+    const containerRuntime = assertPlainObject(root.containerRuntime ?? {}, "config.containerRuntime");
+    assertKnownKeys(containerRuntime, ["autoStartColima"], "config.containerRuntime");
+    const cleanup = assertPlainObject(root.cleanup ?? {}, "config.cleanup");
+    assertKnownKeys(cleanup, ["retainBaselineGenerations"], "config.cleanup");
+    const preparation = root.preparation === undefined
+        ? null
+        : assertPlainObject(root.preparation, "config.preparation");
+    if (preparation) {
+        assertKnownKeys(preparation, [
+            "sourcePolicy",
+            "privacyKey",
+            "batchRows",
+            "maximumRows",
+            "maximumBytes",
+            "diskHeadroomBytes",
+        ], "config.preparation");
+    }
+    const dependentTargets = root.dependentTargets ?? [];
+    if (!Array.isArray(dependentTargets)) {
+        throw new Error("config.dependentTargets must be an array.");
+    }
+    const normalizedDependentTargets = dependentTargets.map((entry, index) => {
+        const path = `config.dependentTargets[${index}]`;
+        const target = assertPlainObject(entry, path);
+        assertKnownKeys(target, ["name", "configPath", "prepareCommand"], path);
+        const name = assertNonEmptyString(target.name, `${path}.name`);
+        if (!IDENTIFIER_PATTERN.test(name)) {
+            throw new Error(`${path}.name must contain only lowercase letters, digits, and hyphens.`);
+        }
+        return Object.freeze({
+            name,
+            configPath: assertRelativePath(target.configPath, `${path}.configPath`),
+            prepareCommand: target.prepareCommand === undefined
+                ? null
+                : assertCommand(target.prepareCommand, `${path}.prepareCommand`),
+        });
+    });
+    if (new Set(normalizedDependentTargets.map((target) => target.name)).size !==
+        normalizedDependentTargets.length) {
+        throw new Error("config.dependentTargets names must be unique.");
+    }
+    const application = assertPlainObject(root.application, "config.application");
+    assertKnownKeys(application, [
+        "startCommand",
+        "proofCommand",
+        "environmentFile",
+        "environmentVariables",
+        "readiness",
+        "httpProofs",
+        "runtimeAdapter",
+    ], "config.application");
+    const readiness = application.readiness === undefined
+        ? null
+        : assertPlainObject(application.readiness, "config.application.readiness");
+    if (readiness) {
+        assertKnownKeys(readiness, ["url", "expectedStatus", "timeoutSeconds"], "config.application.readiness");
+    }
+    const httpProofs = application.httpProofs ?? [];
+    if (!Array.isArray(httpProofs)) {
+        throw new Error("config.application.httpProofs must be an array.");
+    }
+    if (httpProofs.length > 0 &&
+        (!httpProofs.some((proof) => proof?.kind === "positive") ||
+            !httpProofs.some((proof) => proof?.kind === "negative"))) {
+        throw new Error("config.application.httpProofs must include at least one positive and one negative check.");
+    }
+    assertKnownKeys(runtime, [
+        "target",
+        "applicationUrl",
+        "projectId",
+        "apiPort",
+        "databasePort",
+        "studioPort",
+    ], "config.runtime");
+    const safety = assertPlainObject(root.safety ?? {}, "config.safety");
+    assertKnownKeys(safety, [
+        "allowedHosts",
+        "blockedEnvironmentVariables",
+        "authenticationProviders",
+        "hostedAccess",
+        "outboundNetwork",
+    ], "config.safety");
+    const verification = assertPlainObject(root.verification ?? {}, "config.verification");
+    assertKnownKeys(verification, ["commands"], "config.verification");
+    const allowedHosts = assertStringArray(safety.allowedHosts ?? REHEARSAL_DEFAULTS.safety.allowedHosts, "config.safety.allowedHosts");
+    if (allowedHosts.some((host) => !LOOPBACK_HOSTS.has(host))) {
+        throw new Error("config.safety.allowedHosts may contain loopback hosts only in configuration version 1.");
+    }
+    if ((safety.hostedAccess ?? "disabled") !== "disabled") {
+        throw new Error("config.safety.hostedAccess must remain disabled in configuration version 1.");
+    }
+    if ((safety.outboundNetwork ?? "deny") !== "deny") {
+        throw new Error("config.safety.outboundNetwork must remain deny in configuration version 1.");
+    }
+    const ports = {
+        ...(runtimeTarget === "supabase"
+            ? { api: assertPort(runtime.apiPort, "config.runtime.apiPort") }
+            : {}),
+        database: assertPort(runtime.databasePort, "config.runtime.databasePort"),
+        ...(runtimeTarget === "supabase"
+            ? { studio: assertPort(runtime.studioPort, "config.runtime.studioPort") }
+            : {}),
+    };
+    if (new Set(Object.values(ports)).size !== Object.values(ports).length) {
+        throw new Error("Rehearsal runtime ports must be unique.");
+    }
+    const commands = verification.commands ?? [];
+    if (!Array.isArray(commands)) {
+        throw new Error("config.verification.commands must be an array.");
+    }
+    const authentication = supabase?.authentication === undefined
+        ? null
+        : assertPlainObject(supabase.authentication, "config.supabase.authentication");
+    let normalizedAuthentication = null;
+    if (authentication) {
+        if (!supabase) {
+            throw new Error("config.supabase.authentication requires the Supabase runtime target.");
+        }
+        assertKnownKeys(authentication, ["enableLocalSignup", "environmentFile", "providers"], "config.supabase.authentication");
+        if (authentication.enableLocalSignup !== true) {
+            throw new Error("config.supabase.authentication.enableLocalSignup must be true to create the disposable local identity used by an OAuth sign-in.");
+        }
+        if (supabase.serviceEnvironmentFile !== undefined ||
+            supabase.serviceEnvironmentVariables !== undefined) {
+            throw new Error("config.supabase.authentication cannot be combined with the legacy serviceEnvironmentFile or serviceEnvironmentVariables fields.");
+        }
+        if (safety.authenticationProviders !== undefined) {
+            throw new Error("config.safety.authenticationProviders is derived from config.supabase.authentication and must be omitted.");
+        }
+        if (!Array.isArray(authentication.providers) ||
+            authentication.providers.length === 0) {
+            throw new Error("config.supabase.authentication.providers must be a non-empty array.");
+        }
+        const providers = authentication.providers.map((entry, index) => {
+            const path = `config.supabase.authentication.providers[${index}]`;
+            const value = assertPlainObject(entry, path);
+            assertKnownKeys(value, [
+                "name",
+                "clientIdEnvironmentVariable",
+                "clientSecretEnvironmentVariable",
+                "skipNonceCheck",
+                "emailOptional",
+            ], path);
+            const reviewedName = assertNonEmptyString(value.name, `${path}.name`);
+            if (!SUPPORTED_SUPABASE_OAUTH_PROVIDERS.has(reviewedName)) {
+                throw new Error(`${path}.name must be one of: ${[...SUPPORTED_SUPABASE_OAUTH_PROVIDERS].join(", ")}.`);
+            }
+            const name = reviewedName;
+            const environmentVariable = (key) => {
+                const variable = assertNonEmptyString(value[key], `${path}.${key}`);
+                if (!ENVIRONMENT_KEY_PATTERN.test(variable)) {
+                    throw new Error(`${path}.${key} must be a safe environment variable name.`);
+                }
+                return variable;
+            };
+            const optionalBoolean = (key) => {
+                if (value[key] === undefined)
+                    return false;
+                if (typeof value[key] !== "boolean") {
+                    throw new Error(`${path}.${key} must be a boolean.`);
+                }
+                return value[key];
+            };
+            return Object.freeze({
+                name,
+                clientIdEnvironmentVariable: environmentVariable("clientIdEnvironmentVariable"),
+                clientSecretEnvironmentVariable: environmentVariable("clientSecretEnvironmentVariable"),
+                skipNonceCheck: optionalBoolean("skipNonceCheck"),
+                emailOptional: optionalBoolean("emailOptional"),
+            });
+        });
+        if (new Set(providers.map(({ name }) => name)).size !==
+            providers.length) {
+            throw new Error("config.supabase.authentication.providers must not contain duplicate providers.");
+        }
+        const credentialVariables = providers.flatMap((provider) => [
+            provider.clientIdEnvironmentVariable,
+            provider.clientSecretEnvironmentVariable,
+        ]);
+        if (new Set(credentialVariables).size !== credentialVariables.length) {
+            throw new Error("config.supabase.authentication provider environment variables must be unique.");
+        }
+        normalizedAuthentication = Object.freeze({
+            enableLocalSignup: true,
+            environmentFile: assertRelativePath(authentication.environmentFile, "config.supabase.authentication.environmentFile"),
+            providers: Object.freeze(providers),
+        });
+    }
+    const serviceEnvironmentVariables = normalizedAuthentication
+        ? normalizedAuthentication.providers.flatMap((provider) => [
+            provider.clientIdEnvironmentVariable,
+            provider.clientSecretEnvironmentVariable,
+        ])
+        : (supabase?.serviceEnvironmentVariables ?? []);
+    if (!Array.isArray(serviceEnvironmentVariables)) {
+        throw new Error("config.supabase.serviceEnvironmentVariables must be an array.");
+    }
+    const normalizedServiceEnvironmentVariables = serviceEnvironmentVariables.map((value, index) => assertNonEmptyString(value, `config.supabase.serviceEnvironmentVariables[${index}]`));
+    if (new Set(normalizedServiceEnvironmentVariables).size !==
+        normalizedServiceEnvironmentVariables.length) {
+        throw new Error("config.supabase.serviceEnvironmentVariables must not contain duplicates.");
+    }
+    if (Boolean(normalizedAuthentication?.environmentFile ??
+        supabase?.serviceEnvironmentFile) !== Boolean(normalizedServiceEnvironmentVariables.length)) {
+        throw new Error("config.supabase.serviceEnvironmentFile and serviceEnvironmentVariables must be configured together.");
+    }
+    const authenticationProviders = normalizedAuthentication
+        ? normalizedAuthentication.providers.map(({ name }) => name)
+        : safety.authenticationProviders
+            ? assertStringArray(safety.authenticationProviders, "config.safety.authenticationProviders")
+            : [];
+    if (runtimeTarget === "postgresql" && authenticationProviders.length > 0) {
+        throw new Error("config.safety.authenticationProviders is available only for the Supabase target.");
+    }
+    return Object.freeze({
+        schemaVersion: REHEARSAL_CONFIG_VERSION,
+        project: Object.freeze({ name: projectName }),
+        supabase: supabase
+            ? Object.freeze({
+                workdir: assertRelativePath(supabase.workdir, "config.supabase.workdir"),
+                migrationDirectory: assertRelativePath(supabase.migrationDirectory, "config.supabase.migrationDirectory"),
+                rehearsalConfig: assertRelativePath(supabase.rehearsalConfig, "config.supabase.rehearsalConfig"),
+                runtimeWorkdir: assertRelativePath(supabase.runtimeWorkdir, "config.supabase.runtimeWorkdir"),
+                authentication: normalizedAuthentication,
+                serviceEnvironmentFile: normalizedAuthentication
+                    ? normalizedAuthentication.environmentFile
+                    : supabase.serviceEnvironmentFile
+                        ? assertRelativePath(supabase.serviceEnvironmentFile, "config.supabase.serviceEnvironmentFile")
+                        : null,
+                serviceEnvironmentVariables: Object.freeze(normalizedServiceEnvironmentVariables),
+            })
+            : null,
+        postgresql: postgresql
+            ? Object.freeze({
+                migrationDirectory: assertRelativePath(postgresql.migrationDirectory, "config.postgresql.migrationDirectory"),
+                runtimeWorkdir: assertRelativePath(postgresql.runtimeWorkdir ?? ".rehearsal/runtime", "config.postgresql.runtimeWorkdir"),
+                image: (() => {
+                    const image = assertNonEmptyString(postgresql.image ?? "postgres:17-alpine", "config.postgresql.image");
+                    if (!POSTGRES_IMAGE_PATTERN.test(image)) {
+                        throw new Error("config.postgresql.image must name an official versioned Alpine PostgreSQL image, such as postgres:17-alpine.");
+                    }
+                    return image;
+                })(),
+                database: (() => {
+                    const database = assertNonEmptyString(postgresql.database ?? "postgres", "config.postgresql.database");
+                    if (!DATABASE_IDENTIFIER_PATTERN.test(database)) {
+                        throw new Error("config.postgresql.database must be a safe lowercase PostgreSQL identifier.");
+                    }
+                    return database;
+                })(),
+                user: (() => {
+                    const user = assertNonEmptyString(postgresql.user ?? "postgres", "config.postgresql.user");
+                    if (!DATABASE_IDENTIFIER_PATTERN.test(user)) {
+                        throw new Error("config.postgresql.user must be a safe lowercase PostgreSQL identifier.");
+                    }
+                    return user;
+                })(),
+            })
+            : null,
+        baseline: Object.freeze({
+            artifactDirectory: assertRelativePath(baseline.artifactDirectory ??
+                REHEARSAL_DEFAULTS.baseline.artifactDirectory, "config.baseline.artifactDirectory"),
+            sanitizationPolicy: assertRelativePath(baseline.sanitizationPolicy, "config.baseline.sanitizationPolicy"),
+        }),
+        containerRuntime: Object.freeze({
+            autoStartColima: assertBoolean(containerRuntime.autoStartColima ??
+                REHEARSAL_DEFAULTS.containerRuntime.autoStartColima, "config.containerRuntime.autoStartColima"),
+        }),
+        cleanup: Object.freeze({
+            retainBaselineGenerations: assertPositiveInteger(cleanup.retainBaselineGenerations ??
+                REHEARSAL_DEFAULTS.cleanup.retainBaselineGenerations, "config.cleanup.retainBaselineGenerations"),
+        }),
+        preparation: preparation
+            ? Object.freeze({
+                sourcePolicy: assertRelativePath(preparation.sourcePolicy, "config.preparation.sourcePolicy"),
+                privacyKey: assertRelativePath(preparation.privacyKey, "config.preparation.privacyKey"),
+                batchRows: assertPositiveInteger(preparation.batchRows ?? 500, "config.preparation.batchRows"),
+                maximumRows: assertPositiveInteger(preparation.maximumRows ?? 1_000_000, "config.preparation.maximumRows"),
+                maximumBytes: assertPositiveInteger(preparation.maximumBytes ?? 2 * 1024 * 1024 * 1024, "config.preparation.maximumBytes"),
+                diskHeadroomBytes: assertPositiveInteger(preparation.diskHeadroomBytes ?? 64 * 1024 * 1024, "config.preparation.diskHeadroomBytes"),
+            })
+            : null,
+        runtimePolicy: root.runtimePolicy === undefined
+            ? null
+            : assertRelativePath(root.runtimePolicy, "config.runtimePolicy"),
+        identityPolicy: root.identityPolicy === undefined
+            ? null
+            : assertRelativePath(root.identityPolicy, "config.identityPolicy"),
+        dependentTargets: Object.freeze(normalizedDependentTargets),
+        application: Object.freeze({
+            startCommand: assertCommand(application.startCommand, "config.application.startCommand"),
+            proofCommand: assertCommand(application.proofCommand, "config.application.proofCommand"),
+            environmentFile: assertRelativePath(application.environmentFile ?? ".rehearsal/runtime.env", "config.application.environmentFile"),
+            environmentVariables: normalizeApplicationEnvironmentMappings(application.environmentVariables),
+            readiness: readiness
+                ? Object.freeze({
+                    url: assertLoopbackUrl(readiness.url, "config.application.readiness.url", allowedHosts),
+                    expectedStatus: assertHttpStatus(readiness.expectedStatus, "config.application.readiness.expectedStatus"),
+                    timeoutSeconds: assertPositiveInteger(readiness.timeoutSeconds ?? 30, "config.application.readiness.timeoutSeconds"),
+                })
+                : null,
+            httpProofs: Object.freeze(httpProofs.map((proof, index) => {
+                const path = `config.application.httpProofs[${index}]`;
+                const value = assertPlainObject(proof, path);
+                assertKnownKeys(value, ["name", "kind", "url", "method", "expectedStatus", "json"], path);
+                if (typeof value.kind !== "string" ||
+                    !["positive", "negative"].includes(value.kind)) {
+                    throw new Error(`${path}.kind must be positive or negative.`);
+                }
+                const expectedStatus = assertHttpStatus(value.expectedStatus, `${path}.expectedStatus`);
+                const method = assertNonEmptyString(value.method ?? "GET", `${path}.method`).toUpperCase();
+                if (!["GET", "HEAD"].includes(method)) {
+                    throw new Error(`${path}.method must be GET or HEAD.`);
+                }
+                let json = null;
+                if (value.json !== undefined) {
+                    const assertion = assertPlainObject(value.json, `${path}.json`);
+                    assertKnownKeys(assertion, ["path", "equals", "notEquals", "minimumItems"], `${path}.json`);
+                    if (!Array.isArray(assertion.path) ||
+                        assertion.path.length === 0 ||
+                        assertion.path.some((segment) => typeof segment !== "string" || !segment)) {
+                        throw new Error(`${path}.json.path must be a non-empty string array.`);
+                    }
+                    const assertionCount = [
+                        Object.hasOwn(assertion, "equals"),
+                        Object.hasOwn(assertion, "notEquals"),
+                        assertion.minimumItems !== undefined,
+                    ].filter(Boolean).length;
+                    if (assertionCount !== 1) {
+                        throw new Error(`${path}.json must declare exactly one assertion.`);
+                    }
+                    json = Object.freeze({
+                        path: Object.freeze([...assertion.path]),
+                        ...(Object.hasOwn(assertion, "equals")
+                            ? { equals: assertion.equals }
+                            : {}),
+                        ...(Object.hasOwn(assertion, "notEquals")
+                            ? { notEquals: assertion.notEquals }
+                            : {}),
+                        ...(assertion.minimumItems !== undefined
+                            ? {
+                                minimumItems: assertPositiveInteger(assertion.minimumItems, `${path}.json.minimumItems`),
+                            }
+                            : {}),
+                    });
+                }
+                return Object.freeze({
+                    name: assertNonEmptyString(value.name, `${path}.name`),
+                    kind: value.kind,
+                    url: assertLoopbackUrl(value.url, `${path}.url`, allowedHosts),
+                    method,
+                    expectedStatus,
+                    json,
+                });
+            })),
+            runtimeAdapter: application.runtimeAdapter === undefined
+                ? null
+                : assertRelativePath(application.runtimeAdapter, "config.application.runtimeAdapter"),
+        }),
+        runtime: Object.freeze({
+            target: runtimeTarget,
+            applicationUrl: assertLoopbackUrl(runtime.applicationUrl ?? REHEARSAL_DEFAULTS.runtime.applicationUrl, "config.runtime.applicationUrl", allowedHosts),
+            projectId: assertNonEmptyString(runtime.projectId ?? REHEARSAL_DEFAULTS.runtime.projectId, "config.runtime.projectId"),
+            ports: Object.freeze(ports),
+        }),
+        safety: Object.freeze({
+            allowedHosts: Object.freeze(allowedHosts),
+            blockedEnvironmentVariables: Object.freeze(assertStringArray(safety.blockedEnvironmentVariables ??
+                REHEARSAL_DEFAULTS.safety.blockedEnvironmentVariables, "config.safety.blockedEnvironmentVariables")),
+            authenticationProviders: Object.freeze(authenticationProviders),
+            hostedAccess: "disabled",
+            outboundNetwork: "deny",
+        }),
+        verification: Object.freeze({
+            commands: Object.freeze(commands.map((command, index) => assertCommand(command, `config.verification.commands[${index}]`))),
+        }),
+    });
+};
+export const defineRehearsalConfig = (config) => config;
+export const findRehearsalConfigPath = async ({ projectRoot = process.cwd(), configPath, } = {}) => {
+    const root = resolve(projectRoot);
+    if (configPath) {
+        const explicit = resolve(root, configPath);
+        if (relative(root, explicit).startsWith("..")) {
+            throw new Error("The Rehearsal configuration must stay inside the project root.");
+        }
+        await access(explicit);
+        return explicit;
+    }
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = join(root, filename);
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, "ENOENT"))
+                throw error;
+        }
+    }
+    throw new Error(`No Rehearsal configuration was found. Checked: ${CONFIG_FILENAMES.join(", ")}.`);
+};
+export const loadRehearsalConfig = async ({ projectRoot = process.cwd(), configPath, } = {}) => {
+    const root = resolve(projectRoot);
+    const path = await findRehearsalConfigPath({
+        projectRoot: root,
+        ...(configPath === undefined ? {} : { configPath }),
+    });
+    const module = await import(`${pathToFileURL(path).href}?loaded=${Date.now()}`);
+    const config = normalizeConfig(module.default);
+    const resolveOwnedPath = (value) => {
+        const resolved = resolve(root, value);
+        if (relative(root, resolved).startsWith("..")) {
+            throw new Error(`A Rehearsal path escaped the project root: ${value}.`);
+        }
+        return resolved;
+    };
+    const paths = Object.freeze({
+        artifactDirectory: resolveOwnedPath(config.baseline.artifactDirectory),
+        applicationEnvironment: resolveOwnedPath(config.application.environmentFile),
+        migrationDirectory: resolveOwnedPath((config.supabase ?? config.postgresql).migrationDirectory),
+        rehearsalConfig: config.supabase
+            ? resolveOwnedPath(config.supabase.rehearsalConfig)
+            : null,
+        runtimeWorkdir: resolveOwnedPath((config.supabase ?? config.postgresql).runtimeWorkdir),
+        serviceEnvironment: config.supabase?.serviceEnvironmentFile
+            ? resolveOwnedPath(config.supabase.serviceEnvironmentFile)
+            : null,
+        sanitizationPolicy: resolveOwnedPath(config.baseline.sanitizationPolicy),
+        sourcePolicy: config.preparation
+            ? resolveOwnedPath(config.preparation.sourcePolicy)
+            : null,
+        privacyKey: config.preparation
+            ? resolveOwnedPath(config.preparation.privacyKey)
+            : null,
+        runtimePolicy: config.runtimePolicy
+            ? resolveOwnedPath(config.runtimePolicy)
+            : null,
+        identityPolicy: config.identityPolicy
+            ? resolveOwnedPath(config.identityPolicy)
+            : null,
+        supabaseWorkdir: config.supabase
+            ? resolveOwnedPath(config.supabase.workdir)
+            : null,
+        runtimeAdapter: config.application.runtimeAdapter
+            ? resolveOwnedPath(config.application.runtimeAdapter)
+            : null,
+    });
+    if (basename(paths.artifactDirectory) !== ".rehearsal") {
+        throw new Error('config.baseline.artifactDirectory must resolve to a directory named ".rehearsal" so destructive reset and cleanup operations have an explicit safety boundary.');
+    }
+    const requiredRuntimeWorkdir = join(paths.artifactDirectory, "runtime");
+    if (paths.runtimeWorkdir !== requiredRuntimeWorkdir) {
+        throw new Error(`config.${config.runtime.target}.runtimeWorkdir must resolve to the runtime directory inside config.baseline.artifactDirectory.`);
+    }
+    const environmentRelativePath = relative(paths.artifactDirectory, paths.applicationEnvironment);
+    if (!environmentRelativePath ||
+        environmentRelativePath.startsWith("..") ||
+        isAbsolute(environmentRelativePath)) {
+        throw new Error("config.application.environmentFile must resolve to a file inside config.baseline.artifactDirectory.");
+    }
+    if (paths.privacyKey) {
+        const privacyKeyRelativePath = relative(paths.artifactDirectory, paths.privacyKey);
+        if (!privacyKeyRelativePath ||
+            privacyKeyRelativePath.startsWith("..") ||
+            isAbsolute(privacyKeyRelativePath)) {
+            throw new Error("config.preparation.privacyKey must resolve to a secret file inside config.baseline.artifactDirectory.");
+        }
+    }
+    if (!IDENTIFIER_PATTERN.test(config.runtime.projectId)) {
+        throw new Error("config.runtime.projectId must contain only lowercase letters, digits, and hyphens.");
+    }
+    return Object.freeze({
+        config,
+        configPath: path,
+        projectRoot: root,
+        paths,
+    });
+};
+export const inspectDetectedProject = async ({ projectRoot = process.cwd(), } = {}) => {
+    const root = resolve(projectRoot);
+    const packageJsonPath = join(root, "package.json");
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const hasPath = async (path) => stat(join(root, path))
+        .then(() => true)
+        .catch((error) => {
+        if (hasErrorCode(error, "ENOENT"))
+            return false;
+        throw error;
+    });
+    const packageManager = (await hasPath("pnpm-lock.yaml"))
+        ? "pnpm"
+        : (await hasPath("yarn.lock"))
+            ? "yarn"
+            : "npm";
+    const scripts = packageJson.scripts ?? {};
+    const postgresqlMigrationDirectory = (await Promise.all(["database/migrations", "db/migrations", "migrations"].map(async (path) => ({ path, exists: await hasPath(path) })))).find(({ exists }) => exists)?.path;
+    const normalizedProjectName = String(packageJson.name ?? basename(root))
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/gu, "-")
+        .replace(/^-|-$/gu, "");
+    const projectName = normalizedProjectName.slice(0, 52).replace(/-$/u, "") ||
+        "rehearsal-project";
+    return {
+        projectName,
+        packageManager,
+        hasSupabaseConfig: await hasPath("supabase/config.toml"),
+        hasMigrations: await hasPath("supabase/migrations"),
+        hasPostgresqlMigrations: Boolean(postgresqlMigrationDirectory),
+        postgresqlMigrationDirectory: postgresqlMigrationDirectory ?? "database/migrations",
+        applicationCommand: ["dev:rehearsal", "dev", "start"]
+            .find((name) => typeof scripts[name] === "string")
+            ?.replace(/^/u, `${packageManager} run `) ??
+            `${packageManager} run dev`,
+        verificationCommand: ["verify:feature", "test", "check"]
+            .find((name) => typeof scripts[name] === "string")
+            ?.replace(/^/u, `${packageManager} run `) ?? `${packageManager} test`,
+    };
+};
+export const renderDetectedConfig = (detected, { applicationUrl = "http://localhost:5175", ports = { api: 58321, database: 58322, studio: 58323 }, } = {}) => `// @ts-check
+/**
+ * Rehearsal configuration for ${detected.projectName}.
+ * Generated from this project by \`npx rehearsal\` and safe to commit.
+ * Review the CHECK comments. Keep passwords, tokens, and production URLs out of this file.
+ * Docs: https://github.com/Ddupasquier/rehearsal-db/blob/main/docs/configuration.md
+ */
+import { defineRehearsalConfig } from "@rehearsal-db/core";
+
+export default defineRehearsalConfig({
+	// Configuration format. Rehearsal will explain if an upgrade is ever needed.
+	schemaVersion: 1,
+	// Stable local name used in Rehearsal labels and reports.
+	project: { name: ${JSON.stringify(detected.projectName)} },
+
+	// Project files Rehearsal reads. Every path stays inside this repository.
+	supabase: {
+		workdir: ".",
+		migrationDirectory: "supabase/migrations",
+		rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
+		runtimeWorkdir: ".rehearsal/runtime",
+
+		// Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+		// Register http://127.0.0.1:${ports.api}/auth/v1/callback with the provider.
+		// authentication: {
+		// 	enableLocalSignup: true,
+		// 	environmentFile: ".env.rehearsal-service.local",
+		// 	providers: [
+		// 		{
+		// 			name: "google",
+		// 			clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+		// 			clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+		// 			skipNonceCheck: false,
+		// 			emailOptional: false,
+		// 		},
+		// 	],
+		// },
+	},
+
+	// Immutable local baseline files. Rehearsal never reads production on your behalf.
+	baseline: {
+		artifactDirectory: ".rehearsal",
+		sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
+	},
+
+	// Optional source refresh. Enable only after reviewing docs/standalone-workflow.md.
+	// Credentials are read from the environment named by source-access-policy.json.
+	// preparation: {
+	// 	sourcePolicy: "infrastructure/rehearsal/source-access-policy.json",
+	// 	privacyKey: ".rehearsal/secrets/privacy.key",
+	// 	batchRows: 500,
+	// 	maximumRows: 1000000,
+	// 	maximumBytes: 2147483648,
+	// 	diskHeadroomBytes: 67108864,
+	// },
+	// Optional reviewed schemas/extensions/triggers/local-only rows.
+	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
+	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
+	// raw emails/subjects and provider credentials stay in ignored environment files.
+	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
+
+	// Reuse any running Docker-compatible engine; start Colima only when needed.
+	containerRuntime: {
+		autoStartColima: true,
+	},
+
+	// Keep this many baseline generations, always including the active one.
+	cleanup: {
+		retainBaselineGenerations: 2,
+	},
+
+	// Optional: manage another isolated database as part of the same rehearsal.
+	// Give that database its own complete config, ports, project ID, and .rehearsal folder.
+	// dependentTargets: [
+	// 	{
+	// 		name: "publication-api",
+	// 		configPath: "rehearsal.publication.config.mjs",
+	// 		prepareCommand: "npm run rehearsal:prepare-publication",
+	// 	},
+	// ],
+
+	application: {
+		// CHECK: commands detected from package.json. Change them if they are not correct.
+		startCommand: ${JSON.stringify(detected.applicationCommand)},
+		proofCommand: ${JSON.stringify(detected.verificationCommand)},
+		environmentFile: ".rehearsal/runtime.env",
+		// Map generated local runtime values directly into the normal app command.
+		// environmentVariables: { DATABASE_URL: "primary:DATABASE_URL" },
+		// Required by \`rehearsal open\`; use a route that responds only when the app is ready.
+		readiness: { url: ${JSON.stringify(applicationUrl)}, expectedStatus: 200, timeoutSeconds: 30 },
+		// Add at least one real positive and one negative before enabling HTTP proofs.
+		// httpProofs: [],
+		// Optional project-specific restore hook:
+		// runtimeAdapter: "infrastructure/rehearsal/runtime-adapter.mjs",
+	},
+
+	// Disposable local runtime identity, URL, and dedicated ports.
+	runtime: {
+		target: "supabase",
+		applicationUrl: ${JSON.stringify(applicationUrl)},
+		projectId: "${detected.projectName}-rehearsal",
+		apiPort: ${ports.api},
+		databasePort: ${ports.database},
+		studioPort: ${ports.studio},
+	},
+
+	// Only local runtime URLs are accepted; common hosted credentials are quarantined.
+	safety: {
+		allowedHosts: ["127.0.0.1", "::1", "localhost"],
+		blockedEnvironmentVariables: [
+			"SUPABASE_ACCESS_TOKEN",
+			"SUPABASE_DB_PASSWORD",
+			"SUPABASE_PROJECT_ID",
+		],
+		hostedAccess: "disabled",
+		outboundNetwork: "deny",
+	},
+});
+`.replaceAll("\t", "  ");
+export const renderDetectedPostgresqlConfig = (detected, { applicationUrl = "http://localhost:5175", databasePort = 58322 } = {}) => `// @ts-check
+/**
+ * Rehearsal configuration for ${detected.projectName}.
+ * Generated from this project by \`npx rehearsal\` and safe to commit.
+ * Review the CHECK comments. Keep passwords, tokens, and production URLs out of this file.
+ * Docs: https://github.com/Ddupasquier/rehearsal-db/blob/main/docs/configuration.md
+ */
+import { defineRehearsalConfig } from "@rehearsal-db/core";
+
+export default defineRehearsalConfig({
+	// Configuration format. Rehearsal will explain if an upgrade is ever needed.
+	schemaVersion: 1,
+	// Stable local name used in Rehearsal labels and reports.
+	project: { name: ${JSON.stringify(detected.projectName)} },
+
+	// Disposable PostgreSQL settings. The image must already exist locally.
+	postgresql: {
+		migrationDirectory: ${JSON.stringify(detected.postgresqlMigrationDirectory)},
+		runtimeWorkdir: ".rehearsal/runtime",
+		image: "postgres:17-alpine",
+		database: "postgres",
+		user: "postgres",
+	},
+
+	// Immutable local baseline files. Rehearsal never reads production on your behalf.
+	baseline: {
+		artifactDirectory: ".rehearsal",
+		sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
+	},
+
+	// Optional source refresh. Enable only after reviewing docs/standalone-workflow.md.
+	// Credentials are read from the environment named by source-access-policy.json.
+	// preparation: {
+	// 	sourcePolicy: "infrastructure/rehearsal/source-access-policy.json",
+	// 	privacyKey: ".rehearsal/secrets/privacy.key",
+	// 	batchRows: 500,
+	// 	maximumRows: 1000000,
+	// 	maximumBytes: 2147483648,
+	// 	diskHeadroomBytes: 67108864,
+	// },
+	// Optional reviewed schemas/extensions/triggers/local-only rows.
+	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
+	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
+	// raw emails/subjects and provider credentials stay in ignored environment files.
+	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
+
+	// Reuse any running Docker-compatible engine; start Colima only when needed.
+	containerRuntime: {
+		autoStartColima: true,
+	},
+
+	// Keep this many baseline generations, always including the active one.
+	cleanup: {
+		retainBaselineGenerations: 2,
+	},
+
+	// Optional: manage another isolated database as part of the same rehearsal.
+	// Give that database its own complete config, ports, project ID, and .rehearsal folder.
+	// dependentTargets: [
+	// 	{
+	// 		name: "publication-api",
+	// 		configPath: "rehearsal.publication.config.mjs",
+	// 		prepareCommand: "npm run rehearsal:prepare-publication",
+	// 	},
+	// ],
+
+	application: {
+		// CHECK: commands detected from package.json. Change them if they are not correct.
+		startCommand: ${JSON.stringify(detected.applicationCommand)},
+		proofCommand: ${JSON.stringify(detected.verificationCommand)},
+		environmentFile: ".rehearsal/runtime.env",
+		// Map generated local runtime values directly into the normal app command.
+		// environmentVariables: { DATABASE_URL: "primary:DATABASE_URL" },
+		// Required by \`rehearsal open\`; use a route that responds only when the app is ready.
+		readiness: { url: ${JSON.stringify(applicationUrl)}, expectedStatus: 200, timeoutSeconds: 30 },
+		// Add at least one real positive and one negative before enabling HTTP proofs.
+		// httpProofs: [],
+		// Optional project-specific restore hook:
+		// runtimeAdapter: "infrastructure/rehearsal/runtime-adapter.mjs",
+	},
+
+	// Disposable local runtime identity, URL, and dedicated database port.
+	runtime: {
+		target: "postgresql",
+		applicationUrl: ${JSON.stringify(applicationUrl)},
+		projectId: "${detected.projectName}-rehearsal",
+		databasePort: ${databasePort},
+	},
+
+	// Only local runtime URLs are accepted; common hosted credentials are quarantined.
+	safety: {
+		allowedHosts: ["127.0.0.1", "::1", "localhost"],
+		blockedEnvironmentVariables: [
+			"DATABASE_URL",
+			"PGHOST",
+			"PGPASSWORD",
+			"PGPORT",
+			"PGUSER",
+		],
+		hostedAccess: "disabled",
+		outboundNetwork: "deny",
+	},
+});
+`.replaceAll("\t", "  ");