@rehearsal-db/core 0.1.0-beta.1

package/docs/troubleshooting.md

@@ -0,0 +1,50 @@
+# Troubleshooting
+
+## Doctor says Docker is unavailable
+
+Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
+Restarting the computer is rarely necessary.
+
+## A port is already in use
+
+Choose three unique non-privileged ports in config and mirror them in the dedicated
+Supabase config. Do not stop an unrelated database to make the default ports fit.
+
+## Baseline checksum mismatch
+
+Do not edit the checksum or manifest. The artifact is no longer the reviewed input.
+Rebuild the generation through the project-owned baseline process.
+
+## Historical migration changed
+
+Restore the exact represented bytes or intentionally build and review a new baseline.
+Renaming edited history into the candidate suffix does not repair lineage.
+
+## Candidate confirmation mismatch
+
+Run `rehearsal candidates` again. Review every filename, then confirm the new digest only
+if the exact set is intended.
+
+## Migration failed
+
+The runtime is untrusted and should be removed automatically. Correct the candidate SQL,
+rerun doctor and candidates, then execute with the new digest.
+
+## Application proof failed
+
+Run the project proof directly against the generated local environment. Fix the app,
+adapter, fixture expectation, or migration; do not weaken the proof to obtain a pass.
+
+## Local authentication fails
+
+Confirm the provider is enabled in the dedicated local Supabase config, the allowlisted
+service environment file exists with owner-only permissions, and the provider callback
+is the local Auth callback. Do not paste provider secrets into config or terminal output.
+
+## Runtime changes disappeared
+
+`reset` deliberately restores the immutable baseline. `stop` should preserve Docker
+state, but runtime removal or a failed migration discards untrusted state.
+
+Use `--debug` only after ordinary output is insufficient. Diagnostics are redacted, but
+you should still review output before sharing it publicly.

package/docs/tutorial.md

@@ -0,0 +1,96 @@
+# Tutorial: rehearse a migration in a new project
+
+This walkthrough uses a fictional `widgets` application. It demonstrates the complete
+consumer workflow without importing private or hosted data.
+
+## Create the application migration history
+
+The project begins with one historical migration:
+
+```sql
+create table public.widgets (
+  id bigint generated always as identity primary key,
+  name text not null
+);
+```
+
+Place it at `supabase/migrations/20260101000000_create_widgets.sql`. Add a second,
+candidate migration:
+
+```sql
+alter table public.widgets add column description text;
+```
+
+Place that at `supabase/migrations/20260101000100_add_widget_description.sql`.
+
+## Configure the isolated runtime
+
+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.
+
+Keep the generated `.rehearsal` directory ignored. It contains local artifacts and
+runtime state, not source code.
+
+## Build a synthetic baseline
+
+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.
+
+Write the safe rows to `rehearsal/synthetic-data.ndjson` and the exact represented
+statements to `rehearsal/migration-ledger.json`, then run:
+
+```bash
+npx rehearsal baseline create \
+  --records=rehearsal/synthetic-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json
+```
+
+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.
+
+## Prove planning is non-mutating
+
+```bash
+npx rehearsal doctor
+npx rehearsal explain
+npx rehearsal run --dry-run
+npx rehearsal candidates --json
+```
+
+`explain` and `run --dry-run` return the same execution plan. At this point no local
+database has been restored.
+
+## Run and inspect
+
+Copy the exact digest from `candidates`:
+
+```bash
+npx rehearsal run --confirm-candidates=<sha256>
+npx rehearsal inspect migrations
+npx rehearsal status
+```
+
+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.
+
+## Prove failure behavior
+
+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.
+
+Then restore the valid migration set and rerun:
+
+```bash
+npx rehearsal reset
+npx rehearsal verify
+npx rehearsal stop
+```
+
+That cycle—plan, confirm exact bytes, run, exercise the app, reset—is the normal Rehearsal
+workflow.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@rehearsal-db/core",
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "description": "Safely rehearse Supabase migrations against sanitized, production-shaped PostgreSQL data.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
+  },
+  "homepage": "https://github.com/Ddupasquier/rehearsal-db#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": true
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "bin": {
+    "rehearsal": "scripts/operations/rehearsal/rehearsal_cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./scripts/lib/rehearsal/configuration.d.mts",
+      "import": "./scripts/lib/rehearsal/configuration.mjs"
+    },
+    "./baseline": "./scripts/lib/rehearsal/baseline_artifact.mjs",
+    "./baseline-builder": "./scripts/lib/rehearsal/baseline_builder.mjs",
+    "./diagnostics": "./scripts/lib/rehearsal/diagnostics.mjs",
+    "./migrations": "./scripts/lib/rehearsal/migration_history.mjs",
+    "./process-environment": "./scripts/lib/rehearsal/process_environment.mjs",
+    "./schema": "./scripts/lib/rehearsal/schema_snapshot.mjs",
+    "./service-environment": "./scripts/lib/rehearsal/service_environment.mjs"
+  },
+  "files": [
+    "scripts/lib/environment/local_supabase.mjs",
+    "scripts/lib/rehearsal",
+    "scripts/operations/database/manage_rehearsal_database.mjs",
+    "scripts/operations/rehearsal/rehearsal_cli.mjs",
+    "docs/*.md",
+    "README.md",
+    "BENCHMARKS.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "COMPATIBILITY.md",
+    "SUPPORT.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "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",
+    "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 .",
+    "format:check": "prettier --check .",
+    "package:audit": "node scripts/operations/rehearsal/audit_package.mjs"
+  },
+  "keywords": [
+    "postgresql",
+    "supabase",
+    "migration",
+    "testing",
+    "database"
+  ],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "prettier": "^3.9.6",
+    "vitest": "^4.1.10"
+  }
+}

