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

package/dist/src/project/configuration_resolution.mjs

@@ -0,0 +1,81 @@
+/** Load a discovered config and resolve every owned path from the project root. */
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { findRehearsalConfigPath, } from "./configuration_discovery.mjs";
+import { normalizeRehearsalConfig } from "./configuration_normalization.mjs";
+import { assertIdentifier } from "./configuration_validation.mjs";
+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 = normalizeRehearsalConfig(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.");
+        }
+    }
+    assertIdentifier(config.runtime.projectId, "config.runtime.projectId");
+    return Object.freeze({
+        config,
+        configPath: path,
+        projectRoot: root,
+        paths,
+    });
+};

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

@@ -0,0 +1,22 @@
+/** Validate the raw object shape and known keys before applying defaults. */
+import { type PlainObject } from "./configuration_validation.mjs";
+export interface ValidatedConfigurationSchema {
+    root: PlainObject;
+    project: PlainObject;
+    runtime: PlainObject;
+    runtimeTarget: "supabase" | "postgresql";
+    supabase: PlainObject | null;
+    postgresql: PlainObject | null;
+    baseline: PlainObject;
+    containerRuntime: PlainObject;
+    cleanup: PlainObject;
+    preparation: PlainObject | null;
+    dependentTargets: PlainObject[];
+    application: PlainObject;
+    readiness: PlainObject | null;
+    httpProofs: PlainObject[];
+    safety: PlainObject;
+    verification: PlainObject;
+    authentication: PlainObject | null;
+}
+export declare const validateConfigurationSchema: (input: unknown) => ValidatedConfigurationSchema;

package/dist/src/project/configuration_schema.mjs

