@rehearsal-db/core 0.1.0-beta.2 → 0.1.0-beta.4

package/CHANGELOG.md

@@ -5,6 +5,52 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.4] - 2026-10-01
+
+### Added
+
+- A persistent guided session with polished terminal prompts, interactive policy review,
+  concise runtime receipts, expandable technical details, and real-PTY regression tests.
+
+### Changed
+
+- Guided menus now place the next recommended action first and automatically re-inspect
+  project state after every completed step while preserving plain and non-TTY modes.
+
+## [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
@@ -72,7 +118,9 @@ 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.2...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.4...HEAD
+[0.1.0-beta.4]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.3...v0.1.0-beta.4
+[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

@@ -84,8 +84,13 @@ Contributors testing an unreleased change can use `npm link` or install the tarb
 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,14 +107,34 @@ npx rehearsal stop
 npx rehearsal discard
 ```
 
+Running `npx rehearsal` in a terminal opens a state-aware guide that shows completed
+setup steps and recommends available actions. The guide stays open after each action,
+re-inspects the project, and advances to the next useful step. It includes an interactive
+column-by-column policy reviewer, concise completion receipts, and optional technical
+details. 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,38 @@ 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.
+
+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
+requires explicit action, generated, identity, and foreign-key decisions; the guide does
+not silently infer them.
+
+`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.

package/docs/getting-started.md

@@ -34,18 +34,31 @@ 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@beta
-npx rehearsal init
+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 guide remains open afterward
+and recommends the next incomplete stage.
+
+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 +66,14 @@ until the next section's files exist.
 
 ## 2. Add the project-owned inputs
 
-Create the paths named by `rehearsal.config.mjs`:
+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
@@ -79,6 +92,27 @@ 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
+```
+
+After creating the draft, choose **Review the script** in the guide. Rehearsal walks each
+column through sanitization action, generated status, identity status, and optional
+foreign-key metadata. Every answer is explicit, the complete policy is validated before
+writing, and the original draft is replaced only if it did not change during review.
+
+For noninteractive workflows, review every `REVIEW REQUIRED` field directly and remove
+`"draft": true` only after that review. Rehearsal refuses to activate a draft.
+
 Historical migration `supabase/migrations/20260101000000_create_widgets.sql`:
 
 ```sql

package/docs/releasing.md

@@ -37,7 +37,7 @@ publication must change and prove the workflow before narrowing that permission.
    onboarding. Correct and retest the first confusing, missing, or wrong instruction.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
-   executable, and zero-runtime-dependency result.
+   executable, declared runtime dependency inventory, and dependency audit result.
 7. Obtain explicit publication authorization for that exact version and artifact.
 8. Merge the approved release commit through protected `main` and create the exact
    `v<package-version>` tag and GitHub release.

package/docs/sanitization.md

@@ -13,6 +13,18 @@ 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.
+
+In an interactive terminal, the guided **Review the script** action completes these
+decisions one column at a time. Replacement-oriented actions are shown first, retaining
+a value is explicitly labeled as sensitive, and no choice is silently inferred. The
+reviewer validates the completed policy and refuses to overwrite a draft changed during
+the session.
+
 The package exports `validateSanitizationCoverage` and
 `applySanitizationAction` as generic primitives:
 
@@ -67,3 +79,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.2",
+  "version": "0.1.0-beta.4",
   "private": false,
   "description": "Safely rehearse Supabase migrations against sanitized, production-shaped PostgreSQL data.",
   "repository": {
@@ -69,8 +69,11 @@
     "database"
   ],
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
   "devDependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.15",
     "prettier": "^3.9.6",
     "vitest": "^4.1.10"
   }

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(
       "./",

package/scripts/lib/rehearsal/baseline_preparation.mjs

@@ -0,0 +1,201 @@
+/**
+ * Purpose: Inspect explicit local synthetic records and migration evidence, then
+ * create a fail-closed sanitization-policy draft for human review.
+ */
+
+import { createReadStream } from "node:fs";
+import { access, mkdir, open, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { loadRehearsalConfig } from "./configuration.mjs";
+import { buildMigrationLedgerInventory } from "./migration_history.mjs";
+
+const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
+
+const resolveProjectInput = (projectRoot, value, label) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} is required.`);
+  }
+  const path = resolve(projectRoot, value);
+  const owned = relative(projectRoot, path);
+  if (
+    owned === "" ||
+    owned === ".." ||
+    owned.startsWith(`..${sep}`) ||
+    isAbsolute(owned)
+  ) {
+    throw new Error(`${label} must be a file inside the project root.`);
+  }
+  return path;
+};
+
+const pathExists = (path) =>
+  access(path)
+    .then(() => true)
+    .catch((error) => {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    });
+
+const inspectSyntheticRecords = async (path) => {
+  const tables = new Map();
+  let rowCount = 0;
+  const lines = createInterface({
+    input: createReadStream(path, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch (error) {
+      throw new Error("Synthetic baseline input contains invalid NDJSON.", {
+        cause: error,
+      });
+    }
+    if (
+      !record ||
+      !identifierPattern.test(record.table ?? "") ||
+      !record.row ||
+      typeof record.row !== "object" ||
+      Array.isArray(record.row)
+    ) {
+      throw new Error("A synthetic baseline record has an invalid shape.");
+    }
+    const columns = Object.keys(record.row);
+    if (
+      columns.length === 0 ||
+      columns.some((column) => !identifierPattern.test(column))
+    ) {
+      throw new Error(
+        `Synthetic baseline table ${record.table} has invalid or empty columns.`,
+      );
+    }
+    const table = tables.get(record.table) ?? {
+      name: record.table,
+      rowCount: 0,
+      columns: new Set(),
+    };
+    table.rowCount += 1;
+    for (const column of columns) table.columns.add(column);
+    tables.set(record.table, table);
+    rowCount += 1;
+  }
+  if (rowCount === 0) {
+    throw new Error("Synthetic baseline input contains no records.");
+  }
+  return {
+    rowCount,
+    tables: [...tables.values()]
+      .sort((left, right) => left.name.localeCompare(right.name))
+      .map((table) => ({
+        name: table.name,
+        rowCount: table.rowCount,
+        columns: [...table.columns].sort(),
+      })),
+  };
+};
+
+const renderPolicyDraft = ({ migrationCutoff, tables }) =>
+  `${JSON.stringify(
+    {
+      policyVersion: 1,
+      draft: true,
+      migrationCutoff,
+      tables: tables.map((table) => ({
+        name: table.name,
+        group: "synthetic",
+        sourceRows: "STREAM AND SANITIZE",
+        columns: table.columns.map((name) => ({
+          name,
+          action: "REVIEW REQUIRED",
+          generated: "REVIEW REQUIRED",
+          identity: "REVIEW REQUIRED",
+          foreignKey: "REVIEW REQUIRED",
+        })),
+      })),
+    },
+    null,
+    2,
+  )}\n`;
+
+export const planBaselinePreparation = async ({
+  projectRoot = process.cwd(),
+  configPath,
+  recordsPath,
+  ledgerPath,
+}) => {
+  const loaded = await loadRehearsalConfig({ projectRoot, configPath });
+  const records = resolveProjectInput(
+    loaded.projectRoot,
+    recordsPath,
+    "Synthetic records path",
+  );
+  const ledger = resolveProjectInput(
+    loaded.projectRoot,
+    ledgerPath,
+    "Migration ledger path",
+  );
+  const [inspection, ledgerRows] = await Promise.all([
+    inspectSyntheticRecords(records),
+    readFile(ledger, "utf8").then(JSON.parse),
+  ]);
+  const migrationHistory = buildMigrationLedgerInventory(
+    ledgerRows,
+    "Synthetic migration ledger",
+  );
+  const destination = loaded.paths.sanitizationPolicy;
+  if (await pathExists(destination)) {
+    throw new Error(
+      `Rehearsal baseline preparation will not overwrite ${relative(loaded.projectRoot, destination)}.`,
+    );
+  }
+  const migrationCutoff = migrationHistory.at(-1).version;
+  return {
+    projectRoot: loaded.projectRoot,
+    destination,
+    destinationRelative: relative(loaded.projectRoot, destination),
+    recordsPath: relative(loaded.projectRoot, records),
+    ledgerPath: relative(loaded.projectRoot, ledger),
+    migrationCutoff,
+    migrationCount: migrationHistory.length,
+    rowCount: inspection.rowCount,
+    tables: inspection.tables,
+    content: renderPolicyDraft({
+      migrationCutoff,
+      tables: inspection.tables,
+    }),
+  };
+};
+
+export const applyBaselinePreparation = async (plan) => {
+  if (await pathExists(plan.destination)) {
+    throw new Error(
+      `Rehearsal baseline preparation will not overwrite ${plan.destinationRelative}.`,
+    );
+  }
+  await mkdir(dirname(plan.destination), { recursive: true, mode: 0o700 });
+  const handle = await open(plan.destination, "wx", 0o600);
+  try {
+    await handle.writeFile(plan.content);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+
+export const summarizeBaselinePreparation = (plan, { mode }) => ({
+  mode,
+  destination: plan.destinationRelative,
+  recordsPath: plan.recordsPath,
+  ledgerPath: plan.ledgerPath,
+  migrationCutoff: plan.migrationCutoff,
+  migrationCount: plan.migrationCount,
+  rowCount: plan.rowCount,
+  tables: plan.tables,
+  nextAction:
+    mode === "written"
+      ? `Review every REVIEW REQUIRED decision in ${plan.destinationRelative}, remove draft only after review, then create the baseline.`
+      : "Review this schema-only summary, then rerun with --write to create the draft.",
+});

package/scripts/lib/rehearsal/configuration.d.mts

@@ -51,7 +51,13 @@ export declare const loadRehearsalConfig: (options?: {
 export declare const inspectDetectedProject: (options?: {
   projectRoot?: string;
 }) => Promise<unknown>;
-export declare const renderDetectedConfig: (detected: unknown) => string;
+export declare const renderDetectedConfig: (
+  detected: unknown,
+  options?: {
+    applicationUrl?: string;
+    ports?: { api: number; database: number; studio: number };
+  },
+) => string;
 export declare const SANITIZATION_ACTIONS: Readonly<{
   KEEP: "KEEP";
   PSEUDONYMIZE: "PSEUDONYMIZE";
@@ -75,6 +81,13 @@ export declare const validateSanitizationCoverage: (options: {
   columnCount: number;
   tables: ReadonlyArray<Record<string, unknown>>;
 }>;
+export declare const validateRuntimeSanitizationPolicy: (
+  policy: unknown,
+) => unknown;
+export declare const readBoundRuntimeSanitizationPolicy: (options: {
+  bytes: Uint8Array | string;
+  expectedSha256: string;
+}) => unknown;
 export declare const applySanitizationAction: (options: {
   action: string;
   value: unknown;

package/scripts/lib/rehearsal/configuration.mjs

@@ -13,7 +13,9 @@ export {
   SANITIZATION_ACTIONS,
   applySanitizationAction,
   normalizeSanitizationAction,
+  readBoundRuntimeSanitizationPolicy,
   validateSanitizationCoverage,
+  validateRuntimeSanitizationPolicy,
 } from "./sanitization_policy.mjs";
 
 export const REHEARSAL_CONFIG_VERSION = 1;
@@ -494,12 +496,15 @@ export const inspectDetectedProject = async ({
       ? "yarn"
       : "npm";
   const scripts = packageJson.scripts ?? {};
+  const normalizedProjectName = String(packageJson.name ?? basename(root))
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/gu, "-")
+    .replace(/^-|-$/gu, "");
+  const projectName =
+    normalizedProjectName.slice(0, 52).replace(/-$/u, "") ||
+    "rehearsal-project";
   return {
-    projectName:
-      String(packageJson.name ?? basename(root))
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/gu, "-")
-        .replace(/^-|-$/gu, "") || "rehearsal-project",
+    projectName,
     packageManager,
     hasSupabaseConfig: await hasPath("supabase/config.toml"),
     hasMigrations: await hasPath("supabase/migrations"),
@@ -515,7 +520,13 @@ export const inspectDetectedProject = async ({
   };
 };
 
-export const renderDetectedConfig = (detected) => `// @ts-check
+export const renderDetectedConfig = (
+  detected,
+  {
+    applicationUrl = "http://localhost:5175",
+    ports = { api: 58321, database: 58322, studio: 58323 },
+  } = {},
+) => `// @ts-check
 import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
@@ -537,11 +548,11 @@ export default defineRehearsalConfig({
 		environmentFile: ".rehearsal/runtime.env",
 	},
 	runtime: {
-		applicationUrl: "http://localhost:5175",
+		applicationUrl: ${JSON.stringify(applicationUrl)},
 		projectId: "${detected.projectName}-rehearsal",
-		apiPort: 58321,
-		databasePort: 58322,
-		studioPort: 58323,
+		apiPort: ${ports.api},
+		databasePort: ${ports.database},
+		studioPort: ${ports.studio},
 	},
 	safety: {
 		allowedHosts: ["127.0.0.1", "::1", "localhost"],