@rehearsal-db/core 0.1.0-beta.13 → 0.1.0-beta.15

package/CHANGELOG.md

@@ -7,6 +7,99 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ### Added
 
+- A strict, no-emit TypeScript gate now checks the first shared runtime utilities and
+  verifies that consumers can compile against Rehearsal's public configuration types.
+- The documentation site now explains the supported TypeScript surface with examples
+  that are compiled and checked against their rendered documentation source.
+- All shipped implementation and executable-helper source now uses TypeScript. Clean
+  builds emit Node-compatible ESM and declarations into the reviewed package boundary,
+  and tests exercise that compiled output rather than an alternate source path.
+- The published build omits repository-only JavaScript source maps while retaining
+  runtime JavaScript and declarations, keeping the installed package compact.
+
+### Fixed
+
+- Packed onboarding chooses an available local port block for preserved configuration
+  fixtures, so unrelated running Rehearsal projects cannot make the isolation test fail.
+
+## [0.1.0-beta.14] - 2026-10-05
+
+### Added
+
+- Packed-package onboarding is now a required CI job. It covers fresh Supabase and
+  PostgreSQL installs, beta.7 configuration preservation, missing credentials, occupied
+  ports, malformed configuration, and non-destructive partial-setup recovery.
+- The independent test lab can run the same first-install boundary against an exact
+  candidate tarball before either database lifecycle.
+- Installation and setup now report the exact active Rehearsal configuration path and
+  explain when a supported existing nested config prevents root-file generation.
+- Packed-package onboarding covers fresh, nested, existing-root, and repeated installs
+  while proving reviewed configuration bytes are preserved.
+- Privacy policy version 2 can explicitly treat nullable owners as non-matches and match
+  an approved owner through any of a bounded list of pseudonymized identity columns.
+- Bounded JSON unions classify each permitted root type, while JSON dictionaries require
+  reviewed runtime-key formats, key actions, value recipes, and item/depth/byte limits.
+- JSON dictionaries can restrict runtime keys to canonical signed integers within an
+  explicit safe-integer range, preserving positive, negative, and reviewed zero keys
+  without widening numeric maps to arbitrary text.
+- Date shifting can explicitly preserve numeric epoch-millisecond representation,
+  including inside structured JSON, while sharing a stable grouped offset with related
+  epoch or ISO-string dates.
+- Bounded scalar enums retain only explicitly reviewed structural strings, finite
+  numbers, or booleans inside ordinary fields and nested JSON declarations, rejecting
+  out-of-domain values without echoing them in diagnostics.
+- Validated strings preserve bounded, case-sensitive structural codes from open domains
+  using a package-owned portable alphabet, refusing credential-shaped and malformed
+  text without consumer regexes, callbacks, or static identifier lists.
+- Keyed hexadecimal and GTIN pseudonyms preserve reviewed database constraints, while
+  fixed-width digest recipes derive fingerprints only from explicitly named sanitized
+  columns and reject missing, excluded, duplicate, or cyclic inputs.
+- A single GTIN recipe can declare reviewed `allowedLengths`, preserving each source
+  value's 8-, 12-, 13-, or 14-digit shape and check digit even inside structured JSON.
+- Keyed URL pseudonyms replace private HTTPS URLs with deterministic, bounded HTTPS
+  loopback paths without retaining source hosts, paths, credentials, queries, or tokens.
+- Bounded binding substitution can retain permitted surrounding text while replacing
+  exact occurrences of a reviewed UUID with its corresponding keyed UUID pseudonym.
+- External PostgreSQL readers can declare a bounded exact allowlist of provider-owned
+  permission groups. Rehearsal verifies safe membership options, group attributes,
+  nesting, view ownership, and the complete effective privilege surface.
+
+### Documentation
+
+- First-time users now have a short recovery table for interrupted setup, failed
+  upgrades, port conflicts, missing OAuth credentials, and low Docker capacity.
+- The configuration guide documents a safe manual move to the project root, separating
+  config-file-relative JavaScript imports from project-root-relative Rehearsal paths.
+- The sanitization guide documents nullable and multi-column ownership, heterogeneous
+  JSON values, runtime-keyed dictionaries, keyed HTTPS replacements, bounded identity
+  substitution, and their fail-closed boundaries.
+
+### Fixed
+
+- Source preparation now stores and reads each target's access receipt and owner-only
+  reader credential under its configured baseline artifact directory. Nested and
+  multi-target state roots no longer collide, and retirement refuses a receipt from a
+  different target root.
+- Supabase Storage source preparation now recursively traverses real folder placeholder
+  entries while keeping the approved prefix, path, depth, object-count, per-object, and
+  total-byte boundaries fail closed.
+- Approved-owner selection now rejects non-finite numeric values in every declared
+  owner column before choosing a privacy branch, including when another column already
+  matches the approved owner.
+- Pseudonymized canonical integer dictionary keys now share the same keyed identity
+  mapping as numeric columns and nested numeric values using the same namespace, so
+  runtime maps keep their reviewed cross-representation joins.
+- External-reader membership mismatches now return a redacted, actionable source
+  authorization refusal instead of an internal-failure diagnostic.
+- All external-reader privilege, expiration, readable-surface, and security-definer
+  denials now use the same `SOURCE_AUTHORIZATION_REFUSED` diagnostic and exit code 3.
+- Identity claims now sequence PostgreSQL reads on their single transaction client,
+  avoiding deprecated overlapping queries and remaining compatible with pg 9.
+
+## [0.1.0-beta.13] - 2026-10-05
+
+### Added
+
 - Runtime and CI compatibility now cover maintained Node.js 22, 24, and 26 releases;
   Node.js 24 LTS remains the recommended default and release-build runtime.
 - Source access policies can use an externally provisioned, database-expiring

