@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/dist/src/identity/connect.mjs

@@ -0,0 +1,111 @@
+/** Read-only discovery and redacted review for the guided account connection. */
+import pg from "pg";
+import { findVerifiedLocalIdentity, isIdentityNotFoundError, } from "./claim_identity_lookup.mjs";
+import { getIdentityPlanMatchValue } from "./claim_plan.mjs";
+const { Client } = pg;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu;
+const assertLocalDatabase = (connectionString) => {
+    let target;
+    try {
+        target = new URL(connectionString);
+    }
+    catch {
+        throw new Error("Identity connection requires a valid local database URL.");
+    }
+    if (!["postgres:", "postgresql:"].includes(target.protocol) ||
+        !["127.0.0.1", "::1", "localhost"].includes(target.hostname)) {
+        throw new Error("Identity connection may inspect only the local Rehearsal database.");
+    }
+};
+const hasAssociationReceipt = async ({ client, name, placeholderUserId, localUserId, }) => {
+    const relation = await client.query("select to_regclass('rehearsal_internal.identity_claims')::text as relation");
+    if (relation.rows[0]?.relation !== "rehearsal_internal.identity_claims") {
+        return false;
+    }
+    const receipt = await client.query(`select 1
+     from rehearsal_internal.identity_claims
+     where identity_name = $1
+       and placeholder_user_id = $2::uuid
+       and local_user_id = $3::uuid
+     limit 1`, [name, placeholderUserId, localUserId]);
+    return receipt.rows.length === 1;
+};
+export const inspectIdentityConnection = async ({ plan, connectionString, clientFactory, }) => {
+    assertLocalDatabase(connectionString);
+    const matchValue = getIdentityPlanMatchValue(plan);
+    if (!matchValue) {
+        throw new Error("Identity connection plans must use the reviewed local matcher environment.");
+    }
+    const client = clientFactory
+        ? await clientFactory(connectionString)
+        : new Client({
+            connectionString,
+            application_name: "rehearsal-identity-connect",
+        });
+    await client.connect?.();
+    try {
+        const localIdentity = await findVerifiedLocalIdentity({
+            client,
+            plan,
+            matchValue,
+            lock: false,
+        });
+        if (!UUID.test(localIdentity.id)) {
+            throw new Error("Matched local identity is invalid.");
+        }
+        return Object.freeze({
+            name: plan.review.name,
+            provider: localIdentity.provider,
+            planDigest: plan.digest,
+            relationalGroups: plan.review.references.filter((reference) => reference.strategy === "transfer").length,
+            preservedAuditGroups: plan.review.references.filter((reference) => reference.strategy === "preserve-audit").length,
+            nestedJsonGroups: plan.review.jsonReferences.length,
+            signupDefaults: plan.review.signupDefaults.length,
+            storagePathGroups: plan.review.pathReferences.length,
+            assetScopes: plan.review.assets.length,
+            claimKeys: plan.review.claimKeys.length,
+            tokenHookConfigured: plan.review.tokenHook !== null,
+            associated: await hasAssociationReceipt({
+                client,
+                name: plan.identity.name,
+                placeholderUserId: plan.identity.placeholderUserId,
+                localUserId: localIdentity.id,
+            }),
+        });
+    }
+    finally {
+        await client.end?.();
+    }
+};
+const abortableDelay = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason ?? new Error("Identity connection was cancelled."));
+        return;
+    }
+    const timeout = setTimeout(resolve, milliseconds);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(timeout);
+        reject(signal.reason ?? new Error("Identity connection was cancelled."));
+    }, { once: true });
+});
+export const waitForIdentityConnection = async ({ plan, connectionString, clientFactory, inspect = inspectIdentityConnection, signal, pollIntervalMs = 750, timeoutMs = 15 * 60 * 1_000, }) => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Identity connection was cancelled.");
+        }
+        try {
+            return await inspect({
+                plan,
+                connectionString,
+                ...(clientFactory === undefined ? {} : { clientFactory }),
+            });
+        }
+        catch (error) {
+            if (!isIdentityNotFoundError(error))
+                throw error;
+        }
+        await abortableDelay(pollIntervalMs, signal);
+    }
+    throw new Error("Timed out waiting for the approved verified local identity. Nothing was changed.");
+};

