@rehearsal-db/core 0.1.0-beta.12 → 0.1.0-beta.14

package/src/cli/renderers.mjs

@@ -270,6 +270,18 @@ export const renderSetup = (result) => {
   return [
     `REHEARSAL SETUP — ${result.mode.toUpperCase()}`,
     `Project: ${result.project}`,
+    `Configuration: ${result.configurationPath} (${
+      result.configurationAction === "create"
+        ? result.mode === "written"
+          ? "created"
+          : "will create"
+        : "existing"
+    })`,
+    ...(result.rootConfigGenerationSkipped
+      ? [
+          "Root config: not created because the existing supported configuration remains active.",
+        ]
+      : []),
     `Database: ${result.target === "postgresql" ? "PostgreSQL" : "Supabase"}`,
     `Runtime ID: ${result.projectId}`,
     `Application: ${result.applicationUrl}`,
@@ -507,7 +519,10 @@ export const renderSourceAccessPlan = (plan) =>
     "SOURCE ACCESS — PREVIEW",
     "",
     `Target fingerprint: ${plan.review.targetFingerprint}`,
-    `Temporary reader: ${plan.review.reader.role} (${plan.review.reader.validForMinutes} minutes)`,
+    plan.review.reader.mode === "managed"
+      ? `Managed temporary reader: ${plan.review.reader.role} (${plan.review.reader.validForMinutes} minutes)`
+      : `Externally managed reader: ${plan.review.reader.role} (maximum ${plan.review.reader.maximumValidForMinutes} minutes remaining)`,
+    `Source changes by Rehearsal: ${plan.review.reader.sourceChanges ? "export views and temporary roles" : "none"}`,
     `Export schema: ${plan.review.exportSchema}`,
     ...plan.review.relations.map(
       (relation) =>
@@ -516,7 +531,10 @@ export const renderSourceAccessPlan = (plan) =>
     ...(plan.review.assets.length
       ? plan.review.assets.map(
           (asset) =>
-            `  → Storage ${asset.bucket}/${asset.prefix} (${asset.rights})`,
+            `  → Storage ${asset.bucket}/${
+              asset.prefix ??
+              `[private prefix from ${asset.prefixEnvironmentVariable}]`
+            } (${asset.rights})`,
         )
       : ["  ○ No source assets declared"]),
     "",
@@ -574,7 +592,12 @@ export const renderSourceRetirement = ({ mode, plan }) =>
     `Target fingerprint: ${plan.review.targetFingerprint}`,
     `Reader: ${plan.review.readerRole}`,
     `Export schema: ${plan.review.exportSchema}`,
-    ...plan.review.views.map((view) => `  → remove view ${view}`),
+    ...(plan.review.accessMode === "managed"
+      ? plan.review.views.map((view) => `  → remove view ${view}`)
+      : [
+          "  → remove only Rehearsal's local credential and receipt",
+          "  ✓ preserve the provider-owned reader and export views",
+        ]),
     "",
     ...(mode === "preview"
       ? [
@@ -582,7 +605,9 @@ export const renderSourceRetirement = ({ mode, plan }) =>
           `Exact confirmation: --confirm-source-retirement=${plan.digest}`,
         ]
       : [
-          "The exact reader, export views, and local credential files were retired.",
+          plan.review.accessMode === "managed"
+            ? "The exact reader, export views, and local credential files were retired."
+            : "Rehearsal's local credential and receipt were removed. Provider-owned database resources were preserved.",
         ]),
   ].join("\n");
 

package/src/cli/runtime_commands.mjs

@@ -211,6 +211,82 @@ const projectCommandEnvironment = (additional = {}) => ({
   ...additional,
 });
 
+const RUNTIME_STARTUP_FAILURE_PATTERN =
+  /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu;
+
+export const classifyManagerFailure = ({
+  action,
+  output,
+  inferredCategory,
+}) => {
+  if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output)) {
+    return "runtime_dependency_failure";
+  }
+  if (
+    action === "migrate" ||
+    (action === "run" &&
+      /migrateRuntime|candidate migration|migration up/iu.test(output))
+  ) {
+    return "migration_candidate_failure";
+  }
+  return inferredCategory;
+};
+
+export const parseDockerCapacity = (output) => {
+  const [cpuText, memoryText, runningText, totalText] = output
+    .trim()
+    .split(/\s+/u);
+  const values = [cpuText, memoryText, runningText, totalText].map(Number);
+  if (!values.every(Number.isFinite)) return null;
+  const [cpus, memoryBytes, runningContainers, containers] = values;
+  return { cpus, memoryBytes, runningContainers, containers };
+};
+
+export const parseColimaMemory = (output) => {
+  const line = output
+    .split("\n")
+    .map((entry) => entry.trim())
+    .find((entry) => entry.startsWith("Mem:"));
+  if (!line) return null;
+  const columns = line.split(/\s+/u);
+  const totalBytes = Number(columns[1]);
+  const availableBytes = Number(columns[6]);
+  if (![totalBytes, availableBytes].every(Number.isFinite)) return null;
+  return { totalBytes, availableBytes };
+};
+
+const diagnosticCommand = (command, args) =>
+  spawnSync(command, args, {
+    encoding: "utf8",
+    env: projectCommandEnvironment(),
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5_000,
+  });
+
+const inspectContainerCapacity = () => {
+  const docker = diagnosticCommand("docker", [
+    "info",
+    "--format",
+    "{{.NCPU}} {{.MemTotal}} {{.ContainersRunning}} {{.Containers}}",
+  ]);
+  const capacity =
+    docker.status === 0 ? parseDockerCapacity(docker.stdout) : null;
+  if (!capacity) return undefined;
+
+  const context = diagnosticCommand("docker", ["context", "show"]);
+  if (context.status !== 0 || context.stdout.trim() !== "colima") {
+    return { engine: "docker-compatible", ...capacity };
+  }
+  const memory = diagnosticCommand("colima", ["ssh", "--", "free", "-b"]);
+  return {
+    engine: "colima",
+    ...capacity,
+    ...(memory.status === 0
+      ? { runtimeMemory: parseColimaMemory(memory.stdout) ?? undefined }
+      : {}),
+  };
+};
+
 export const topologyCommandEnvironment = (topology) =>
   Object.fromEntries(
     topology.targets.map((target) => [
@@ -344,14 +420,15 @@ export const createRuntimeCommands = ({
       const inferred = normalizeRehearsalError(
         new Error(completeOutput || `Rehearsal ${action} failed.`),
       );
-      const category =
-        action === "migrate" ||
-        (action === "run" &&
-          /migrateRuntime|candidate migration|migration up/iu.test(
-            completeOutput,
-          ))
-          ? "migration_candidate_failure"
-          : inferred.category;
+      const category = classifyManagerFailure({
+        action,
+        output: completeOutput,
+        inferredCategory: inferred.category,
+      });
+      const startupFailure = category === "runtime_dependency_failure";
+      const engineCapacity = startupFailure
+        ? inspectContainerCapacity()
+        : undefined;
       const conciseOutput = completeOutput
         .replaceAll(String.fromCodePoint(27), "")
         .split("\n")
@@ -366,10 +443,16 @@ export const createRuntimeCommands = ({
         message: `The local Rehearsal ${action} operation did not complete.`,
         expected: "the isolated runtime operation to finish and verify",
         actual: conciseOutput || `exit ${result.status}`,
-        context: { action },
+        context: { action, ...(engineCapacity ? { engineCapacity } : {}) },
         refused: "The runtime was not reported as trusted.",
         suggestions: [
           "Review the concise failure above, then rerun rehearsal doctor before retrying.",
+          ...(startupFailure
+            ? [
+                "Stop unrelated local stacks or increase Docker/Colima capacity, then retry. Rehearsal will not change engine settings or bypass service health checks.",
+                "Run docker stats --no-stream to identify active containers using the shared engine.",
+              ]
+            : []),
           "Use --debug only when the safe diagnostic detail is needed.",
         ],
         cause: new Error(completeOutput || `exit ${result.status}`),

package/src/cli/source_commands.mjs

@@ -13,7 +13,10 @@ import {
   pruneBaselineGenerations,
   verifyActiveBaseline,
 } from "../baseline/artifact.mjs";
-import { readPrivacyKey } from "../baseline/privacy_engine.mjs";
+import {
+  createPrivacyEngine,
+  readPrivacyKey,
+} from "../baseline/privacy_engine.mjs";
 import { loadRehearsalConfig } from "../project/configuration.mjs";
 import {
   createSourceAccessPlan,
@@ -21,9 +24,11 @@ import {
 } from "../source/access.mjs";
 import { streamApprovedSupabaseAssets } from "../source/asset_transfer.mjs";
 import { refreshPostgresqlBaseline } from "../source/baseline.mjs";
+import { resolvePrivacyMappedAssets } from "../source/privacy_paths.mjs";
 import {
   applyPostgresqlSourceAccess,
   planPostgresqlSourceAccessRetirement,
+  resolvePostgresqlSourceStatePaths,
   retirePostgresqlSourceAccess,
 } from "../source/postgresql_access.mjs";
 import { loadRuntimeTopology } from "../runtime/topology.mjs";
@@ -50,6 +55,7 @@ export const runSourceAccess = async ({ flags, planOptions }) => {
     plan,
     confirmation: flags.sourceAccessConfirmation,
     projectRoot: loaded.projectRoot,
+    artifactRoot: loaded.paths.artifactDirectory,
   });
   return {
     mode: "written",
@@ -63,6 +69,8 @@ export const runSourceRetirement = async ({ flags, planOptions }) => {
   const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
   const plan = await planPostgresqlSourceAccessRetirement({
     projectRoot: loaded.projectRoot,
+    artifactRoot: loaded.paths.artifactDirectory,
+    credentialFile: sourcePolicy.reader.credentialFile,
     targetFingerprint: sourcePolicy.targetFingerprint,
   });
   if (!flags.sourceRetirementConfirmation) return { mode: "preview", plan };
@@ -72,6 +80,7 @@ export const runSourceRetirement = async ({ flags, planOptions }) => {
     administratorEnvironmentVariable:
       sourcePolicy.administratorEnvironmentVariable,
     projectRoot: loaded.projectRoot,
+    artifactRoot: loaded.paths.artifactDirectory,
     credentialFile: sourcePolicy.reader.credentialFile,
   });
   return { mode: "written", plan };
@@ -98,6 +107,11 @@ const readSourceReaderCredential = async (path) => {
 
 export const runSourceBaselineRefresh = async ({ planOptions }) => {
   const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+  const { credentialPath } = resolvePostgresqlSourceStatePaths({
+    projectRoot: loaded.projectRoot,
+    artifactRoot: loaded.paths.artifactDirectory,
+    credentialFile: sourcePolicy.reader.credentialFile,
+  });
   const [
     sourceAccessReceipt,
     privacyPolicyBytes,
@@ -110,10 +124,17 @@ export const runSourceBaselineRefresh = async ({ planOptions }) => {
     ).then(JSON.parse),
     readFile(loaded.paths.sanitizationPolicy),
     readPrivacyKey(loaded.paths.privacyKey),
-    readSourceReaderCredential(
-      join(loaded.projectRoot, sourcePolicy.reader.credentialFile),
-    ),
+    readSourceReaderCredential(credentialPath),
   ]);
+  const privacyPolicy = JSON.parse(privacyPolicyBytes.toString("utf8"));
+  const assetPrivacyEngine = createPrivacyEngine({
+    policy: privacyPolicy,
+    key: privacyKey,
+  });
+  const assetDeclarations = resolvePrivacyMappedAssets({
+    sourcePolicy,
+    privacyPolicy,
+  });
   return refreshPostgresqlBaseline({
     connectionString,
     sourcePolicy,
@@ -133,10 +154,12 @@ export const runSourceBaselineRefresh = async ({ planOptions }) => {
           baseUrl:
             process.env[sourcePolicy.assetReader.baseUrlEnvironmentVariable],
           token: process.env[sourcePolicy.assetReader.tokenEnvironmentVariable],
-          declarations: sourcePolicy.assets,
+          declarations: assetDeclarations,
           maximumObjects: sourcePolicy.assetReader.maximumObjects,
           maximumObjectBytes: sourcePolicy.assetReader.maximumObjectBytes,
           maximumTotalBytes: sourcePolicy.assetReader.maximumTotalBytes,
+          pathMapper: ({ mapping, value }) =>
+            assetPrivacyEngine.remapPath({ mapping, value }),
         })
       : [],
   });
@@ -244,9 +267,15 @@ export const buildRefreshWorkflowPlan = async (planOptions) => {
 };
 
 export const createRefreshWorkflow =
-  ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment }) =>
+  ({
+    runRuntimeStack,
+    prepareDependentTargets,
+    topologyCommandEnvironment,
+    buildPlan = buildRefreshWorkflowPlan,
+    refreshBaseline = runSourceBaselineRefresh,
+  }) =>
   async ({ flags, planOptions }) => {
-    const context = await buildRefreshWorkflowPlan(planOptions);
+    const context = await buildPlan(planOptions);
     if (!flags.refreshConfirmation) {
       return { mode: "preview", plan: context.plan };
     }
@@ -259,7 +288,7 @@ export const createRefreshWorkflow =
     let runtime;
     let preparations = [];
     try {
-      refreshed = await runSourceBaselineRefresh({ planOptions });
+      refreshed = await refreshBaseline({ planOptions });
       const stack = await runRuntimeStack({
         command: "reset",
         flags,

package/src/identity/claim.mjs

@@ -740,18 +740,18 @@ export const applyIdentityClaim = async ({
       "select 1 from auth.users where id = $1::uuid limit 1",
       [plan.identity.placeholderUserId],
     );
-    const placeholderReferenceCounts =
-      localUserId === plan.identity.placeholderUserId
-        ? []
-        : await Promise.all(
-            plan.identity.references.map((reference) =>
-              countIdentityRows({
-                client,
-                reference,
-                userId: plan.identity.placeholderUserId,
-              }),
-            ),
-          );
+    const placeholderReferenceCounts = [];
+    if (localUserId !== plan.identity.placeholderUserId) {
+      for (const reference of plan.identity.references) {
+        placeholderReferenceCounts.push(
+          await countIdentityRows({
+            client,
+            reference,
+            userId: plan.identity.placeholderUserId,
+          }),
+        );
+      }
+    }
     const transferReferences = plan.identity.references.filter(
       (reference) => reference.strategy === "transfer",
     );
@@ -762,15 +762,17 @@ export const applyIdentityClaim = async ({
       const index = plan.identity.references.indexOf(reference);
       return placeholderReferenceCounts[index] ?? 0;
     });
-    const transferLocalCounts =
-      localUserId === plan.identity.placeholderUserId ||
-      preservedReferences.length === 0
-        ? []
-        : await Promise.all(
-            transferReferences.map((reference) =>
-              countIdentityRows({ client, reference, userId: localUserId }),
-            ),
-          );
+    const transferLocalCounts = [];
+    if (
+      localUserId !== plan.identity.placeholderUserId &&
+      preservedReferences.length > 0
+    ) {
+      for (const reference of transferReferences) {
+        transferLocalCounts.push(
+          await countIdentityRows({ client, reference, userId: localUserId }),
+        );
+      }
+    }
     const alreadyClaimed =
       localUserId !== plan.identity.placeholderUserId &&
       transferPlaceholderCounts.every((count) => count === 0) &&

package/src/project/install_scaffold.mjs

@@ -138,6 +138,31 @@ const uniqueProjects = (projects) => [
 
 const skip = (reason) => ({ status: "skipped", reason });
 
+export const renderInstalledRehearsalScaffold = (result) => {
+  if (result.status !== "ready") {
+    return `Rehearsal did not create project files: ${result.reason}.\nNext: run npx rehearsal from the application directory.`;
+  }
+  const changed = result.files.filter((file) => file.action !== "unchanged");
+  return [
+    "Rehearsal is ready in this project.",
+    `Configuration: ${result.configurationPath} (${result.configurationAction === "create" ? "created" : "existing"})`,
+    ...(result.rootConfigGenerationSkipped
+      ? [
+          `  Existing supported configuration detected at ${result.configurationPath}.`,
+          "  rehearsal.config.mjs was not created because Rehearsal preserves one active configuration and never creates a competing file.",
+        ]
+      : []),
+    ...(changed.length
+      ? [
+          ...changed.map(
+            (file) => `  ${file.action === "create" ? "+" : "~"} ${file.path}`,
+          ),
+        ]
+      : ["  Existing Rehearsal files preserved."]),
+    `Next: review ${result.configurationPath}, then run npx rehearsal.`,
+  ].join("\n");
+};
+
 export const resolveRehearsalConsumerRoot = async ({
   packageRoot,
   initCwd,
@@ -281,11 +306,20 @@ export const createInstalledRehearsalScaffold = async ({
     isPortAvailable,
   });
   const result = await applyRehearsalSetup(plan);
-  await loadRehearsalConfig({ projectRoot: resolution.projectRoot });
+  const loaded = await loadRehearsalConfig({
+    projectRoot: resolution.projectRoot,
+  });
+  const configurationPath = relative(resolution.projectRoot, loaded.configPath);
+  const configurationAction =
+    result.files.find(({ path }) => path === configurationPath)?.action ??
+    "unchanged";
   return {
     status: "ready",
     projectRoot: resolution.projectRoot,
     target: plan.target,
     files: result.files,
+    configurationPath,
+    configurationAction,
+    rootConfigGenerationSkipped: configurationPath !== "rehearsal.config.mjs",
   };
 };

package/src/project/setup.mjs

@@ -23,6 +23,11 @@ import {
   renderDetectedPostgresqlConfig,
 } from "./configuration.mjs";
 import { resolveRuntimeTarget } from "../targets/target.mjs";
+export {
+  assertSupportedRehearsalNodeRuntime,
+  inspectRehearsalNodeRuntime,
+} from "../shared/node_runtime.mjs";
+import { assertSupportedRehearsalNodeRuntime } from "../shared/node_runtime.mjs";
 
 const CONFIG_PATH = "rehearsal.config.mjs";
 const LOCAL_SUPABASE_CONFIG_PATH =
@@ -82,29 +87,6 @@ export const isRehearsalPortAvailable = async (port) => {
   return canBindToPort(port);
 };
 
-export const inspectRehearsalNodeRuntime = (
-  version = process.versions.node,
-) => {
-  const major = Number.parseInt(String(version).split(".")[0], 10);
-  return {
-    version: String(version),
-    major,
-    supported: major === 24,
-  };
-};
-
-export const assertSupportedRehearsalNodeRuntime = (
-  version = process.versions.node,
-) => {
-  const runtime = inspectRehearsalNodeRuntime(version);
-  if (!runtime.supported) {
-    throw new Error(
-      `Rehearsal setup requires Node.js 24; this shell is using Node.js ${runtime.version}. Switch to Node.js 24, then rerun setup. With nvm: nvm install 24 && nvm use 24.`,
-    );
-  }
-  return runtime;
-};
-
 export const findAvailableRehearsalPorts = async ({
   isAvailable = isRehearsalPortAvailable,
 } = {}) => {
@@ -392,6 +374,9 @@ export const planRehearsalSetup = async ({
   ];
   return {
     projectRoot: root,
+    configurationPath: existingConfigPath
+      ? relative(root, existingConfigPath)
+      : CONFIG_PATH,
     project: detected.projectName,
     projectId,
     target: runtimeTarget,
@@ -462,6 +447,11 @@ export const applyRehearsalSetup = async (plan) => {
 
 export const summarizeRehearsalSetup = (plan, { mode }) => ({
   mode,
+  configurationPath: plan.configurationPath,
+  configurationAction:
+    plan.files.find((file) => file.path === plan.configurationPath)?.action ??
+    "unchanged",
+  rootConfigGenerationSkipped: plan.configurationPath !== CONFIG_PATH,
   project: plan.project,
   projectId: plan.projectId,
   target: plan.target,
@@ -479,6 +469,6 @@ export const summarizeRehearsalSetup = (plan, { mode }) => ({
   safety: plan.safety,
   nextAction:
     mode === "written"
-      ? "Review the generated commands and sanitization policy path, then run rehearsal doctor."
+      ? `Review ${plan.configurationPath}, including its commands and sanitization policy path, then run rehearsal doctor.`
       : "Review this plan, then rerun rehearsal setup --write to create it.",
 });

package/src/runtime/plan.mjs

@@ -22,6 +22,10 @@ import {
 import { createCandidateMigrationReceipt } from "./restore.mjs";
 import { readMigrationFileInventory } from "./migration_history.mjs";
 import { REHEARSAL_VERSION } from "../shared/diagnostics.mjs";
+import {
+  inspectRehearsalNodeRuntime,
+  REHEARSAL_NODE_LABEL,
+} from "../shared/node_runtime.mjs";
 import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
 import {
   readBoundRuntimeSanitizationPolicy,
@@ -357,17 +361,17 @@ export const runRehearsalDoctor = async (options = {}) => {
     };
   }
   const { config, paths, projectRoot } = loaded;
-  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  const nodeRuntime = inspectRehearsalNodeRuntime();
   const checkDefinitions = [
     {
       id: "node",
       label: "Node.js compatibility",
       run: async () => {
-        if (nodeMajor !== 24)
+        if (!nodeRuntime.supported)
           throw new Error(`Node ${process.versions.node} is unsupported.`);
         return `Node ${process.versions.node}`;
       },
-      remediation: "Use Node.js 24.",
+      remediation: `Use ${REHEARSAL_NODE_LABEL}. Node.js 24 LTS is recommended.`,
     },
     {
       id: "operating-system",

package/src/runtime/restore.mjs

@@ -194,11 +194,19 @@ const buildIdentitySequenceSql = (table) =>
       const schema = tableSchema(table);
       const relation = qualifiedRelation(table);
       const columnName = quoteIdentifier(column.name);
-      return `select setval(
-	pg_get_serial_sequence(${quoteLiteral(`${schema}.${table.name}`)}, ${quoteLiteral(column.name)}),
-	coalesce((select max(${columnName}) from ${relation}), 1),
-	exists(select 1 from ${relation})
-);`;
+      const sequenceValueQuery = `select max(${columnName})::bigint, exists(select 1 from ${relation}) from ${relation}`;
+      return `do $rehearsal_sequence$
+declare
+	sequence_name text := pg_get_serial_sequence(${quoteLiteral(`${schema}.${table.name}`)}, ${quoteLiteral(column.name)});
+	maximum_value bigint;
+	has_rows boolean;
+begin
+	if sequence_name is not null then
+		execute ${quoteLiteral(sequenceValueQuery)} into maximum_value, has_rows;
+		perform setval(sequence_name, coalesce(maximum_value, 1), has_rows);
+	end if;
+end
+$rehearsal_sequence$;`;
     })
     .join("\n");
 

package/src/shared/diagnostics.mjs

@@ -94,6 +94,13 @@ export class RehearsalError extends Error {
 const inferCategory = (error) => {
   const message = String(error?.message ?? error);
   if (/checksum/iu.test(message)) return "baseline_checksum_mismatch";
+  if (
+    /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu.test(
+      message,
+    )
+  ) {
+    return "runtime_dependency_failure";
+  }
   if (/candidate|migration history diverges/iu.test(message)) {
     return "migration_candidate_failure";
   }

package/src/shared/node_runtime.mjs

@@ -0,0 +1,31 @@
+/**
+ * Supported Node.js release lines. Keep this aligned with package.json and the
+ * verification matrix.
+ */
+
+export const REHEARSAL_NODE_MAJORS = Object.freeze([22, 24, 26]);
+export const REHEARSAL_NODE_LABEL = "Node.js 22, 24, or 26";
+export const REHEARSAL_RECOMMENDED_NODE_MAJOR = 24;
+
+export const inspectRehearsalNodeRuntime = (
+  version = process.versions.node,
+) => {
+  const major = Number.parseInt(String(version).split(".")[0], 10);
+  return {
+    version: String(version),
+    major,
+    supported: REHEARSAL_NODE_MAJORS.includes(major),
+  };
+};
+
+export const assertSupportedRehearsalNodeRuntime = (
+  version = process.versions.node,
+) => {
+  const runtime = inspectRehearsalNodeRuntime(version);
+  if (!runtime.supported) {
+    throw new Error(
+      `Rehearsal requires ${REHEARSAL_NODE_LABEL}; this shell is using Node.js ${runtime.version}. Switch to a supported release, then rerun setup. With nvm: nvm install --lts && nvm use --lts.`,
+    );
+  }
+  return runtime;
+};