@rehearsal-db/core 0.1.0-beta.8 → 0.1.0-rc.1

package/dist/src/targets/supabase_environment.mjs

@@ -0,0 +1,162 @@
+/**
+ * Purpose: Start and inspect local-only Supabase workdirs without inheriting hosted
+ * credentials. Do not run directly; this module is reusable script infrastructure.
+ */
+import { spawnSync } from "node:child_process";
+import { createCleanProcessEnvironment, } from "../shared/process_environment.mjs";
+export const parseSupabaseStatusEnvironment = (output) => {
+    const values = {};
+    for (const line of output.split("\n")) {
+        const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/u);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rawValue = match[2];
+        if (key === undefined || rawValue === undefined)
+            continue;
+        let value = rawValue.trim();
+        if (value.startsWith('"') && value.endsWith('"')) {
+            const parsed = JSON.parse(value);
+            if (typeof parsed !== "string")
+                continue;
+            value = parsed;
+        }
+        values[key] = value;
+    }
+    return values;
+};
+export const parseLocalSupabaseEnvironment = (output) => {
+    const values = parseSupabaseStatusEnvironment(output);
+    const required = (label, value) => {
+        if (!value)
+            throw new Error(`Local Supabase status omitted its ${label}.`);
+        return value;
+    };
+    const apiUrl = required("API URL", values.API_URL);
+    const databaseUrl = required("database URL", values.DB_URL);
+    const publishableKey = required("publishable key", values.PUBLISHABLE_KEY ?? values.ANON_KEY);
+    const serviceRoleKey = required("service-role key", values.SERVICE_ROLE_KEY ?? values.SECRET_KEY);
+    const api = new URL(apiUrl);
+    const database = new URL(databaseUrl);
+    const loopbackHosts = ["127.0.0.1", "::1", "localhost"];
+    if (!loopbackHosts.includes(api.hostname) ||
+        !loopbackHosts.includes(database.hostname) ||
+        !["postgres:", "postgresql:"].includes(database.protocol)) {
+        throw new Error("Refusing to use a non-local Supabase status target.");
+    }
+    const databaseName = decodeURIComponent(database.pathname.replace(/^\//u, ""));
+    if (!database.port ||
+        !databaseName ||
+        !database.username ||
+        !database.password) {
+        throw new Error("Local Supabase status returned an incomplete database URL.");
+    }
+    return {
+        apiUrl,
+        databaseUrl,
+        publishableKey,
+        serviceRoleKey,
+        studioUrl: values.STUDIO_URL,
+        databaseHost: database.hostname,
+        databasePort: database.port,
+        databaseName,
+        databaseUser: decodeURIComponent(database.username),
+        databasePassword: decodeURIComponent(database.password),
+    };
+};
+export const runLocalCommand = (command, args, { capture = false, cwd = process.cwd(), input, environment = {}, maxBuffer = 16 * 1024 * 1024, } = {}) => {
+    const shouldPipe = capture || input !== undefined;
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        env: createCleanProcessEnvironment({ overrides: environment }),
+        input,
+        maxBuffer,
+        stdio: shouldPipe ? ["pipe", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        const detail = [result.stdout, result.stderr]
+            .filter(Boolean)
+            .join("\n")
+            .trim();
+        throw new Error(`${command} ${args.join(" ")} failed${detail ? `:\n${detail}` : "."}`);
+    }
+    return result.stdout ?? "";
+};
+export const localCommandSucceeds = (command, args, { cwd = process.cwd(), environment = {}, } = {}) => spawnSync(command, args, {
+    cwd,
+    env: createCleanProcessEnvironment({ overrides: environment }),
+    stdio: "ignore",
+}).status === 0;
+export const ensureLocalContainerRuntime = ({ cwd = process.cwd(), autoStartColima = true, } = {}) => {
+    if (localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    if (autoStartColima && localCommandSucceeds("colima", ["version"], { cwd })) {
+        runLocalCommand("colima", ["start"], { cwd });
+    }
+    if (!localCommandSucceeds("docker", ["info"], { cwd })) {
+        throw new Error("A local Docker-compatible runtime is required. Install Docker or Colima, then rerun the command.");
+    }
+};
+const withWorkdir = (args, workdir) => (workdir ? [...args, "--workdir", workdir] : [...args]);
+export const readLocalSupabaseEnvironment = ({ cwd, workdir, environment = {}, } = {}) => {
+    const output = runLocalCommand("supabase", withWorkdir(["status", "-o", "env"], workdir), { capture: true, cwd, environment });
+    return parseLocalSupabaseEnvironment(output);
+};
+export const startLocalSupabase = ({ cwd, workdir, exclude = [], environment = {}, applyMigrations = true, autoStartColima = true, } = {}) => {
+    ensureLocalContainerRuntime({ cwd, autoStartColima });
+    const startArguments = withWorkdir(["start", ...(exclude.length ? ["--exclude", exclude.join(",")] : [])], workdir);
+    runLocalCommand("supabase", startArguments, {
+        capture: true,
+        cwd,
+        environment,
+    });
+    if (applyMigrations) {
+        runLocalCommand("supabase", withWorkdir(["migration", "up", "--local"], workdir), { capture: true, cwd, environment });
+    }
+    return readLocalSupabaseEnvironment({ cwd, workdir, environment });
+};
+export const stopLocalSupabase = ({ cwd, workdir, environment = {}, } = {}) => {
+    if (!localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    runLocalCommand("supabase", withWorkdir(["stop"], workdir), {
+        cwd,
+        environment,
+    });
+};
+export const removeLocalSupabaseProjectResources = ({ cwd = process.cwd(), projectId, } = {}) => {
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/u.test(projectId ?? "")) {
+        throw new Error("Refusing to remove local Supabase resources without an exact safe project id.");
+    }
+    const label = `com.supabase.cli.project=${projectId}`;
+    const list = (resource, format) => runLocalCommand("docker", [resource, "ls", "--filter", `label=${label}`, "--format", format], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const containers = runLocalCommand("docker", ["ps", "--all", "--filter", `label=${label}`, "--format", "{{.ID}}"], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (containers.length) {
+        runLocalCommand("docker", ["rm", "--force", ...containers], {
+            capture: true,
+            cwd,
+        });
+    }
+    const volumes = list("volume", "{{.Name}}");
+    if (volumes.length) {
+        runLocalCommand("docker", ["volume", "rm", "--force", ...volumes], {
+            capture: true,
+            cwd,
+        });
+    }
+    const networks = list("network", "{{.ID}}");
+    if (networks.length) {
+        runLocalCommand("docker", ["network", "rm", ...networks], {
+            capture: true,
+            cwd,
+        });
+    }
+};

package/dist/src/targets/target.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+declare const TARGETS: Readonly<{
+    supabase: Readonly<{
+        id: "supabase";
+        label: "Supabase";
+    }>;
+    postgresql: Readonly<{
+        id: "postgresql";
+        label: "PostgreSQL";
+    }>;
+}>;
+export type RehearsalRuntimeTargetId = keyof typeof TARGETS;
+export type RehearsalRuntimeTarget = (typeof TARGETS)[RehearsalRuntimeTargetId];
+export interface RuntimeInvocation {
+    readonly action: string;
+    readonly configPath: string | undefined;
+    readonly confirmation: string | undefined;
+}
+export interface RuntimeManagerArguments {
+    managerPath: string;
+    action: string;
+    configPath?: string;
+    confirmation?: string;
+}
+export declare const REHEARSAL_RUNTIME_TARGETS: readonly ("postgresql" | "supabase")[];
+export declare const parseRuntimeInvocation: (arguments_?: readonly string[]) => RuntimeInvocation;
+export declare const buildRuntimeManagerArguments: ({ managerPath, action, configPath, confirmation, }: RuntimeManagerArguments) => string[];
+export declare const resolveRuntimeTarget: (value?: unknown) => RehearsalRuntimeTarget;
+export {};

package/dist/src/targets/target.mjs

@@ -0,0 +1,39 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+const TARGETS = Object.freeze({
+    supabase: Object.freeze({
+        id: "supabase",
+        label: "Supabase",
+    }),
+    postgresql: Object.freeze({
+        id: "postgresql",
+        label: "PostgreSQL",
+    }),
+});
+export const REHEARSAL_RUNTIME_TARGETS = Object.freeze(Object.keys(TARGETS));
+export const parseRuntimeInvocation = (arguments_ = process.argv.slice(2)) => {
+    const action = arguments_.find((argument) => !argument.startsWith("--"));
+    const valueAfter = (prefix) => arguments_
+        .find((argument) => argument.startsWith(prefix))
+        ?.slice(prefix.length);
+    return Object.freeze({
+        action: action ?? "status",
+        configPath: valueAfter("--config="),
+        confirmation: valueAfter("--confirm-candidates="),
+    });
+};
+export const buildRuntimeManagerArguments = ({ managerPath, action, configPath, confirmation, }) => [
+    managerPath,
+    action,
+    ...(configPath ? [`--config=${configPath}`] : []),
+    ...(confirmation ? [`--confirm-candidates=${confirmation}`] : []),
+];
+export const resolveRuntimeTarget = (value = "supabase") => {
+    if (typeof value !== "string" || !Object.hasOwn(TARGETS, value)) {
+        throw new Error(`Unsupported Rehearsal runtime target: ${String(value)}. Supported targets: ${REHEARSAL_RUNTIME_TARGETS.join(", ")}.`);
+    }
+    return TARGETS[value];
+};

package/docs/README.md

@@ -0,0 +1,40 @@
+# Rehearsal documentation
+
+Welcome. You do not need to read this documentation from top to bottom. Choose what you
+want to accomplish and follow that path.
+
+## Start here
+
+| Your goal                           | Best next page                        |
+| ----------------------------------- | ------------------------------------- |
+| Add Rehearsal to a project          | [Getting started](getting-started.md) |
+| Try it in a disposable project      | [Hands-on tutorial](tutorial.md)      |
+| Fix a setup or runtime problem      | [Troubleshooting](troubleshooting.md) |
+| Browse the friendlier web-docs home | [Documentation home](index.md)        |
+
+## Work safely
+
+- [Baselines](baselines.md) — the verified starting copy
+- [Sanitization](sanitization.md) — what may enter that copy
+- [Production-shaped preparation](production-source.md) — the optional source boundary
+- [Security model](security-model.md) — the independent safety barriers
+- [Standalone workflow](standalone-workflow.md) — the complete declarative contract
+
+## Look something up
+
+- [CLI commands](commands.md)
+- [Configuration](configuration.md)
+- [TypeScript](typescript.md)
+- [Runtime and identity policies](runtime-policies.md)
+- [Database adapters](adapters.md)
+- [Glossary](glossary.md)
+
+## Follow the project
+
+- [Roadmap](roadmap.md)
+- [Stability and the first stable release](stability.md)
+- [Repository architecture](architecture.md)
+- [Release process](releasing.md)
+
+To preview the styled documentation locally, run `npm run docs:preview`, then open the
+address it prints.

package/docs/adapters.md

@@ -5,8 +5,17 @@ database driver starts and manages a kind of local database, such as Supabase or
 PostgreSQL. A project
 runtime adapter adds narrowly scoped application behavior after that database is ready.
 
-Adapters are an advanced escape hatch for project-specific restore behavior. They live
-in the consuming repository and are loaded only from the path declared in config.
+Adapters are a backward-compatible advanced escape hatch for project-specific restore
+behavior. New projects should first use `runtimePolicy`, `identityPolicy`, application
+environment mappings, HTTP proofs, and dependent targets. Those package-owned paths are
+portable and reject executable declarations.
+
+If the application needs another database, use
+[`dependentTargets`](configuration.md#dependent-databases) instead of opening a second
+connection or managing another container from a runtime adapter. Rehearsal owns that
+database's identity, ports, lifecycle, verification order, and cleanup preview; the
+project declares its baseline and proof. `prepareCommand` remains available for legacy
+schema-specific transformations.
 
 An adapter may export:
 
@@ -18,10 +27,10 @@ An adapter may export:
 Each hook must return the documented status shape expected by the engine. It receives a
 local SQL executor; it should not open another connection or perform network access.
 
-Good adapter responsibilities include mapping sanitized application identities to local
-Auth users and verifying a domain-specific relationship after restore. Bad responsibilities
-include extracting production data, embedding credentials, contacting hosted services,
-or weakening the engine's local-only checks.
+Use an adapter only when the documented declarative formats clearly reject a required
+local behavior. Extracting production data, embedding credentials, contacting hosted
+services, weakening local-only checks, or reimplementing container lifecycle is never an
+adapter responsibility.
 
 Keep adapters small, deterministic, tested, and visibly project-owned. If a behavior is
 generic across unrelated projects, propose it for the engine instead of copying it into

package/docs/architecture.md

@@ -0,0 +1,183 @@
+# Repository architecture
+
+Rehearsal separates shipped product code, repository automation, tests, fixtures, and
+documentation so each file has one obvious home.
+
+```text
+rehearsal-db/
+├── src/                    TypeScript product source
+│   ├── application/       application lifecycle and HTTP proofs
+│   ├── baseline/          sanitized baseline creation and validation
+│   ├── cli/               the `rehearsal` executable
+│   ├── identity/          local account and Storage association
+│   ├── project/           configuration, setup, and support
+│   ├── runtime/           plans and disposable-runtime lifecycle
+│   ├── shared/            small target-neutral utilities
+│   ├── source/            approved source access and refresh
+│   └── targets/           PostgreSQL and Supabase adapters
+├── scripts/
+│   ├── build/             clean TypeScript compilation helpers
+│   ├── install/           TypeScript install-hook source
+│   ├── runtime/           TypeScript runtime-launcher source
+│   └── verification/      repository-only package and fixture proofs
+├── dist/                   generated ESM and declaration output; never edit directly
+├── types/                  compatibility entry point for generated declarations
+├── tests/
+│   ├── unit/              mirrors the `src/` domains
+│   ├── integration/       multi-module and terminal behavior
+│   ├── contracts/         public documentation and package promises
+│   └── fixtures/          disposable example projects
+└── docs/                  user and maintainer documentation
+```
+
+## Boundaries
+
+- `src/` must never import from tests or repository-only verification scripts.
+- `dist/` is rebuilt from TypeScript before tests and packaging; never hand-edit it.
+- Database-specific lifecycle behavior belongs in `src/targets/`.
+- `scripts/verification/` is never included in the npm package.
+- Public consumers use only the paths declared in `package.json#exports`.
+- Unit tests mirror their source domain. Cross-domain workflows belong in
+  `tests/integration/`; durable public promises belong in `tests/contracts/`.
+
+## CLI modules
+
+The executable is split by responsibility so no command file becomes a second
+application layer. Scripted commands and the interactive guide resolve through the same
+typed registry and produce the same result contract:
+
+- `rehearsal.mts` owns process lifecycle, project locking, guided-loop coordination, and
+  top-level error handling. It does not implement commands.
+- `arguments.mts` owns the command-line contract and mutation classification.
+- `command_contract.mts`, `command_registry.mts`, and `command_output.mts` define command
+  context, handler selection, stable JSON envelopes, human rendering, and exit codes.
+- `*_command_handlers.mts` and `runtime_action_handlers.mts` group handlers by project,
+  source, identity, inspection, application, or runtime responsibility.
+- `cli_commands.mts` composes those focused families in precedence order without
+  implementing their behavior.
+- `guided.mts` owns the interactive home screen and first-run questions.
+- `runtime_commands.mts` coordinates local runtimes and project proofs.
+- `source_commands.mts` coordinates approved source access and refresh.
+- `renderers.mts` formats human-readable results without changing state.
+- `terminal.mts` owns prompts, colors, and terminal exit behavior.
+
+Command handlers receive an explicit context containing parsed flags, selected config,
+guided state, and session-local caches. They return a rendered, text, or silent result;
+only the shared output boundary creates JSON envelopes or writes final human output.
+Session caches never appear in the public parsed-flags type.
+
+Repository contracts keep the process entry point at 300 lines or fewer and every
+handler-family module at 350 lines or fewer. A new command belongs in the narrowest
+existing family, or in a new focused family when it represents a genuinely separate
+responsibility.
+
+## Configuration pipeline
+
+The stable `project/configuration.mts` facade keeps existing imports compatible while
+configuration work moves through explicit phases:
+
+1. `configuration_discovery.mts` selects one supported project-owned config path.
+2. `configuration_schema.mts` validates the raw object shape and rejects unknown keys.
+3. `configuration_normalization.mts` applies defaults and semantic safety constraints.
+4. `configuration_resolution.mts` resolves owned paths from the project root and checks
+   destructive-operation boundaries.
+
+The public contract/defaults, primitive validators, project detection, and starter
+rendering have their own focused modules. `NormalizedRehearsalConfig` is inferred from
+the normalizer, while the package's public declarations are emitted from the same
+TypeScript implementation. Repository contracts keep the facade at 50 lines or fewer
+and each configuration phase at 700 lines or fewer.
+
+## Installed-consumer verification
+
+Repository verification installs the package tarball into disposable projects; it must
+not import unpublished product source by accident. One scenario catalog drives both the
+individual fixture commands and `npm run release:verify`.
+
+- `scenarios/artifact.mjs` selects or packs one tarball, reads its package identity, and
+  records its SHA-256 before installation.
+- `scenarios/workspace.mjs` creates and removes only scenario-owned scratch roots.
+- `scenarios/process.mjs` starts commands with inherited credentials removed unless a
+  scenario explicitly supplies a safe value.
+- `scenarios/application_session.mjs` owns persistent application and terminal-session
+  checks.
+- `scenarios/catalog.mjs` is the sole ordered list of installed-consumer scenarios.
+- Fixture files contain only the target setup and assertions unique to that scenario.
+
+Each scenario remains independently runnable through its `test:fixture:*` script. The
+complete release gate runs every catalog entry against the same immutable tarball and
+writes its version, SHA-256, tool environment, commands, timings, and results under
+`test-results/release-gate/`.
+
+## Runtime lifecycle
+
+`runtime/lifecycle_engine.mts` owns the target-neutral lifecycle contract. Both
+PostgreSQL and Supabase use it to dispatch commands, verify active baseline inputs,
+calculate and confirm the exact migration set, write target-bound receipts, validate
+runtime markers, and roll back a failed reset or migration without hiding the original
+failure.
+
+The files in `src/targets/` remain drivers. They prove ownership before deleting local
+resources and implement only the behavior that genuinely differs: Docker PostgreSQL
+containers and SQL setup on one side; Supabase CLI, Auth, Storage, and generated config
+on the other. An ordinary `stop` never enters rollback or discard, so later `start`
+preserves the sandbox database and Storage contents.
+
+Repository contracts keep each target driver at 900 lines or fewer and the shared
+lifecycle engine at 300 lines or fewer. A new database target must use this lifecycle
+boundary rather than copying an existing driver's orchestration.
+
+## Identity claim pipeline
+
+The stable `identity/claim.mts` facade exposes policy validation, deterministic planning,
+and confirmed execution while keeping those responsibilities separate:
+
+1. `claim_contract.mts` defines the normalized policy, plan, database, and receipt types.
+2. `claim_policy.mts` validates and normalizes the reviewed declaration.
+3. `claim_plan.mts` binds the local matcher value to an immutable redacted review and
+   digest without opening a database or Storage connection.
+4. `claim_sql.mts` generates identifier-safe relational, JSON, signup-default, and path
+   SQL without executing it.
+5. `claim_identity_lookup.mts` performs read-only local Auth and reference discovery.
+6. `claim_verification.mts` checks signup defaults and token-hook claim shapes.
+7. `claim_executor.mts` alone owns the database transaction, Storage staging, rollback,
+   commit, old-object cleanup, and final receipt.
+8. `connect.mts` performs read-only, provider-neutral sign-in discovery and produces the
+   redacted preview used by the interactive copied-account connection.
+
+Repository contracts keep the facade at 50 lines or fewer and every identity-claim
+stage at 600 lines or fewer. Provider callbacks and consumer application behavior stay
+outside this pipeline.
+
+## Privacy rule pipeline
+
+The stable `baseline/privacy_engine.mts` facade preserves the documented privacy import
+path while policy work is divided into fail-closed typed stages:
+
+1. `privacy_contract.mts` defines normalized policy and execution types.
+2. `privacy_recipe_validation.mts` normalizes only reviewed rule shapes;
+   `privacy_policy.mts` validates complete policy structure.
+3. `privacy_dependency_graph.mts` checks owner bindings, path mappings, sanitized digest
+   inputs, cycles, and shared date groups.
+4. `privacy_transforms.mts` implements deterministic pseudonyms and bounded paths.
+5. `privacy_rule_registry.mts` explicitly registers every action and derivation kind;
+   unknown kinds have no fallback execution path.
+6. `privacy_structured_json.mts` owns bounded object, array, union, and dictionary rules.
+7. `privacy_pipeline.mts` resolves reviewed bindings and executes rows, while
+   `privacy_key.mts` owns the local secret-file boundary.
+
+Repository contracts keep the facade at 50 lines or fewer and every privacy stage at
+700 lines or fewer. Adding a rule requires its normalized type, validator, registered
+handler, focused boundary tests, and documentation—without widening policy version 2.
+
+## Adding something new
+
+1. Put policy and reusable behavior in the domain that owns it.
+2. Put target-specific implementation behind the target boundary.
+3. Add its focused test under the matching `tests/unit/` domain.
+4. Add an integration or contract test only when behavior crosses domains or becomes a
+   public promise.
+5. Update the documentation map when adding a new guide.
+
+Run `npm run build` after changing TypeScript source. Tests import the generated package
+code so the same JavaScript boundary consumers install is exercised locally.

package/docs/baselines.md

@@ -15,6 +15,20 @@ safe row.
 { "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }
 ```
 
+`public` is the default schema. Name another schema explicitly when needed:
+
+```json
+{
+  "schema": "app_api",
+  "table": "publication_products",
+  "row": { "id": 1 }
+}
+```
+
+Use the same optional `schema` on that table in the sanitization policy. Rehearsal keeps
+same-named tables in different schemas separate. An undeclared schema or table is
+rejected.
+
 Use synthetic or reviewed sanitized values. A `.json` array is not NDJSON and will be
 rejected.
 
@@ -67,7 +81,14 @@ npx rehearsal baseline create \
 ```
 
 Add `--assets=rehearsal/assets.json` only when using approved Supabase Storage files.
-Rehearsal validates everything and shows counts before activation. It never extracts data.
+Rehearsal validates everything and shows counts before activation. These commands read
+project-local files only.
+
+The separately enabled `baseline refresh` command can stream a reviewed source through
+privacy policy version 2. It stages a private generation, verifies capacity, counts,
+checksums, source schema, migration evidence, privacy coverage, and drift, then switches
+the active symlink atomically. Failure or interruption removes the staged generation and
+preserves the prior active baseline and edited runtime.
 
 ## Why historical migrations are locked