@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.11

package/docs/standalone-workflow.md

@@ -0,0 +1,109 @@
+# Standalone workflow contract
+
+Rehearsal's normal commands remain local-only. `run`, `start`, `reset`,
+`migrate`, `verify`, and `cleanup` never receive source credentials and never
+connect to a hosted database.
+
+The optional preparation workflow is a separate security boundary. It has
+three deliberately separate phases:
+
+1. `source plan` reads declarations and produces a redacted, exact plan.
+2. `source apply` requires the plan digest and source-owner credentials from a
+   named environment variable. It creates only the declared, time-limited
+   reader and export surface.
+3. `refresh` uses that reader in a read-only repeatable-read transaction, builds
+   privately, activates only after verification, resets the local runtime, and applies
+   reviewed retention. `baseline refresh` is the lower-level baseline-only form.
+
+`source retire` has its own preview and digest. It removes only the exact
+reader and export objects Rehearsal recorded. It never searches for similarly
+named roles or removes unrelated grants.
+
+## What belongs in declarations
+
+Projects declare application meaning; Rehearsal executes it. Declarations may
+name:
+
+- approved source relations and columns;
+- whether rows are approved public data or belong to one explicitly approved
+  owner;
+- privacy actions and bounded transformation recipes;
+- hashed server-side owner bindings and explicit approved/other-owner branches;
+- bounded nested JSON objects and arrays with required/optional fields;
+- licensed or consented Storage buckets and prefixes;
+- schema and extension prerequisites;
+- local identities and reference locations;
+- ordinary application commands and observable proof expectations.
+
+Declarations cannot contain JavaScript callbacks, SQL fragments, passwords,
+tokens, production URLs, or automatic consent decisions. Unknown fields,
+tables, columns, recipes, JSON keys, and target identities fail closed.
+
+## Credential separation
+
+Provisioning, extraction, asset, provider, and local-runtime credentials are
+separate. A declaration contains only the name of an environment variable or
+owner-only secret file. Rehearsal never puts credential values in command-line
+arguments, reports, baselines, receipts, or a launched application.
+
+The current workflow creates and verifies its own temporary PostgreSQL reader. An
+externally provisioned reader is not yet accepted because Rehearsal cannot currently
+prove that reader's complete scope and retirement behavior.
+
+## Snapshot and privacy guarantees
+
+Database schema, migration evidence, and selected rows are read in one
+read-only repeatable-read PostgreSQL transaction. Rehearsal rechecks the source
+identity and migration evidence before commit. Rows stream in bounded batches;
+record bodies never appear in progress or error output.
+
+Storage objects do not share the database transaction guarantee. Their inventory records
+size and version metadata; transfer requires that version, verifies the exact byte count,
+and records a SHA-256 in the immutable baseline. Transfer refuses an object that changes,
+exceeds its declared limit, or falls outside an approved bucket and prefix.
+
+Privacy policy version 2 is executable without project sanitizer code. It
+supports exact keep, exclusion, keyed pseudonyms, constants, and a small set of
+documented derivations. Policies classify every selected field and supported
+nested JSON key. A new or unknown field blocks refresh until the policy is
+reviewed again.
+
+The pseudonym key is an owner-only local secret. It is not stored in the
+baseline or source control. Receipts bind the policy bytes, schema shape,
+source scope, migration evidence, and key fingerprint without storing the key
+or source identifiers.
+
+## Restore, identities, and applications
+
+Restore performs only supported declarative prerequisites. Application schema
+changes remain immutable migration files; configuration is never an arbitrary
+privileged-SQL escape hatch.
+
+Local identities never reuse production sessions, refresh tokens, password
+hashes, provider secrets, or MFA material. An approved provider association is
+performed inside the local runtime and must match the reviewed receipt.
+
+Rehearsal launches ordinary project commands with a minimal environment and
+generated local connection files. It verifies every configured dependency
+before launch, owns only the child process group it starts, and does not claim
+to provide an operating-system firewall.
+
+Proofs require explicit positives and negatives. A process starting, a non-5xx
+response, an empty 200, a 401, or a 404 cannot satisfy a declared positive.
+Reports distinguish engine readiness, dependency readiness, proof completion,
+and provider behavior that was directly observed by a person.
+
+## Failure and upgrade behavior
+
+- Failed, interrupted, changed-policy, low-disk, or drifted refreshes leave the
+  prior active baseline and any edited runtime untouched.
+- Setup and upgrades preview exact file changes and never overwrite a reviewed
+  policy, config, baseline, or local edit silently.
+- Reset, discard, and cleanup operate only on purpose-created Rehearsal
+  resources and retain their existing exact-preview protections.
+- Rehearsal does not make legal, consent, licensing, backup, disaster-recovery,
+  universal-database, or OS-firewall guarantees.
+
+The final acceptance gate uses the exact packed or published artifact in clean
+Supabase and PostgreSQL consumers. Consumer integration code is removed only
+after that replacement is proved and the removal is separately approved.

