@rehearsal-db/core 0.1.0-beta.5 → 0.1.0-beta.7

package/docs/baselines.md

@@ -1,33 +1,92 @@
 # Baselines
 
-A baseline is an immutable, digest-addressed starting point for a disposable runtime.
-It binds sanitized rows, represented migration bytes, optional Storage assets, schema
-evidence, policy identity, and verification metadata.
+A baseline is the locked starting point for every rehearsal. It combines safe rows with
+the exact historical migrations that created their schema. Resetting the runtime always
+returns to this point.
 
-## Generation lifecycle
+## Required inputs
 
-New content is written to a private building directory. Individual files are checksummed
-and made read-only. A complete manifest is verified before an atomic `current` symlink
-selects the generation. An interrupted build cannot replace the active baseline.
+### Records
 
-## Migration lineage
+Records use NDJSON: one complete JSON object per line. Each object names a table and one
+safe row.
 
-The manifest records the exact ordered historical prefix. A migration with the same
-timestamp but different bytes is modified history, not a candidate. New migrations must
-form an ordered suffix. Candidate confirmation binds the exact filenames and checksums.
+```json
+{ "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }
+```
 
-## Restore lifecycle
+Use synthetic or reviewed sanitized values. A `.json` array is not NDJSON and will be
+rejected.
 
-`reset` destroys only the explicitly labelled local runtime, replays the represented
-schema, streams sanitized rows, restores checksummed local Storage assets, reapplies
-normal enforcement, and verifies counts and foreign keys. A failure removes trust and
-cannot leave a successful receipt.
+### Migration ledger
 
-## Persistence model
+The ledger is a JSON array in migration order:
 
-The baseline never changes during normal use. The restored runtime is writable and its
-changes persist across application restarts while the local containers remain. Run
-`reset` to discard sandbox changes and return to the exact baseline.
+```json
+[
+  {
+    "version": "20260101000000",
+    "name": "create_widgets",
+    "statements": [
+      "create table public.widgets (id bigint primary key, name text not null)"
+    ]
+  }
+]
+```
 
-Treat baseline files as sensitive even after sanitization: owner-only permissions,
-ignored paths, encrypted disks, bounded retention, and explicit deletion are prudent.
+Each entry must match the version, name, order, and SQL represented by the historical
+migration. Equivalent-looking SQL is not enough. Generate this evidence with reviewed
+project tooling for a real migration history; do not reconstruct a large ledger by hand.
+
+### Sanitization policy
+
+The policy records the approved treatment of every included table and column. The guide
+can create a shape-only draft from the records and walk you through its review. A draft
+with undecided fields cannot become a baseline. See [Sanitization](sanitization.md).
+
+### Storage manifest (optional)
+
+Supabase projects may include a bounded set of approved local Storage files. Plain
+PostgreSQL projects do not support Supabase Storage. Every file is checksum-verified and
+must remain inside the project.
+
+## Create a baseline
+
+The guided action is recommended:
+
+```bash
+npx rehearsal
+```
+
+For automation, use explicit safe local paths:
+
+```bash
+npx rehearsal baseline create \
+  --records=rehearsal/sanitized-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json
+```
+
+Add `--assets=rehearsal/assets.json` only when using approved Supabase Storage files.
+Rehearsal validates everything and shows counts before activation. It never extracts data.
+
+## Why historical migrations are locked
+
+The baseline records the exact ordered historical migration files. If a file keeps the
+same timestamp but its bytes change, Rehearsal reports modified history instead of
+treating it as a new candidate. New migrations must form an ordered suffix after the
+baseline cutoff.
+
+## What reset does
+
+`reset` removes only the exactly labeled local runtime, rebuilds the represented schema,
+loads the safe rows, restores approved Storage files when present, and verifies counts and
+relationships. A failed restore cannot produce a successful receipt.
+
+The baseline itself never changes during normal use. Runtime edits persist until you
+reset or discard that runtime.
+
+## Storage and privacy
+
+Baseline files can still be sensitive after sanitization. Rehearsal stores them under the
+ignored `.rehearsal/` directory with checksums and read-only files. Keep them off shared
+drives, use encrypted disks, retain them only as long as needed, and never commit them.

package/docs/commands.md

@@ -1,77 +1,107 @@
 # CLI commands
 
