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

package/src/shared/diagnostics.mjs

@@ -1,207 +0,0 @@
-/**
- * Purpose: Provide stable Rehearsal result, failure, redaction, and rendering
- * contracts for humans and automation. Do not run directly; this module is reusable
- * script infrastructure.
- */
-
-import { createHash } from "node:crypto";
-import packageManifest from "../../package.json" with { type: "json" };
-
-export const REHEARSAL_RESULT_VERSION = 1;
-export const REHEARSAL_VERSION = packageManifest.version;
-
-export const REHEARSAL_EXIT_CODES = Object.freeze({
-  success: 0,
-  configuration_invalid: 2,
-  unsafe_environment: 3,
-  baseline_invalid: 4,
-  baseline_checksum_mismatch: 5,
-  migration_candidate_failure: 6,
-  migration_verification_failure: 7,
-  application_proof_failure: 8,
-  runtime_dependency_failure: 9,
-  internal_failure: 10,
-});
-
-const SECRET_KEY_PATTERN =
-  /(?:authorization|cookie|credential|database[_-]?url|jwt|key|password|secret|service[_-]?role|token)/iu;
-const JWT_PATTERN =
-  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
-const CONNECTION_STRING_PATTERN =
-  /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?):\/\/[^\s"']+/giu;
-const BEARER_PATTERN = /\bBearer\s+[^\s"']+/giu;
-const SUPABASE_KEY_PATTERN = /\bsb_(?:publishable|secret)_[A-Za-z0-9_-]+\b/gu;
-
-const redactString = (value) =>
-  value
-    .replace(CONNECTION_STRING_PATTERN, "[REDACTED_CONNECTION_STRING]")
-    .replace(JWT_PATTERN, "[REDACTED_JWT]")
-    .replace(BEARER_PATTERN, "Bearer [REDACTED]")
-    .replace(SUPABASE_KEY_PATTERN, "[REDACTED_KEY]");
-
-export const redactDiagnosticValue = (value, key = "") => {
-  if (SECRET_KEY_PATTERN.test(key)) return "[REDACTED]";
-  if (typeof value === "string") return redactString(value);
-  if (Array.isArray(value)) {
-    return value.map((entry) => redactDiagnosticValue(entry));
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([entryKey, entryValue]) => [
-        entryKey,
-        redactDiagnosticValue(entryValue, entryKey),
-      ]),
-    );
-  }
-  return value;
-};
-
-const diagnosticIdFor = ({ category, code, message }) =>
-  createHash("sha256")
-    .update(`${category}\0${code}\0${message}`)
-    .digest("hex")
-    .slice(0, 12);
-
-export class RehearsalError extends Error {
-  constructor({
-    category,
-    code,
-    message,
-    expected,
-    actual,
-    context,
-    refused,
-    suggestions = [],
-    cause,
-  }) {
-    super(message, { cause });
-    this.name = "RehearsalError";
-    if (!Object.hasOwn(REHEARSAL_EXIT_CODES, category)) {
-      throw new Error(`Unknown Rehearsal error category: ${category}.`);
-    }
-    this.category = category;
-    this.code = code;
-    this.expected = expected;
-    this.actual = actual;
-    this.context = context;
-    this.refused = refused;
-    this.suggestions = suggestions;
-    this.diagnosticId = diagnosticIdFor({ category, code, message });
-    this.exitCode = REHEARSAL_EXIT_CODES[category];
-  }
-}
-
-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";
-  }
-  if (/baseline|artifact|generation|sanitization policy/iu.test(message)) {
-    return "baseline_invalid";
-  }
-  if (/migration|ledger|replay/iu.test(message)) {
-    return "migration_verification_failure";
-  }
-  if (/config|unknown rehearsal|unsupported rehearsal/iu.test(message)) {
-    return "configuration_invalid";
-  }
-  if (/loopback|hosted|unsafe|credential|outbound/iu.test(message)) {
-    return "unsafe_environment";
-  }
-  if (
-    /docker|postgres(?:ql)?|supabase|runtime|command|enoent|node\.js|ports?\b/iu.test(
-      message,
-    )
-  ) {
-    return "runtime_dependency_failure";
-  }
-  return "internal_failure";
-};
-
-export const normalizeRehearsalError = (error, overrides = {}) => {
-  if (error instanceof RehearsalError) return error;
-  const message = String(error?.message ?? error);
-  const category = overrides.category ?? inferCategory(error);
-  return new RehearsalError({
-    category,
-    code: overrides.code ?? category.toUpperCase(),
-    message,
-    expected: overrides.expected,
-    actual: overrides.actual,
-    context: overrides.context,
-    refused:
-      overrides.refused ??
-      "Rehearsal stopped before performing the requested operation.",
-    suggestions: overrides.suggestions ?? [],
-    cause: error,
-  });
-};
-
-export const createRehearsalResult = ({
-  command,
-  status,
-  data,
-  warnings = [],
-  startedAt = new Date(),
-  durationMs = 0,
-}) =>
-  redactDiagnosticValue({
-    schemaVersion: REHEARSAL_RESULT_VERSION,
-    rehearsalVersion: REHEARSAL_VERSION,
-    command,
-    status,
-    startedAt: startedAt.toISOString(),
-    durationMs,
-    warnings,
-    data,
-  });
-
-export const serializeRehearsalError = (error, { debug = false } = {}) => {
-  const failure = normalizeRehearsalError(error);
-  return redactDiagnosticValue({
-    schemaVersion: REHEARSAL_RESULT_VERSION,
-    rehearsalVersion: REHEARSAL_VERSION,
-    status: "error",
-    error: {
-      category: failure.category,
-      code: failure.code,
-      message: failure.message,
-      expected: failure.expected,
-      actual: failure.actual,
-      context: failure.context,
-      refused: failure.refused,
-      suggestions: failure.suggestions,
-      diagnosticId: failure.diagnosticId,
-      ...(debug && failure.cause
-        ? { cause: String(failure.cause?.message ?? failure.cause) }
-        : {}),
-    },
-  });
-};
-
-const formatValue = (value) =>
-  typeof value === "string" ? value : JSON.stringify(value);
-
-export const renderHumanError = (error, { debug = false } = {}) => {
-  const { error: failure } = serializeRehearsalError(error, { debug });
-  return [
-    `Rehearsal stopped: ${failure.message}`,
-    failure.expected ? `Expected: ${formatValue(failure.expected)}` : null,
-    failure.actual ? `Actual: ${formatValue(failure.actual)}` : null,
-    failure.context ? `Context: ${formatValue(failure.context)}` : null,
-    failure.refused ? `Refused: ${failure.refused}` : null,
-    ...(failure.suggestions ?? []).map((value) => `Try: ${value}`),
-    `Diagnostic: ${failure.diagnosticId} (${failure.category})`,
-    debug && failure.cause ? `Cause: ${failure.cause}` : null,
-  ]
-    .filter(Boolean)
-    .join("\n");
-};

