@rehearsal-db/core 0.1.0-beta.8 → 0.1.0-rc.1

package/dist/package.json

@@ -0,0 +1,100 @@
+{
+    "name": "@rehearsal-db/core",
+    "version": "0.1.0-rc.1",
+    "private": false,
+    "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
+    },
+    "homepage": "https://ddupasquier.github.io/rehearsal-db/",
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "type": "module",
+    "engines": {
+        "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
+    },
+    "bin": {
+        "rehearsal": "dist/src/cli/rehearsal.mjs"
+    },
+    "exports": {
+        ".": {
+            "types": "./types/configuration.d.mts",
+            "import": "./dist/src/index.mjs"
+        },
+        "./baseline": "./dist/src/baseline/artifact.mjs",
+        "./baseline-builder": "./dist/src/baseline/builder.mjs",
+        "./diagnostics": "./dist/src/shared/diagnostics.mjs",
+        "./migrations": "./dist/src/runtime/migration_history.mjs",
+        "./process-environment": "./dist/src/shared/process_environment.mjs",
+        "./privacy": "./dist/src/baseline/privacy_engine.mjs",
+        "./schema": "./dist/src/baseline/schema_snapshot.mjs",
+        "./service-environment": "./dist/src/runtime/service_environment.mjs",
+        "./source-access": "./dist/src/source/access.mjs"
+    },
+    "files": [
+        "dist",
+        "types",
+        "docs/*.md",
+        "README.md",
+        "BENCHMARKS.md",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "COMPATIBILITY.md",
+        "SUPPORT.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "postinstall": "node dist/scripts/install/create_root_config.mjs",
+        "prepack": "npm run build",
+        "build": "node scripts/build/clean.mjs && tsc --project tsconfig.build.json",
+        "docs:build": "node scripts/docs/build.mjs",
+        "docs:preview": "node scripts/docs/serve.mjs",
+        "test": "npm run build && vitest run",
+        "test:unit": "npm run build && vitest run tests/unit",
+        "test:integration": "npm run build && vitest run tests/integration tests/contracts",
+        "test:docs": "npm run build && vitest run tests/contracts/documentationCommands.test.mjs",
+        "test:fixture": "npm run build && node scripts/verification/run_scenario.mjs supabase",
+        "test:fixture:postgresql": "npm run build && node scripts/verification/run_scenario.mjs postgresql",
+        "test:fixture:dependent": "npm run build && node scripts/verification/run_scenario.mjs dependent-target",
+        "test:fixture:onboarding": "npm run build && node scripts/verification/run_scenario.mjs onboarding",
+        "test:fixture:typescript": "npm run build && node scripts/verification/run_scenario.mjs typescript",
+        "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
+        "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
+        "release:verify": "node scripts/verification/release_gate.mjs",
+        "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
+        "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+        "typecheck": "npm run build && tsc --project tsconfig.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "package:audit": "node scripts/verification/audit_package.mjs"
+    },
+    "keywords": [
+        "postgresql",
+        "supabase",
+        "migration",
+        "testing",
+        "database"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@clack/prompts": "^1.8.1",
+        "pg": "^8.23.1"
+    },
+    "devDependencies": {
+        "@fontsource-variable/dm-sans": "^5.3.0",
+        "@fontsource-variable/fraunces": "^5.3.0",
+        "@lydell/node-pty": "^1.2.0-beta.15",
+        "@types/node": "22.20.5",
+        "@types/pg": "^8.23.1",
+        "marked": "^18.0.14",
+        "prettier": "^3.9.6",
+        "typescript": "7.0.2",
+        "vitest": "^5.0.2"
+    }
+}

package/dist/scripts/install/create_root_config.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+export {};

package/dist/scripts/install/create_root_config.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+import { fileURLToPath } from "node:url";
+import { createInstalledRehearsalScaffold, renderInstalledRehearsalScaffold, } from "../../src/project/install_scaffold.mjs";
+const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
+try {
+    const result = await createInstalledRehearsalScaffold({ packageRoot });
+    console.log(renderInstalledRehearsalScaffold(result));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Rehearsal could not safely create project files during installation: ${message}\nNext: run npx rehearsal from the application directory.`);
+}

package/dist/scripts/runtime/manage_database.d.mts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Select the configured database runtime and forward the requested
+ * lifecycle action to its isolated driver.
+ */
+export {};

package/dist/scripts/runtime/manage_database.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * 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 } from "../../src/targets/target.mjs";
+import { runRuntimeTarget } from "../../src/targets/driver.mjs";
+const invocation = parseRuntimeInvocation();
+const { config } = await loadRehearsalConfig({
+    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 {};