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

package/{scripts → dist/scripts}/runtime/manage_database.mjs

@@ -3,16 +3,14 @@
  * Purpose: Select the configured database runtime and forward the requested
  * lifecycle action to its isolated driver.
  */
-
 import { loadRehearsalConfig } from "../../src/project/configuration.mjs";
-import {
-  parseRuntimeInvocation,
-  runRuntimeTarget,
-} from "../../src/targets/target.mjs";
-
+import { parseRuntimeInvocation } from "../../src/targets/target.mjs";
+import { runRuntimeTarget } from "../../src/targets/driver.mjs";
 const invocation = parseRuntimeInvocation();
 const { config } = await loadRehearsalConfig({
-  projectRoot: process.cwd(),
-  configPath: invocation.configPath,
+    projectRoot: process.cwd(),
+    ...(invocation.configPath === undefined
+        ? {}
+        : { configPath: invocation.configPath }),
 });
 await runRuntimeTarget(config.runtime.target);

package/dist/src/application/interactive_task.d.mts

@@ -0,0 +1,30 @@
+/** Run identity discovery while an owned local application remains available. */
+import type { EventEmitter } from "node:events";
+import { type ApplicationDiagnostics, type ApplicationSession, type ApplicationSessionSignal } from "./session.mjs";
+type SignalTarget = Pick<EventEmitter, "prependListener" | "removeListener">;
+interface SessionInput {
+    readonly isTTY?: boolean;
+    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+}
+/**
+ * A terminal interruption aborts the task and retires the owned process group.
+ * A completed task leaves the session running so its caller can deliberately
+ * stop, reuse, or hand it back to the persistent application holder.
+ */
+export declare const runApplicationSessionTask: <Value>({ session, task, signalTarget, input, onReady, }: {
+    session: ApplicationSession;
+    task: (signal: AbortSignal) => Promise<Value>;
+    signalTarget?: SignalTarget;
+    input?: SessionInput;
+    onReady?: (ready: ApplicationSession["ready"]) => void;
+}) => Promise<Readonly<{
+    completed: true;
+    value: Value;
+    diagnostics: ApplicationDiagnostics;
+}> | Readonly<{
+    completed: false;
+    signal: ApplicationSessionSignal;
+    diagnostics: ApplicationDiagnostics;
+}>>;
+export {};

package/dist/src/application/interactive_task.mjs

@@ -0,0 +1,83 @@
+/** Run identity discovery while an owned local application remains available. */
+import { summarizeProjectCommandFailure, } from "./session.mjs";
+const SESSION_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
+/**
+ * A terminal interruption aborts the task and retires the owned process group.
+ * A completed task leaves the session running so its caller can deliberately
+ * stop, reuse, or hand it back to the persistent application holder.
+ */
+export const runApplicationSessionTask = async ({ session, task, signalTarget = process, input = process.stdin, onReady = () => undefined, }) => {
+    if (!session ||
+        typeof session.wait !== "function" ||
+        typeof session.stop !== "function") {
+        throw new Error("A started application session is required.");
+    }
+    let finishInterruption = () => undefined;
+    const interruption = new Promise((resolve) => {
+        finishInterruption = resolve;
+    });
+    const handlers = new Map(SESSION_SIGNALS.map((signal) => [
+        signal,
+        () => finishInterruption({ kind: "interrupted", signal }),
+    ]));
+    for (const [signal, handler] of handlers) {
+        signalTarget.prependListener(signal, handler);
+    }
+    const onInput = (chunk) => {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (bytes.includes(0x03)) {
+            finishInterruption({ kind: "interrupted", signal: "SIGINT" });
+        }
+        else if (bytes.includes(0x1a)) {
+            finishInterruption({ kind: "interrupted", signal: "SIGTSTP" });
+        }
+    };
+    if (input?.isTTY)
+        input.prependListener("data", onInput);
+    const abortController = new AbortController();
+    try {
+        onReady(session.ready);
+        const outcome = await Promise.race([
+            interruption,
+            task(abortController.signal).then((value) => ({
+                kind: "completed",
+                value,
+            })),
+            session.wait().then((exit) => ({ kind: "exited", ...exit })),
+        ]);
+        if (outcome.kind === "exited") {
+            throw new Error(`Application exited before identity connection finished (${summarizeProjectCommandFailure({
+                status: outcome.status,
+                signal: outcome.signal,
+                stdoutByteCount: session.diagnostics().stdoutBytes,
+                stderrByteCount: session.diagnostics().stderrBytes,
+            })}).`);
+        }
+        if (outcome.kind === "interrupted") {
+            abortController.abort(new Error(`Identity connection was interrupted by ${outcome.signal}.`));
+            await session.stop();
+            return Object.freeze({
+                completed: false,
+                signal: outcome.signal,
+                diagnostics: session.diagnostics(),
+            });
+        }
+        return Object.freeze({
+            completed: true,
+            value: outcome.value,
+            diagnostics: session.diagnostics(),
+        });
+    }
+    catch (error) {
+        abortController.abort(error);
+        await session.stop();
+        throw error;
+    }
+    finally {
+        for (const [signal, handler] of handlers) {
+            signalTarget.removeListener(signal, handler);
+        }
+        if (input?.isTTY)
+            input.removeListener("data", onInput);
+    }
+};