package/README.md

@@ -45,7 +45,9 @@ For an ordinary npm application install, Rehearsal safely creates a commented
 `rehearsal.config.mjs` in the project root, adds only its local-artifact entries to
 `.gitignore`, and prepares the isolated local runtime configuration. It detects the
 project name, database target, migration paths, commands, and free ports. Review lines
-marked `CHECK`, then open the guide. Existing files are never overwritten.
+marked `CHECK`, then open the guide. Existing files are never overwritten. If a supported
+root or nested config already exists, Rehearsal reports that active path and does not
+create a competing file; see [Configuration](docs/configuration.md#workspaces-and-custom-paths).
 
 If install scripts are disabled or the workspace root is ambiguous, installation makes
 no guess. Run `npx rehearsal` inside the application and choose **Set the stage** for the
@@ -143,6 +145,7 @@ Reference:
 
 - [CLI commands](docs/commands.md)
 - [Configuration](docs/configuration.md)
+- [TypeScript types](docs/typescript.md)
 - [Baselines](docs/baselines.md)
 - [Sanitization](docs/sanitization.md)
 - [Security model](docs/security-model.md)

package/dist/package.json

@@ -0,0 +1,100 @@
+{
+    "name": "@rehearsal-db/core",
+    "version": "0.1.0-beta.15",
+    "private": false,
+    "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
+    },
+    "homepage": "https://ddupasquier.github.io/rehearsal-db/",
+    "publishConfig": {
+        "access": "public",
+        "tag": "beta",
+        "provenance": true
+    },
+    "type": "module",
+    "engines": {
+        "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
+    },
+    "bin": {
+        "rehearsal": "dist/src/cli/rehearsal.mjs"
+    },
+    "exports": {
+        ".": {
+            "types": "./types/configuration.d.mts",
+            "import": "./dist/src/index.mjs"
+        },
+        "./baseline": "./dist/src/baseline/artifact.mjs",
+        "./baseline-builder": "./dist/src/baseline/builder.mjs",
+        "./diagnostics": "./dist/src/shared/diagnostics.mjs",
+        "./migrations": "./dist/src/runtime/migration_history.mjs",
+        "./process-environment": "./dist/src/shared/process_environment.mjs",
+        "./privacy": "./dist/src/baseline/privacy_engine.mjs",
+        "./schema": "./dist/src/baseline/schema_snapshot.mjs",
+        "./service-environment": "./dist/src/runtime/service_environment.mjs",
+        "./source-access": "./dist/src/source/access.mjs"
+    },
+    "files": [
+        "dist",
+        "types",
+        "docs/*.md",
+        "README.md",
+        "BENCHMARKS.md",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "COMPATIBILITY.md",
+        "SUPPORT.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "postinstall": "node dist/scripts/install/create_root_config.mjs",
+        "prepack": "npm run build",
+        "build": "node scripts/build/clean.mjs && tsc --project tsconfig.build.json",
+        "docs:build": "node scripts/docs/build.mjs",
+        "docs:preview": "node scripts/docs/serve.mjs",
+        "test": "npm run build && vitest run",
+        "test:unit": "npm run build && vitest run tests/unit",
+        "test:integration": "npm run build && vitest run tests/integration tests/contracts",
+        "test:docs": "npm run build && vitest run tests/contracts/documentationCommands.test.mjs",
+        "test:fixture": "npm run build && node scripts/verification/fixtures/supabase.mjs",
+        "test:fixture:postgresql": "npm run build && node scripts/verification/fixtures/postgresql.mjs",
+        "test:fixture:dependent": "npm run build && node scripts/verification/fixtures/dependent.mjs",
+        "test:fixture:onboarding": "npm run build && node scripts/verification/fixtures/onboarding.mjs",
+        "test:fixture:typescript": "npm run build && node scripts/verification/fixtures/typescript.mjs",
+        "test:fixture:standalone": "npm run build && node scripts/verification/fixtures/standalone.mjs",
+        "test:fixture:privacy": "npm run build && node scripts/verification/fixtures/privacy.mjs",
+        "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
+        "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+        "typecheck": "tsc --project tsconfig.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "package:audit": "node scripts/verification/audit_package.mjs"
+    },
+    "keywords": [
+        "postgresql",
+        "supabase",
+        "migration",
+        "testing",
+        "database"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@clack/prompts": "^1.8.1",
+        "pg": "^8.23.1"
+    },
+    "devDependencies": {
+        "@fontsource-variable/dm-sans": "^5.3.0",
+        "@fontsource-variable/fraunces": "^5.3.0",
+        "@lydell/node-pty": "^1.2.0-beta.15",
+        "@types/node": "22.20.5",
+        "@types/pg": "^8.23.1",
+        "marked": "^18.0.14",
+        "prettier": "^3.9.6",
+        "typescript": "7.0.2",
+        "vitest": "^5.0.2"
+    }
+}