package/dist/src/identity/provider_configuration.d.mts

@@ -0,0 +1,37 @@
+/** Render reviewed local OAuth declarations into the disposable Supabase runtime. */
+export interface SupabaseAuthenticationProvider {
+    name: "google" | "github";
+    clientIdEnvironmentVariable: string;
+    clientSecretEnvironmentVariable: string;
+    skipNonceCheck?: boolean;
+    emailOptional?: boolean;
+}
+export interface SupabaseAuthentication {
+    providers: readonly SupabaseAuthenticationProvider[];
+}
+interface TomlSection {
+    name: string;
+    start: number;
+    end: number;
+}
+interface ProviderReplacementSection extends TomlSection {
+    provider: string;
+}
+interface ProviderTransition {
+    readonly replacedProviders: readonly string[];
+    readonly replacementSections: readonly ProviderReplacementSection[];
+}
+export declare const inspectSupabaseAuthenticationProviderTransition: ({ source, authentication, }: {
+    source: string;
+    authentication: SupabaseAuthentication | null;
+}) => Readonly<ProviderTransition>;
+export declare const renderSupabaseAuthenticationProviders: ({ authentication, apiPort, }: {
+    authentication: SupabaseAuthentication | null;
+    apiPort: number;
+}) => string;
+export declare const applySupabaseAuthenticationProviders: ({ source, authentication, apiPort, }: {
+    source: string;
+    authentication: SupabaseAuthentication | null;
+    apiPort: number;
+}) => string;
+export {};

package/dist/src/identity/provider_configuration.mjs