package/docs/troubleshooting.md

@@ -1,14 +1,107 @@
 # Troubleshooting
 
+Start with:
+
+```bash
+npx rehearsal doctor
+```
+
+Doctor names each missing or unsafe item. If you still need help, run
+`npx rehearsal support`, review the report, and attach it to a GitHub issue.
+
+## `npx rehearsal` cannot find the command
+
+Confirm you are in the project directory and install the beta locally:
+
+```bash
+npm install --save-dev @rehearsal-db/core@beta
+npx rehearsal --help
+```
+
+Do not use `sudo` or require a global install.
+
+## Installation did not create `rehearsal.config.mjs`
+
+Rehearsal intentionally skips automatic creation when install scripts are disabled, the
+install is global or temporary, or more than one workspace application could own the
+config. From the intended application directory, run:
+
+```bash
+npx rehearsal
+```
+
+Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this guided path;
+automatic root generation is currently tested with npm. An existing supported config is
+kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`.
+
+## Setup says Node.js 24 is required
+
+Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
+the current shell before installing or running it. With nvm:
+
+```bash
+nvm install 24
+nvm use 24
+node --version
+```
+
+Then reinstall Rehearsal in the consuming project. The guided CLI checks this before it
+writes setup files.
+
 ## Doctor says Docker is unavailable
 
 Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
 Restarting the computer is rarely necessary.
 
+## Docker or Colima is out of disk space
+
+Preview what Rehearsal can safely remove:
+
+```bash
+npx rehearsal cleanup --include-images
+```
+
+Review the list, then add `--write` and the printed `--confirm-cleanup` digest. Rehearsal
+keeps the newest Supabase image for each service, refuses images used by any running or
+stopped container, and never runs a global Docker or volume prune. Add
+`--include-runtime` only when this project's disposable database may also be removed.
+
+For example, copy the full digest from your preview:
+
+```bash
+npx rehearsal cleanup --include-images --write --confirm-cleanup=PASTE_FULL_DIGEST_HERE
+```
+
+For Colima, disk capacity belongs to the user rather than the project. Increase it with
+`colima stop` followed by a larger `colima start --disk <GiB>` value. Rehearsal respects
+that configuration and does not choose a disk size.
+
+## The guide does not show styled menus
+
+Rehearsal uses numbered menus when terminal styling is unavailable, `NO_COLOR` is set, or
+`--plain` is used. Enter the number beside your choice. This is the same workflow and has
+the same safety checks.
+
+If bare `npx rehearsal` prints help, the command is not connected to an interactive
+terminal. Run it directly in a terminal rather than through a pipe or background task.
+
+## Doctor says the PostgreSQL image is unavailable
+
+Rehearsal will not download an image during a rehearsal. Pull and review the exact image
+declared in `rehearsal.config.mjs`, then rerun Doctor:
+
+```bash
+docker pull postgres:17-alpine
+npx rehearsal doctor
+```
+
 ## 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.
+Rerun `rehearsal setup` to select a different available block. Setup checks both active
+listeners and whether every selected port can be bound, then checks again before writing.
+For an existing configuration, choose unique non-privileged ports and mirror them in the
+dedicated Supabase config when using Supabase. Do not stop an unrelated database to make
+defaults fit.
 
 ## Baseline checksum mismatch
 
@@ -35,16 +128,48 @@ rerun doctor and candidates, then execute with the new digest.
 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.
 
+## The local application loads a hosted value from `.env`
+
+Rehearsal removes undeclared hosted credentials from the child process environment, but
+frameworks such as Vite may independently read project `.env` files after the process
+starts. Give the configured `startCommand` or framework test mode an explicit safe local
+override for the affected value. Do not delete or rewrite a developer's normal `.env`
+file as part of a rehearsal.
+
+## `rehearsal open` cannot start the app
+
+`open` requires `application.readiness` in `rehearsal.config.mjs`. Confirm that its URL
+uses `localhost`, `127.0.0.1`, or `::1`, matches the app's sandbox port, and returns the
+configured status after startup. Rehearsal leaves the verified database runtime running
+when application startup fails, so retrying does not discard local database or Storage
+changes.
+
 ## 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.
 
+If `identity plan` refuses the matcher, read the message literally:
+
+- **Provider or matcher type is unsupported:** use only the combinations documented in
+  [Runtime and identity policies](runtime-policies.md).
+- **No verified identity matches:** complete an ordinary local sign-in, confirm the
+  correct environment value is present, then run the plan again.
+- **More than one identity matches:** narrow the provider allowlist or use a hashed
+  provider-subject matcher. Rehearsal will not guess between accounts.
+- **Provider subject conflicts:** the local Auth identity disagrees with itself; remove
+  and recreate that disposable local sign-in instead of forcing a claim.
+
 ## Runtime changes disappeared
 
 `reset` deliberately restores the immutable baseline. `stop` should preserve Docker
 state, but runtime removal or a failed migration discards untrusted state.
 
+## `Ctrl+Z` exits instead of suspending
+
+This is intentional inside the guided interface. It exits the entire Rehearsal session
+and restores the terminal. Choose **Exit** for the same result.
+
 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

@@ -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.1",
+  "version": "0.1.0-beta.11",
   "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"
@@ -21,26 +21,27 @@
     "node": ">=24 <25"
   },
   "bin": {
-    "rehearsal": "scripts/operations/rehearsal/rehearsal_cli.mjs"
+    "rehearsal": "src/cli/rehearsal.mjs"
   },
   "exports": {
     ".": {
-      "types": "./scripts/lib/rehearsal/configuration.d.mts",
-      "import": "./scripts/lib/rehearsal/configuration.mjs"
+      "types": "./src/project/configuration.d.mts",
+      "import": "./src/project/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"
+    "./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"
   },
   "files": [
-    "scripts/lib/environment/local_supabase.mjs",
-    "scripts/lib/rehearsal",
-    "scripts/operations/database/manage_rehearsal_database.mjs",
-    "scripts/operations/rehearsal/rehearsal_cli.mjs",
+    "src",
+    "scripts/install/create_root_config.mjs",
+    "scripts/runtime/manage_database.mjs",
     "docs/*.md",
     "README.md",
     "BENCHMARKS.md",
@@ -51,15 +52,23 @@
     "LICENSE"
   ],
   "scripts": {
+    "postinstall": "node scripts/install/create_root_config.mjs",
+    "docs:build": "node scripts/docs/build.mjs",
+    "docs:preview": "node scripts/docs/serve.mjs",
     "test": "vitest run",
-    "test:unit": "vitest run tests/scripts",
+    "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/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 {} +",
+    "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: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 {} +",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "package:audit": "node scripts/operations/rehearsal/audit_package.mjs"
+    "package:audit": "node scripts/verification/audit_package.mjs"
   },
   "keywords": [
     "postgresql",
@@ -69,9 +78,16 @@
     "database"
   ],
   "license": "MIT",
-  "dependencies": {},
+  "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",
+    "marked": "^18.0.14",
     "prettier": "^3.9.6",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.2"
   }
 }

package/scripts/install/create_root_config.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+
+import { fileURLToPath } from "node:url";
+import { createInstalledRehearsalScaffold } from "../../src/project/install_scaffold.mjs";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+try {
+  const result = await createInstalledRehearsalScaffold({ packageRoot });
+  if (result.status === "ready") {
+    const changed = result.files.filter((file) => file.action !== "unchanged");
+    console.log(
+      [
+        "Rehearsal is ready in this project.",
+        ...(changed.length
+          ? [
+              ...changed.map(
+                (file) =>
+                  `  ${file.action === "create" ? "+" : "~"} ${file.path}`,
+              ),
+            ]
+          : ["  Existing Rehearsal configuration preserved."]),
+        "Next: review rehearsal.config.mjs, then run npx rehearsal.",
+      ].join("\n"),
+    );
+  } else {
+    console.log(
+      `Rehearsal did not create project files: ${result.reason}.\nNext: run npx rehearsal from the application directory.`,
+    );
+  }
+} 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/scripts/runtime/manage_database.mjs

@@ -0,0 +1,18 @@
+#!/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,
+  runRuntimeTarget,
+} from "../../src/targets/target.mjs";
+
+const invocation = parseRuntimeInvocation();
+const { config } = await loadRehearsalConfig({
+  projectRoot: process.cwd(),
+  configPath: invocation.configPath,
+});
+await runRuntimeTarget(config.runtime.target);

package/src/README.md

@@ -0,0 +1,17 @@
+# 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`.