package/dist/scripts/install/create_root_config.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+export {};

package/dist/scripts/install/create_root_config.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+import { fileURLToPath } from "node:url";
+import { createInstalledRehearsalScaffold, renderInstalledRehearsalScaffold, } from "../../src/project/install_scaffold.mjs";
+const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
+try {
+    const result = await createInstalledRehearsalScaffold({ packageRoot });
+    console.log(renderInstalledRehearsalScaffold(result));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Rehearsal could not safely create project files during installation: ${message}\nNext: run npx rehearsal from the application directory.`);
+}

package/dist/scripts/runtime/manage_database.d.mts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Select the configured database runtime and forward the requested
+ * lifecycle action to its isolated driver.
+ */
+export {};

package/{scripts → dist/scripts}/runtime/manage_database.mjs

@@ -3,16 +3,14 @@
  * Purpose: Select the configured database runtime and forward the requested
  * lifecycle action to its isolated driver.
  */
-
 import { loadRehearsalConfig } from "../../src/project/configuration.mjs";
-import {
-  parseRuntimeInvocation,
-  runRuntimeTarget,
-} from "../../src/targets/target.mjs";
-
+import { parseRuntimeInvocation } from "../../src/targets/target.mjs";
+import { runRuntimeTarget } from "../../src/targets/driver.mjs";
 const invocation = parseRuntimeInvocation();
 const { config } = await loadRehearsalConfig({
-  projectRoot: process.cwd(),
-  configPath: invocation.configPath,
+    projectRoot: process.cwd(),
+    ...(invocation.configPath === undefined
+        ? {}
+        : { configPath: invocation.configPath }),
 });
 await runRuntimeTarget(config.runtime.target);

package/dist/src/application/session.d.mts

@@ -0,0 +1,96 @@
+/** Launch ordinary application commands against verified local runtime files. */
+import { spawn } from "node:child_process";
+import type { EventEmitter } from "node:events";
+declare const SESSION_SIGNALS: string[];
+type SessionSignal = (typeof SESSION_SIGNALS)[number];
+export interface ApplicationReadiness {
+    readonly url: string;
+    readonly expectedStatus?: number;
+    readonly timeoutSeconds?: number;
+}
+export interface ApplicationSession {
+    readonly pid: number | undefined;
+    readonly ready: Readonly<{
+        url: string;
+        status: number;
+    }>;
+    readonly stop: () => Promise<void>;
+    readonly wait: () => Promise<ChildExit>;
+    readonly diagnostics: () => ApplicationDiagnostics;
+}
+export interface ApplicationDiagnostics {
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+}
+interface ChildExit {
+    readonly status: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+interface SessionInput {
+    readonly isTTY?: boolean;
+    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+}
+interface EnvironmentInput {
+    readonly files: Readonly<Record<string, string>> & {
+        readonly primary: string;
+    };
+    readonly mappings: Readonly<Record<string, string>>;
+}
+interface HttpJsonAssertion {
+    readonly path: readonly string[];
+    readonly equals?: unknown;
+    readonly notEquals?: unknown;
+    readonly minimumItems?: number;
+}
+export interface HttpProofCheck {
+    readonly name: string;
+    readonly kind: "positive" | "negative";
+    readonly url: string;
+    readonly method?: string;
+    readonly expectedStatus: number;
+    readonly timeoutMs?: number;
+    readonly json?: HttpJsonAssertion | null;
+}
+type SignalTarget = Pick<EventEmitter, "prependListener" | "removeListener">;
+export declare const buildApplicationEnvironment: ({ files, mappings, }: EnvironmentInput) => Promise<Record<string, string>>;
+export declare const summarizeProjectCommandFailure: ({ error, status, signal, stdout, stderr, stdoutByteCount, stderrByteCount, }: {
+    error?: NodeJS.ErrnoException;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout?: string;
+    stderr?: string;
+    stdoutByteCount?: number;
+    stderrByteCount?: number;
+}) => string;
+export declare const startApplicationSession: ({ command, cwd, files, mappings, readiness, inheritedEnvironment, spawnImplementation, fetchImplementation, signalTarget, }: EnvironmentInput & {
+    command: string;
+    cwd: string;
+    readiness: ApplicationReadiness;
+    inheritedEnvironment?: NodeJS.ProcessEnv;
+    spawnImplementation?: typeof spawn;
+    fetchImplementation?: typeof fetch;
+    signalTarget?: SignalTarget;
+}) => Promise<ApplicationSession>;
+/**
+ * Keep a ready application session attached until the user interrupts it.
+ * The child process group is always stopped before this function returns.
+ */
+export declare const holdApplicationSession: ({ session, signalTarget, input, onReady, }: {
+    session: ApplicationSession;
+    signalTarget?: SignalTarget;
+    input?: SessionInput;
+    onReady?: (ready: ApplicationSession["ready"]) => void;
+}) => Promise<Readonly<{
+    signal: SessionSignal;
+    diagnostics: ApplicationDiagnostics;
+}>>;
+export declare const runHttpProofs: ({ checks, fetchImplementation, }: {
+    checks: readonly HttpProofCheck[];
+    fetchImplementation?: typeof fetch;
+}) => Promise<readonly Readonly<{
+    name: string;
+    kind: "positive" | "negative";
+    status: number;
+}>[]>;
+export {};