@rehearsal-db/core 0.1.0-beta.4 → 0.1.0-beta.6

package/docs/tutorial.md

@@ -1,96 +1,107 @@
-# Tutorial: rehearse a migration in a new project
+# Safe hands-on tutorial
 
-This walkthrough uses a fictional `widgets` application. It demonstrates the complete
-consumer workflow without importing private or hosted data.
+This tutorial runs a complete PostgreSQL rehearsal in a temporary fictional project. It
+does not use your application, production data, or a hosted database.
 
-## Create the application migration history
+Allow about five minutes. You need Node.js 24 and a running Docker-compatible engine.
 
-The project begins with one historical migration:
+## 1. Prepare Rehearsal
 
-```sql
-create table public.widgets (
-  id bigint generated always as identity primary key,
-  name text not null
-);
+If you do not already have this repository, clone it:
+
+```bash
+git clone https://github.com/Ddupasquier/rehearsal-db.git
+cd rehearsal-db
 ```
 
-Place it at `supabase/migrations/20260101000000_create_widgets.sql`. Add a second,
-candidate migration:
+Then run:
 
-```sql
-alter table public.widgets add column description text;
+```bash
+npm ci --ignore-scripts
+docker pull postgres:17-alpine
 ```
 
-Place that at `supabase/migrations/20260101000100_add_widget_description.sql`.
+If you already have this repository open, use that checkout.
 
-## Configure the isolated runtime
+## 2. Make a temporary project
 
-Run `npx rehearsal init --write`, then edit the result. Give the runtime unique local
-ports and a unique project ID. Its `rehearsalConfig` must point at a dedicated, unlinked
-Supabase config. Never reuse a hosted project reference or production environment file.
+From the Rehearsal repository root, run this block exactly:
 
-Keep the generated `.rehearsal` directory ignored. It contains local artifacts and
-runtime state, not source code.
+```bash
+rehearsal_repo=$PWD
+tutorial_dir=$(mktemp -d)
+cp -R tests/fixtures/postgresql-project "$tutorial_dir/app"
+cd "$tutorial_dir/app"
+npm install --ignore-scripts --no-save "$rehearsal_repo"
+```
 
-## Build a synthetic baseline
+The temporary project contains:
 
-The baseline contains the historical migration bundle, a one-row sanitized data stream,
-and a manifest binding their checksums. Baseline construction is deliberately separate
-from runtime execution: the application owns extraction and policy; the engine accepts
-only a completed, verified artifact.
+- one historical migration that creates a `widgets` table;
+- one candidate migration that adds a `description` column;
+- one synthetic row;
+- a reviewed sanitization policy;
+- an application proof that checks the migrated database.
 
-Write the safe rows to `rehearsal/synthetic-data.ndjson` and the exact represented
-statements to `rehearsal/migration-ledger.json`, then run:
+## 3. Create the baseline
+
+Open the guide:
 
 ```bash
-npx rehearsal baseline create \
-  --records=rehearsal/synthetic-data.ndjson \
-  --ledger=rehearsal/migration-ledger.json
+npx rehearsal
 ```
 
-For an executable sample, inspect `tests/fixtures/rehearsal-project` in the repository.
-The maintained fixture proof invokes this public command through the packed npm tarball
-and never contacts a hosted service.
+The project begins at Stage 3 of 4. Choose **Create the baseline**. Accept the detected
+record and ledger files, review the summary, then confirm creation.
 
-## Prove planning is non-mutating
+The project should advance to Stage 4 of 4 with every item checked.
 
-```bash
-npx rehearsal doctor
-npx rehearsal explain
-npx rehearsal run --dry-run
-npx rehearsal candidates --json
+## 4. Run the migration
+
+Choose **Run a rehearsal**. The guide should show exactly one candidate:
+
+```text
+20260101000100_add_widget_description.sql
 ```
 
-`explain` and `run --dry-run` return the same execution plan. At this point no local
-database has been restored.
+Confirm it. Rehearsal creates a loopback-only PostgreSQL container, restores the baseline,
+applies the candidate, and runs the fixture proof.
 
-## Run and inspect
+Success ends with an application-proof message and suggests exercising the local
+application before verification.
 
-Copy the exact digest from `candidates`:
+## 5. Try the runtime commands
+
+Exit the guide, then run:
 
 ```bash
