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

package/CHANGELOG.md

@@ -5,6 +5,58 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.3] - 2026-10-01
+
+### Added
+
+- A state-aware interactive home screen that guides setup, baseline preparation,
+  migration review, runtime management, verification, and cleanup without requiring
+  users to memorize commands.
+- A safe `setup` workflow that previews and creates a dedicated local Supabase config,
+  chooses an available port block, updates protective ignore rules, and summarizes
+  readiness without overwriting project files.
+- A schema-only `baseline prepare` workflow that generates a fail-closed policy draft
+  with explicit `REVIEW REQUIRED` decisions and never prints source row values.
+- Interactive confirmation of the exact candidate migration set plus friendly progress
+  and timing while a rehearsal runs.
+
+### Changed
+
+- Human output now recommends the next useful action, uses compact first-run readiness
+  summaries, respects `NO_COLOR` and `--plain`, and renders singular counts correctly.
+- Bare `rehearsal` opens the guide only in a terminal and remains noninteractive and
+  script-safe when standard input or output is redirected.
+
+### Fixed
+
+- Setup detects unsupported Node.js versions before writing, ignores ports occupied by
+  Docker or SSH forwarding, and rechecks its selected ports immediately before commit.
+- Generated project identifiers are bounded to values accepted by the local runtime.
+
+### Security
+
+- Reviewed sanitization policy bytes are checksum-bound to the active baseline and are
+  revalidated during planning and runtime restore.
+- Draft or incomplete sanitization policies cannot be activated as baselines.
+
+## [0.1.0-beta.2] - 2026-09-15
+
+### Fixed
+
+- Generate `rehearsal.config.mjs` so first-time initialization works in both CommonJS
+  and ESM projects instead of failing when a fresh npm project declares CommonJS.
+- Report the exact table and represented-migration counts after creating a synthetic
+  baseline instead of rendering missing result fields as `undefined`.
+- Keep the copyable getting-started migration bytes identical to its migration-ledger
+  example so the documented runtime replay passes exact-history verification.
+- Install the current prerelease through npm's `beta` tag so new projects do not resolve
+  the superseded bootstrap release from npm's historical `latest` tag.
+
+### Security
+
+- Removed the completed first-package bootstrap credential path. All future publication
+  uses the package's trusted GitHub Actions OIDC publisher and cannot read an npm token.
+
 ## [0.1.0-beta.1] - 2026-09-14
 
 ### Changed