package/src/shared/node_runtime.mjs

@@ -1,31 +0,0 @@
-/**
- * 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;
-};

package/src/shared/operation_guard.mjs

@@ -1,162 +0,0 @@
-/** Project-wide mutation lock and installed-package integrity guard. */
-
-import { createHash, randomBytes } from "node:crypto";
-import {
-  lstat,
-  mkdir,
-  readFile,
-  readdir,
-  realpath,
-  rename,
-  rm,
-  stat,
-  writeFile,
-} from "node:fs/promises";
-import { readFileSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
-
-const LOCK_ROOT = join(tmpdir(), "rehearsal-db-operation-locks");
-
-const digest = (value) => createHash("sha256").update(value).digest("hex");
-
-const packageFiles = (root, directory = root) =>
-  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
-    const path = join(directory, entry.name);
-    if (entry.isDirectory()) return packageFiles(root, path);
-    if (!entry.isFile()) return [];
-    return [relative(root, path)];
-  });
-
-export const createInstalledPackageFingerprint = ({ packageRoot }) => {
-  const files = [
-    "package.json",
-    ...["src", "scripts/runtime"].flatMap((directory) =>
-      packageFiles(packageRoot, join(packageRoot, directory)),
-    ),
-  ].sort();
-  const hash = createHash("sha256");
-  for (const file of files) {
-    hash.update(file);
-    hash.update("\0");
-    hash.update(readFileSync(join(packageRoot, file)));
-    hash.update("\0");
-  }
-  return Object.freeze({ files: files.length, sha256: hash.digest("hex") });
-};
-
-export const assertInstalledPackageFingerprint = ({
-  packageRoot,
-  expected,
-}) => {
-  const actual = createInstalledPackageFingerprint({ packageRoot });
-  if (actual.files !== expected?.files || actual.sha256 !== expected?.sha256) {
-    throw new Error(
-      "The installed Rehearsal package changed during this operation. Reinstall the intended version, then start a new command.",
-    );
-  }
-  return actual;
-};
-
-const processIsAlive = (pid) => {
-  if (!Number.isSafeInteger(pid) || pid < 1) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === "EPERM";
-  }
-};
-
-const assertPrivateLockRoot = async () => {
-  await mkdir(LOCK_ROOT, { recursive: true, mode: 0o700 });
-  const details = await stat(LOCK_ROOT);
-  if (
-    !details.isDirectory() ||
-    (details.mode & 0o077) !== 0 ||
-    (typeof process.getuid === "function" && details.uid !== process.getuid())
-  ) {
-    throw new Error("The Rehearsal operation-lock directory is not private.");
-  }
-};
-
-export const acquireProjectOperation = async ({ projectRoot, command }) => {
-  await assertPrivateLockRoot();
-  const canonicalRoot = await realpath(projectRoot);
-  const projectHash = digest(canonicalRoot);
-  const lockDirectory = join(LOCK_ROOT, projectHash);
-  const ownerPath = join(lockDirectory, "owner.json");
-  const token = randomBytes(16).toString("hex");
-  const owner = {
-    formatVersion: 1,
-    pid: process.pid,
-    command,
-    projectHash,
-    token,
-    startedAt: new Date().toISOString(),
-  };
-
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      await mkdir(lockDirectory, { mode: 0o700 });
-      await writeFile(ownerPath, `${JSON.stringify(owner)}\n`, {
-        mode: 0o600,
-        flag: "wx",
-      });
-      const assertOwnership = (current) => {
-        if (current.token !== token || current.pid !== process.pid) {
-          throw new Error(
-            "The Rehearsal operation lock changed ownership unexpectedly.",
-          );
-        }
-      };
-      return Object.freeze({
-        command,
-        async release() {
-          const current = JSON.parse(await readFile(ownerPath, "utf8"));
-          assertOwnership(current);
-          await rm(lockDirectory, { recursive: true });
-        },
-        releaseSync() {
-          const current = JSON.parse(readFileSync(ownerPath, "utf8"));
-          assertOwnership(current);
-          rmSync(lockDirectory, { recursive: true });
-        },
-      });
-    } catch (error) {
-      if (error?.code !== "EEXIST" || attempt > 0) throw error;
-      const details = await lstat(lockDirectory);
-      if (!details.isDirectory() || details.isSymbolicLink()) {
-        throw new Error("The Rehearsal operation lock is unsafe.");
-      }
-      let current;
-      try {
-        current = JSON.parse(await readFile(ownerPath, "utf8"));
-      } catch {
-        throw new Error(
-          "Another Rehearsal operation owns this project, or its lock is incomplete.",
-        );
-      }
-      if (processIsAlive(current.pid)) {
-        throw new Error(
-          `Another Rehearsal operation is already running for this project (PID ${current.pid}).`,
-        );
-      }
-      const staleDirectory = `${lockDirectory}.stale-${token}`;
-      try {
-        await rename(lockDirectory, staleDirectory);
-      } catch (renameError) {
-        if (renameError?.code === "ENOENT") continue;
-        throw renameError;
-      }
-      await rm(staleDirectory, { recursive: true });
-    }
-  }
-  throw new Error("Rehearsal could not acquire its project operation lock.");
-};
-
-export const inspectProjectOperationLocks = async () =>
-  readdir(LOCK_ROOT).catch((error) => {
-    if (error?.code === "ENOENT") return [];
-    throw error;
-  });

