@rehearsal-db/core 0.1.0-beta.6 → 0.1.0-beta.8

package/scripts/lib/rehearsal/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 "./configuration.mjs";
+import { createCleanProcessEnvironment } from "./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/configuration.d.mts

@@ -22,6 +22,12 @@ export interface RehearsalConfig {
     artifactDirectory?: string;
     sanitizationPolicy: string;
   };
+  containerRuntime?: {
+    autoStartColima?: boolean;
+  };
+  cleanup?: {
+    retainBaselineGenerations?: number;
+  };
   application: {
     startCommand: string;
     proofCommand: string;

package/scripts/lib/rehearsal/configuration.mjs

@@ -23,6 +23,8 @@ export const REHEARSAL_CONFIG_VERSION = 1;
 
 export const REHEARSAL_DEFAULTS = Object.freeze({
   baseline: Object.freeze({ artifactDirectory: ".rehearsal" }),
+  containerRuntime: Object.freeze({ autoStartColima: true }),
+  cleanup: Object.freeze({ retainBaselineGenerations: 2 }),
   runtime: Object.freeze({
     applicationUrl: "http://localhost:5175",
     projectId: "rehearsal-local",
@@ -111,6 +113,20 @@ const assertPort = (value, path) => {
   return value;
 };
 
+const assertBoolean = (value, path) => {
+  if (typeof value !== "boolean") {
+    throw new Error(`${path} must be true or false.`);
+  }
+  return value;
+};
+
+const assertPositiveInteger = (value, path) => {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${path} must be a positive integer.`);
+  }
+  return value;
+};
+
 const assertStringArray = (value, path) => {
   if (
     !Array.isArray(value) ||
@@ -151,6 +167,8 @@ const normalizeConfig = (input) => {
       "supabase",
       "postgresql",
       "baseline",
+      "containerRuntime",
+      "cleanup",
       "application",
       "runtime",
       "safety",
@@ -219,6 +237,17 @@ const normalizeConfig = (input) => {
     ["artifactDirectory", "sanitizationPolicy"],
     "config.baseline",
   );
+  const containerRuntime = assertPlainObject(
+    root.containerRuntime ?? {},
+    "config.containerRuntime",
+  );
+  assertKnownKeys(
+    containerRuntime,
+    ["autoStartColima"],
+    "config.containerRuntime",
+  );
+  const cleanup = assertPlainObject(root.cleanup ?? {}, "config.cleanup");
+  assertKnownKeys(cleanup, ["retainBaselineGenerations"], "config.cleanup");
   const application = assertPlainObject(root.application, "config.application");
   assertKnownKeys(
     application,
@@ -426,6 +455,20 @@ const normalizeConfig = (input) => {
         "config.baseline.sanitizationPolicy",
       ),
     }),
+    containerRuntime: Object.freeze({
+      autoStartColima: assertBoolean(
+        containerRuntime.autoStartColima ??
+          REHEARSAL_DEFAULTS.containerRuntime.autoStartColima,
+        "config.containerRuntime.autoStartColima",
+      ),
+    }),
+    cleanup: Object.freeze({
+      retainBaselineGenerations: assertPositiveInteger(
+        cleanup.retainBaselineGenerations ??
+          REHEARSAL_DEFAULTS.cleanup.retainBaselineGenerations,
+        "config.cleanup.retainBaselineGenerations",
+      ),
+    }),
     application: Object.freeze({
       startCommand: assertCommand(
         application.startCommand,
@@ -649,27 +692,60 @@ export const renderDetectedConfig = (
     applicationUrl = "http://localhost:5175",
     ports = { api: 58321, database: 58322, studio: 58323 },
   } = {},
-) => `// @ts-check
+) =>
+  `// @ts-check
+/**
+ * Rehearsal configuration for ${detected.projectName}.
+ * Generated from this project by \`npx rehearsal\` and safe to commit.
+ * Review the CHECK comments. Keep passwords, tokens, and production URLs out of this file.
+ * Docs: https://github.com/Ddupasquier/rehearsal-db/blob/main/docs/configuration.md
+ */
 import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
+	// Configuration format. Rehearsal will explain if an upgrade is ever needed.
 	schemaVersion: 1,
+	// Stable local name used in Rehearsal labels and reports.
 	project: { name: ${JSON.stringify(detected.projectName)} },
+
+	// Project files Rehearsal reads. Every path stays inside this repository.
 	supabase: {
 		workdir: ".",
 		migrationDirectory: "supabase/migrations",
 		rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
 		runtimeWorkdir: ".rehearsal/runtime",
+
+		// Optional local-only identity-provider credentials. Enable both keys together.
+		// serviceEnvironmentFile: ".env.rehearsal-service.local",
+		// serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
 	},
+
+	// Immutable local baseline files. Rehearsal never reads production on your behalf.
 	baseline: {
 		artifactDirectory: ".rehearsal",
 		sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
 	},
+
+	// Reuse any running Docker-compatible engine; start Colima only when needed.
+	containerRuntime: {
+		autoStartColima: true,
+	},
+
+	// Keep this many baseline generations, always including the active one.
+	cleanup: {
+		retainBaselineGenerations: 2,
+	},
+
 	application: {
+		// CHECK: commands detected from package.json. Change them if they are not correct.
 		startCommand: ${JSON.stringify(detected.applicationCommand)},
 		proofCommand: ${JSON.stringify(detected.verificationCommand)},
 		environmentFile: ".rehearsal/runtime.env",
+		// Optional project-specific restore hook:
+		// runtimeAdapter: "infrastructure/rehearsal/runtime-adapter.mjs",
 	},
+
+	// Disposable local runtime identity, URL, and dedicated ports.
 	runtime: {
 		target: "supabase",
 		applicationUrl: ${JSON.stringify(applicationUrl)},
@@ -678,6 +754,8 @@ export default defineRehearsalConfig({
 		databasePort: ${ports.database},
 		studioPort: ${ports.studio},
 	},
+
+	// Only local runtime URLs are accepted; common hosted credentials are quarantined.
 	safety: {
 		allowedHosts: ["127.0.0.1", "::1", "localhost"],
 		blockedEnvironmentVariables: [
@@ -688,19 +766,29 @@ export default defineRehearsalConfig({
 		hostedAccess: "disabled",
 		outboundNetwork: "deny",
 	},
-	verification: { commands: [${JSON.stringify(detected.verificationCommand)}] },
 });
-`;
+`.replaceAll("\t", "  ");
 
 export const renderDetectedPostgresqlConfig = (
   detected,
   { applicationUrl = "http://localhost:5175", databasePort = 58322 } = {},
-) => `// @ts-check
+) =>
+  `// @ts-check
+/**
+ * Rehearsal configuration for ${detected.projectName}.
+ * Generated from this project by \`npx rehearsal\` and safe to commit.
+ * Review the CHECK comments. Keep passwords, tokens, and production URLs out of this file.
+ * Docs: https://github.com/Ddupasquier/rehearsal-db/blob/main/docs/configuration.md
+ */
 import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
+	// Configuration format. Rehearsal will explain if an upgrade is ever needed.
 	schemaVersion: 1,
+	// Stable local name used in Rehearsal labels and reports.
 	project: { name: ${JSON.stringify(detected.projectName)} },
+
+	// Disposable PostgreSQL settings. The image must already exist locally.
 	postgresql: {
 		migrationDirectory: ${JSON.stringify(detected.postgresqlMigrationDirectory)},
 		runtimeWorkdir: ".rehearsal/runtime",
@@ -708,21 +796,41 @@ export default defineRehearsalConfig({
 		database: "postgres",
 		user: "postgres",
 	},
+
+	// Immutable local baseline files. Rehearsal never reads production on your behalf.
 	baseline: {
 		artifactDirectory: ".rehearsal",
 		sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
 	},
+
+	// Reuse any running Docker-compatible engine; start Colima only when needed.
+	containerRuntime: {
+		autoStartColima: true,
+	},
+
+	// Keep this many baseline generations, always including the active one.
+	cleanup: {
+		retainBaselineGenerations: 2,
+	},
+
 	application: {
+		// CHECK: commands detected from package.json. Change them if they are not correct.
 		startCommand: ${JSON.stringify(detected.applicationCommand)},
 		proofCommand: ${JSON.stringify(detected.verificationCommand)},
 		environmentFile: ".rehearsal/runtime.env",
+		// Optional project-specific restore hook:
+		// runtimeAdapter: "infrastructure/rehearsal/runtime-adapter.mjs",
 	},
+
+	// Disposable local runtime identity, URL, and dedicated database port.
 	runtime: {
 		target: "postgresql",
 		applicationUrl: ${JSON.stringify(applicationUrl)},
 		projectId: "${detected.projectName}-rehearsal",
 		databasePort: ${databasePort},
 	},
+
+	// Only local runtime URLs are accepted; common hosted credentials are quarantined.
 	safety: {
 		allowedHosts: ["127.0.0.1", "::1", "localhost"],
 		blockedEnvironmentVariables: [
@@ -735,6 +843,5 @@ export default defineRehearsalConfig({
 		hostedAccess: "disabled",
 		outboundNetwork: "deny",
 	},
-	verification: { commands: [${JSON.stringify(detected.verificationCommand)}] },
 });
-`;
+`.replaceAll("\t", "  ");

package/scripts/lib/rehearsal/diagnostics.mjs

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 
 export const REHEARSAL_RESULT_VERSION = 1;
-export const REHEARSAL_VERSION = "0.1.0-beta.6";
+export const REHEARSAL_VERSION = "0.1.0-beta.8";
 
 export const REHEARSAL_EXIT_CODES = Object.freeze({
   success: 0,

package/scripts/lib/rehearsal/plan.mjs

@@ -237,7 +237,7 @@ export const buildRehearsalPlan = async (options = {}) => {
         "versioned configuration accepts loopback hosts only",
         `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(", ")}`,
@@ -651,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" ||
@@ -660,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.",
     },