-All commands run from the consuming project root. State-reporting commands accept
-`--json`; `--verbose` and `--debug` increase safe diagnostics without revealing row
-values or credentials.
-
-| Command                                                      | Mutates local state | Purpose                                                   |
-| ------------------------------------------------------------ | ------------------- | --------------------------------------------------------- |
-| `rehearsal` or `rehearsal guide`                             | No by default       | Open the guided, state-aware interactive home screen.     |
-| `rehearsal setup`                                            | No                  | Preview safe config, local runtime, and ignore files.     |
-| `rehearsal setup --write`                                    | Project files       | Create the previewed first-run scaffolding.               |
-| `rehearsal init`                                             | No                  | Preview safe starter configuration.                       |
-| `rehearsal init --write`                                     | Config only         | Create config without overwriting.                        |
-| `rehearsal baseline prepare --records= --ledger=`            | No                  | Preview a fail-closed policy draft from local shape.      |
-| `rehearsal baseline prepare --records= --ledger= --write`    | Policy only         | Write the draft without exposing row values.              |
-| `rehearsal baseline create --records=<path> --ledger=<path>` | Artifact only       | Activate a baseline from explicit safe local inputs.      |
-| `rehearsal doctor`                                           | No                  | Check dependencies, inputs, and safety barriers.          |
-| `rehearsal support`                                          | No                  | Print a privacy-safe, copy-ready support report.          |
-| `rehearsal explain`                                          | No                  | Print the immutable execution plan.                       |
-| `rehearsal run --dry-run`                                    | No                  | Alias the same plan used by `explain`.                    |
-| `rehearsal candidates`                                       | No                  | Print pending migrations and their exact digest.          |
-| `rehearsal inspect baseline`                                 | No                  | Print data-free artifact provenance.                      |
-| `rehearsal inspect migrations`                               | No                  | Classify each migration.                                  |
-| `rehearsal run --confirm-candidates=<sha256>`                | Yes, local only     | Reset, apply exact candidates, verify, and run app proof. |
-| `rehearsal start`                                            | Runtime only        | Start a verified runtime without resetting its data.      |
-| `rehearsal migrate --confirm-candidates=<sha256>`            | Yes, local only     | Apply the exact suffix without resetting current data.    |
-| `rehearsal verify`                                           | No data mutation    | Verify the current local runtime and receipt.             |
-| `rehearsal status`                                           | No                  | Report runtime, baseline, and candidate state.            |
-| `rehearsal reset`                                            | Yes, local only     | Replace runtime data with the immutable baseline.         |
-| `rehearsal stop`                                             | Runtime only        | Stop this project's local services.                       |
-| `rehearsal discard`                                          | Yes, local only     | Remove only this project's disposable runtime and volume. |
-
-In an interactive terminal, `run` and `migrate` display the candidate files and ask for
-confirmation before touching the runtime. In automation, they require the digest from
-the current candidate set. Any added, removed, reordered, or edited migration changes
-the digest and invalidates either form of confirmation.
-
-`baseline create` never extracts data. The NDJSON and migration-ledger files must already
-exist inside the project and be safe to retain. Add `--assets=<manifest.json>` to include
-bounded local Storage bytes; every manifest `file` must also remain inside the project.
-The guided home screen scans a bounded set of small project-local JSON and NDJSON files,
-skips generated and private runtime directories, and offers structurally matching paths
-so they do not need to be memorized. It never displays row values. Before activation it
-validates the selected files and referenced assets, shows row, table, migration, and asset
-counts, and asks for confirmation. Invalid input returns to the guide without writing.
-
-The guide is a persistent session: after setup, policy review, baseline creation, or a
-runtime action it re-reads project state and offers the next relevant action. Generated
-policy drafts can be completed interactively without editing JSON. Each column still
-receives explicit action, generated, identity, and foreign-key decisions. A human may
-apply the displayed safe preset to a table, then review only selected exceptions; the
-guide never silently applies a preset.
-
-`baseline prepare` reads only table and column names from the NDJSON records; row values
-are never included in its result. Its generated policy deliberately marks every column
-decision `REVIEW REQUIRED` and cannot be activated until a human completes the metadata
-and removes the `draft` marker. Rehearsal binds the reviewed policy checksum to the
-baseline and rejects later policy changes during planning and restore.
-
-Automation should use `--json` and inspect both exit status and the versioned envelope.
-Exit-code meanings are documented in the root README. Scripts must not parse human text.
-When standard input or output is not an interactive terminal, bare `rehearsal` prints
-help instead of prompting. Use `--plain` to disable decorative terminal styling.
-`NO_COLOR` also selects the plain numbered interface. Both interactive modes preserve
-the same safety decisions and cancellation behavior.
-
-`setup` chooses an available local port block and generates a conservative Supabase
-configuration with hosted access and optional networked services disabled. It does not
-overwrite an existing Rehearsal config, dedicated Supabase config, or concurrently
-changed `.gitignore`. After writing, it includes a Doctor readiness summary. `init`
-remains available for config-only/manual onboarding.
-
-`support` reports the Rehearsal, Node.js, npm, Supabase CLI, Docker client, and Docker
-server versions plus readiness check statuses. It can run before configuration exists.
-The report deliberately excludes project names and paths, row values, credentials,
-migration SQL, baseline identifiers, and raw command output. It reports only the count
-of quarantined hosted variables, never their names. Always review it before sharing.
+Run commands from the project directory containing `rehearsal.config.mjs`. The examples
+use `npx`, so a global install is not required.
+
+## Guided mode
+
+```bash
+npx rehearsal
+```
+
+The guide reads the current project state and recommends the next useful action. It stays
+open after each action. Press `Ctrl+Z` at a prompt to exit the entire session.
+
+Use `npx rehearsal guide` for the same screen or add `--plain` to use numbered menus
+without decorative terminal styling. When input or output is not an interactive terminal,
+bare `npx rehearsal` prints help instead of waiting for input.
+
+## Setup and baseline
+
+| Command                                                           | What it does                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------ |
+| `npx rehearsal setup --target=supabase`                           | Preview Supabase setup files.                          |
+| `npx rehearsal setup --target=postgresql`                         | Preview PostgreSQL setup files.                        |
+| Add `--write` to either setup command                             | Create the previewed files without overwriting.        |
+| `npx rehearsal init`                                              | Preview only `rehearsal.config.mjs`.                   |
+| `npx rehearsal init --write`                                      | Create only `rehearsal.config.mjs`.                    |
+| `npx rehearsal baseline prepare --records=<path> --ledger=<path>` | Preview a sanitization-policy draft.                   |
+| Add `--write` to `baseline prepare`                               | Write the draft for human review.                      |
+| `npx rehearsal baseline create --records=<path> --ledger=<path>`  | Create and activate a baseline from safe local inputs. |
+
+Add `--assets=<manifest.json>` to `baseline create` only for approved local Supabase
+Storage files. Baseline commands never extract data or connect to another database.
+
+## Check and inspect
+
+| Command                            | What it does                                          |
+| ---------------------------------- | ----------------------------------------------------- |
+| `npx rehearsal doctor`             | Check dependencies, inputs, and safety rules.         |
+| `npx rehearsal support`            | Print a privacy-safe report for a support request.    |
+| `npx rehearsal explain`            | Show the exact plan without changing anything.        |
+| `npx rehearsal run --dry-run`      | Show the same non-mutating plan.                      |
+| `npx rehearsal candidates`         | List pending migrations and their approval digest.    |
+| `npx rehearsal inspect baseline`   | Show baseline metadata without row values.            |
+| `npx rehearsal inspect migrations` | Classify every historical and candidate migration.    |
+| `npx rehearsal status`             | Report baseline, candidates, and local runtime state. |
+
+State-reporting commands accept `--json` for scripts. Scripts should use the JSON fields
+and process exit code, not parse human-facing text.
+
+## Run and manage the local database
+
+| Command                                               | What it does                                                        |
+| ----------------------------------------------------- | ------------------------------------------------------------------- |
+| `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply the exact candidates, verify, and run the app proof.   |
+| `npx rehearsal migrate --confirm-candidates=<sha256>` | Apply the exact candidates without resetting existing runtime data. |
+| `npx rehearsal start`                                 | Start an existing verified runtime.                                 |
+| `npx rehearsal verify`                                | Verify the current runtime and receipt.                             |
+| `npx rehearsal reset`                                 | Discard runtime edits and restore the baseline.                     |
+| `npx rehearsal stop`                                  | Stop the runtime but keep its local state.                          |
+| `npx rehearsal discard`                               | Remove this project's disposable runtime and volume.                |
+| `npx rehearsal cleanup`                               | Preview conservative cleanup without removing anything.             |
+
+In a terminal, the guide displays candidate filenames and asks for confirmation. In a
+script, copy the digest from `candidates` into `--confirm-candidates`. Adding, removing,
+reordering, or editing a migration changes that digest.
+
+## Clean up disk space
+
+Start with a preview:
+
+```bash
+npx rehearsal cleanup
+```
+
+By default, cleanup selects only old baseline generations beyond the retention setting
+in `rehearsal.config.mjs`. Add options to broaden the preview:
+
+| Command option      | Additional resources considered                                        |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--include-runtime` | This project's disposable runtime and its database volumes.            |
+| `--include-images`  | Older unused Supabase images; the newest image for each service stays. |
+| `--write`           | Apply the exact freshly verified preview.                              |
+| `--confirm-cleanup` | Full cleanup digest printed by the preview; required with `--write`.   |
+
+Image cleanup never removes an image used by any running or stopped container and never
+runs a global Docker prune. Images may be shared by projects and can be downloaded again,
+so they remain excluded unless you explicitly add `--include-images`. Database volumes
+belonging to other projects are never included. This follows
+[Docker's conservative pruning guidance](https://docs.docker.com/engine/manage-resources/pruning/).
+
+## Common options
+
+| Option                          | Meaning                                                          |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `--json`                        | Return the versioned machine-readable result.                    |
+| `--verbose`                     | Show more safe detail.                                           |
+| `--debug`                       | Show the most diagnostic detail; still review it before sharing. |
+| `--plain`                       | Disable decorative interactive prompts.                          |
+| `--config=<path>`               | Use a specific config file inside the project.                   |
+| `--target=supabase\|postgresql` | Choose the setup target.                                         |
+| `--include-runtime`             | Include this project's runtime in a cleanup preview.             |
+| `--include-images`              | Include older unused Supabase images in a cleanup preview.       |
+| `--confirm-cleanup=<digest>`    | Confirm the exact cleanup set printed by the preview.            |
+| `--write`                       | Apply a setup, policy, or cleanup preview.                       |
+
+Run `npx rehearsal --help` to print the command list available in your installed version.

package/docs/configuration.md

@@ -1,38 +1,79 @@
 # Configuration reference
 
-`rehearsal.config.mjs` is executable configuration with a strict versioned schema. The
-initializer uses an explicit ESM extension so the same generated file works in CommonJS
-and ESM projects.
-Unknown fields and unknown schema versions are errors, not warnings.
+Most users should let the guide create this file:
+
+```bash
+npx rehearsal
+```
+
+The first run uses your chosen database type and detects the project name, migration
+folder, package-manager commands, and free local ports. After you approve the setup
+preview, it creates a commented `rehearsal.config.mjs` with those values filled in.
+Installation itself does not use a `postinstall` script or silently modify the project.
+
+Review lines marked `CHECK`, especially the application proof command. Optional settings
+are present as commented examples, and secrets never belong in this file. Rehearsal will
+not overwrite an existing config.
+
+Use this page when changing the generated file. The schema is strict: misspelled fields,
+unknown fields, and unsupported versions are errors. The `.mjs` extension works in both
+CommonJS and ESM projects.
 
 ```ts
+// @ts-check
 import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
+  // Configuration format. Rehearsal will explain if an upgrade is ever needed.
   schemaVersion: 1,
+  // Stable local name used in Rehearsal labels and reports.
   project: { name: "example-app" },
+
+  // Project files Rehearsal reads. Every path stays inside this repository.
   supabase: {
     workdir: ".",
     migrationDirectory: "supabase/migrations",
     rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
     runtimeWorkdir: ".rehearsal/runtime",
+
+    // Optional; configure both keys together.
+    // serviceEnvironmentFile: ".env.rehearsal-service.local",
+    // serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
   },
   baseline: {
     artifactDirectory: ".rehearsal",
     sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
   },
+  containerRuntime: {
+    autoStartColima: true,
+  },
+  cleanup: {
+    retainBaselineGenerations: 2,
+  },
   application: {
+    // CHECK: replace these when the detected package scripts are not correct.
     startCommand: "npm run dev:rehearsal",
     proofCommand: "npm run test:rehearsal",
+    environmentFile: ".rehearsal/runtime.env",
   },
   runtime: {
+    target: "supabase",
     applicationUrl: "http://localhost:5175",
     projectId: "example-app-rehearsal",
     apiPort: 58321,
     databasePort: 58322,
     studioPort: 58323,
   },
-  safety: { hostedAccess: "disabled", outboundNetwork: "deny" },
+  safety: {
+    allowedHosts: ["127.0.0.1", "::1", "localhost"],
+    blockedEnvironmentVariables: [
+      "SUPABASE_ACCESS_TOKEN",
+      "SUPABASE_DB_PASSWORD",
+      "SUPABASE_PROJECT_ID",
+    ],
+    hostedAccess: "disabled",
+    outboundNetwork: "deny",
+  },
 });
 ```
 
@@ -42,6 +83,29 @@ All paths resolve inside the consuming project. The artifact directory must be n
 `.rehearsal`; this is an intentional deletion guard. `runtimeWorkdir` must be its
 `runtime` child, and the generated application environment file must remain inside it.
 
+Rehearsal never overwrites this config. To start over, move the existing file somewhere
+safe, run setup again, and compare the two files before deleting either one.
+
+## Container runtime and cleanup
+
+```ts
+containerRuntime: {
+  autoStartColima: true,
+},
+cleanup: {
+  retainBaselineGenerations: 2,
+},
+```
+
+Rehearsal uses whichever Docker-compatible engine already answers `docker info`. If none
+is running and `autoStartColima` is `true`, Rehearsal may run `colima start`. It respects
+the user's Colima CPU, memory, and disk settings and never changes them. Set the field to
+`false` when you prefer to start Docker or Colima yourself.
+
+`retainBaselineGenerations` controls how many immutable baseline generations survive
+`rehearsal cleanup`; it must be at least 1. Runtime deletion and shared-image inspection
+are command choices, not automatic retention settings. See [CLI commands](commands.md).
+
 ## Supabase service environment
 
 Some local identity providers need a client ID and secret. Configure both fields or
@@ -58,9 +122,12 @@ terminate at local Auth. They do not grant hosted database access.
 
 ## Safety fields
 
-Version 1 accepts loopback hosts only. `hostedAccess` can only be `disabled`, and
-`outboundNetwork` can only be `deny`. Ambient hosted Supabase variables are quarantined
-from child processes. There is no force flag to weaken these rules.
+Version 1 accepts loopback runtime URLs only. `hostedAccess` can only be `disabled`, and
+`outboundNetwork` can only be `deny`. Common hosted Supabase and PostgreSQL credentials
+are quarantined from child processes. These fields are fail-closed configuration rules,
+not a host firewall: trusted project proof commands and runtime adapters remain ordinary
+local code and must be reviewed. There is no force flag to weaken the configuration
+rules.
 
 ## Ports and project identity
 
@@ -68,6 +135,40 @@ Use unique, non-privileged ports that do not overlap. `projectId` accepts lowerc
 letters, numbers, and hyphens. It labels the local Docker resources so cleanup targets
 only this project.
 
+## Database runtime
+
+`runtime.target` selects the isolated database driver. It is optional in existing
+configurations and currently defaults to `"supabase"`, so upgrading does not change an
+existing project's behavior. Unknown targets are rejected before any runtime action.
+
+For ordinary PostgreSQL, use `postgresql` instead of `supabase`:
+
+```ts
+postgresql: {
+  migrationDirectory: "database/migrations",
+  runtimeWorkdir: ".rehearsal/runtime",
+  image: "postgres:17-alpine",
+  database: "postgres",
+  user: "postgres",
+},
+runtime: {
+  target: "postgresql",
+  applicationUrl: "http://localhost:5175",
+  projectId: "example-app-rehearsal",
+  databasePort: 58322,
+},
+```
+
+The image must be an official versioned Alpine PostgreSQL image and must already exist
+locally. Rehearsal runs it with `--pull=never`, publishes it only on `127.0.0.1`, and
+creates a fresh random runtime password in owner-readable ignored files. It manages only
+the exactly named container and volume carrying the matching project label.
+Plain PostgreSQL does not restore Supabase Storage assets or synthesize Supabase Auth
+users.
+
+Project-owned runtime adapters remain the place for application-specific setup and
+checks; they do not replace the database driver.
+
 ## Application proof
 
 `proofCommand` is mandatory and project-owned. It should test restored relationships,