package/scripts/lib/environment/local_supabase.mjs

@@ -0,0 +1,197 @@
+/**
+ * Purpose: Start and inspect local-only Supabase workdirs without inheriting hosted
+ * credentials. Do not run directly; this module is reusable script infrastructure.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createCleanProcessEnvironment } from "../rehearsal/process_environment.mjs";
+
+export const parseSupabaseStatusEnvironment = (output) => {
+  const values = {};
+  for (const line of output.split("\n")) {
+    const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
+    if (!match) continue;
+    let value = match[2].trim();
+    if (value.startsWith('"') && value.endsWith('"')) value = JSON.parse(value);
+    values[match[1]] = value;
+  }
+  return values;
+};
+
+export const runLocalCommand = (
+  command,
+  args,
+  {
+    capture = false,
+    cwd = process.cwd(),
+    input,
+    environment = {},
+    maxBuffer = 16 * 1024 * 1024,
+  } = {},
+) => {
+  const shouldPipe = capture || input !== undefined;
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    env: createCleanProcessEnvironment({ overrides: environment }),
+    input,
+    maxBuffer,
+    stdio: shouldPipe ? ["pipe", "pipe", "pipe"] : "inherit",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = [result.stdout, result.stderr]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    throw new Error(
+      `${command} ${args.join(" ")} failed${detail ? `:\n${detail}` : "."}`,
+    );
+  }
+  return result.stdout ?? "";
+};
+
+export const localCommandSucceeds = (
+  command,
+  args,
+  { cwd = process.cwd(), environment = {} } = {},
+) =>
+  spawnSync(command, args, {
+    cwd,
+    env: createCleanProcessEnvironment({ overrides: environment }),
+    stdio: "ignore",
+  }).status === 0;
+
+export const ensureLocalContainerRuntime = ({ cwd = process.cwd() } = {}) => {
+  if (localCommandSucceeds("docker", ["info"], { cwd })) return;
+  if (localCommandSucceeds("colima", ["version"], { cwd })) {
+    runLocalCommand(
+      "colima",
+      ["start", "--cpu", "4", "--memory", "4", "--disk", "40"],
+      { cwd },
+    );
+  }
+  if (!localCommandSucceeds("docker", ["info"], { cwd })) {
+    throw new Error(
+      "A local Docker-compatible runtime is required. Install Docker or Colima, then rerun the command.",
+    );
+  }
+};
+
+const withWorkdir = (args, workdir) =>
+  workdir ? [...args, "--workdir", workdir] : args;
+
+export const readLocalSupabaseEnvironment = ({
+  cwd,
+  workdir,
+  environment = {},
+} = {}) => {
+  const output = runLocalCommand(
+    "supabase",
+    withWorkdir(["status", "-o", "env"], workdir),
+    { capture: true, cwd, environment },
+  );
+  const values = parseSupabaseStatusEnvironment(output);
+  const localEnvironment = {
+    apiUrl: values.API_URL,
+    publishableKey: values.PUBLISHABLE_KEY ?? values.ANON_KEY,
+    serviceRoleKey: values.SERVICE_ROLE_KEY ?? values.SECRET_KEY,
+    studioUrl: values.STUDIO_URL,
+  };
+  for (const [label, value] of [
+    ["API URL", localEnvironment.apiUrl],
+    ["publishable key", localEnvironment.publishableKey],
+    ["service-role key", localEnvironment.serviceRoleKey],
+  ]) {
+    if (!value) throw new Error(`Local Supabase status omitted its ${label}.`);
+  }
+  const hostname = new URL(localEnvironment.apiUrl).hostname;
+  if (!["127.0.0.1", "::1", "localhost"].includes(hostname)) {
+    throw new Error("Refusing to use a non-loopback Supabase status target.");
+  }
+  return localEnvironment;
+};
+
+export const startLocalSupabase = ({
+  cwd,
+  workdir,
+  exclude = [],
+  environment = {},
+  applyMigrations = true,
+} = {}) => {
+  ensureLocalContainerRuntime({ cwd });
+  const startArguments = withWorkdir(
+    ["start", ...(exclude.length ? ["--exclude", exclude.join(",")] : [])],
+    workdir,
+  );
+  runLocalCommand("supabase", startArguments, {
+    capture: true,
+    cwd,
+    environment,
+  });
+  if (applyMigrations) {
+    runLocalCommand(
+      "supabase",
+      withWorkdir(["migration", "up", "--local"], workdir),
+      { capture: true, cwd, environment },
+    );
+  }
+  return readLocalSupabaseEnvironment({ cwd, workdir, environment });
+};
+
+export const stopLocalSupabase = ({ cwd, workdir, environment = {} } = {}) => {
+  if (!localCommandSucceeds("docker", ["info"], { cwd })) return;
+  runLocalCommand("supabase", withWorkdir(["stop"], workdir), {
+    cwd,
+    environment,
+  });
+};
+
+export const removeLocalSupabaseProjectResources = ({
+  cwd = process.cwd(),
+  projectId,
+} = {}) => {
+  if (!/^[a-z0-9][a-z0-9-]{1,62}$/u.test(projectId ?? "")) {
+    throw new Error(
+      "Refusing to remove local Supabase resources without an exact safe project id.",
+    );
+  }
+  const label = `com.supabase.cli.project=${projectId}`;
+  const list = (resource, format) =>
+    runLocalCommand(
+      "docker",
+      [resource, "ls", "--filter", `label=${label}`, "--format", format],
+      { capture: true, cwd },
+    )
+      .split("\n")
+      .map((value) => value.trim())
+      .filter(Boolean);
+  const containers = runLocalCommand(
+    "docker",
+    ["ps", "--all", "--filter", `label=${label}`, "--format", "{{.ID}}"],
+    { capture: true, cwd },
+  )
+    .split("\n")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (containers.length) {
+    runLocalCommand("docker", ["rm", "--force", ...containers], {
+      capture: true,
+      cwd,
+    });
+  }
+  const volumes = list("volume", "{{.Name}}");
+  if (volumes.length) {
+    runLocalCommand("docker", ["volume", "rm", "--force", ...volumes], {
+      capture: true,
+      cwd,
+    });
+  }
+  const networks = list("network", "{{.ID}}");
+  if (networks.length) {
+    runLocalCommand("docker", ["network", "rm", ...networks], {
+      capture: true,
+      cwd,
+    });
+  }
+};