package/dist/src/application/session.d.mts

@@ -0,0 +1,97 @@
+/** Launch ordinary application commands against verified local runtime files. */
+import { spawn } from "node:child_process";
+import type { EventEmitter } from "node:events";
+declare const SESSION_SIGNALS: string[];
+type SessionSignal = (typeof SESSION_SIGNALS)[number];
+export type ApplicationSessionSignal = SessionSignal;
+export interface ApplicationReadiness {
+    readonly url: string;
+    readonly expectedStatus?: number;
+    readonly timeoutSeconds?: number;
+}
+export interface ApplicationSession {
+    readonly pid: number | undefined;
+    readonly ready: Readonly<{
+        url: string;
+        status: number;
+    }>;
+    readonly stop: () => Promise<void>;
+    readonly wait: () => Promise<ChildExit>;
+    readonly diagnostics: () => ApplicationDiagnostics;
+}
+export interface ApplicationDiagnostics {
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+}
+interface ChildExit {
+    readonly status: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+interface SessionInput {
+    readonly isTTY?: boolean;
+    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+}
+interface EnvironmentInput {
+    readonly files: Readonly<Record<string, string>> & {
+        readonly primary: string;
+    };
+    readonly mappings: Readonly<Record<string, string>>;
+}
+interface HttpJsonAssertion {
+    readonly path: readonly string[];
+    readonly equals?: unknown;
+    readonly notEquals?: unknown;
+    readonly minimumItems?: number;
+}
+export interface HttpProofCheck {
+    readonly name: string;
+    readonly kind: "positive" | "negative";
+    readonly url: string;
+    readonly method?: string;
+    readonly expectedStatus: number;
+    readonly timeoutMs?: number;
+    readonly json?: HttpJsonAssertion | null;
+}
+type SignalTarget = Pick<EventEmitter, "prependListener" | "removeListener">;
+export declare const buildApplicationEnvironment: ({ files, mappings, }: EnvironmentInput) => Promise<Record<string, string>>;
+export declare const summarizeProjectCommandFailure: ({ error, status, signal, stdout, stderr, stdoutByteCount, stderrByteCount, }: {
+    error?: NodeJS.ErrnoException;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout?: string;
+    stderr?: string;
+    stdoutByteCount?: number;
+    stderrByteCount?: number;
+}) => string;
+export declare const startApplicationSession: ({ command, cwd, files, mappings, readiness, inheritedEnvironment, spawnImplementation, fetchImplementation, signalTarget, }: EnvironmentInput & {
+    command: string;
+    cwd: string;
+    readiness: ApplicationReadiness;
+    inheritedEnvironment?: NodeJS.ProcessEnv;
+    spawnImplementation?: typeof spawn;
+    fetchImplementation?: typeof fetch;
+    signalTarget?: SignalTarget;
+}) => Promise<ApplicationSession>;
+/**
+ * Keep a ready application session attached until the user interrupts it.
+ * The child process group is always stopped before this function returns.
+ */
+export declare const holdApplicationSession: ({ session, signalTarget, input, onReady, }: {
+    session: ApplicationSession;
+    signalTarget?: SignalTarget;
+    input?: SessionInput;
+    onReady?: (ready: ApplicationSession["ready"]) => void;
+}) => Promise<Readonly<{
+    signal: SessionSignal;
+    diagnostics: ApplicationDiagnostics;
+}>>;
+export declare const runHttpProofs: ({ checks, fetchImplementation, }: {
+    checks: readonly HttpProofCheck[];
+    fetchImplementation?: typeof fetch;
+}) => Promise<readonly Readonly<{
+    name: string;
+    kind: "positive" | "negative";
+    status: number;
+}>[]>;
+export {};

package/dist/src/application/session.mjs

@@ -0,0 +1,380 @@
+/** Launch ordinary application commands against verified local runtime files. */
+import { spawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { parseEnv } from "node:util";
+import { createCleanProcessEnvironment, isLoopbackUrl, } from "../shared/process_environment.mjs";
+const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
+const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
+const SESSION_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
+const parseCommand = (source) => {
+    if (typeof source !== "string" || !source.trim())
+        throw new Error("Application command is empty.");
+    const values = [];
+    let value = "";
+    let quote = null;
+    for (const character of source) {
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            else
+                value += character;
+        }
+        else if (character === '"' || character === "'")
+            quote = character;
+        else if (/\s/u.test(character)) {
+            if (value)
+                values.push(value);
+            value = "";
+        }
+        else
+            value += character;
+    }
+    if (quote)
+        throw new Error("Application command contains an unmatched quote.");
+    if (value)
+        values.push(value);
+    const [program, ...args] = values;
+    if (!program)
+        throw new Error("Application command is empty.");
+    return [program, ...args];
+};
+const readOwnedEnvironment = async (path) => {
+    const details = await stat(path);
+    if (!details.isFile() || (details.mode & 0o077) !== 0) {
+        throw new Error("Runtime environment file must be an owner-only regular file.");
+    }
+    const parsed = parseEnv(await readFile(path, "utf8"));
+    return Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === "string"));
+};
+const assertLocalValue = (key, value) => {
+    if (/(_URL|_URI|_ENDPOINT)$/u.test(key)) {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            throw new Error(`Mapped runtime variable ${key} is not a URL.`);
+        }
+        if (!isLoopbackUrl(value) &&
+            !["postgres:", "postgresql:"].includes(parsed.protocol)) {
+            throw new Error(`Mapped runtime variable ${key} is not local.`);
+        }
+        if (["postgres:", "postgresql:"].includes(parsed.protocol) &&
+            !["127.0.0.1", "::1", "localhost"].includes(parsed.hostname)) {
+            throw new Error(`Mapped runtime variable ${key} is not local.`);
+        }
+    }
+};
+export const buildApplicationEnvironment = async ({ files, mappings, }) => {
+    if (!files?.primary)
+        throw new Error("Primary runtime environment file is required.");
+    const environments = {};
+    for (const [name, path] of Object.entries(files)) {
+        environments[name] = await readOwnedEnvironment(path);
+    }
+    if (!mappings || typeof mappings !== "object" || Array.isArray(mappings)) {
+        throw new Error("Application environment mappings must be an object.");
+    }
+    const result = {};
+    for (const [destination, reference] of Object.entries(mappings)) {
+        if (!ENV_KEY.test(destination) || typeof reference !== "string") {
+            throw new Error("Application environment mapping is invalid.");
+        }
+        const separator = reference.indexOf(":");
+        if (separator < 1)
+            throw new Error(`Application mapping ${destination} has an invalid reference.`);
+        const target = reference.slice(0, separator);
+        const source = reference.slice(separator + 1);
+        const sourceValue = environments[target]?.[source];
+        if (!ENV_KEY.test(source) || !sourceValue) {
+            throw new Error(`Application mapping ${destination} references a missing runtime value.`);
+        }
+        assertLocalValue(source, sourceValue);
+        result[destination] = sourceValue;
+    }
+    return result;
+};
+const boundedAppend = (current, chunk) => `${current}${chunk}`.slice(-MAX_DIAGNOSTIC_BYTES);
+const childHasExited = (child) => child.exitCode !== null || child.signalCode !== null;
+const waitForChildExit = (child) => {
+    if (childHasExited(child)) {
+        return Promise.resolve({
+            status: child.exitCode,
+            signal: child.signalCode,
+        });
+    }
+    return new Promise((resolve) => {
+        child.once("exit", (status, signal) => resolve({ status, signal }));
+    });
+};
+export const summarizeProjectCommandFailure = ({ error, status, signal, stdout = "", stderr = "", stdoutByteCount, stderrByteCount, }) => {
+    const stdoutBytes = stdoutByteCount ?? Buffer.byteLength(String(stdout));
+    const stderrBytes = stderrByteCount ?? Buffer.byteLength(String(stderr));
+    if (error) {
+        const code = /^[A-Z0-9_]+$/u.test(error.code ?? "")
+            ? ` (${error.code})`
+            : "";
+        return `command could not start${code}; output withheld`;
+    }
+    const outcome = signal
+        ? `signal ${signal}`
+        : `exit ${Number.isInteger(status) ? status : "unknown"}`;
+    return `${outcome}; stdout ${stdoutBytes} bytes; stderr ${stderrBytes} bytes; output withheld`;
+};
+const waitForReadiness = async ({ readiness, fetchImplementation, child, }) => {
+    if (!readiness || !isLoopbackUrl(readiness.url)) {
+        throw new Error("Application readiness must use a loopback URL.");
+    }
+    const expected = readiness.expectedStatus ?? 200;
+    const deadline = Date.now() + (readiness.timeoutSeconds ?? 30) * 1_000;
+    let lastStatus = null;
+    while (Date.now() < deadline) {
+        if (childHasExited(child))
+            throw new Error("Application exited before becoming ready.");
+        try {
+            const response = await fetchImplementation(readiness.url, {
+                redirect: "manual",
+                signal: AbortSignal.timeout(2_000),
+            });
+            lastStatus = response.status;
+            if (response.status === expected)
+                return { url: readiness.url, status: response.status };
+        }
+        catch {
+            // A bounded retry is expected while the local process starts.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    throw new Error(`Application readiness timed out${lastStatus === null ? "" : ` after HTTP ${lastStatus}`}.`);
+};
+const stopOwnedChild = async (child) => {
+    if (childHasExited(child))
+        return;
+    const exit = waitForChildExit(child);
+    const kill = (signal) => {
+        try {
+            if (process.platform === "win32")
+                child.kill(signal);
+            else {
+                if (child.pid === undefined) {
+                    throw new Error("Application child process has no process identifier.");
+                }
+                process.kill(-child.pid, signal);
+            }
+        }
+        catch (error) {
+            if (typeof error !== "object" ||
+                error === null ||
+                !("code" in error) ||
+                error.code !== "ESRCH")
+                throw error;
+        }
+    };
+    kill("SIGTERM");
+    await Promise.race([
+        exit,
+        new Promise((resolve) => setTimeout(resolve, 5_000)),
+    ]);
+    if (!childHasExited(child)) {
+        kill("SIGKILL");
+        await exit;
+    }
+};
+export const startApplicationSession = async ({ command, cwd, files, mappings, readiness, inheritedEnvironment = process.env, spawnImplementation = spawn, fetchImplementation = fetch, signalTarget = process, }) => {
+    const mapped = await buildApplicationEnvironment({ files, mappings });
+    const [program, ...args] = parseCommand(command);
+    const child = spawnImplementation(program, args, {
+        cwd,
+        env: createCleanProcessEnvironment({
+            inheritedEnvironment,
+            overrides: mapped,
+        }),
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout = boundedAppend(stdout, chunk.toString("utf8"));
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr = boundedAppend(stderr, chunk.toString("utf8"));
+    });
+    await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+    });
+    let interruptStartup = () => undefined;
+    const interruption = new Promise((_, reject) => {
+        interruptStartup = (signal) => reject(new Error(`Application startup was interrupted by ${signal}.`));
+    });
+    const startupHandlers = new Map(SESSION_SIGNALS.map((signal) => [signal, () => interruptStartup(signal)]));
+    for (const [signal, handler] of startupHandlers) {
+        signalTarget.prependListener(signal, handler);
+    }
+    try {
+        const ready = await Promise.race([
+            waitForReadiness({
+                readiness,
+                fetchImplementation,
+                child,
+            }),
+            interruption,
+        ]);
+        return Object.freeze({
+            pid: child.pid,
+            ready,
+            stop: () => stopOwnedChild(child),
+            wait: () => waitForChildExit(child),
+            diagnostics: () => ({
+                stdoutBytes: Buffer.byteLength(stdout),
+                stderrBytes: Buffer.byteLength(stderr),
+            }),
+        });
+    }
+    catch (error) {
+        await stopOwnedChild(child);
+        throw error;
+    }
+    finally {
+        for (const [signal, handler] of startupHandlers) {
+            signalTarget.removeListener(signal, handler);
+        }
+    }
+};
+/**
+ * Keep a ready application session attached until the user interrupts it.
+ * The child process group is always stopped before this function returns.
+ */
+export const holdApplicationSession = async ({ session, signalTarget = process, input = process.stdin, onReady = () => undefined, }) => {
+    if (!session ||
+        typeof session.wait !== "function" ||
+        typeof session.stop !== "function") {
+        throw new Error("A started application session is required.");
+    }
+    let finishInterruption = () => undefined;
+    const interruption = new Promise((resolve) => {
+        finishInterruption = resolve;
+    });
+    const handlers = new Map(SESSION_SIGNALS.map((signal) => [
+        signal,
+        () => finishInterruption({ kind: "interrupted", signal }),
+    ]));
+    for (const [signal, handler] of handlers) {
+        signalTarget.prependListener(signal, handler);
+    }
+    const onInput = (chunk) => {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (bytes.includes(0x03)) {
+            finishInterruption({ kind: "interrupted", signal: "SIGINT" });
+        }
+        else if (bytes.includes(0x1a)) {
+            finishInterruption({ kind: "interrupted", signal: "SIGTSTP" });
+        }
+    };
+    if (input?.isTTY)
+        input.prependListener("data", onInput);
+    try {
+        onReady(session.ready);
+        const outcome = await Promise.race([
+            interruption,
+            session.wait().then((exit) => ({ kind: "exited", ...exit })),
+        ]);
+        if (outcome.kind === "exited") {
+            const diagnostics = session.diagnostics?.() ?? {};
+            throw new Error(`Application exited before the sandbox was closed (${summarizeProjectCommandFailure({
+                status: outcome.status,
+                signal: outcome.signal,
+                stdoutByteCount: diagnostics.stdoutBytes ?? 0,
+                stderrByteCount: diagnostics.stderrBytes ?? 0,
+            })}).`);
+        }
+        return Object.freeze({
+            signal: outcome.signal,
+            diagnostics: session.diagnostics?.() ?? {
+                stdoutBytes: 0,
+                stderrBytes: 0,
+            },
+        });
+    }
+    finally {
+        try {
+            // npm can forward the terminal's SIGINT after the CLI receives it.
+            // Keep our handlers installed until the owned process group is fully
+            // stopped so a duplicate signal cannot terminate Rehearsal mid-cleanup.
+            await session.stop();
+        }
+        finally {
+            for (const [signal, handler] of handlers) {
+                signalTarget.removeListener(signal, handler);
+            }
+            if (input?.isTTY)
+                input.removeListener("data", onInput);
+        }
+    }
+};
+const valueAtPath = (value, path) => {
+    let current = value;
+    for (const segment of path) {
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, segment)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+};
+export const runHttpProofs = async ({ checks, fetchImplementation = fetch, }) => {
+    if (!Array.isArray(checks) || checks.length < 2) {
+        throw new Error("HTTP proof requires explicit positive and negative checks.");
+    }
+    if (!checks.some((check) => check.kind === "positive") ||
+        !checks.some((check) => check.kind === "negative")) {
+        throw new Error("HTTP proof requires at least one positive and one negative check.");
+    }
+    const results = [];
+    for (const check of checks) {
+        if (!isLoopbackUrl(check.url))
+            throw new Error(`HTTP proof ${check.name} is not local.`);
+        const response = await fetchImplementation(check.url, {
+            method: check.method ?? "GET",
+            redirect: "manual",
+            signal: AbortSignal.timeout(check.timeoutMs ?? 5_000),
+        });
+        if (response.status !== check.expectedStatus) {
+            throw new Error(`HTTP proof ${check.name} expected status ${check.expectedStatus} but received ${response.status}.`);
+        }
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.length > 1024 * 1024)
+            throw new Error(`HTTP proof ${check.name} returned too much data.`);
+        if (check.json) {
+            let parsed;
+            try {
+                parsed = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new Error(`HTTP proof ${check.name} did not return JSON.`);
+            }
+            const actual = valueAtPath(parsed, check.json.path);
+            if (Object.hasOwn(check.json, "equals") &&
+                !Object.is(actual, check.json.equals)) {
+                throw new Error(`HTTP proof ${check.name} did not return its required value.`);
+            }
+            if (Object.hasOwn(check.json, "notEquals") &&
+                Object.is(actual, check.json.notEquals)) {
+                throw new Error(`HTTP proof ${check.name} returned a forbidden value.`);
+            }
+            if (check.json.minimumItems !== undefined &&
+                (!Array.isArray(actual) || actual.length < check.json.minimumItems)) {
+                throw new Error(`HTTP proof ${check.name} returned too few matching items.`);
+            }
+        }
+        results.push({
+            name: check.name,
+            kind: check.kind,
+            status: response.status,
+        });
+    }
+    return Object.freeze(results);
+};