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

package/dist/src/project/configuration_normalization.mjs

@@ -0,0 +1,302 @@
+/**
+ * Purpose: Load and strictly validate the versioned, project-owned Rehearsal
+ * configuration contract. Do not run directly; this module is reusable script
+ * infrastructure.
+ */
+import { REHEARSAL_CONFIG_VERSION, REHEARSAL_DEFAULTS, } from "./configuration_contract.mjs";
+import { validateConfigurationSchema } from "./configuration_schema.mjs";
+import { assertBoolean, assertCommand, assertDatabaseIdentifier, assertEnvironmentKey, assertEnvironmentReference, assertHttpStatus, assertIdentifier, assertKnownKeys, assertLoopbackUrl, assertNonEmptyString, assertPlainObject, assertPort, assertPostgresImage, assertPositiveInteger, assertRelativePath, assertStringArray, } from "./configuration_validation.mjs";
+const LOOPBACK_HOSTS = new Set(REHEARSAL_DEFAULTS.safety.allowedHosts);
+const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
+const normalizeApplicationEnvironmentMappings = (value = {}) => {
+    const mappings = assertPlainObject(value, "config.application.environmentVariables");
+    return Object.freeze(Object.fromEntries(Object.entries(mappings).map(([key, reference]) => {
+        const path = `config.application.environmentVariables.${key}`;
+        assertEnvironmentKey(key, path);
+        return [key, assertEnvironmentReference(reference, path)];
+    })));
+};
+export const normalizeRehearsalConfig = (input) => {
+    const { root, project, runtime, runtimeTarget, supabase, postgresql, baseline, containerRuntime, cleanup, preparation, dependentTargets, application, readiness, httpProofs, safety, verification, authentication, } = validateConfigurationSchema(input);
+    const projectName = assertIdentifier(project.name, "config.project.name");
+    const normalizedDependentTargets = dependentTargets.map((target, index) => {
+        const path = `config.dependentTargets[${index}]`;
+        const name = assertIdentifier(target.name, `${path}.name`);
+        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.");
+    }
+    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.");
+    }
+    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.");
+    }
+    let normalizedAuthentication = null;
+    if (authentication) {
+        if (!supabase) {
+            throw new Error("config.supabase.authentication requires the Supabase runtime target.");
+        }
+        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 = entry;
+            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) => {
+                return assertEnvironmentKey(value[key], `${path}.${key}`);
+            };
+            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: assertPostgresImage(postgresql.image ?? "postgres:17-alpine", "config.postgresql.image"),
+                database: assertDatabaseIdentifier(postgresql.database ?? "postgres", "config.postgresql.database"),
+                user: assertDatabaseIdentifier(postgresql.user ?? "postgres", "config.postgresql.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, LOOPBACK_HOSTS),
+                    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, LOOPBACK_HOSTS),
+                    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, LOOPBACK_HOSTS),
+            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}]`))),
+        }),
+    });
+};

package/dist/src/project/configuration_rendering.d.mts

@@ -0,0 +1,14 @@
+/** Render reviewed starter configurations without reading or writing a project. */
+import type { DetectedProject } from "./project_detection.mjs";
+export declare const renderDetectedConfig: (detected: DetectedProject, { applicationUrl, ports, }?: {
+    applicationUrl?: string;
+    ports?: {
+        api: number;
+        database: number;
+        studio: number;
+    };
+}) => string;
+export declare const renderDetectedPostgresqlConfig: (detected: DetectedProject, { applicationUrl, databasePort }?: {
+    applicationUrl?: string | undefined;
+    databasePort?: number | undefined;
+}) => string;

package/dist/src/project/configuration_rendering.mjs

@@ -0,0 +1,224 @@
+/** Render reviewed starter configurations without reading or writing a project. */
+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", "  ");

package/dist/src/project/configuration_resolution.d.mts

@@ -0,0 +1,125 @@
+/** Load a discovered config and resolve every owned path from the project root. */
+import { type RehearsalConfigPathOptions } from "./configuration_discovery.mjs";
+import { normalizeRehearsalConfig } from "./configuration_normalization.mjs";
+export type NormalizedRehearsalConfig = ReturnType<typeof normalizeRehearsalConfig>;
+export declare const loadRehearsalConfig: ({ projectRoot, configPath, }?: RehearsalConfigPathOptions) => Promise<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;
+    }>;
+}>>;