package/src/shared/process_environment.mjs

@@ -1,68 +0,0 @@
-/**
- * Purpose: Build minimal child-process environments and validate loopback URLs for
- * the project-neutral Rehearsal runtime. Do not run directly; this module is reusable
- * script infrastructure.
- */
-
-const SAFE_SYSTEM_ENVIRONMENT_KEYS = Object.freeze([
-  "CI",
-  "COLORTERM",
-  "FORCE_COLOR",
-  "HOME",
-  "LANG",
-  "LANGUAGE",
-  "LC_ALL",
-  "LOGNAME",
-  "NO_COLOR",
-  "PATH",
-  "SHELL",
-  "TERM",
-  "TMP",
-  "TMPDIR",
-  "TEMP",
-  "USER",
-]);
-
-const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "localhost"]);
-
-export const isLoopbackUrl = (value) => {
-  try {
-    const parsed = new URL(value);
-    return (
-      ["http:", "https:"].includes(parsed.protocol) &&
-      LOOPBACK_HOSTNAMES.has(parsed.hostname)
-    );
-  } catch {
-    return false;
-  }
-};
-
-export const assertLoopbackUrl = (label, value) => {
-  if (!value || !isLoopbackUrl(value)) {
-    throw new Error(
-      `${label} must use a loopback URL; received a non-local target.`,
-    );
-  }
-};
-
-export const pickEnvironmentVariables = (source, keys) =>
-  Object.fromEntries(
-    keys.flatMap((key) => {
-      const value = source[key];
-      return value === undefined ? [] : [[key, value]];
-    }),
-  );
-
-export const createCleanProcessEnvironment = ({
-  inheritedEnvironment = process.env,
-  overrides = {},
-  passthroughKeys = [],
-} = {}) => ({
-  ...pickEnvironmentVariables(inheritedEnvironment, [
-    ...SAFE_SYSTEM_ENVIRONMENT_KEYS,
-    ...passthroughKeys,
-  ]),
-  ...Object.fromEntries(
-    Object.entries(overrides).filter(([, value]) => value !== undefined),
-  ),
-});