@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/docs/configuration.md

@@ -1,15 +1,21 @@
 # Configuration reference
 
-Most users should let the guide create this file:
+An ordinary npm application install creates this file in the application root when the
+root can be identified safely:
 
 ```bash
-npx rehearsal
+npm install --save-dev @rehearsal-db/core
 ```
 
-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.
+The install hook detects the database type, project name, migration folder,
+package-manager commands, and free local ports. It also creates the dedicated local
+runtime config and appends the two Rehearsal local-artifact entries to `.gitignore`.
+Existing configs and existing ignore content are never rewritten.
+
+When lifecycle scripts are disabled or the application root is not provable, run
+`npx rehearsal` inside the application. The guide provides the same setup with a preview
+and confirmation. Automatic root generation is tested with npm. pnpm and Yarn users
+should use this guided fallback because their lifecycle and workspace layouts vary.
 
 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
@@ -19,6 +25,11 @@ Use this page when changing the generated file. The schema is strict: misspelled
 unknown fields, and unsupported versions are errors. The `.mjs` extension works in both
 CommonJS and ESM projects.
 
+The generated file also receives editor and compiler checking through the package's
+public TypeScript declarations. See [TypeScript](typescript.md) for the supported type
+surface and checked examples. Keep the runnable configuration as `.mjs`; a project does
+not need to rename it to `.ts`.
+
 ```ts
 // @ts-check
 import { defineRehearsalConfig } from "@rehearsal-db/core";
@@ -36,9 +47,21 @@ export default defineRehearsalConfig({
     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"],
+    // Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+    // Register http://127.0.0.1:58321/auth/v1/callback with the provider.
+    // authentication: {
+    //   enableLocalSignup: true,
+    //   environmentFile: ".env.rehearsal-service.local",
+    //   providers: [
+    //     {
+    //       name: "google",
+    //       clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+    //       clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+    //       skipNonceCheck: false,
+    //       emailOptional: false,
+    //     },
+    //   ],
+    // },
   },
   baseline: {
     artifactDirectory: ".rehearsal",
@@ -54,10 +77,12 @@ export default defineRehearsalConfig({
   //   diskHeadroomBytes: 67108864,
   // },
   // runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
-  // Optional signup defaults, role/reference transfer, Storage paths, and token checks.
+  // Optional copied-account association. The JSON stores reviewed matcher hashes only;
+  // raw emails/subjects and provider credentials stay in ignored environment files.
+  // After setup, run: npx rehearsal identity connect
   // identityPolicy: "infrastructure/rehearsal/identity-policy.json",
   containerRuntime: {
-    autoStartColima: true,
+    autoStartColima: false,
   },
   cleanup: {
     retainBaselineGenerations: 2,
@@ -111,8 +136,64 @@ 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.
+Rehearsal never overwrites this config. Do not move it merely to inspect a newer template.
+After upgrading, run `npx rehearsal init` to print the current release's generated
+template beside the path of your existing config. This comparison is read-only; adding a
+new optional key remains your decision. `npx rehearsal init --write` still refuses to
+replace an existing config. Rehearsal lists important optional settings that are
+available but not enabled before printing the template, so they are easier to find.
+
+If setup was interrupted after creating only some files, rerun
+`npx rehearsal setup --write`. It recreates missing generated files while preserving every
+existing config and local runtime file. When a config itself is invalid, keep it as a
+backup, generate a fresh file, and manually carry over only reviewed settings. See
+[Getting started](getting-started.md#if-setup-or-an-upgrade-is-interrupted) for the short
+recovery table.
+
+### Workspaces and custom paths
+
+For an npm workspace, automatic creation proceeds only when exactly one application
+package already declares `@rehearsal-db/core` in the manifest or lockfile visible to the
+install hook. npm can save a new `--workspace` dependency after that hook runs, so a
+first workspace install may safely skip creation. If several applications declare it,
+Rehearsal also refuses to choose. Run `npx rehearsal` inside each intended application.
+Global installs, package caches, temporary `npx` installs, and Rehearsal's own source
+checkout never receive project files.
+
+Supported existing config paths—including
+`infrastructure/rehearsal/rehearsal.config.mjs`—are preserved, and a second root config
+is not created. The install hook reports the exact active path when npm displays lifecycle
+output, and setup always prints it. `npx rehearsal init --json` is the package-manager-
+independent way to check the `destination`. Rehearsal checks the supported root filenames
+first and then the supported nested filenames; finding any one of them prevents automatic
+creation of another. Use
+`--config=<project-relative-path>` for other explicit paths when running commands.
+
+### Move an existing config to the project root
+
+Relocation is deliberately manual because the config may contain reviewed settings and
+JavaScript imports. Rehearsal will never move it or create a competing root file.
+
+From the directory containing `package.json`:
+
+1. Stop active Rehearsal commands and confirm the current path with
+   `npx rehearsal init --json`.
+2. Make a backup outside every supported discovery path, such as
+   `.rehearsal/config-backups/rehearsal.config.mjs`.
+3. Move—do not copy—the active file to `./rehearsal.config.mjs`. Use `git mv` when it is
+   tracked so review history remains clear.
+4. Update relative JavaScript `import` specifiers inside the moved file. Imports resolve
+   from the config file's own folder, so a nested `../../something.mjs` import usually
+   changes after moving to the root.
+5. Leave config values such as `migrationDirectory`, `sanitizationPolicy`,
+   `runtimePolicy`, `identityPolicy`, and `dependentTargets[].configPath` unchanged unless
+   the referenced project file also moved. Rehearsal resolves those values from the
+   project root, not from the config file's folder.
+6. Run `npx rehearsal init --json`, confirm its `destination` is
+   `rehearsal.config.mjs`, then run `npx rehearsal doctor` and review the Git diff.
+
+If validation fails, restore the backup to its original path. Do not run setup while the
+move is half-finished; setup may correctly conclude that no supported config exists.
 
 `preparation.privacyKey` must stay inside `.rehearsal`; it is ignored and owner-readable
 only. Source, runtime, and identity policy files are declarations that may be reviewed in
@@ -135,15 +216,18 @@ approval sequence.
 
 `runtimePolicy` replaces common restore adapters with reviewed schemas, allowlisted
 extensions, managed triggers, local-only singleton rows, and structural expectations.
-`identityPolicy` declares a hashed verified email, copied placeholder, safe signup
-defaults, required role/reference transfers, Storage path rewrites, and token checks. See
+`identityPolicy` declares a hashed verified-email or provider-subject matcher, copied
+placeholder, safe signup defaults, required role/reference transfers, Storage path
+rewrites, and token checks. Provider credentials stay in the local Supabase runtime
+environment; association values stay in named environment variables and only their
+SHA-256 receipts are tracked. See
 [Runtime and identity policies](runtime-policies.md).
 
 ## Container runtime and cleanup
 
 ```ts
 containerRuntime: {
-  autoStartColima: true,
+  autoStartColima: false,
 },
 cleanup: {
   retainBaselineGenerations: 2,
@@ -151,9 +235,17 @@ cleanup: {
 ```
 
 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.
+is running and `autoStartColima` is `true`, Rehearsal may run `colima start`. This is an
+explicit opt-in because starting a shared Docker engine can also restart unrelated
+containers whose restart policy is `always` or `unless-stopped`. Rehearsal respects the
+user's Colima CPU, memory, and disk settings and never changes them. The generated default
+is `false`: start Docker or Colima yourself before a mutating command. Rehearsal never
+stops a shared container engine automatically.
+
+After each Supabase start, Rehearsal changes only the exact target's containers to
+Docker's `no` restart policy. Its database and Storage volumes remain intact,
+`rehearsal start` can resume it, and restarting Docker does not silently wake stopped
+Rehearsal stacks.
 
 `retainBaselineGenerations` controls how many immutable baseline generations survive an
 approved `rehearsal refresh` or `rehearsal cleanup`; it must be at least 1. Refresh shows
@@ -217,19 +309,72 @@ negative controls, such as unauthorized, malformed, withheld, or missing records
 response that merely avoids a server error does not prove that eligible data was
 published or can be found.
 
-## Supabase service environment
+## Supabase authentication
 
-Some local identity providers need a client ID and secret. Configure both fields or
-neither:
+Rehearsal can configure a Google or GitHub OAuth connection in its disposable local
+Supabase runtime. Declare the provider and the names of its credential variables:
 
 ```ts
-serviceEnvironmentFile: ".env.rehearsal-service.local",
-serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+authentication: {
+  enableLocalSignup: true,
+  environmentFile: ".env.rehearsal-service.local",
+  providers: [
+    {
+      name: "google",
+      clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+      clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+      skipNonceCheck: false,
+      emailOptional: false,
+    },
+  ],
+},
+```
+
+Create the ignored file, add the values, then restrict it to your account:
+
+```dotenv
+REHEARSAL_GOOGLE_CLIENT_ID=your-local-oauth-client-id
+REHEARSAL_GOOGLE_CLIENT_SECRET=your-local-oauth-client-secret
+```
+
+```bash
+chmod 600 .env.rehearsal-service.local
 ```
 
-The file must be ignored, owner-readable only, and contain only the exact allowlisted
-names. These credentials may authorize an identity handshake, but the callback must
-terminate at local Auth. They do not grant hosted database access.
+Register `http://127.0.0.1:<apiPort>/auth/v1/callback` with the provider, using the
+`runtime.apiPort` value from this config. `rehearsal explain` also prints the exact URL.
+Rehearsal writes that callback and `env(...)` references into the disposable runtime; it
+never copies credential values into tracked configuration. Use `name: "github"` and
+distinct GitHub variable names for GitHub. Duplicate providers, reused variable names,
+unsupported providers, extra keys, and a template that already owns the same provider
+are refused. This follows Supabase's documented
+[`env()` configuration pattern](https://supabase.com/docs/guides/local-development/managing-config).
+
+`enableLocalSignup: true` explicitly acknowledges that disposable local Auth may create
+the temporary user returned by OAuth. Rehearsal changes the generated runtime copy only;
+the tracked Supabase template and every hosted project remain unchanged.
+
+The older `serviceEnvironmentFile`, `serviceEnvironmentVariables`, and
+`safety.authenticationProviders` fields remain compatible for projects that manually
+own their Supabase provider TOML. Do not combine those fields with the declarative
+`authentication` block.
+
+To migrate a manual Google or GitHub setup, replace those three legacy config fields
+with the `authentication` block together. The tracked Supabase template may keep its
+existing provider section: Rehearsal replaces a compatible legacy section only in the
+generated disposable runtime copy. The section may contain `enabled`, `client_id`,
+`secret`, `redirect_uri`, `skip_nonce_check`, and `email_optional`. The latter two must
+match the explicit `skipNonceCheck` and `emailOptional` declarations, which default to
+`false`. Keep them false unless the provider integration has a reviewed need; Supabase
+warns in its [CLI configuration reference](https://supabase.com/docs/guides/local-development/cli/config#auth.external.provider.skip_nonce_check)
+that skipping nonce validation reduces replay protection. Unknown settings,
+duplicate sections, nested provider tables, or mismatched options fail
+`rehearsal doctor` before reset. Rehearsal never edits the tracked template during this
+transition.
+
+Provider connection and copied-account association are separate. This block lets the
+ordinary application sign-in reach local Auth. An optional `identityPolicy` decides
+whether that verified local identity may claim a reviewed copied account.
 
 ## Safety fields
 
@@ -281,7 +426,7 @@ Declarative runtime policies are preferred for supported schema prerequisites an
 checks. Existing project-owned adapters remain compatible but do not replace the
 database driver.
 
-## Application proof
+## Application proof and hands-on sessions
 
 `startCommand` is the ordinary application command. When `readiness` is present,
 `rehearsal run` launches it with a minimal environment, waits for the exact local status,
@@ -306,6 +451,15 @@ package-owned checks and must include real positive and negative expectations. A
 404, 401, empty result, or non-5xx response is not a positive unless it matches the
 declared status and body assertion.
 
+After a successful rehearsal, `rehearsal open` uses the same `startCommand`, readiness
+check, and environment mappings for a hands-on session. It starts and verifies every
+configured database target but does not reset them. The app remains available until
+`Ctrl+C` or `Ctrl+Z`; Rehearsal then stops only its application process group. Database
+and Storage changes remain for the next `open`, `verify`, or `start` command.
+
+`application.readiness` is required for `open`. Point it at a route that returns the
+configured status only when the local app is ready. Keep the URL on a loopback host.
+
 ## Runtime adapters
 
 Existing adapters remain compatible, but new projects should first use `runtimePolicy`,
@@ -326,9 +480,10 @@ may use these explicit subpaths:
 - `@rehearsal-db/core/service-environment`
 - `@rehearsal-db/core/source-access`
 
-These advanced entry points are ESM JavaScript APIs in the first beta. The root
-configuration and sanitization API has TypeScript declarations; the advanced subpaths do
-not yet promise a typed surface.
+These advanced entry points ship as ordinary ESM JavaScript with generated TypeScript
+declarations. The root configuration and sanitization contract remains the explicitly
+reviewed public type surface. The exact current boundary is documented in
+[TypeScript](typescript.md).
 
 Undocumented files under `scripts/` are package internals and are not compatibility
 contracts.

package/docs/getting-started.md

@@ -7,7 +7,8 @@ Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
 ## 1. Check the required tools
 
-You need Node.js 24, npm, and a running Docker-compatible engine:
+You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24
+LTS is the recommended default:
 
 ```bash
 node --version
@@ -15,8 +16,8 @@ npm --version
 docker info
 ```
 
-`node --version` must begin with `v24`. If `docker info` fails, start Docker Desktop,
-Colima, or your usual Docker engine.
+`node --version` must begin with `v22`, `v24`, or `v26`. If `docker info` fails, start
+Docker Desktop, Colima, or your usual Docker engine.
 
 Choose the extra requirement for your project:
 
@@ -34,22 +35,39 @@ Rehearsal will use that image with downloads disabled.
 Run these commands from the directory containing your project's `package.json`:
 
 ```bash
-npm install --save-dev @rehearsal-db/core@beta
+npm install --save-dev @rehearsal-db/core
 npx rehearsal
 ```
 
-Choose **Set the stage**, then choose Supabase or PostgreSQL. Rehearsal previews every file
-before asking to create it. It will not replace an existing file.
-
-Review the generated `rehearsal.config.mjs`, especially:
+With npm, a normal application install creates `rehearsal.config.mjs`, the dedicated
+local runtime config, and the required `.gitignore` entries when Rehearsal can prove the
+application root. It never replaces an existing file. Review the generated config,
+especially:
 
 - the migration directory;
 - the application start and proof commands;
 - the local ports.
 
+If a supported configuration already exists elsewhere—such as
+`infrastructure/rehearsal/rehearsal.config.mjs`—the installer reports that exact active
+path and does not generate a competing root file. Keep using it, or follow the explicit
+[root relocation guide](configuration.md#move-an-existing-config-to-the-project-root).
+
+If lifecycle scripts were disabled, a global/cache install was used, or a workspace has
+more than one possible application, no project files are created automatically. Run
+`npx rehearsal` inside the intended application, choose **Set the stage**, select
+Supabase or PostgreSQL, and approve the same safe setup preview.
+
 The proof command should check behavior changed by the migration. A test that only checks
 whether the home page loads is usually too weak.
 
+If the sandbox needs Google or GitHub sign-in, uncomment
+`supabase.authentication` in `rehearsal.config.mjs`. Add the named credentials to
+`.env.rehearsal-service.local`, run `chmod 600 .env.rehearsal-service.local`, and
+register the local callback printed in the config. See
+[Supabase authentication](configuration.md#supabase-authentication). Rehearsal keeps the
+values out of tracked files and generates the disposable provider configuration for you.
+
 ## 3. Prepare safe baseline inputs
 
 A **baseline** is the locked starting point restored before each rehearsal. Start with a
@@ -125,7 +143,17 @@ Once temporary source access is ready, `npx rehearsal refresh` previews the safe
 replacement workflow. It means “get a newly verified copy.” By contrast, `reset` means
 “discard local edits and restore the copy I already have.”
 
-## 6. Test and clean up
+## 6. Use the sandbox and clean up
+
+Choose **Open the sandbox app**, or run:
+
+```bash
+npx rehearsal open
+```
+
+Open the local URL printed by Rehearsal. The app stays available for hands-on testing
+until you press `Ctrl+C`. Only the app stops; your local database and Storage changes are
+kept. Run `npx rehearsal open` again to continue where you left off.
 
 Use the guide for normal runtime tasks:
 
@@ -151,6 +179,35 @@ npx rehearsal run --confirm-candidates=PASTE_DIGEST_HERE
 Replace `postgresql` with `supabase` when needed. See [CLI commands](commands.md) for the
 complete reference and [Troubleshooting](troubleshooting.md) when a check fails.
 
+Running setup again is safe: existing configuration and runtime files are reported as
+unchanged. Rehearsal only adds missing ignore entries. It never refreshes an existing
+config during an upgrade. After upgrading, run `npx rehearsal init` to see important
+optional settings you have not enabled and compare your file with the installed
+release's current template.
+
+### If setup or an upgrade is interrupted
+
+Do not delete `.rehearsal/` or your existing config. Start with:
+
+```bash
+npx rehearsal doctor
+npx rehearsal init
+```
+
+Use the reported problem to choose the smallest recovery:
+
+| Problem                             | Safe recovery                                                                                                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A generated runtime file is missing | Run `npx rehearsal setup --write`. Existing files stay unchanged; only missing files are created.                                                                          |
+| A port is already in use            | Stop the conflicting local process or choose new dedicated ports, then rerun setup.                                                                                        |
+| The config is malformed             | Move it to a backup name, run `npx rehearsal setup --write`, then copy reviewed choices into the new file.                                                                 |
+| OAuth credentials are missing       | Create the ignored file named by `supabase.authentication.environmentFile`, add only the declared keys, and run `chmod 600` on it. Ambient shell credentials are not used. |
+| An npm upgrade fails                | Keep the existing config, baseline, and lockfile. Restore dependencies with your package manager, then run `npx rehearsal init` before retrying.                           |
+| Docker storage is low               | Run `npx rehearsal cleanup` for an exact preview. Rehearsal never performs a global Docker prune or silently removes volumes.                                              |
+
+`setup --write` and package installation never replace a config. If an existing file is
+invalid, Rehearsal fails closed and leaves it available for comparison.
+
 ## Files Rehearsal creates
 
 - `rehearsal.config.mjs` — reviewed project configuration

package/docs/index.md

@@ -0,0 +1,67 @@
+# Rehearsal documentation
+
+## Why an empty database is not enough
+
+Most migration tests start with an empty database. Production does not.
+
+Existing rows, relationships, authentication identities, stored files, and migration
+history are where risky changes break. A migration can build successfully and still fail
+against the data and application behavior you actually have.
+
+Rehearsal catches those problems before deployment. It restores a reviewed, sanitized
+baseline into a disposable local PostgreSQL or Supabase environment, applies only the
+exact migrations you approve, and runs your application's own proof.
+
+| Empty-database tests miss…                        | Rehearsal exercises…                                      |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| old rows and edge cases                           | a reviewed, production-shaped baseline                    |
+| relationships between data, identities, and files | database, Auth, and Storage in one local sandbox          |
+| whether the product still behaves correctly       | your automated proof and hands-on application walkthrough |
+
+## Pick the path that fits today
+
+You do not need to read everything before your first rehearsal. Start with the outcome
+you want, then follow the links when a term or safety check is new.
+
+| I want to…                              | Go here                                                           |
+| --------------------------------------- | ----------------------------------------------------------------- |
+| Set up my own project                   | [Getting started](getting-started.md)                             |
+| Try Rehearsal without touching my app   | [Hands-on tutorial](tutorial.md)                                  |
+| Understand what makes a copy safe       | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
+| Look up a command or setting            | [CLI commands](commands.md) and [Configuration](configuration.md) |
+| Reduce Docker and Supabase resource use | [Container runtime lifecycle](runtime-lifecycle.md)               |
+| Add editor and compiler type checks     | [TypeScript](typescript.md)                                       |
+| Fix something that did not work         | [Troubleshooting](troubleshooting.md)                             |
+
+## The short version
+
+Rehearsal restores an approved local baseline, applies only the migration files you
+reviewed, and runs the application checks your project owns. The normal workflow stays
+on your computer and does not deploy anything.
+
+1. **Prepare** a safe baseline.
+2. **Review** the exact candidate migrations.
+3. **Run** them in a disposable local database.
+4. **Prove** the application behavior that matters.
+5. **Open** the sandbox for hands-on testing.
+
+## Safety is part of the workflow
+
+Rehearsal does not ask you to trust one giant switch. Baseline checksums, local-only
+networking, exact confirmation digests, project-owned proofs, and narrowly owned cleanup
+each protect a different boundary.
+
+Start with synthetic data when you can. If a project needs a production-shaped copy,
+read [Production-shaped preparation](production-source.md) before providing any source
+access.
+
+## Still unsure where to begin?
+
+Run the interactive guide from the project you want to test:
+
+```bash
+npx rehearsal
+```
+
+It reads the project state, explains the next safe step, and keeps the full command
+reference available when you need it.