@rehearsal-db/core 0.1.0-rc.3 → 0.1.0-rc.4

package/CHANGELOG.md

@@ -5,6 +5,28 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-rc.4] - 2026-10-11
+
+### Added
+
+- `discover --json` exposes a versioned, read-only Project Profile for editor clients,
+  separating proven facts, evidence-backed suggestions, and decisions that remain with
+  the user.
+- Project discovery reports bounded application, package-manager, migration, target,
+  runtime, baseline-retention, configuration, and local-address metadata without reading
+  environment files, contacting databases, starting containers, or executing project code.
+- Public TypeScript contracts now cover discovery results, retained baseline generations,
+  application readiness, cleanup policy, and structured PostgreSQL and Supabase runtime
+  state consumed by the Rehearsal VS Code extension.
+
+### Changed
+
+- Plans and status results expose the additional bounded metadata required for a
+  project-aware editor experience while retaining core ownership of all safety checks and
+  mutating operations.
+- Documentation now includes the supported VS Code integration boundary, privacy model,
+  compatibility floor, and safe automatic-refresh behavior.
+
 ## [0.1.0-rc.3] - 2026-10-10
 
 ### Added
@@ -605,7 +627,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-rc.3...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.4...HEAD
+[0.1.0-rc.4]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.3...v0.1.0-rc.4
 [0.1.0-rc.3]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.2...v0.1.0-rc.3
 [0.1.0-rc.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.1...v0.1.0-rc.2
 [0.1.0-rc.1]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.18...v0.1.0-rc.1

package/README.md

@@ -166,6 +166,7 @@ Start here:
 
 - [Documentation home](docs/index.md) — choose the shortest path for your goal
 - [Getting started](docs/getting-started.md) — set up your own project
+- [VS Code extension](docs/vscode.md) — use the project-aware visual workbench
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
 - [Next steps](docs/roadmap.md) — see the current product sequence

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "0.1.0-rc.3",
+    "version": "0.1.0-rc.4",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -22,6 +22,9 @@
     "bin": {
         "rehearsal": "dist/src/cli/rehearsal.mjs"
     },
+    "rehearsalContracts": {
+        "projectDiscovery": 1
+    },
     "exports": {
         ".": {
             "types": "./types/configuration.d.mts",

package/dist/src/baseline/artifact.d.mts

@@ -66,6 +66,17 @@ export interface BaselinePrunePlan {
     readonly retained: string[];
     readonly removed: string[];
 }
+export interface BaselineGenerationSummary {
+    readonly generationId: string;
+    readonly createdAt: string | null;
+    readonly active: boolean;
+    readonly formatVersion: 1 | 2;
+    readonly rowCount: number;
+    readonly tableCount: number;
+    readonly migrationCount: number;
+    readonly migrationCutoff: string;
+    readonly storageAssetCount: number;
+}
 export declare const createBaselineGenerationId: ({ now, }?: {
     now?: Date;
 }) => string;
@@ -91,6 +102,9 @@ export declare const removeStagedBaselineGeneration: ({ artifactRoot, generation
 export declare const resolveActiveBaselinePaths: ({ artifactRoot, }: {
     artifactRoot: string;
 }) => Promise<ActiveBaselinePaths>;
+export declare const inspectBaselineGenerations: ({ artifactRoot, }: {
+    artifactRoot: string;
+}) => Promise<readonly BaselineGenerationSummary[]>;
 export declare const verifyActiveBaseline: ({ artifactRoot, }: {
     artifactRoot: string;
 }) => Promise<BaselineManifest>;

package/dist/src/baseline/artifact.mjs

@@ -46,6 +46,12 @@ const assertGenerationId = (value) => {
     }
     return value;
 };
+const generationCreatedAt = (generationId) => {
+    const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-/u.exec(generationId);
+    return match
+        ? `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`
+        : null;
+};
 const assertArtifactRoot = (artifactRoot) => {
     const resolved = resolve(artifactRoot);
     if (basename(resolved) !== ".rehearsal" || resolved === sep) {
@@ -364,6 +370,50 @@ export const resolveActiveBaselinePaths = async ({ artifactRoot, }) => {
         schemaPath: join(generationDirectory, "production-schema.sql"),
     };
 };
+export const inspectBaselineGenerations = async ({ artifactRoot, }) => {
+    const root = assertArtifactRoot(artifactRoot);
+    const active = basename((await resolveActiveBaselinePaths({ artifactRoot: root }))
+        .generationDirectory);
+    const generationsRoot = join(root, generationsDirectoryName);
+    await verifyNoSymlink(generationsRoot, "The Rehearsal generations directory");
+    const entries = await readdir(generationsRoot, { withFileTypes: true });
+    if (entries.length > 1_000) {
+        throw new Error("The Rehearsal baseline generation limit was exceeded.");
+    }
+    const summaries = [];
+    for (const entry of entries.sort((left, right) => right.name.localeCompare(left.name))) {
+        if (!entry.isDirectory() || !generationPattern.test(entry.name))
+            continue;
+        const generationDirectory = assertInsideRoot(root, join(generationsRoot, entry.name));
+        await verifyNoSymlink(generationDirectory, "A Rehearsal baseline generation");
+        const manifest = parseManifest(await readFile(join(generationDirectory, "baseline-manifest.json"), "utf8"));
+        if (manifest.generationId !== entry.name ||
+            ![1, 2].includes(manifest.formatVersion) ||
+            !Number.isSafeInteger(manifest.rowCount) ||
+            manifest.rowCount < 0 ||
+            !isObject(manifest.tableCounts) ||
+            !isObject(manifest.migrations) ||
+            !isObject(manifest.storageAssets) ||
+            typeof manifest.migrationCutoff !== "string") {
+            throw new Error(`Rehearsal baseline generation ${entry.name} has an invalid manifest.`);
+        }
+        summaries.push({
+            generationId: entry.name,
+            createdAt: generationCreatedAt(entry.name),
+            active: entry.name === active,
+            formatVersion: manifest.formatVersion,
+            rowCount: manifest.rowCount,
+            tableCount: Object.keys(manifest.tableCounts).length,
+            migrationCount: Object.keys(manifest.migrations).length,
+            migrationCutoff: manifest.migrationCutoff,
+            storageAssetCount: Object.keys(manifest.storageAssets).length,
+        });
+    }
+    if (!summaries.some(({ active: isActive }) => isActive)) {
+        throw new Error("The active Rehearsal baseline generation is unavailable.");
+    }
+    return Object.freeze(summaries.map((summary) => Object.freeze(summary)));
+};
 export const verifyActiveBaseline = async ({ artifactRoot, }) => {
     const paths = await resolveActiveBaselinePaths({ artifactRoot });
     const { generationDirectory } = paths;

package/dist/src/cli/basic_command_handlers.mjs

@@ -20,6 +20,7 @@ Commands:
   identity claim --identity= --confirm-identity= Apply the exact local association
   identity connect [--identity=] Keep the app open, detect sign-in, and connect once
   doctor                     Check whether Rehearsal is safe and ready
+  discover                   Inspect project metadata and explain setup suggestions
   support                    Print a safe, copy-ready support report
   activity                   Report idle, busy, stale, or invalid operation state
   explain                    Show the immutable execution plan

package/dist/src/cli/inspection_command_handlers.mjs

@@ -1,11 +1,29 @@
 /** Read-only readiness, support, planning, and inspection command handlers. */
 import { collectRehearsalSupportReport } from "../project/support_report.mjs";
+import { discoverProjectProfile } from "../project/project_discovery.mjs";
 import { inspectRehearsalBaseline, inspectRehearsalMigrations, } from "../runtime/plan.mjs";
 import { buildRuntimeStackPlan, runRuntimeStackDoctor, topologyCandidateSummary, } from "./runtime_commands.mjs";
 import { renderBaseline, renderCandidates, renderDoctor, renderMigrations, renderPlan, renderSupportReport, } from "./renderers.mjs";
 import { exactCommands, renderedCommand } from "./command_contract.mjs";
 import { inspectProjectOperationState } from "../shared/operation_guard.mjs";
 export const createInspectionCommandHandlers = () => [
+    exactCommands("discover", ["discover"], async ({ planOptions }) => {
+        const data = await discoverProjectProfile({
+            projectRoot: planOptions.projectRoot ?? process.cwd(),
+        });
+        return renderedCommand({
+            data,
+            render: (result) => [
+                `PROJECT PROFILE — READ ONLY`,
+                `Detected: ${result.detected.length}`,
+                `Suggested: ${result.suggested.length}`,
+                `Your decision: ${result.decisions.length}`,
+                `Configuration: ${result.configuration.state.replaceAll("_", " ")}`,
+                "",
+                "Run rehearsal discover --json for evidence and proposed configuration fields.",
+            ].join("\n"),
+        });
+    }),
     exactCommands("activity", ["activity"], async ({ planOptions }) => {
         const data = await inspectProjectOperationState({
             projectRoot: planOptions.projectRoot ?? process.cwd(),

package/dist/src/cli/runtime_commands.d.mts

@@ -80,6 +80,18 @@ export declare const buildRuntimeStackPlan: (planOptions: RehearsalConfigPathOpt
         open: "keep-until-stop" | "stop-on-application-exit";
         dataOnStop: string;
     };
+    application: {
+        startCommand: string;
+        proofCommand: string;
+        readiness: {
+            url: string;
+            expectedStatus: number;
+            timeoutSeconds: number;
+        } | null;
+    };
+    cleanup: {
+        retainBaselineGenerations: number;
+    };
     execution: string[];
     guarantee: string;
     paths: {
@@ -88,6 +100,39 @@ export declare const buildRuntimeStackPlan: (planOptions: RehearsalConfigPathOpt
         sanitizationPolicy: string;
     };
 } | {
+    config: {
+        schemaVersion: 1;
+        path: string;
+        project: string;
+    };
+    environment: {
+        target: "postgresql" | "supabase";
+        kind: string;
+        applicationUrl: string;
+        projectId: string;
+        ports: Readonly<{
+            api?: number;
+            database: number;
+            studio?: number;
+        }>;
+        hostedAccess: "disabled";
+        outboundNetwork: "deny";
+        authenticationProviders: readonly string[];
+        authenticationCallback: string | null;
+        barriers: string[];
+    };
+    application: {
+        startCommand: string;
+        proofCommand: string;
+        readiness: {
+            url: string;
+            expectedStatus: number;
+            timeoutSeconds: number;
+        } | null;
+    };
+    cleanup: {
+        retainBaselineGenerations: number;
+    };
     targets: {
         name: string;
         declaration: RuntimeTopologyTarget["declaration"];

package/dist/src/cli/runtime_commands.mjs

@@ -36,7 +36,12 @@ export const buildRuntimeStackPlan = async (planOptions) => {
         });
     }
     const candidates = await inspectRuntimeTopologyCandidates(planOptions);
+    const primaryPlan = targets[0].plan;
     return {
+        config: primaryPlan.config,
+        environment: primaryPlan.environment,
+        application: primaryPlan.application,
+        cleanup: primaryPlan.cleanup,
         targets,
         migrations: {
             candidateCount: candidates.candidateCount,

package/dist/src/index.d.mts

@@ -1,4 +1,4 @@
 /** Public Rehearsal package entry point. */
-export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
-export type { DetectedProject, NormalizedRehearsalConfig, RehearsalConfig, RehearsalConfigPathOptions, RehearsalConfigVersion, } from "./project/configuration.mjs";
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, discoverProjectProfile, findRehearsalConfigPath, inspectDetectedProject, PROJECT_DISCOVERY_SCHEMA_VERSION, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export type { DetectedProject, DecisionDiscoveryItem, DetectedDiscoveryItem, DiscoveredConfigurationField, DiscoveryConfidence, DiscoveryEvidence, DiscoveryValue, NormalizedRehearsalConfig, ProjectDiscoveryResult, RehearsalConfig, RehearsalConfigPathOptions, RehearsalConfigVersion, } from "./project/configuration.mjs";
 export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

package/dist/src/index.mjs

@@ -1,3 +1,3 @@
 /** Public Rehearsal package entry point. */
-export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, discoverProjectProfile, findRehearsalConfigPath, inspectDetectedProject, PROJECT_DISCOVERY_SCHEMA_VERSION, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
 export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

package/dist/src/project/configuration.d.mts

@@ -10,4 +10,6 @@ export { loadRehearsalConfig } from "./configuration_resolution.mjs";
 export type { NormalizedRehearsalConfig } from "./configuration_resolution.mjs";
 export { inspectDetectedProject } from "./project_detection.mjs";
 export type { DetectedProject } from "./project_detection.mjs";
+export { discoverProjectProfile, probeContainerEngineWithoutStarting, PROJECT_DISCOVERY_SCHEMA_VERSION, } from "./project_discovery.mjs";
+export type { ContainerEngineProbe, DecisionDiscoveryItem, DetectedDiscoveryItem, DiscoveredConfigurationField, DiscoveryConfidence, DiscoveryEvidence, DiscoveryValue, ProjectDiscoveryResult, SuggestedDiscoveryItem, } from "./project_discovery.mjs";
 export { renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./configuration_rendering.mjs";

package/dist/src/project/configuration.mjs

@@ -6,4 +6,5 @@ export { defineRehearsalConfig, REHEARSAL_CONFIG_VERSION, REHEARSAL_DEFAULTS, }
 export { findRehearsalConfigPath } from "./configuration_discovery.mjs";
 export { loadRehearsalConfig } from "./configuration_resolution.mjs";
 export { inspectDetectedProject } from "./project_detection.mjs";
+export { discoverProjectProfile, probeContainerEngineWithoutStarting, PROJECT_DISCOVERY_SCHEMA_VERSION, } from "./project_discovery.mjs";
 export { renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./configuration_rendering.mjs";

package/dist/src/project/project_discovery.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Build a read-only, explainable profile from bounded project metadata.
+ *
+ * Discovery never imports project modules, reads environment files, contacts a
+ * database, or starts a container engine. Suggestions are intentionally kept
+ * separate from facts and from choices that require a person.
+ */
+import type { ContainerEngineProbe, ProjectDiscoveryResult } from "./project_discovery_contract.mjs";
+export { PROJECT_DISCOVERY_SCHEMA_VERSION } from "./project_discovery_contract.mjs";
+export type { ContainerEngineProbe, DecisionDiscoveryItem, DetectedDiscoveryItem, DiscoveredConfigurationField, DiscoveryConfidence, DiscoveryEvidence, DiscoveryValue, ProjectDiscoveryResult, SuggestedDiscoveryItem, } from "./project_discovery_contract.mjs";
+export { probeContainerEngineWithoutStarting } from "./project_discovery_metadata.mjs";
+export declare const discoverProjectProfile: ({ projectRoot, containerEngineProbe, }?: {
+    projectRoot?: string;
+    containerEngineProbe?: ContainerEngineProbe;
+}) => Promise<ProjectDiscoveryResult>;