@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.11

package/src/runtime/cleanup.mjs

@@ -0,0 +1,381 @@
+/**
+ * Purpose: Preview and apply narrowly scoped Rehearsal cleanup without global
+ * Docker pruning or deletion of unowned database resources.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { stat } from "node:fs/promises";
+import {
+  planBaselineGenerationPrune,
+  pruneBaselineGenerations,
+} from "../baseline/artifact.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
+
+const SUPABASE_IMAGE_PREFIX = "public.ecr.aws/supabase/";
+
+const commandResult = (command, args, { projectRoot }) =>
+  spawnSync(command, args, {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: createCleanProcessEnvironment(),
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+const runDocker = (args, { projectRoot, allowFailure = false }) => {
+  const result = commandResult("docker", args, { projectRoot });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    const detail = [result.stdout, result.stderr]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    throw new Error(
+      `docker ${args.join(" ")} failed${detail ? `:\n${detail}` : "."}`,
+    );
+  }
+  return result;
+};
+
+const nonEmptyLines = (value) =>
+  String(value ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+const dockerAvailable = (projectRoot) =>
+  runDocker(["info"], { projectRoot, allowFailure: true }).status === 0;
+
+export const parsePosixDiskUsage = (output) => {
+  const columns = nonEmptyLines(output).at(-1)?.split(/\s+/u) ?? [];
+  if (columns.length < 6) return null;
+  const totalKiB = Number(columns[1]);
+  const usedKiB = Number(columns[2]);
+  const availableKiB = Number(columns[3]);
+  const usedPercent = Number.parseInt(columns[4], 10);
+  if (![totalKiB, usedKiB, availableKiB, usedPercent].every(Number.isFinite)) {
+    return null;
+  }
+  return {
+    totalBytes: totalKiB * 1024,
+    usedBytes: usedKiB * 1024,
+    availableBytes: availableKiB * 1024,
+    usedPercent,
+  };
+};
+
+const inspectContainerDisk = (projectRoot) => {
+  const context = commandResult("docker", ["context", "show"], {
+    projectRoot,
+  });
+  if (context.status !== 0 || context.stdout.trim() !== "colima") return null;
+  const result = commandResult(
+    "colima",
+    ["ssh", "--", "df", "-Pk", "/var/lib/docker"],
+    { projectRoot },
+  );
+  const usage = result.status === 0 ? parsePosixDiskUsage(result.stdout) : null;
+  return usage ? { backend: "colima", ...usage } : null;
+};
+
+const inspectDockerUsage = (projectRoot) => {
+  if (!dockerAvailable(projectRoot)) {
+    return { available: false, resources: [], disk: null };
+  }
+  const result = runDocker(["system", "df", "--format", "{{json .}}"], {
+    projectRoot,
+  });
+  return {
+    available: true,
+    resources: nonEmptyLines(result.stdout).map((line) => JSON.parse(line)),
+    disk: inspectContainerDisk(projectRoot),
+  };
+};
+
+const inspectUsedImageIds = (projectRoot) => {
+  const containers = nonEmptyLines(
+    runDocker(["container", "ls", "--all", "--quiet"], { projectRoot }).stdout,
+  );
+  if (containers.length === 0) return new Set();
+  return new Set(
+    nonEmptyLines(
+      runDocker(
+        ["container", "inspect", "--format", "{{.Image}}", ...containers],
+        { projectRoot },
+      ).stdout,
+    ),
+  );
+};
+
+const splitImageTag = (value) => {
+  const separator = value.lastIndexOf(":");
+  if (separator <= value.lastIndexOf("/")) return null;
+  return {
+    repository: value.slice(0, separator),
+    tag: value.slice(separator + 1),
+  };
+};
+
+export const selectOlderUnusedSupabaseImages = ({ images, usedImageIds }) => {
+  const byRepository = new Map();
+  for (const image of images) {
+    for (const fullTag of image.RepoTags ?? []) {
+      const parsed = splitImageTag(fullTag);
+      if (!parsed?.repository.startsWith(SUPABASE_IMAGE_PREFIX)) continue;
+      const entries = byRepository.get(parsed.repository) ?? [];
+      entries.push({
+        id: image.Id,
+        createdAt: image.Created,
+        bytes: image.Size,
+        fullTag,
+      });
+      byRepository.set(parsed.repository, entries);
+    }
+  }
+
+  const candidatesById = new Map();
+  for (const entries of byRepository.values()) {
+    const newestId = [...entries].sort(
+      (left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt),
+    )[0]?.id;
+    for (const entry of entries) {
+      if (entry.id === newestId || usedImageIds.has(entry.id)) continue;
+      const existing = candidatesById.get(entry.id) ?? {
+        id: entry.id,
+        createdAt: entry.createdAt,
+        bytes: entry.bytes,
+        tags: [],
+      };
+      existing.tags.push(entry.fullTag);
+      candidatesById.set(entry.id, existing);
+    }
+  }
+  return [...candidatesById.values()]
+    .map((entry) => ({ ...entry, tags: [...new Set(entry.tags)].sort() }))
+    .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+};
+
+const inspectUnusedImages = (projectRoot) => {
+  const imageIds = [
+    ...new Set(
+      nonEmptyLines(
+        runDocker(["image", "ls", "--quiet", "--no-trunc"], {
+          projectRoot,
+        }).stdout,
+      ),
+    ),
+  ];
+  if (imageIds.length === 0) return [];
+  const images = nonEmptyLines(
+    runDocker(["image", "inspect", "--format", "{{json .}}", ...imageIds], {
+      projectRoot,
+    }).stdout,
+  ).map((line) => JSON.parse(line));
+  return selectOlderUnusedSupabaseImages({
+    images,
+    usedImageIds: inspectUsedImageIds(projectRoot),
+  });
+};
+
+const runtimeDetected = async ({ config, paths, projectRoot }) => {
+  try {
+    await stat(paths.runtimeWorkdir);
+    return true;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  if (!dockerAvailable(projectRoot)) return false;
+  if (config.runtime.target === "postgresql") {
+    const containers = runDocker(
+      [
+        "container",
+        "ls",
+        "--all",
+        "--filter",
+        `label=com.rehearsal-db.project=${config.runtime.projectId}`,
+        "--quiet",
+      ],
+      { projectRoot },
+    );
+    const volumes = runDocker(
+      [
+        "volume",
+        "ls",
+        "--filter",
+        `label=com.rehearsal-db.project=${config.runtime.projectId}`,
+        "--quiet",
+      ],
+      { projectRoot },
+    );
+    return (
+      nonEmptyLines(containers.stdout).length > 0 ||
+      nonEmptyLines(volumes.stdout).length > 0
+    );
+  }
+  const containers = runDocker(
+    [
+      "container",
+      "ls",
+      "--all",
+      "--filter",
+      `label=com.supabase.cli.project=${config.runtime.projectId}`,
+      "--quiet",
+    ],
+    { projectRoot },
+  );
+  const volumes = nonEmptyLines(
+    runDocker(["volume", "ls", "--format", "{{.Name}}"], { projectRoot })
+      .stdout,
+  );
+  return (
+    nonEmptyLines(containers.stdout).length > 0 ||
+    volumes.some((name) => name.endsWith(`_${config.runtime.projectId}`))
+  );
+};
+
+const inspectBaselineCleanup = async ({ artifactRoot, retain }) => {
+  try {
+    return {
+      available: true,
+      ...(await planBaselineGenerationPrune({ artifactRoot, retain })),
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { available: false, retained: [], removed: [] };
+    }
+    throw error;
+  }
+};
+
+const cleanupIdentity = (plan) => ({
+  projectId: plan.projectId,
+  retainBaselineGenerations: plan.retainBaselineGenerations,
+  baselineGenerations: plan.baselines.removed,
+  runtime: plan.runtime.included && plan.runtime.detected,
+  images: plan.images.candidates.map(({ id, tags }) => ({ id, tags })),
+});
+
+const cleanupDigest = (plan) =>
+  createHash("sha256")
+    .update(JSON.stringify(cleanupIdentity(plan)))
+    .digest("hex");
+
+export const planRehearsalCleanup = async ({
+  projectRoot = process.cwd(),
+  configPath,
+  includeRuntime = false,
+  includeImages = false,
+  inspection = { inspectDockerUsage, runtimeDetected },
+} = {}) => {
+  const loaded = await loadRehearsalConfig({ projectRoot, configPath });
+  const docker = inspection.inspectDockerUsage(loaded.projectRoot);
+  const baselines = await inspectBaselineCleanup({
+    artifactRoot: loaded.paths.artifactDirectory,
+    retain: loaded.config.cleanup.retainBaselineGenerations,
+  });
+  const images = {
+    requested: includeImages,
+    inspected: includeImages && docker.available,
+    candidates:
+      includeImages && docker.available
+        ? inspectUnusedImages(loaded.projectRoot)
+        : [],
+  };
+  const plan = {
+    project: loaded.config.project.name,
+    projectId: loaded.config.runtime.projectId,
+    target: loaded.config.runtime.target,
+    retainBaselineGenerations: loaded.config.cleanup.retainBaselineGenerations,
+    baselines,
+    runtime: {
+      included: includeRuntime,
+      detected: await inspection.runtimeDetected({ ...loaded }),
+    },
+    images,
+    docker,
+  };
+  return Object.freeze({ ...plan, digest: cleanupDigest(plan) });
+};
+
+const removePlannedImages = ({ candidates, projectRoot }) => {
+  if (candidates.length === 0) return [];
+  const usedImageIds = inspectUsedImageIds(projectRoot);
+  const removed = [];
+  for (const candidate of candidates) {
+    if (usedImageIds.has(candidate.id)) {
+      throw new Error(
+        `Cleanup stopped because a container began using ${candidate.id}. Preview the cleanup again.`,
+      );
+    }
+    for (const tag of candidate.tags) {
+      const inspection = runDocker(
+        ["image", "inspect", "--format", "{{.Id}}", tag],
+        { projectRoot, allowFailure: true },
+      );
+      if (inspection.status !== 0) continue;
+      if (inspection.stdout.trim() !== candidate.id) {
+        throw new Error(
+          `Cleanup stopped because ${tag} changed after the preview. Preview the cleanup again.`,
+        );
+      }
+      runDocker(["image", "rm", tag], { projectRoot });
+      removed.push(tag);
+    }
+  }
+  return removed;
+};
+
+export const applyRehearsalCleanup = async ({
+  plan,
+  confirmation,
+  projectRoot = process.cwd(),
+  configPath,
+  removeRuntime = async () => undefined,
+  inspection,
+} = {}) => {
+  if (confirmation !== plan?.digest) {
+    throw new Error(
+      "Cleanup requires the exact --confirm-cleanup digest from a fresh preview. Nothing was removed.",
+    );
+  }
+  const refreshed = await planRehearsalCleanup({
+    projectRoot,
+    configPath,
+    includeRuntime: plan.runtime.included,
+    includeImages: plan.images.inspected,
+    ...(inspection ? { inspection } : {}),
+  });
+  if (refreshed.digest !== plan.digest) {
+    throw new Error(
+      "Cleanup targets changed after the preview. Nothing was removed; preview the cleanup again.",
+    );
+  }
+  if (plan.images.requested && !refreshed.images.inspected) {
+    throw new Error(
+      "Docker is unavailable, so Rehearsal cannot verify or remove unused images.",
+    );
+  }
+  if (refreshed.runtime.included && refreshed.runtime.detected) {
+    await removeRuntime();
+  }
+  const loaded = await loadRehearsalConfig({ projectRoot, configPath });
+  const baselines = refreshed.baselines.available
+    ? await pruneBaselineGenerations({
+        artifactRoot: loaded.paths.artifactDirectory,
+        retain: refreshed.retainBaselineGenerations,
+        expectedRemoved: refreshed.baselines.removed,
+      })
+    : { retained: [], removed: [] };
+  const images = removePlannedImages({
+    candidates: refreshed.images.candidates,
+    projectRoot: loaded.projectRoot,
+  });
+  return {
+    project: refreshed.project,
+    projectId: refreshed.projectId,
+    baselines,
+    runtimeRemoved: refreshed.runtime.included && refreshed.runtime.detected,
+    imagesRemoved: images,
+  };
+};

package/{scripts/lib/rehearsal → src/runtime}/plan.mjs

@@ -10,15 +10,19 @@ import { createConnection } from "node:net";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { performance } from "node:perf_hooks";
-import { verifyActiveBaseline } from "./baseline_artifact.mjs";
+import { verifyActiveBaseline } from "../baseline/artifact.mjs";
 import {
   inspectDetectedProject,
   loadRehearsalConfig,
-} from "./configuration.mjs";
-import { createCandidateMigrationReceipt } from "./runtime_restore.mjs";
+} from "../project/configuration.mjs";
+import { createCandidateMigrationReceipt } from "./restore.mjs";
 import { readMigrationFileInventory } from "./migration_history.mjs";
-import { REHEARSAL_VERSION } from "./diagnostics.mjs";
+import { REHEARSAL_VERSION } from "../shared/diagnostics.mjs";
 import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
+import {
+  readBoundRuntimeSanitizationPolicy,
+  validateRuntimeSanitizationPolicy,
+} from "../baseline/sanitization_policy.mjs";
 
 const commandAvailable = (command, args = ["--version"]) => {
   const result = spawnSync(command, args, {
@@ -101,6 +105,14 @@ const resultCheck = async ({ id, label, run, remediation }) => {
 };
 
 const assertRuntimeConfigMatches = async ({ config, paths }) => {
+  if (config.runtime.target === "postgresql") {
+    if (paths.rehearsalConfig !== null || paths.supabaseWorkdir !== null) {
+      throw new Error(
+        "The PostgreSQL target unexpectedly resolved Supabase paths.",
+      );
+    }
+    return `isolated PostgreSQL image ${config.postgresql.image} and a loopback database port are configured`;
+  }
   const source = await readFile(paths.rehearsalConfig, "utf8");
   const expected = [
     ["project_id", config.runtime.projectId],
@@ -155,8 +167,15 @@ const assertConfiguredCommand = async ({ command, projectRoot }) => {
 
 const loadPlanInputs = async (options = {}) => {
   const loaded = await loadRehearsalConfig(options);
-  const baseline = await verifyActiveBaseline({
-    artifactRoot: loaded.paths.artifactDirectory,
+  const [baseline, policyBytes] = await Promise.all([
+    verifyActiveBaseline({
+      artifactRoot: loaded.paths.artifactDirectory,
+    }),
+    readFile(loaded.paths.sanitizationPolicy),
+  ]);
+  readBoundRuntimeSanitizationPolicy({
+    bytes: policyBytes,
+    expectedSha256: baseline.sanitizationPolicySha256,
   });
   const currentFiles = await readMigrationFileInventory(
     new URL("./", pathToFileURL(`${loaded.paths.migrationDirectory}/`)),
@@ -206,7 +225,8 @@ export const buildRehearsalPlan = async (options = {}) => {
       project: config.project.name,
     },
     environment: {
-      kind: "isolated_local_supabase",
+      target: config.runtime.target,
+      kind: `isolated_local_${config.runtime.target}`,
       applicationUrl: config.runtime.applicationUrl,
       projectId: config.runtime.projectId,
       ports: config.runtime.ports,
@@ -215,9 +235,9 @@ export const buildRehearsalPlan = async (options = {}) => {
       authenticationProviders: config.safety.authenticationProviders,
       barriers: [
         "versioned configuration accepts loopback hosts only",
-        "runtime uses a dedicated local Supabase workdir and project id",
+        `runtime uses a dedicated local ${config.runtime.target === "supabase" ? "Supabase workdir" : "PostgreSQL container and volume"} and project id`,
         "child processes receive an allowlisted environment",
-        "application egress policy denies hosted targets and side effects",
+        "configuration accepts only loopback runtime URLs and quarantines common hosted credentials",
         ...(config.safety.authenticationProviders.length
           ? [
               `external identity is limited to: ${config.safety.authenticationProviders.join(", ")}`,
@@ -371,14 +391,37 @@ export const runRehearsalDoctor = async (options = {}) => {
       remediation: "Use npm for the initial Rehearsal contract.",
     },
     {
-      id: "supabase-cli",
-      label: "Supabase CLI",
+      id:
+        config.runtime.target === "supabase"
+          ? "supabase-cli"
+          : "postgresql-image",
+      label:
+        config.runtime.target === "supabase"
+          ? "Supabase CLI"
+          : "PostgreSQL image",
       run: async () => {
-        const result = commandAvailable("supabase");
-        if (!result.available) throw new Error("Supabase CLI is unavailable.");
-        return result.version;
+        if (config.runtime.target === "supabase") {
+          const result = commandAvailable("supabase");
+          if (!result.available)
+            throw new Error("Supabase CLI is unavailable.");
+          return result.version;
+        }
+        const result = commandAvailable("docker", [
+          "image",
+          "inspect",
+          config.postgresql.image,
+        ]);
+        if (!result.available) {
+          throw new Error(
+            `PostgreSQL image ${config.postgresql.image} is unavailable locally.`,
+          );
+        }
+        return config.postgresql.image;
       },
-      remediation: "Install the Supabase CLI in the project and retry.",
+      remediation:
+        config.runtime.target === "supabase"
+          ? "Install the Supabase CLI in the project and retry."
+          : `Pull and review ${config.postgresql.image}, then retry.`,
     },
     {
       id: "docker",
@@ -401,17 +444,33 @@ export const runRehearsalDoctor = async (options = {}) => {
       run: async () => {
         await Promise.all([
           verifyPath(paths.migrationDirectory, "directory"),
-          verifyPath(paths.rehearsalConfig, "file"),
+          ...(paths.rehearsalConfig
+            ? [verifyPath(paths.rehearsalConfig, "file")]
+            : []),
           verifyPath(paths.sanitizationPolicy, "file"),
           ...(paths.runtimeAdapter
             ? [verifyPath(paths.runtimeAdapter, "file")]
             : []),
         ]);
-        return "migrations, local runtime config, and sanitization policy exist";
+        return config.runtime.target === "supabase"
+          ? "migrations, local runtime config, and sanitization policy exist"
+          : "migrations and sanitization policy exist";
       },
       remediation:
         "Correct the missing project path in the Rehearsal configuration.",
     },
+    {
+      id: "sanitization-policy",
+      label: "Reviewed sanitization policy",
+      run: async () => {
+        const policy = validateRuntimeSanitizationPolicy(
+          JSON.parse(await readFile(paths.sanitizationPolicy, "utf8")),
+        );
+        return `${policy.tables.length} table classifications reviewed through ${policy.migrationCutoff}`;
+      },
+      remediation:
+        "Complete every REVIEW REQUIRED decision, remove draft only after review, and retry.",
+    },
     {
       id: "runtime-isolation",
       label: "Runtime target isolation",
@@ -423,6 +482,9 @@ export const runRehearsalDoctor = async (options = {}) => {
       id: "service-environment",
       label: "Local service credentials",
       run: async () => {
+        if (config.runtime.target === "postgresql") {
+          return "no local service credentials required";
+        }
         const environment = await readRehearsalServiceEnvironment({
           path: paths.serviceEnvironment,
           keys: config.supabase.serviceEnvironmentVariables,
@@ -449,6 +511,42 @@ export const runRehearsalDoctor = async (options = {}) => {
         );
         const occupied = availability.filter((entry) => !entry.available);
         if (occupied.length) {
+          if (config.runtime.target === "postgresql") {
+            const status = spawnSync(
+              "docker",
+              [
+                "ps",
+                "--filter",
+                `label=com.rehearsal-db.project=${config.runtime.projectId}`,
+                "--format",
+                "{{.Ports}}",
+              ],
+              {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: Object.fromEntries(
+                  ["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap(
+                    (key) =>
+                      process.env[key] === undefined
+                        ? []
+                        : [[key, process.env[key]]],
+                  ),
+                ),
+                stdio: ["ignore", "pipe", "pipe"],
+              },
+            );
+            if (
+              status.status !== 0 ||
+              !String(status.stdout).includes(
+                `127.0.0.1:${config.runtime.ports.database}->5432/tcp`,
+              )
+            ) {
+              throw new Error(
+                `Configured database port is occupied by an unverified process: database=${config.runtime.ports.database}.`,
+              );
+            }
+            return "occupied only by the configured local Rehearsal runtime";
+          }
           const serviceEnvironment = await readRehearsalServiceEnvironment({
             path: paths.serviceEnvironment,
             keys: config.supabase.serviceEnvironmentVariables,
@@ -553,7 +651,7 @@ export const runRehearsalDoctor = async (options = {}) => {
     },
     {
       id: "safety-policy",
-      label: "Hosted access and side effects",
+      label: "Hosted target configuration",
       run: async () => {
         if (
           config.safety.hostedAccess !== "disabled" ||
@@ -562,8 +660,8 @@ export const runRehearsalDoctor = async (options = {}) => {
           throw new Error("The safety policy is not fail closed.");
         }
         return config.safety.authenticationProviders.length
-          ? `hosted access disabled; application egress denied; identity providers: ${config.safety.authenticationProviders.join(", ")}`
-          : "hosted access disabled; outbound network denied";
+          ? `hosted database targets disabled; hosted credentials quarantined; local identity providers: ${config.safety.authenticationProviders.join(", ")}`
+          : "hosted database targets disabled; common hosted credentials quarantined";
       },
       remediation: "Restore the version-1 fail-closed safety policy.",
     },