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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.16",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -21,27 +21,26 @@
     "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
   },
   "bin": {
-    "rehearsal": "src/cli/rehearsal.mjs"
+    "rehearsal": "dist/src/cli/rehearsal.mjs"
   },
   "exports": {
     ".": {
-      "types": "./src/project/configuration.d.mts",
-      "import": "./src/project/configuration.mjs"
+      "types": "./types/configuration.d.mts",
+      "import": "./dist/src/index.mjs"
     },
-    "./baseline": "./src/baseline/artifact.mjs",
-    "./baseline-builder": "./src/baseline/builder.mjs",
-    "./diagnostics": "./src/shared/diagnostics.mjs",
-    "./migrations": "./src/runtime/migration_history.mjs",
-    "./process-environment": "./src/shared/process_environment.mjs",
-    "./privacy": "./src/baseline/privacy_engine.mjs",
-    "./schema": "./src/baseline/schema_snapshot.mjs",
-    "./service-environment": "./src/runtime/service_environment.mjs",
-    "./source-access": "./src/source/access.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": [
-    "src",
-    "scripts/install/create_root_config.mjs",
-    "scripts/runtime/manage_database.mjs",
+    "dist",
+    "types",
     "docs/*.md",
     "README.md",
     "BENCHMARKS.md",
@@ -52,21 +51,26 @@
     "LICENSE"
   ],
   "scripts": {
-    "postinstall": "node scripts/install/create_root_config.mjs",
+    "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": "vitest run",
-    "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration tests/contracts",
-    "test:docs": "vitest run tests/contracts/documentationCommands.test.mjs",
-    "test:fixture": "node scripts/verification/fixtures/supabase.mjs",
-    "test:fixture:postgresql": "node scripts/verification/fixtures/postgresql.mjs",
-    "test:fixture:dependent": "node scripts/verification/fixtures/dependent.mjs",
-    "test:fixture:onboarding": "node scripts/verification/fixtures/onboarding.mjs",
-    "test:fixture:standalone": "node scripts/verification/fixtures/standalone.mjs",
-    "test:fixture:privacy": "node scripts/verification/fixtures/privacy.mjs",
-    "check": "npm run check:syntax && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
-    "check:syntax": "find src scripts tests -type f -name '*.mjs' -exec node --check {} +",
+    "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"
@@ -87,8 +91,11 @@
     "@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/types/configuration.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility declaration entry point.
+ * Public types are emitted from the TypeScript implementation in dist/src.
+ */
+export * from "../dist/src/index.mjs";

package/scripts/install/create_root_config.mjs

@@ -1,19 +0,0 @@
-#!/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) {
-  console.warn(
-    `Rehearsal could not safely create project files during installation: ${String(error?.message ?? error)}\nNext: run npx rehearsal from the application directory.`,
-  );
-}

package/src/README.md

@@ -1,17 +0,0 @@
-# Source layout
-
-Production code is grouped by the responsibility it owns:
-
-- `application/` starts and proves the project application.
-- `baseline/` creates, validates, and stores safe baseline artifacts.
-- `cli/` is the human and automation entry point.
-- `identity/` associates copied data with verified local users.
-- `project/` owns configuration, setup, and support reporting.
-- `runtime/` plans, verifies, resets, migrates, and cleans local runtimes.
-- `shared/` contains small target-neutral infrastructure.
-- `source/` controls approved source access and baseline refresh.
-- `targets/` contains the PostgreSQL and Supabase runtime adapters.
-
-Place a new module in the domain that owns its policy. Keep database-specific behavior
-behind `targets/`, repository-only checks under `scripts/verification/`, and public
-imports behind the export map in `package.json`.

package/src/application/session.mjs

@@ -1,435 +0,0 @@
-/** 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);
-  return values;
-};
-
-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.",
-    );
-  }
-  return parseEnv(await readFile(path, "utf8"));
-};
-
-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);
-    if (!ENV_KEY.test(source) || !environments[target]?.[source]) {
-      throw new Error(
-        `Application mapping ${destination} references a missing runtime value.`,
-      );
-    }
-    assertLocalValue(source, environments[target][source]);
-    result[destination] = environments[target][source];
-  }
-  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 process.kill(-child.pid, signal);
-    } catch (error) {
-      if (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;
-  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;
-  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);
-};