-npx rehearsal run --confirm-candidates=<sha256>
-npx rehearsal inspect migrations
 npx rehearsal status
+npx rehearsal verify
+npx rehearsal reset
+npx rehearsal stop
+npx rehearsal discard
 ```
 
-The historical migration should be `represented_by_baseline`; the description migration
-should be `applied_to_current_runtime`. Test normal creates, updates, and deletes through
-your local application. They affect only this disposable database.
+`discard` removes only the labeled tutorial container and volume. The temporary project
+directory remains on disk and can be deleted when you no longer need it.
+
+## What you proved
 
-## Prove failure behavior
+You used the same packaged CLI a normal project installs. Rehearsal verified the baseline,
+approved an exact migration, ran it in a disposable database, tested the result, and
+cleaned up only its own runtime.
 
-Add a timestamped migration containing invalid SQL, rerun `candidates`, and use its new
-digest. The command must fail with `migration_candidate_failure`, remove the untrusted
-runtime, and never produce a successful receipt.
+Next, follow [Getting started](getting-started.md) in your own project. Start with synthetic
+rows until the workflow and application proof are reliable.
 
-Then restore the valid migration set and rerun:
+## Supabase check
+
+If Supabase CLI 2.117.0 is installed, the repository also has a fully automated Supabase
+proof:
 
 ```bash
