@rehearsal-db/core 0.1.0-beta.2 → 0.1.0-beta.3

package/scripts/lib/rehearsal/plan.mjs

@@ -19,6 +19,10 @@ import { createCandidateMigrationReceipt } from "./runtime_restore.mjs";
 import { readMigrationFileInventory } from "./migration_history.mjs";
 import { REHEARSAL_VERSION } from "./diagnostics.mjs";
 import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
+import {
+  readBoundRuntimeSanitizationPolicy,
+  validateRuntimeSanitizationPolicy,
+} from "./sanitization_policy.mjs";
 
 const commandAvailable = (command, args = ["--version"]) => {
   const result = spawnSync(command, args, {
@@ -155,8 +159,15 @@ const assertConfiguredCommand = async ({ command, projectRoot }) => {
 
 const loadPlanInputs = async (options = {}) => {
   const loaded = await loadRehearsalConfig(options);
-  const baseline = await verifyActiveBaseline({
-    artifactRoot: loaded.paths.artifactDirectory,
+  const [baseline, policyBytes] = await Promise.all([
+    verifyActiveBaseline({
+      artifactRoot: loaded.paths.artifactDirectory,
+    }),
+    readFile(loaded.paths.sanitizationPolicy),
+  ]);
+  readBoundRuntimeSanitizationPolicy({
+    bytes: policyBytes,
+    expectedSha256: baseline.sanitizationPolicySha256,
   });
   const currentFiles = await readMigrationFileInventory(
     new URL("./", pathToFileURL(`${loaded.paths.migrationDirectory}/`)),
@@ -412,6 +423,18 @@ export const runRehearsalDoctor = async (options = {}) => {
       remediation:
         "Correct the missing project path in the Rehearsal configuration.",
     },
+    {
+      id: "sanitization-policy",
+      label: "Reviewed sanitization policy",
+      run: async () => {
+        const policy = validateRuntimeSanitizationPolicy(
+          JSON.parse(await readFile(paths.sanitizationPolicy, "utf8")),
+        );
+        return `${policy.tables.length} table classifications reviewed through ${policy.migrationCutoff}`;
+      },
+      remediation:
+        "Complete every REVIEW REQUIRED decision, remove draft only after review, and retry.",
+    },
     {
       id: "runtime-isolation",
       label: "Runtime target isolation",

package/scripts/lib/rehearsal/sanitization_policy.mjs

@@ -3,6 +3,8 @@
  * Projects own the policy, schema inventory, pseudonym keys, and derivation logic.
  */
 
+import { createHash } from "node:crypto";
+
 export const SANITIZATION_ACTIONS = Object.freeze({
   KEEP: "KEEP",
   PSEUDONYMIZE: "PSEUDONYMIZE",
@@ -44,6 +46,114 @@ export const normalizeSanitizationAction = (action) => {
   return normalized;
 };
 
+export const validateRuntimeSanitizationPolicy = (policy) => {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("A Rehearsal sanitization policy object is required.");
+  }
+  if (policy.draft === true) {
+    throw new Error(
+      "The sanitization policy is still a REVIEW REQUIRED draft.",
+    );
+  }
+  if (policy.policyVersion !== 1) {
+    throw new Error("The sanitization policy must use policyVersion 1.");
+  }
+  if (!/^\d{14}$/u.test(policy.migrationCutoff ?? "")) {
+    throw new Error(
+      "The sanitization policy must declare a timestamp migrationCutoff.",
+    );
+  }
+  if (!Array.isArray(policy.tables) || policy.tables.length === 0) {
+    throw new Error("The sanitization policy does not list tables.");
+  }
+  const tables = new Set();
+  for (const table of policy.tables) {
+    const tableName = assertIdentifier(
+      table?.name,
+      "Sanitization policy table name",
+    );
+    if (tables.has(tableName)) {
+      throw new Error(`Sanitization policy duplicates table ${tableName}.`);
+    }
+    tables.add(tableName);
+    if (!["STREAM AND SANITIZE", "EXCLUDE"].includes(table.sourceRows)) {
+      throw new Error(
+        `Sanitization policy table ${tableName} has an invalid sourceRows decision.`,
+      );
+    }
+    if (!Array.isArray(table.columns) || table.columns.length === 0) {
+      throw new Error(
+        `Sanitization policy table ${tableName} must list its columns.`,
+      );
+    }
+    const columns = new Set();
+    for (const column of table.columns) {
+      const columnName = assertIdentifier(
+        column?.name,
+        `Sanitization policy column in ${tableName}`,
+      );
+      if (columns.has(columnName)) {
+        throw new Error(
+          `Sanitization policy duplicates column ${tableName}.${columnName}.`,
+        );
+      }
+      columns.add(columnName);
+      normalizeSanitizationAction(column.action);
+      if (!["ALWAYS", "NEVER"].includes(column.generated)) {
+        throw new Error(
+          `Sanitization policy column ${tableName}.${columnName} must classify generated as ALWAYS or NEVER.`,
+        );
+      }
+      if (!["YES", "NO"].includes(column.identity)) {
+        throw new Error(
+          `Sanitization policy column ${tableName}.${columnName} must classify identity as YES or NO.`,
+        );
+      }
+      if (column.foreignKey !== null) {
+        if (
+          !column.foreignKey ||
+          typeof column.foreignKey !== "object" ||
+          Array.isArray(column.foreignKey)
+        ) {
+          throw new Error(
+            `Sanitization policy column ${tableName}.${columnName} has an invalid foreignKey decision.`,
+          );
+        }
+        assertIdentifier(
+          column.foreignKey.schema,
+          `Foreign-key schema for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.foreignKey.table,
+          `Foreign-key table for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.foreignKey.column,
+          `Foreign-key column for ${tableName}.${columnName}`,
+        );
+      }
+    }
+  }
+  return policy;
+};
+
+export const readBoundRuntimeSanitizationPolicy = ({
+  bytes,
+  expectedSha256,
+}) => {
+  const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const policy = validateRuntimeSanitizationPolicy(
+    JSON.parse(source.toString("utf8")),
+  );
+  const actualSha256 = createHash("sha256").update(source).digest("hex");
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(
+      "The active sanitization policy does not match the reviewed baseline policy checksum.",
+    );
+  }
+  return policy;
+};
+
 const indexTables = (tables, label) => {
   if (!Array.isArray(tables)) throw new Error(`${label} must be an array.`);
   const index = new Map();

package/scripts/lib/rehearsal/setup.mjs

@@ -0,0 +1,347 @@
+/**
+ * Purpose: Plan and apply conservative first-run Rehearsal scaffolding without
+ * contacting hosted services or overwriting project-owned files.
+ */
+
+import { createConnection, createServer } from "node:net";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  inspectDetectedProject,
+  renderDetectedConfig,
+} from "./configuration.mjs";
+
+const CONFIG_PATH = "rehearsal.config.mjs";
+const LOCAL_SUPABASE_CONFIG_PATH =
+  "infrastructure/rehearsal/supabase/config.toml";
+const GITIGNORE_PATH = ".gitignore";
+const PORT_OFFSETS = Object.freeze({
+  shadow: 0,
+  api: 1,
+  database: 2,
+  studio: 3,
+  smtp: 4,
+  pooler: 9,
+});
+
+const pathExists = (path) =>
+  access(path)
+    .then(() => true)
+    .catch((error) => {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    });
+
+const readOptionalFile = async (path) => {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const canConnectToPort = (port) =>
+  new Promise((resolveAvailability) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (result) => {
+      socket.destroy();
+      resolveAvailability(result);
+    };
+    socket.setTimeout(500);
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.once("timeout", () => finish(false));
+  });
+
+const canBindToPort = (port) =>
+  new Promise((resolveAvailability) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", () => resolveAvailability(false));
+    server.listen({ host: "127.0.0.1", port, exclusive: true }, () => {
+      server.close(() => resolveAvailability(true));
+    });
+  });
+
+export const isRehearsalPortAvailable = async (port) => {
+  if (await canConnectToPort(port)) return false;
+  return canBindToPort(port);
+};
+
+export const inspectRehearsalNodeRuntime = (
+  version = process.versions.node,
+) => {
+  const major = Number.parseInt(String(version).split(".")[0], 10);
+  return {
+    version: String(version),
+    major,
+    supported: major === 24,
+  };
+};
+
+export const assertSupportedRehearsalNodeRuntime = (
+  version = process.versions.node,
+) => {
+  const runtime = inspectRehearsalNodeRuntime(version);
+  if (!runtime.supported) {
+    throw new Error(
+      `Rehearsal setup requires Node.js 24; this shell is using Node.js ${runtime.version}. Switch to Node.js 24, then rerun setup. With nvm: nvm install 24 && nvm use 24.`,
+    );
+  }
+  return runtime;
+};
+
+export const findAvailableRehearsalPorts = async ({
+  isAvailable = isRehearsalPortAvailable,
+} = {}) => {
+  for (let base = 58_320; base <= 65_520; base += 20) {
+    const entries = Object.entries(PORT_OFFSETS).map(([name, offset]) => [
+      name,
+      base + offset,
+    ]);
+    const availability = await Promise.all(
+      entries.map(([, port]) => isAvailable(port)),
+    );
+    if (availability.every(Boolean)) return Object.fromEntries(entries);
+  }
+  throw new Error(
+    "Rehearsal could not find an available local port block between 58320 and 65529.",
+  );
+};
+
+const databaseMajorVersionFrom = (source) => {
+  const match = /^\s*major_version\s*=\s*(\d+)\s*(?:#.*)?$/imu.exec(
+    source ?? "",
+  );
+  return match ? Number(match[1]) : 17;
+};
+
+export const renderSafeLocalSupabaseConfig = ({
+  projectId,
+  applicationUrl,
+  ports,
+  databaseMajorVersion = 17,
+}) => `# Generated by Rehearsal for a disposable, local-only runtime.
+# Review project-specific Auth or Storage additions before enabling them here.
+project_id = ${JSON.stringify(projectId)}
+
+[api]
+enabled = true
+port = ${ports.api}
+schemas = ["public"]
+extra_search_path = ["public", "extensions"]
+
+[db]
+port = ${ports.database}
+shadow_port = ${ports.shadow}
+major_version = ${databaseMajorVersion}
+
+[db.pooler]
+enabled = false
+port = ${ports.pooler}
+
+[db.migrations]
+enabled = true
+schema_paths = []
+
+[db.seed]
+enabled = false
+sql_paths = []
+
+[studio]
+enabled = true
+port = ${ports.studio}
+api_url = "http://127.0.0.1"
+
+[local_smtp]
+enabled = false
+port = ${ports.smtp}
+
+[auth]
+enabled = true
+site_url = ${JSON.stringify(applicationUrl)}
+enable_signup = false
+
+[storage]
+enabled = true
+
+[realtime]
+enabled = false
+
+[edge_runtime]
+enabled = false
+
+[analytics]
+enabled = false
+`;
+
+const appendGitignoreEntries = (source) => {
+  const original = source ?? "";
+  const lines = new Set(
+    original
+      .split(/\r?\n/u)
+      .map((line) => line.trim())
+      .filter(Boolean),
+  );
+  const entries = [".rehearsal/", ".env.rehearsal-service.local"];
+  const missing = entries.filter(
+    (entry) =>
+      !lines.has(entry) &&
+      !lines.has(`/${entry}`) &&
+      !lines.has(entry.replace(/\/$/u, "")),
+  );
+  if (missing.length === 0) return original;
+  const prefix =
+    original && !original.endsWith("\n") ? `${original}\n` : original;
+  const separator = prefix && !prefix.endsWith("\n\n") ? "\n" : "";
+  return `${prefix}${separator}# Rehearsal local artifacts\n${missing.join("\n")}\n`;
+};
+
+const assertCreateTargetAvailable = async (file) => {
+  if (file.action === "create" && (await pathExists(file.absolutePath))) {
+    throw new Error(
+      `Rehearsal setup will not overwrite the existing file at ${file.path}.`,
+    );
+  }
+};
+
+export const planRehearsalSetup = async ({
+  projectRoot = process.cwd(),
+  isPortAvailable,
+} = {}) => {
+  const root = resolve(projectRoot);
+  const detected = await inspectDetectedProject({ projectRoot: root });
+  const ports = await findAvailableRehearsalPorts({
+    ...(isPortAvailable ? { isAvailable: isPortAvailable } : {}),
+  });
+  const applicationUrl = "http://localhost:5175";
+  const projectId = `${detected.projectName}-rehearsal`;
+  const sourceSupabaseConfig = await readOptionalFile(
+    join(root, "supabase/config.toml"),
+  );
+  const originalGitignore = await readOptionalFile(join(root, GITIGNORE_PATH));
+  const nextGitignore = appendGitignoreEntries(originalGitignore);
+  for (const path of [CONFIG_PATH, LOCAL_SUPABASE_CONFIG_PATH]) {
+    if (await pathExists(join(root, path))) {
+      throw new Error(
+        `Rehearsal setup will not overwrite the existing file at ${path}.`,
+      );
+    }
+  }
+  const files = [
+    {
+      path: CONFIG_PATH,
+      absolutePath: join(root, CONFIG_PATH),
+      action: "create",
+      mode: 0o600,
+      content: renderDetectedConfig(detected, {
+        applicationUrl,
+        ports,
+      }),
+    },
+    {
+      path: LOCAL_SUPABASE_CONFIG_PATH,
+      absolutePath: join(root, LOCAL_SUPABASE_CONFIG_PATH),
+      action: "create",
+      mode: 0o600,
+      content: renderSafeLocalSupabaseConfig({
+        projectId,
+        applicationUrl,
+        ports,
+        databaseMajorVersion: databaseMajorVersionFrom(sourceSupabaseConfig),
+      }),
+    },
+    {
+      path: GITIGNORE_PATH,
+      absolutePath: join(root, GITIGNORE_PATH),
+      action:
+        nextGitignore === (originalGitignore ?? "")
+          ? "unchanged"
+          : originalGitignore === null
+            ? "create"
+            : "update",
+      mode: 0o644,
+      originalContent: originalGitignore,
+      content: nextGitignore,
+    },
+  ];
+  return {
+    projectRoot: root,
+    project: detected.projectName,
+    projectId,
+    applicationUrl,
+    detected,
+    ports,
+    isPortAvailable: isPortAvailable ?? isRehearsalPortAvailable,
+    files,
+    safety: [
+      "hosted access remains disabled",
+      "the Supabase runtime binds to dedicated local ports",
+      "external identity providers, realtime, edge functions, and analytics start disabled",
+      "configuration files are never overwritten and .gitignore updates are concurrency-checked",
+    ],
+  };
+};
+
+export const applyRehearsalSetup = async (plan) => {
+  assertSupportedRehearsalNodeRuntime();
+  const unavailablePorts = (
+    await Promise.all(
+      Object.values(plan.ports).map(async (port) => ({
+        port,
+        available: await plan.isPortAvailable(port),
+      })),
+    )
+  ).filter(({ available }) => !available);
+  if (unavailablePorts.length) {
+    throw new Error(
+      `Rehearsal setup ports became occupied after the preview (${unavailablePorts.map(({ port }) => port).join(", ")}); rerun setup to choose another local port block.`,
+    );
+  }
+  for (const file of plan.files) await assertCreateTargetAvailable(file);
+  const gitignore = plan.files.find((file) => file.path === GITIGNORE_PATH);
+  if (gitignore?.action === "update") {
+    const current = await readOptionalFile(gitignore.absolutePath);
+    if (current !== gitignore.originalContent) {
+      throw new Error(
+        ".gitignore changed after the setup preview; rerun rehearsal setup before writing.",
+      );
+    }
+  }
+  for (const file of plan.files.filter(
+    (entry) => entry.action !== "unchanged",
+  )) {
+    await mkdir(dirname(file.absolutePath), { recursive: true, mode: 0o700 });
+    await writeFile(file.absolutePath, file.content, {
+      flag: file.action === "create" ? "wx" : "w",
+      mode: file.mode,
+    });
+  }
+  return {
+    projectRoot: plan.projectRoot,
+    files: plan.files.map((file) => ({
+      path: relative(plan.projectRoot, file.absolutePath),
+      action: file.action,
+    })),
+  };
+};
+
+export const summarizeRehearsalSetup = (plan, { mode }) => ({
+  mode,
+  project: plan.project,
+  projectId: plan.projectId,
+  applicationUrl: plan.applicationUrl,
+  detected: plan.detected,
+  ports: {
+    api: plan.ports.api,
+    database: plan.ports.database,
+    studio: plan.ports.studio,
+  },
+  files: plan.files.map((file) => ({ path: file.path, action: file.action })),
+  safety: plan.safety,
+  nextAction:
+    mode === "written"
+      ? "Review the generated commands and sanitization policy path, then run rehearsal doctor."
+      : "Review this plan, then rerun rehearsal setup --write to create it.",
+});

package/scripts/operations/database/manage_rehearsal_database.mjs

@@ -44,10 +44,12 @@ import {
 } from "../../lib/rehearsal/migration_history.mjs";
 import { loadRehearsalConfig } from "../../lib/rehearsal/configuration.mjs";
 import { readRehearsalServiceEnvironment } from "../../lib/rehearsal/service_environment.mjs";
+import { readBoundRuntimeSanitizationPolicy } from "../../lib/rehearsal/sanitization_policy.mjs";
 import {
   captureLocalPublicSchema,
   compareProductionSchemaDumps,
 } from "../../lib/rehearsal/schema_snapshot.mjs";
+import { formatCount } from "../../lib/rehearsal/human_output.mjs";
 
 const repositoryRoot = process.cwd();
 const loadedConfiguration = await loadRehearsalConfig({
@@ -443,11 +445,15 @@ const configureProjectRuntime = ({ environment, baseline }) => {
 };
 
 const readActive = async () => {
-  const [baseline, paths, manifest] = await Promise.all([
+  const [baseline, paths, policyBytes] = await Promise.all([
     verifyActiveBaseline({ artifactRoot }),
     resolveActiveBaselinePaths({ artifactRoot }),
-    readFile(manifestPath, "utf8").then(JSON.parse),
+    readFile(manifestPath),
   ]);
+  const manifest = readBoundRuntimeSanitizationPolicy({
+    bytes: policyBytes,
+    expectedSha256: baseline.sanitizationPolicySha256,
+  });
   return { baseline, paths, manifest };
 };
 
@@ -496,7 +502,7 @@ const resetRuntime = async () => {
       { mode: 0o600 },
     );
     console.log(
-      `Restored Rehearsal baseline ${active.baseline.generationId}: ${active.baseline.rowCount} rows across ${Object.keys(active.baseline.tableCounts).length} tables.`,
+      `Restored Rehearsal baseline ${active.baseline.generationId}: ${formatCount(active.baseline.rowCount, "row")} across ${formatCount(Object.keys(active.baseline.tableCounts).length, "table")}.`,
     );
     console.log(projectRuntime.message);
     return environment;
@@ -621,7 +627,7 @@ const verifyRuntime = async () => {
     }
   }
   console.log(
-    `Verified Rehearsal runtime ${baseline.generationId}: immutable baseline and migration history are valid with ${migrationComparison.candidates.length} applied candidate migrations. Runtime rows may differ from the baseline until the next reset.`,
+    `Verified Rehearsal runtime ${baseline.generationId}: immutable baseline and migration history are valid with ${formatCount(migrationComparison.candidates.length, "applied candidate migration")}. Runtime rows may differ from the baseline until the next reset.`,
   );
   if (projectVerification) console.log(projectVerification.message);
   return { baseline, candidateReceipt, migrationComparison };
@@ -652,7 +658,7 @@ const migrateRuntime = async () => {
     return receipt;
   }
   console.log(
-    `Candidate migrations (${receipt.candidateSha256}): ${receipt.candidates.map((candidate) => candidate.filename).join(", ")}`,
+    `${receipt.candidates.length === 1 ? "Candidate migration" : "Candidate migrations"} (${receipt.candidateSha256}): ${receipt.candidates.map((candidate) => candidate.filename).join(", ")}`,
   );
   const confirmation = process.argv
     .find((argument) => argument.startsWith("--confirm-candidates="))
@@ -707,7 +713,7 @@ const migrateRuntime = async () => {
       { mode: 0o600 },
     );
     console.log(
-      `Applied ${receipt.candidates.length} confirmed candidate migrations to the disposable Rehearsal runtime.`,
+      `Applied ${formatCount(receipt.candidates.length, "confirmed candidate migration")} to the disposable Rehearsal runtime.`,
     );
     return receipt;
   } catch (error) {