@@ -54,6 +106,8 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.1...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.3...HEAD
+[0.1.0-beta.3]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.2...v0.1.0-beta.3
+[0.1.0-beta.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.1...v0.1.0-beta.2
 [0.1.0-beta.1]: https://github.com/Ddupasquier/rehearsal-db/releases/tag/v0.1.0-beta.1
 [0.1.0-beta.0]: https://github.com/Ddupasquier/rehearsal-db/releases/tag/v0.1.0-beta.0

package/README.md

@@ -77,15 +77,20 @@ invariants. Reset restores and reproves the exact starting data.
 Install the current beta from npm:
 
 ```bash
-npm install --save-dev @rehearsal-db/core
+npm install --save-dev @rehearsal-db/core@beta
 ```
 
 Contributors testing an unreleased change can use `npm link` or install the tarball
 produced by `npm pack` from a local checkout. In a consuming project, the commands are:
 
 ```bash
+npx rehearsal
+npx rehearsal setup
+npx rehearsal setup --write
 npx rehearsal init
 npx rehearsal init --write
+npx rehearsal baseline prepare --records=<safe.ndjson> --ledger=<ledger.json>
+npx rehearsal baseline prepare --records=<safe.ndjson> --ledger=<ledger.json> --write
 npx rehearsal baseline create --records=<safe.ndjson> --ledger=<ledger.json>
 npx rehearsal doctor
 npx rehearsal explain
@@ -102,13 +107,32 @@ npx rehearsal stop
 npx rehearsal discard
 ```
 
-`init` previews a typed `rehearsal.config.ts`; it writes only with `--write` and never
-overwrites an existing file. Review all detected values. Rehearsal intentionally does
-not detect, copy, or enable a hosted project.
+Running `npx rehearsal` in a terminal opens a state-aware guide that shows completed
+setup steps and recommends available actions. The explicit commands remain the stable
+interface for automation and CI.
+
+`setup` previews a conservative first-run scaffold: the Rehearsal configuration, a
+dedicated local-only Supabase configuration on an available port block, and protective
+`.gitignore` entries. It writes only with `--write`, never overwrites project files, and
+does not copy enabled external providers from the application's Supabase configuration.
+After writing, it runs the same readiness checks as `doctor` and shows the remaining
+project-owned inputs. Use `init` when you want to create only the configuration file
+manually.
+
+`baseline prepare` inspects only the shape of explicit local synthetic records and writes
+a fail-closed sanitization-policy draft. Every column remains `REVIEW REQUIRED` until a
+human classifies its sanitization action, generated/identity behavior, and foreign key.
+Drafts cannot be activated, and a reviewed policy is checksum-bound to its baseline.
+
+`init` previews a type-aware ESM `rehearsal.config.mjs`; it writes only with `--write`
+and never overwrites an existing file. The explicit `.mjs` extension makes the generated
+configuration executable in both CommonJS and ESM projects. Review all detected values.
+Rehearsal intentionally does not detect, copy, or enable a hosted project.
 
 `doctor` must end with `READY` before execution. `explain` and `run --dry-run` use the
-same immutable planner and perform no state-changing operations. If migrations are
-pending, execution requires the exact candidate digest printed by the plan:
+same immutable planner and perform no state-changing operations. In a terminal,
+`rehearsal run` displays and confirms the exact candidate set before touching the local
+runtime. Automation supplies the digest explicitly:
 
 ```bash
 npx rehearsal run --confirm-candidates=<sha256>

package/docs/commands.md

@@ -6,8 +6,13 @@ 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 explain`                                          | No                  | Print the immutable execution plan.                       |
@@ -24,12 +29,30 @@ values or credentials.
 | `rehearsal stop`                                             | Runtime only        | Stop this project's local services.                       |
 | `rehearsal discard`                                          | Yes, local only     | Remove only this project's disposable runtime and volume. |
 
-`run` requires the digest from the current candidate set. Any added, removed, reordered,
-or edited migration changes the digest and invalidates the confirmation.
+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 can ask for these paths so they do not need to be supplied as
+flags.
+
+`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.
+
+`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.

package/docs/configuration.md

@@ -1,6 +1,8 @@
 # Configuration reference
 
-`rehearsal.config.ts` is executable configuration with a strict versioned schema.
+`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.
 
 ```ts

package/docs/getting-started.md

@@ -34,18 +34,30 @@ its labeled local runtime. It does not need a hosted Supabase project or credent
 
 ## 1. Install and initialize
 
+Confirm this shell is running the supported Node.js major before installing:
+
+```bash
+node --version # v24.x
+```
+
 ```bash
-npm install --save-dev @rehearsal-db/core
-npx rehearsal init
+npm install --save-dev @rehearsal-db/core@beta
+npx rehearsal
 ```
 
-`init` is a preview. Read the generated configuration, then explicitly write it:
+Choose **Set up Rehearsal** in the guide. It previews a versioned configuration, a
+dedicated local-only Supabase configuration using available ports, and protective
+`.gitignore` entries before asking permission to write.
+
+The same flow is available noninteractively as an explicit preview and write:
 
 ```bash
-npx rehearsal init --write
+npx rehearsal setup
+npx rehearsal setup --write
 ```
 
-Rehearsal never overwrites an existing configuration.
+Rehearsal never overwrites an existing configuration. For config-only/manual setup, use
+`npx rehearsal init` followed by `npx rehearsal init --write`.
 
 The generated configuration is intentionally incomplete until you review its ports,
 project ID, application commands, and project-owned input paths. Do not run `doctor`
@@ -53,14 +65,14 @@ until the next section's files exist.
 
 ## 2. Add the project-owned inputs
 
-Create the paths named by `rehearsal.config.ts`:
+Review or create the project-owned inputs named by `rehearsal.config.mjs`:
 
-- a dedicated local Supabase `config.toml`;
+- the dedicated local Supabase `config.toml` (`setup` creates a conservative one);
 - a sanitization policy describing every exported field;
 - an active baseline below `.rehearsal/`;
 - an application proof command that exits nonzero when the restored app is wrong.
 
-For the generated default paths:
+If you used config-only `init`, also create the dedicated Supabase config manually:
 
 ```bash
 mkdir -p infrastructure/rehearsal/supabase infrastructure/rehearsal rehearsal
@@ -68,7 +80,7 @@ cp supabase/config.toml infrastructure/rehearsal/supabase/config.toml
 ```
 
 Edit the copied Supabase config. Give it the same unique `project_id`, API port, database
-port, and Studio port used by `rehearsal.config.ts`. Disable services your proof does
+port, and Studio port used by `rehearsal.config.mjs`. Disable services your proof does
 not need. This must remain an unlinked local config; never run `supabase link` from it.
 
 Also replace the generated `application.startCommand`, `application.proofCommand`, and
@@ -79,13 +91,29 @@ Start with synthetic rows shaped like your schema. Do not start onboarding with
 production data. The following SQL, policy, row, and ledger form one matched example;
 do not mix them with differently shaped snippets.
 
+If you already have the safe NDJSON rows and migration ledger, Rehearsal can enumerate
+their table and column shape into a fail-closed policy draft without printing values:
+
+```bash
+npx rehearsal baseline prepare \
+  --records=rehearsal/synthetic-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json
+npx rehearsal baseline prepare \
+  --records=rehearsal/synthetic-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json \
+  --write
+```
+
+Review every `REVIEW REQUIRED` field, replace it with correct metadata, and remove
+`"draft": true` only after that review. Rehearsal refuses to activate a draft.
+
 Historical migration `supabase/migrations/20260101000000_create_widgets.sql`:
 
 ```sql
 create table public.widgets (
-  id bigint generated by default as identity primary key,
-  name text not null,
-  created_at timestamptz not null default now()
+	id bigint generated by default as identity primary key,
+	name text not null,
+	created_at timestamptz not null default now()
 );
 
 insert into storage.buckets (id, name, public)
@@ -238,7 +266,8 @@ stops only this project's runtime.
 
 ## Generated files
 
-- `rehearsal.config.ts` is written only by `init --write`.
+- `rehearsal.config.mjs` is written only by `init --write`. Its explicit ESM extension
+  works whether the consuming project's `package.json` uses CommonJS or ESM.
 - `.rehearsal/generations/<id>/` contains one immutable baseline generation.
 - `.rehearsal/current` selects the active generation atomically.
 - `.rehearsal/runtime/` contains the disposable local Supabase project and receipts.

package/docs/production-source.md

@@ -22,7 +22,7 @@ never row bodies.
 
 ## What not to do
 
-- Do not point `rehearsal.config.ts` at a hosted URL.
+- Do not point `rehearsal.config.mjs` at a hosted URL.
 - Do not put a production connection string in `.rehearsal/runtime.env`.
 - Do not grant table-wide access merely because a view is inconvenient.
 - Do not commit sanitized baselines; sanitized data is still data.

package/docs/releasing.md

@@ -5,48 +5,27 @@ environment. The workflow builds and hashes the candidate before the environment
 approval gate, then publishes those exact bytes with npm provenance. A local working
 tree is never the release source.
 
-The initial publishable `0.1.0-beta.1` release branch is the first change allowed to set
-`"private": false`. Publication still requires the exact protected-main tag, prerelease
-flag, artifact checks, and protected `npm` environment gate described below.
-
 `0.1.0-beta.0` was prepared under the unavailable `@rehearsal` npm scope and was never
 published. `0.1.0-beta.1` supersedes that candidate under `@rehearsal-db/core` without
 rewriting the earlier Git tag or GitHub prerelease.
 
-## One-time first-package bootstrap
+## Trusted publication boundary
 
-npm trusted publishing and staged publishing are package-level settings, so they cannot
-be configured until `@rehearsal-db/core` exists in the registry. The first public version has
-a deliberately narrower bootstrap path:
+`@rehearsal-db/core` trusts only the GitHub Actions publisher for repository
+`Ddupasquier/rehearsal-db`, workflow `publish.yml`, and environment `npm`. The publish job
+requests a short-lived GitHub OIDC identity after the protected environment approval;
+it does not read an npm token or retain a registry credential. Package publishing access
+requires 2FA and disallows bypass tokens.
 
-1. The npm owner enables 2FA and creates or confirms the public `@rehearsal-db` organization
-   scope. Do not send a password, OTP, recovery code, or access token to another person.
-2. After the reviewed release change reaches protected `main`, the owner creates the
-   exact `v0.1.0-beta.1` GitHub release and marks it as a prerelease. The prepare job runs without npm credentials,
-   packs the tag, and uploads its versioned tarball plus SHA-1 and SHA-256 metadata. The
-   publish job waits at the protected environment and cannot run yet.
-3. The owner downloads or inspects that prepared artifact, confirms its version and
-   checksum, and explicitly authorizes those exact bytes.
-4. Only then, the owner creates a short-lived granular npm token with read/write access
-   limited to the `@rehearsal-db` scope and **Bypass 2FA** enabled. npm requires that bypass
-   for a non-interactive first publish; the environment approval remains the human
-   release gate. Store the token only as the `NPM_TOKEN` secret in the protected GitHub
-   `npm` environment.
-5. The owner approves the waiting `npm` deployment. GitHub Actions publishes the exact
-   uploaded tarball with provenance. The workflow
-   refuses to use the bootstrap secret for any version other than `0.1.0-beta.1`.
-6. Immediately after the registry verification passes, the owner deletes the GitHub
-   environment secret and revokes the temporary npm token.
-7. From the new package's npm settings, configure the trusted GitHub Actions publisher
-   for repository `Ddupasquier/rehearsal-db`, workflow `publish.yml`, and environment
-   `npm`. Allow direct `npm publish` for this workflow because the protected GitHub
-   environment supplies the human gate. A later switch to npm staged publication must
-   change and prove the workflow before narrowing the trusted publisher permission.
-8. Set package publishing access to require 2FA and disallow traditional tokens.
+The initial `0.1.0-beta.1` package creation required a one-time bootstrap credential
+because npm cannot configure a trusted publisher before a package exists. That
+credential is not part of the maintained release architecture: it was deleted from the
+GitHub environment after publication, must remain revoked at npm, and cannot be consumed
+by this workflow.
 
-This bootstrap token is a one-release compromise imposed by npm's package-creation
-boundary. It is never committed, printed, copied into a ticket, or retained for later
-versions.
+Direct `npm publish` is allowed only for this trusted publisher because the protected
+GitHub `npm` environment supplies the human gate. A later switch to npm staged
+publication must change and prove the workflow before narrowing that permission.
 
 ## Every release candidate
 
@@ -66,7 +45,9 @@ versions.
    the approved version and checksum.
 10. Verify public visibility, ownership, provenance, registry SHA-1, README rendering,
     exact-version clean installation, CLI execution, signatures, and the unrelated
-    installed Docker fixture.
+    installed Docker fixture. Allow up to six minutes for a first package to propagate
+    through the public registry before classifying a missing packument as a release
+    failure.
 11. Replace consuming projects' temporary Git/archive references only on their own
     protected integration branches and rerun their complete verification.
 

package/docs/sanitization.md

@@ -13,6 +13,12 @@ Every exported field should receive one action:
 
 Fail if a new column is unclassified. Do not default unknown fields to `KEEP`.
 
+For runtime restore, each included column must also classify whether it is generated,
+whether it is an identity column, and its foreign-key target or explicit absence. Run
+`rehearsal baseline prepare` to create a shape-only draft from synthetic NDJSON. The
+draft uses `REVIEW REQUIRED` placeholders and cannot be activated until they are
+replaced and the `draft` marker is removed.
+
 The package exports `validateSanitizationCoverage` and
 `applySanitizationAction` as generic primitives:
 
@@ -67,3 +73,7 @@ Before activation, verify:
 
 Completeness is not correctness. Human review of the policy and export boundary remains
 mandatory before any real source is introduced.
+
+The exact reviewed policy bytes are checksum-bound to the active baseline. Planning,
+candidate inspection, and runtime restore refuse to continue if that file later changes;
+build a new reviewed baseline instead of editing the active policy in place.

package/docs/troubleshooting.md

@@ -1,5 +1,19 @@
 # Troubleshooting
 
+## 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`.
@@ -7,8 +21,10 @@ Restarting the computer is rarely necessary.
 
 ## A port is already in use
 
-Choose three unique non-privileged ports in config and mirror them in the dedicated
-Supabase config. Do not stop an unrelated database to make the default ports fit.
+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. Do not stop an unrelated database to make defaults fit.
 
 ## Baseline checksum mismatch
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "private": false,
   "description": "Safely rehearse Supabase migrations against sanitized, production-shaped PostgreSQL data.",
   "repository": {

package/scripts/lib/rehearsal/baseline_builder.mjs

@@ -19,6 +19,7 @@ import {
   createMigrationReplayReceipt,
   readMigrationSourceBundle,
 } from "./migration_history.mjs";
+import { validateRuntimeSanitizationPolicy } from "./sanitization_policy.mjs";
 
 const resolveProjectInput = (projectRoot, value, label) => {
   if (typeof value !== "string" || value.trim() === "") {
@@ -103,10 +104,9 @@ export const createSyntheticBaselineFromFiles = async ({
         })),
       )
     : [];
-  const policy = JSON.parse(policyBytes.toString("utf8"));
-  if (!Array.isArray(policy.tables)) {
-    throw new Error("The configured sanitization policy does not list tables.");
-  }
+  const policy = validateRuntimeSanitizationPolicy(
+    JSON.parse(policyBytes.toString("utf8")),
+  );
   const expectedTables = policy.tables
     .filter((table) => table.sourceRows !== "EXCLUDE")
     .map((table) => table.name);
@@ -117,6 +117,11 @@ export const createSyntheticBaselineFromFiles = async ({
     JSON.parse(ledgerBytes.toString("utf8")),
     "Synthetic migration ledger",
   );
+  if (policy.migrationCutoff !== sourceMigrationHistory.at(-1).version) {
+    throw new Error(
+      `The sanitization policy cutoff ${policy.migrationCutoff} does not match migration ledger cutoff ${sourceMigrationHistory.at(-1).version}.`,
+    );
+  }
   const migrationFiles = await readMigrationSourceBundle({
     directory: new URL(
       "./",
@@ -148,8 +153,8 @@ export const createSyntheticBaselineFromFiles = async ({
   return {
     generationId,
     migrationCutoff: baseline.migrationCutoff,
-    migrationCount: baseline.migrationCount,
+    migrationCount: Object.keys(baseline.migrations).length,
     rowCount: baseline.rowCount,
-    tableCount: baseline.tableCount,
+    tableCount: Object.keys(baseline.tableCounts).length,
   };
 };