@@ -0,0 +1,132 @@
+/** Render reviewed local OAuth declarations into the disposable Supabase runtime. */
+const escapePattern = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const LEGACY_PROVIDER_KEYS = new Set([
+    "client_id",
+    "email_optional",
+    "enabled",
+    "redirect_uri",
+    "secret",
+    "skip_nonce_check",
+]);
+const SAFE_BOOLEAN_PROVIDER_KEYS = new Set([
+    "email_optional",
+    "skip_nonce_check",
+]);
+const readTomlSections = (source) => {
+    const lines = source.split("\n");
+    const sections = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(lines[index]);
+        if (!match)
+            continue;
+        if (sections.length)
+            sections.at(-1).end = index;
+        sections.push({ name: match[1], start: index, end: lines.length });
+    }
+    return { lines, sections };
+};
+const validateLegacyProviderSection = ({ lines, section, provider, }) => {
+    const seen = new Set();
+    for (const line of lines.slice(section.start + 1, section.end)) {
+        if (!line.trim() || /^\s*#/u.test(line))
+            continue;
+        const assignment = /^\s*([A-Za-z0-9_]+)\s*=/u.exec(line);
+        if (!assignment || !LEGACY_PROVIDER_KEYS.has(assignment[1])) {
+            throw new Error(`The local Supabase template auth.external.${provider.name} section contains an unsupported setting. Rehearsal left the tracked template unchanged.`);
+        }
+        const key = assignment[1];
+        if (seen.has(key)) {
+            throw new Error(`The local Supabase template auth.external.${provider.name} section contains duplicate ${key} settings.`);
+        }
+        seen.add(key);
+        if (SAFE_BOOLEAN_PROVIDER_KEYS.has(key) &&
+            !new RegExp(`^\\s*${escapePattern(key)}\\s*=\\s*${key === "skip_nonce_check"
+                ? (provider.skipNonceCheck ?? false)
+                : (provider.emailOptional ?? false)}\\s*(?:#.*)?$`, "u").test(line)) {
+            throw new Error(`The local Supabase template auth.external.${provider.name}.${key} setting must match its explicit declarative authentication option before Rehearsal can replace the legacy provider in its disposable runtime copy.`);
+        }
+    }
+};
+export const inspectSupabaseAuthenticationProviderTransition = ({ source, authentication, }) => {
+    if (!authentication)
+        return Object.freeze({ replacedProviders: [], replacementSections: [] });
+    const { lines, sections } = readTomlSections(source);
+    const replacementSections = [];
+    for (const provider of authentication.providers) {
+        const sectionName = `auth.external.${provider.name}`;
+        const nested = sections.filter((section) => section.name.startsWith(`${sectionName}.`));
+        if (nested.length) {
+            throw new Error(`The local Supabase template contains unsupported nested ${sectionName} configuration. Rehearsal left the tracked template unchanged.`);
+        }
+        const matching = sections.filter((section) => section.name === sectionName);
+        if (matching.length > 1) {
+            throw new Error(`The local Supabase template declares ${sectionName} more than once.`);
+        }
+        if (matching.length === 1) {
+            validateLegacyProviderSection({
+                lines,
+                section: matching[0],
+                provider,
+            });
+            replacementSections.push({ ...matching[0], provider: provider.name });
+        }
+    }
+    return Object.freeze({
+        replacedProviders: Object.freeze(replacementSections.map(({ provider }) => provider)),
+        replacementSections: Object.freeze(replacementSections),
+    });
+};
+export const renderSupabaseAuthenticationProviders = ({ authentication, apiPort, }) => {
+    if (!authentication)
+        return "";
+    return authentication.providers
+        .map((provider) => `# Generated by Rehearsal from config.supabase.authentication.
+[auth.external.${provider.name}]
+enabled = true
+client_id = "env(${provider.clientIdEnvironmentVariable})"
+secret = "env(${provider.clientSecretEnvironmentVariable})"
+redirect_uri = "http://127.0.0.1:${apiPort}/auth/v1/callback"
+${provider.skipNonceCheck ? "skip_nonce_check = true\n" : ""}${provider.emailOptional ? "email_optional = true\n" : ""}
+`)
+        .join("\n");
+};
+const enableLocalSignup = (source) => {
+    const lines = source.split("\n");
+    let inAuth = false;
+    let authSections = 0;
+    let signupSettings = 0;
+    const updated = lines.map((line) => {
+        const section = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(line);
+        if (section) {
+            inAuth = section[1] === "auth";
+            if (inAuth)
+                authSections += 1;
+            return line;
+        }
+        if (!inAuth || !/^\s*enable_signup\s*=/u.test(line))
+            return line;
+        signupSettings += 1;
+        const comment = line.match(/\s+#.*$/u)?.[0] ?? "";
+        return `enable_signup = true${comment}`;
+    });
+    if (authSections !== 1 || signupSettings !== 1) {
+        throw new Error("The local Supabase template must declare exactly one [auth] section with one enable_signup setting before Rehearsal can configure OAuth.");
+    }
+    return updated.join("\n");
+};
+export const applySupabaseAuthenticationProviders = ({ source, authentication, apiPort, }) => {
+    if (!authentication)
+        return source;
+    const transition = inspectSupabaseAuthenticationProviderTransition({
+        source,
+        authentication,
+    });
+    const { lines } = readTomlSections(source);
+    const replacedIndexes = new Set(transition.replacementSections.flatMap((section) => Array.from({ length: section.end - section.start }, (_, offset) => section.start + offset)));
+    const transitionedSource = lines
+        .filter((_, index) => !replacedIndexes.has(index))
+        .join("\n");
+    const runtimeSource = enableLocalSignup(transitionedSource);
+    const separator = runtimeSource.endsWith("\n") ? "\n" : "\n\n";
+    return `${runtimeSource}${separator}${renderSupabaseAuthenticationProviders({ authentication, apiPort })}`;
+};

package/dist/src/identity/storage.d.mts

@@ -0,0 +1,21 @@
+/** Copy and verify local Supabase Storage objects during an identity claim. */
+export interface StorageObjectReceipt {
+    readonly bytes: number;
+    readonly sha256: string;
+}
+export interface SupabaseStorageTransfer {
+    copyAndVerify(input: {
+        bucket: string;
+        source: string;
+        destination: string;
+    }): Promise<StorageObjectReceipt>;
+    remove(input: {
+        bucket: string;
+        paths: readonly string[];
+    }): Promise<void>;
+}
+export declare const createSupabaseStorageTransfer: ({ url, serviceRoleKey, fetchImpl, }: {
+    url: string;
+    serviceRoleKey: string;
+    fetchImpl?: typeof fetch;
+}) => SupabaseStorageTransfer;

package/dist/src/identity/storage.mjs

@@ -0,0 +1,122 @@
+/** Copy and verify local Supabase Storage objects during an identity claim. */
+import { createHash } from "node:crypto";
+import { assertLoopbackUrl } from "../shared/process_environment.mjs";
+const BUCKET = /^[a-z0-9][a-z0-9.-]{0,99}$/u;
+const MAXIMUM_VERIFICATION_BYTES = 100 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+const objectPath = (value) => {
+    if (typeof value !== "string" ||
+        !value ||
+        value.startsWith("/") ||
+        value.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new Error("A Storage identity-claim path is unsafe.");
+    }
+    return value.split("/").map(encodeURIComponent).join("/");
+};
+const readVerifiedObject = async ({ fetchImpl, baseUrl, headers, bucket, path, }) => {
+    const response = await fetchImpl(`${baseUrl}/storage/v1/object/${encodeURIComponent(bucket)}/${objectPath(path)}?rehearsal=${Date.now()}`, {
+        headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`Supabase Storage could not read an identity-claim object (HTTP ${response.status}).`);
+    }
+    const declaredBytes = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredBytes) &&
+        declaredBytes > MAXIMUM_VERIFICATION_BYTES) {
+        throw new Error("A Storage identity-claim object exceeds the 100 MiB verification limit.");
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAXIMUM_VERIFICATION_BYTES) {
+        throw new Error("A Storage identity-claim object exceeds the 100 MiB verification limit.");
+    }
+    return Object.freeze({
+        bytes: bytes.length,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+};
+export const createSupabaseStorageTransfer = ({ url, serviceRoleKey, fetchImpl = globalThis.fetch, }) => {
+    assertLoopbackUrl("Rehearsal Supabase Storage", url);
+    if (typeof serviceRoleKey !== "string" || !serviceRoleKey) {
+        throw new Error("The local runtime environment has no Storage service key.");
+    }
+    if (typeof fetchImpl !== "function") {
+        throw new Error("A Fetch implementation is required for Storage transfer.");
+    }
+    const baseUrl = url.replace(/\/$/u, "");
+    const headers = Object.freeze({
+        apikey: serviceRoleKey,
+        authorization: `Bearer ${serviceRoleKey}`,
+    });
+    const removePaths = async ({ bucket, paths, }) => {
+        if (!BUCKET.test(bucket ?? "") || !Array.isArray(paths) || !paths.length) {
+            throw new Error("A Storage identity-claim removal is invalid.");
+        }
+        paths.forEach(objectPath);
+        const response = await fetchImpl(`${baseUrl}/storage/v1/object/${encodeURIComponent(bucket)}`, {
+            method: "DELETE",
+            headers: { ...headers, "content-type": "application/json" },
+            body: JSON.stringify({ prefixes: paths }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(`Supabase Storage could not remove identity-claim objects (HTTP ${response.status}).`);
+        }
+    };
+    return Object.freeze({
+        async copyAndVerify({ bucket, source, destination, }) {
+            if (!BUCKET.test(bucket ?? "")) {
+                throw new Error("A Storage identity-claim bucket is invalid.");
+            }
+            objectPath(source);
+            objectPath(destination);
+            if (source === destination) {
+                throw new Error("A Storage identity-claim copy must change the path.");
+            }
+            const sourceReceipt = await readVerifiedObject({
+                fetchImpl,
+                baseUrl,
+                headers,
+                bucket,
+                path: source,
+            });
+            try {
+                const response = await fetchImpl(`${baseUrl}/storage/v1/object/copy`, {
+                    method: "POST",
+                    headers: { ...headers, "content-type": "application/json" },
+                    body: JSON.stringify({
+                        bucketId: bucket,
+                        sourceKey: source,
+                        destinationKey: destination,
+                    }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                if (!response.ok) {
+                    throw new Error(`Supabase Storage could not copy an identity-claim object (HTTP ${response.status}).`);
+                }
+                const destinationReceipt = await readVerifiedObject({
+                    fetchImpl,
+                    baseUrl,
+                    headers,
+                    bucket,
+                    path: destination,
+                });
+                if (sourceReceipt.bytes !== destinationReceipt.bytes ||
+                    sourceReceipt.sha256 !== destinationReceipt.sha256) {
+                    throw new Error("Supabase Storage copied an identity object with a different byte digest.");
+                }
+                return destinationReceipt;
+            }
+            catch (error) {
+                try {
+                    await removePaths({ bucket, paths: [destination] });
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "Storage identity-copy verification failed and destination cleanup needs attention.");
+                }
+                throw error;
+            }
+        },
+        remove: removePaths,
+    });
+};

package/dist/src/index.d.mts

@@ -0,0 +1,4 @@
+/** Public Rehearsal package entry point. */
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export type { DetectedProject, NormalizedRehearsalConfig, RehearsalConfig, RehearsalConfigPathOptions, RehearsalConfigVersion, } from "./project/configuration.mjs";
+export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

package/dist/src/index.mjs

@@ -0,0 +1,3 @@
+/** Public Rehearsal package entry point. */
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

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

@@ -0,0 +1,13 @@
+/**
+ * Stable public facade for Rehearsal configuration. Implementation concerns
+ * live in focused modules so callers keep one compatible import path.
+ */
+export { defineRehearsalConfig, REHEARSAL_CONFIG_VERSION, REHEARSAL_DEFAULTS, } from "./configuration_contract.mjs";
+export type { RehearsalConfig, RehearsalConfigVersion, } from "./configuration_contract.mjs";
+export { findRehearsalConfigPath } from "./configuration_discovery.mjs";
+export type { RehearsalConfigPathOptions } from "./configuration_discovery.mjs";
+export { loadRehearsalConfig } from "./configuration_resolution.mjs";
+export type { NormalizedRehearsalConfig } from "./configuration_resolution.mjs";
+export { inspectDetectedProject } from "./project_detection.mjs";
+export type { DetectedProject } from "./project_detection.mjs";
+export { renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./configuration_rendering.mjs";

package/dist/src/project/configuration.mjs

@@ -0,0 +1,9 @@
+/**
+ * Stable public facade for Rehearsal configuration. Implementation concerns
+ * live in focused modules so callers keep one compatible import path.
+ */
+export { defineRehearsalConfig, REHEARSAL_CONFIG_VERSION, REHEARSAL_DEFAULTS, } from "./configuration_contract.mjs";
+export { findRehearsalConfigPath } from "./configuration_discovery.mjs";
+export { loadRehearsalConfig } from "./configuration_resolution.mjs";
+export { inspectDetectedProject } from "./project_detection.mjs";
+export { renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./configuration_rendering.mjs";

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

@@ -0,0 +1,125 @@
+/** Public configuration types, format version, and stable defaults. */
+export type RehearsalConfigVersion = 1;
+export interface RehearsalConfig {
+    schemaVersion: RehearsalConfigVersion;
+    project: {
+        name: string;
+    };
+    supabase?: {
+        workdir: string;
+        migrationDirectory: string;
+        rehearsalConfig: string;
+        runtimeWorkdir: string;
+        authentication?: {
+            enableLocalSignup: true;
+            environmentFile: string;
+            providers: Array<{
+                name: "google" | "github";
+                clientIdEnvironmentVariable: string;
+                clientSecretEnvironmentVariable: string;
+                skipNonceCheck?: boolean;
+                emailOptional?: boolean;
+            }>;
+        };
+        serviceEnvironmentFile?: string;
+        serviceEnvironmentVariables?: string[];
+    };
+    postgresql?: {
+        migrationDirectory: string;
+        runtimeWorkdir?: string;
+        image?: string;
+        database?: string;
+        user?: string;
+    };
+    baseline: {
+        artifactDirectory?: string;
+        sanitizationPolicy: string;
+    };
+    containerRuntime?: {
+        autoStartColima?: boolean;
+    };
+    cleanup?: {
+        retainBaselineGenerations?: number;
+    };
+    preparation?: {
+        sourcePolicy: string;
+        privacyKey: string;
+        batchRows?: number;
+        maximumRows?: number;
+        maximumBytes?: number;
+        diskHeadroomBytes?: number;
+    };
+    runtimePolicy?: string;
+    identityPolicy?: string;
+    dependentTargets?: Array<{
+        name: string;
+        configPath: string;
+        prepareCommand?: string;
+    }>;
+    application: {
+        startCommand: string;
+        proofCommand: string;
+        environmentFile?: string;
+        environmentVariables?: Record<string, string>;
+        readiness?: {
+            url: string;
+            expectedStatus: number;
+            timeoutSeconds?: number;
+        };
+        httpProofs?: Array<{
+            name: string;
+            kind: "positive" | "negative";
+            url: string;
+            method?: string;
+            expectedStatus: number;
+            json?: {
+                path: string[];
+                equals?: unknown;
+                notEquals?: unknown;
+                minimumItems?: number;
+            };
+        }>;
+        runtimeAdapter?: string;
+    };
+    runtime: {
+        target?: "supabase" | "postgresql";
+        applicationUrl?: string;
+        projectId?: string;
+        apiPort?: number;
+        databasePort: number;
+        studioPort?: number;
+    };
+    safety?: {
+        allowedHosts?: string[];
+        blockedEnvironmentVariables?: string[];
+        authenticationProviders?: string[];
+        hostedAccess?: "disabled";
+        outboundNetwork?: "deny";
+    };
+    verification?: {
+        commands?: string[];
+    };
+}
+export declare const REHEARSAL_CONFIG_VERSION = 1;
+export declare const REHEARSAL_DEFAULTS: Readonly<{
+    baseline: Readonly<{
+        artifactDirectory: ".rehearsal";
+    }>;
+    containerRuntime: Readonly<{
+        autoStartColima: false;
+    }>;
+    cleanup: Readonly<{
+        retainBaselineGenerations: 2;
+    }>;
+    runtime: Readonly<{
+        applicationUrl: "http://localhost:5175";
+        projectId: "rehearsal-local";
+    }>;
+    safety: Readonly<{
+        allowedHosts: readonly string[];
+        blockedEnvironmentVariables: readonly string[];
+        hostedAccess: "disabled";
+        outboundNetwork: "deny";
+    }>;
+}>;
+export declare const defineRehearsalConfig: <const Config extends RehearsalConfig>(config: Config) => Config;

package/dist/src/project/configuration_contract.mjs

@@ -0,0 +1,27 @@
+/** Public configuration types, format version, and stable defaults. */
+export const REHEARSAL_CONFIG_VERSION = 1;
+export const REHEARSAL_DEFAULTS = Object.freeze({
+    baseline: Object.freeze({ artifactDirectory: ".rehearsal" }),
+    containerRuntime: Object.freeze({ autoStartColima: false }),
+    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",
+    }),
+});
+export const defineRehearsalConfig = (config) => config;

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

@@ -0,0 +1,7 @@
+/** Locate the one supported Rehearsal configuration owned by a project. */
+export declare const CONFIG_FILENAMES: readonly string[];
+export interface RehearsalConfigPathOptions {
+    projectRoot?: string;
+    configPath?: string;
+}
+export declare const findRehearsalConfigPath: ({ projectRoot, configPath, }?: RehearsalConfigPathOptions) => Promise<string>;

package/dist/src/project/configuration_discovery.mjs

@@ -0,0 +1,37 @@
+/** Locate the one supported Rehearsal configuration owned by a project. */
+import { access } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+export 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 hasErrorCode = (error, code) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code;
+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(", ")}.`);
+};