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

package/docs/troubleshooting.md

@@ -1,14 +1,93 @@
 # 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.
+
+## 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,6 +114,22 @@ 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
@@ -46,5 +141,10 @@ is the local Auth callback. Do not paste provider secrets into config or termina
 `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.10",
   "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,26 @@
     "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/runtime/manage_database.mjs",
     "docs/*.md",
     "README.md",
     "BENCHMARKS.md",
@@ -52,14 +52,18 @@
   ],
   "scripts": {
     "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",
+    "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",
     "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 {} +",
+    "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 +73,13 @@
     "database"
   ],
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "pg": "^8.23.1"
+  },
   "devDependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.15",
     "prettier": "^3.9.6",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.2"
   }
 }

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`.