-npx rehearsal reset
-npx rehearsal verify
-npx rehearsal stop
+cd "$rehearsal_repo"
+npm run test:fixture
 ```
 
-That cycle—plan, confirm exact bytes, run, exercise the app, reset—is the normal Rehearsal
-workflow.
+The PostgreSQL equivalent is `npm run test:fixture:postgresql`.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "private": false,
-  "description": "Safely rehearse Supabase migrations against sanitized, production-shaped PostgreSQL data.",
+  "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
@@ -39,6 +39,7 @@
   "files": [
     "scripts/lib/environment/local_supabase.mjs",
     "scripts/lib/rehearsal",
+    "scripts/lib/runtime",
     "scripts/operations/database/manage_rehearsal_database.mjs",
     "scripts/operations/rehearsal/rehearsal_cli.mjs",
     "docs/*.md",
@@ -55,6 +56,7 @@
     "test:unit": "vitest run tests/scripts",
     "test:docs": "vitest run tests/contracts/documentationCommands.test.mjs",
     "test:fixture": "node scripts/operations/rehearsal/prove_independent_fixture.mjs",
+    "test:fixture:postgresql": "node scripts/operations/rehearsal/prove_postgresql_fixture.mjs",
     "check": "npm run check:syntax && npm run test && npm run format:check && npm run package:audit",
     "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
     "format": "prettier --write .",
@@ -75,6 +77,6 @@
   "devDependencies": {
     "@lydell/node-pty": "^1.2.0-beta.15",
     "prettier": "^3.9.6",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.2"
   }
 }

package/scripts/lib/rehearsal/baseline_preparation.mjs

@@ -4,13 +4,14 @@
  */
 
 import { createReadStream } from "node:fs";
-import { access, mkdir, open, readFile } from "node:fs/promises";
+import { access, lstat, mkdir, open, readFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { loadRehearsalConfig } from "./configuration.mjs";
 import { buildMigrationLedgerInventory } from "./migration_history.mjs";
 
 const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
+const storageBucketPattern = /^[a-z0-9][a-z0-9.-]{0,99}$/u;
 
 const resolveProjectInput = (projectRoot, value, label) => {
   if (typeof value !== "string" || value.trim() === "") {
@@ -37,6 +38,19 @@ const pathExists = (path) =>
       throw error;
     });
 
+const assertRegularInput = async (path, label) => {
+  let stats;
+  try {
+    stats = await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`${label} does not exist.`);
+    throw error;
+  }
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(`${label} must be a regular project-local file.`);
+  }
+};
+
 const inspectSyntheticRecords = async (path) => {
   const tables = new Map();
   let rowCount = 0;
@@ -97,6 +111,120 @@ const inspectSyntheticRecords = async (path) => {
   };
 };
 
+const inspectAssetManifest = async (path, projectRoot) => {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    throw new Error("Storage asset manifest contains invalid JSON.", {
+      cause: error,
+    });
+  }
+  if (!Array.isArray(manifest)) {
+    throw new Error("Storage asset manifest must be a JSON array.");
+  }
+  const destinations = new Set();
+  for (const [index, asset] of manifest.entries()) {
+    if (
+      !asset ||
+      typeof asset !== "object" ||
+      Array.isArray(asset) ||
+      !storageBucketPattern.test(asset.bucket ?? "") ||
+      typeof asset.objectPath !== "string" ||
+      !asset.objectPath ||
+      asset.objectPath
+        .split("/")
+        .some((segment) => !segment || segment === "." || segment === "..") ||
+      typeof asset.file !== "string" ||
+      !asset.file.trim() ||
+      (asset.contentType !== undefined && typeof asset.contentType !== "string")
+    ) {
+      throw new Error(
+        `Storage asset manifest entry ${index + 1} has an invalid shape.`,
+      );
+    }
+    const destination = `${asset.bucket}/${asset.objectPath}`;
+    if (destinations.has(destination)) {
+      throw new Error(`Duplicate Storage asset destination: ${destination}.`);
+    }
+    destinations.add(destination);
+    const assetFile = resolveProjectInput(
+      projectRoot,
+      asset.file,
+      `Storage asset file in entry ${index + 1}`,
+    );
+    await assertRegularInput(
+      assetFile,
+      `Storage asset file in entry ${index + 1}`,
+    );
+  }
+  return { assetCount: manifest.length };
+};
+
+export const inspectBaselineInputFiles = async ({
+  projectRoot = process.cwd(),
+  configPath,
+  recordsPath,
+  ledgerPath,
+  assetsPath,
+}) => {
+  const loaded = await loadRehearsalConfig({ projectRoot, configPath });
+  const records = resolveProjectInput(
+    loaded.projectRoot,
+    recordsPath,
+    "Synthetic records path",
+  );
+  const ledger = resolveProjectInput(
+    loaded.projectRoot,
+    ledgerPath,
+    "Migration ledger path",
+  );
+  const assets = assetsPath
+    ? resolveProjectInput(
+        loaded.projectRoot,
+        assetsPath,
+        "Storage asset manifest path",
+      )
+    : undefined;
+  await Promise.all([
+    assertRegularInput(records, "Synthetic records path"),
+    assertRegularInput(ledger, "Migration ledger path"),
+    ...(assets
+      ? [assertRegularInput(assets, "Storage asset manifest path")]
+      : []),
+  ]);
+  let ledgerRows;
+  try {
+    ledgerRows = JSON.parse(await readFile(ledger, "utf8"));
+  } catch (error) {
+    throw new Error("Migration ledger contains invalid JSON.", {
+      cause: error,
+    });
+  }
+  const [inspection, assetInspection] = await Promise.all([
+    inspectSyntheticRecords(records),
+    assets
+      ? inspectAssetManifest(assets, loaded.projectRoot)
+      : Promise.resolve({ assetCount: 0 }),
+  ]);
+  const migrationHistory = buildMigrationLedgerInventory(
+    ledgerRows,
+    "Synthetic migration ledger",
+  );
+  return {
+    projectRoot: loaded.projectRoot,
+    recordsPath: relative(loaded.projectRoot, records),
+    ledgerPath: relative(loaded.projectRoot, ledger),
+    assetsPath: assets ? relative(loaded.projectRoot, assets) : undefined,
+    migrationHistory,
+    migrationCutoff: migrationHistory.at(-1).version,
+    migrationCount: migrationHistory.length,
+    rowCount: inspection.rowCount,
+    tables: inspection.tables,
+    assetCount: assetInspection.assetCount,
+  };
+};
+
 const renderPolicyDraft = ({ migrationCutoff, tables }) =>
   `${JSON.stringify(
     {
@@ -127,43 +255,30 @@ export const planBaselinePreparation = async ({
   ledgerPath,
 }) => {
   const loaded = await loadRehearsalConfig({ projectRoot, configPath });
-  const records = resolveProjectInput(
-    loaded.projectRoot,
+  const inspection = await inspectBaselineInputFiles({
+    projectRoot: loaded.projectRoot,
+    configPath,
     recordsPath,
-    "Synthetic records path",
-  );
-  const ledger = resolveProjectInput(
-    loaded.projectRoot,
     ledgerPath,
-    "Migration ledger path",
-  );
-  const [inspection, ledgerRows] = await Promise.all([
-    inspectSyntheticRecords(records),
-    readFile(ledger, "utf8").then(JSON.parse),
-  ]);
-  const migrationHistory = buildMigrationLedgerInventory(
-    ledgerRows,
-    "Synthetic migration ledger",
-  );
+  });
   const destination = loaded.paths.sanitizationPolicy;
   if (await pathExists(destination)) {
     throw new Error(
       `Rehearsal baseline preparation will not overwrite ${relative(loaded.projectRoot, destination)}.`,
     );
   }
-  const migrationCutoff = migrationHistory.at(-1).version;
   return {
     projectRoot: loaded.projectRoot,
     destination,
     destinationRelative: relative(loaded.projectRoot, destination),
-    recordsPath: relative(loaded.projectRoot, records),
-    ledgerPath: relative(loaded.projectRoot, ledger),
-    migrationCutoff,
-    migrationCount: migrationHistory.length,
+    recordsPath: inspection.recordsPath,
+    ledgerPath: inspection.ledgerPath,
+    migrationCutoff: inspection.migrationCutoff,
+    migrationCount: inspection.migrationCount,
     rowCount: inspection.rowCount,
     tables: inspection.tables,
     content: renderPolicyDraft({
-      migrationCutoff,
+      migrationCutoff: inspection.migrationCutoff,
       tables: inspection.tables,
     }),
   };

package/scripts/lib/rehearsal/configuration.d.mts

@@ -3,7 +3,7 @@ export type RehearsalConfigVersion = 1;
 export interface RehearsalConfig {
   schemaVersion: RehearsalConfigVersion;
   project: { name: string };
-  supabase: {
+  supabase?: {
     workdir: string;
     migrationDirectory: string;
     rehearsalConfig: string;
@@ -11,6 +11,13 @@ export interface RehearsalConfig {
     serviceEnvironmentFile?: string;
     serviceEnvironmentVariables?: string[];
   };
+  postgresql?: {
+    migrationDirectory: string;
+    runtimeWorkdir?: string;
+    image?: string;
+    database?: string;
+    user?: string;
+  };
   baseline: {
     artifactDirectory?: string;
     sanitizationPolicy: string;
@@ -22,11 +29,12 @@ export interface RehearsalConfig {
     runtimeAdapter?: string;
   };
   runtime: {
+    target?: "supabase" | "postgresql";
     applicationUrl?: string;
     projectId?: string;
-    apiPort: number;
+    apiPort?: number;
     databasePort: number;
-    studioPort: number;
+    studioPort?: number;
   };
   safety?: {
     allowedHosts?: string[];
@@ -58,6 +66,13 @@ export declare const renderDetectedConfig: (
     ports?: { api: number; database: number; studio: number };
   },
 ) => string;
+export declare const renderDetectedPostgresqlConfig: (
+  detected: unknown,
+  options?: {
+    applicationUrl?: string;
+    databasePort?: number;
+  },
+) => string;
 export declare const SANITIZATION_ACTIONS: Readonly<{
   KEEP: "KEEP";
   PSEUDONYMIZE: "PSEUDONYMIZE";