@@ -0,0 +1,160 @@
+/** Validate the raw object shape and known keys before applying defaults. */
+import { resolveRuntimeTarget } from "../targets/target.mjs";
+import { REHEARSAL_CONFIG_VERSION } from "./configuration_contract.mjs";
+import { assertKnownKeys, assertPlainObject, } from "./configuration_validation.mjs";
+const assertObjectArray = (value, path) => {
+    if (!Array.isArray(value))
+        throw new Error(`${path} must be an array.`);
+    return value.map((entry, index) => assertPlainObject(entry, `${path}[${index}]`));
+};
+export const validateConfigurationSchema = (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 runtime = assertPlainObject(root.runtime ?? {}, "config.runtime");
+    assertKnownKeys(runtime, [
+        "target",
+        "applicationUrl",
+        "projectId",
+        "apiPort",
+        "databasePort",
+        "studioPort",
+    ], "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 = assertObjectArray(root.dependentTargets ?? [], "config.dependentTargets");
+    dependentTargets.forEach((target, index) => assertKnownKeys(target, ["name", "configPath", "prepareCommand"], `config.dependentTargets[${index}]`));
+    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 = assertObjectArray(application.httpProofs ?? [], "config.application.httpProofs");
+    httpProofs.forEach((proof, index) => {
+        const path = `config.application.httpProofs[${index}]`;
+        assertKnownKeys(proof, ["name", "kind", "url", "method", "expectedStatus", "json"], path);
+        if (proof.json !== undefined) {
+            assertKnownKeys(assertPlainObject(proof.json, `${path}.json`), ["path", "equals", "notEquals", "minimumItems"], `${path}.json`);
+        }
+    });
+    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 authentication = supabase?.authentication === undefined
+        ? null
+        : assertPlainObject(supabase.authentication, "config.supabase.authentication");
+    if (authentication) {
+        assertKnownKeys(authentication, ["enableLocalSignup", "environmentFile", "providers"], "config.supabase.authentication");
+        if (Array.isArray(authentication.providers)) {
+            const providers = assertObjectArray(authentication.providers, "config.supabase.authentication.providers");
+            providers.forEach((provider, index) => assertKnownKeys(provider, [
+                "name",
+                "clientIdEnvironmentVariable",
+                "clientSecretEnvironmentVariable",
+                "skipNonceCheck",
+                "emailOptional",
+            ], `config.supabase.authentication.providers[${index}]`));
+        }
+    }
+    return {
+        root,
+        project,
+        runtime,
+        runtimeTarget,
+        supabase,
+        postgresql,
+        baseline,
+        containerRuntime,
+        cleanup,
+        preparation,
+        dependentTargets,
+        application,
+        readiness,
+        httpProofs,
+        safety,
+        verification,
+        authentication,
+    };
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Purpose: Provide the reusable, side-effect-free validators used by the
+ * Rehearsal configuration schema and normalizer.
+ */
+export type PlainObject = Record<string, unknown>;
+export declare const isPlainObject: (value: unknown) => value is PlainObject;
+export declare const assertPlainObject: (value: unknown, path: string) => PlainObject;
+export declare const assertKnownKeys: (value: PlainObject, keys: readonly string[], path: string) => void;
+export declare const assertNonEmptyString: (value: unknown, path: string) => string;
+export declare const assertRelativePath: (value: unknown, path: string) => string;
+export declare const assertCommand: (value: unknown, path: string) => string;
+export declare const assertIdentifier: (value: unknown, path: string) => string;
+export declare const assertDatabaseIdentifier: (value: unknown, path: string) => string;
+export declare const assertPostgresImage: (value: unknown, path: string) => string;
+export declare const assertEnvironmentKey: (value: unknown, path: string) => string;
+export declare const assertEnvironmentReference: (value: unknown, path: string) => string;
+export declare const assertPort: (value: unknown, path: string) => number;
+export declare const assertBoolean: (value: unknown, path: string) => boolean;
+export declare const assertPositiveInteger: (value: unknown, path: string) => number;
+export declare const assertHttpStatus: (value: unknown, path: string) => number;
+export declare const assertStringArray: (value: unknown, path: string) => string[];
+export declare const assertLoopbackUrl: (value: unknown, path: string, allowedHosts: readonly string[], supportedHosts: ReadonlySet<string>) => string;

package/dist/src/project/configuration_validation.mjs

@@ -0,0 +1,136 @@
+/**
+ * Purpose: Provide the reusable, side-effect-free validators used by the
+ * Rehearsal configuration schema and normalizer.
+ */
+import { isAbsolute } from "node:path";
+const SAFE_COMMAND_PATTERN = /^[^\n\r\0]+$/u;
+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 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;
+export const isPlainObject = (value) => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype;
+export const assertPlainObject = (value, path) => {
+    if (!isPlainObject(value))
+        throw new Error(`${path} must be an object.`);
+    return value;
+};
+export 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}.`);
+        }
+    }
+};
+export const assertNonEmptyString = (value, path) => {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${path} must be a non-empty string.`);
+    }
+    return value.trim();
+};
+export 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;
+};
+export 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;
+};
+export const assertIdentifier = (value, path) => {
+    const identifier = assertNonEmptyString(value, path);
+    if (!IDENTIFIER_PATTERN.test(identifier)) {
+        throw new Error(`${path} must contain only lowercase letters, digits, and hyphens.`);
+    }
+    return identifier;
+};
+export const assertDatabaseIdentifier = (value, path) => {
+    const identifier = assertNonEmptyString(value, path);
+    if (!DATABASE_IDENTIFIER_PATTERN.test(identifier)) {
+        throw new Error(`${path} must be a safe lowercase PostgreSQL identifier.`);
+    }
+    return identifier;
+};
+export const assertPostgresImage = (value, path) => {
+    const image = assertNonEmptyString(value, path);
+    if (!POSTGRES_IMAGE_PATTERN.test(image)) {
+        throw new Error(`${path} must name an official versioned Alpine PostgreSQL image, such as postgres:17-alpine.`);
+    }
+    return image;
+};
+export const assertEnvironmentKey = (value, path) => {
+    const key = assertNonEmptyString(value, path);
+    if (!ENVIRONMENT_KEY_PATTERN.test(key)) {
+        throw new Error(`${path} must be a safe environment variable name.`);
+    }
+    return key;
+};
+export const assertEnvironmentReference = (value, path) => {
+    if (typeof value !== "string" || !ENVIRONMENT_REFERENCE_PATTERN.test(value)) {
+        throw new Error(`${path} must reference target:VARIABLE, such as primary:DATABASE_URL.`);
+    }
+    return value;
+};
+export 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;
+};
+export const assertBoolean = (value, path) => {
+    if (typeof value !== "boolean") {
+        throw new Error(`${path} must be true or false.`);
+    }
+    return value;
+};
+export const assertPositiveInteger = (value, path) => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${path} must be a positive integer.`);
+    }
+    return value;
+};
+export 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;
+};
+export 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()))];
+};
+export const assertLoopbackUrl = (value, path, allowedHosts, supportedHosts) => {
+    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) ||
+        !supportedHosts.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, "");
+};

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

@@ -0,0 +1,42 @@
+/**
+ * Purpose: Resolve an npm consumer root conservatively and create the same
+ * project-owned scaffolding used by the guided setup command.
+ */
+export type ConsumerRootResolution = {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "resolved";
+    projectRoot: string;
+};
+export interface ResolveConsumerRootOptions {
+    packageRoot?: string;
+    initCwd?: string;
+    localPrefix?: string;
+    globalInstall?: boolean | string;
+    workspace?: string;
+}
+export interface InstalledScaffoldOptions {
+    packageRoot?: string;
+    environment?: NodeJS.ProcessEnv;
+    isPortAvailable?: (port: number) => boolean | Promise<boolean>;
+}
+export interface InstalledScaffoldFile {
+    path: string;
+    action: string;
+}
+export type InstalledScaffoldResult = {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "ready";
+    projectRoot: string;
+    target: string;
+    files: InstalledScaffoldFile[];
+    configurationPath: string;
+    configurationAction: string;
+    rootConfigGenerationSkipped: boolean;
+};
+export declare const renderInstalledRehearsalScaffold: (result: InstalledScaffoldResult) => string;
+export declare const resolveRehearsalConsumerRoot: ({ packageRoot, initCwd, localPrefix, globalInstall, workspace, }?: ResolveConsumerRootOptions) => Promise<ConsumerRootResolution>;
+export declare const createInstalledRehearsalScaffold: ({ packageRoot, environment, isPortAvailable, }?: InstalledScaffoldOptions) => Promise<InstalledScaffoldResult>;