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

package/src/cli/source_commands.mjs

@@ -0,0 +1,326 @@
+/**
+ * CLI orchestration for temporary production-source access and safe baseline
+ * replacement. Domain validation remains in src/source and src/baseline.
+ */
+
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import {
+  activateBaselineGeneration,
+  planBaselineGenerationPrune,
+  planBaselineReplacementPrune,
+  pruneBaselineGenerations,
+  verifyActiveBaseline,
+} from "../baseline/artifact.mjs";
+import { readPrivacyKey } from "../baseline/privacy_engine.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import {
+  createSourceAccessPlan,
+  validateSourceAccessPolicy,
+} from "../source/access.mjs";
+import { streamApprovedSupabaseAssets } from "../source/asset_transfer.mjs";
+import { refreshPostgresqlBaseline } from "../source/baseline.mjs";
+import {
+  applyPostgresqlSourceAccess,
+  planPostgresqlSourceAccessRetirement,
+  retirePostgresqlSourceAccess,
+} from "../source/postgresql_access.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+
+export const loadPreparationContext = async (planOptions) => {
+  const loaded = await loadRehearsalConfig(planOptions);
+  if (!loaded.config.preparation) {
+    throw new Error(
+      "Source preparation is not configured. Review docs/standalone-workflow.md, then enable config.preparation.",
+    );
+  }
+  const sourcePolicyBytes = await readFile(loaded.paths.sourcePolicy);
+  const sourcePolicy = validateSourceAccessPolicy(
+    JSON.parse(sourcePolicyBytes.toString("utf8")),
+  );
+  return { loaded, sourcePolicy, sourcePolicyBytes };
+};
+
+export const runSourceAccess = async ({ flags, planOptions }) => {
+  const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+  const plan = createSourceAccessPlan({ policy: sourcePolicy });
+  if (!flags.sourceAccessConfirmation) return { mode: "preview", plan };
+  const applied = await applyPostgresqlSourceAccess({
+    plan,
+    confirmation: flags.sourceAccessConfirmation,
+    projectRoot: loaded.projectRoot,
+  });
+  return {
+    mode: "written",
+    plan,
+    receipt: applied.receipt,
+    credentialFile: relative(loaded.projectRoot, applied.credentialPath),
+  };
+};
+
+export const runSourceRetirement = async ({ flags, planOptions }) => {
+  const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+  const plan = await planPostgresqlSourceAccessRetirement({
+    projectRoot: loaded.projectRoot,
+    targetFingerprint: sourcePolicy.targetFingerprint,
+  });
+  if (!flags.sourceRetirementConfirmation) return { mode: "preview", plan };
+  await retirePostgresqlSourceAccess({
+    plan,
+    confirmation: flags.sourceRetirementConfirmation,
+    administratorEnvironmentVariable:
+      sourcePolicy.administratorEnvironmentVariable,
+    projectRoot: loaded.projectRoot,
+    credentialFile: sourcePolicy.reader.credentialFile,
+  });
+  return { mode: "written", plan };
+};
+
+const readSourceReaderCredential = async (path) => {
+  const details = await stat(path);
+  if (!details.isFile() || (details.mode & 0o077) !== 0) {
+    throw new Error(
+      "Source reader credential must be an owner-only regular file.",
+    );
+  }
+  const lines = (await readFile(path, "utf8")).split(/\r?\n/u).filter(Boolean);
+  if (
+    lines.length !== 1 ||
+    !lines[0].startsWith("REHEARSAL_SOURCE_DATABASE_URL=")
+  ) {
+    throw new Error("Source reader credential file has an invalid shape.");
+  }
+  const value = lines[0].slice("REHEARSAL_SOURCE_DATABASE_URL=".length);
+  if (!value) throw new Error("Source reader credential file is empty.");
+  return value;
+};
+
+export const runSourceBaselineRefresh = async ({ planOptions }) => {
+  const { loaded, sourcePolicy } = await loadPreparationContext(planOptions);
+  const [
+    sourceAccessReceipt,
+    privacyPolicyBytes,
+    privacyKey,
+    connectionString,
+  ] = await Promise.all([
+    readFile(
+      join(loaded.paths.artifactDirectory, "source-access-receipt.json"),
+      "utf8",
+    ).then(JSON.parse),
+    readFile(loaded.paths.sanitizationPolicy),
+    readPrivacyKey(loaded.paths.privacyKey),
+    readSourceReaderCredential(
+      join(loaded.projectRoot, sourcePolicy.reader.credentialFile),
+    ),
+  ]);
+  return refreshPostgresqlBaseline({
+    connectionString,
+    sourcePolicy,
+    sourceAccessReceipt,
+    privacyPolicyBytes,
+    privacyKey,
+    artifactRoot: loaded.paths.artifactDirectory,
+    migrationDirectory: loaded.paths.migrationDirectory,
+    limits: {
+      batchRows: loaded.config.preparation.batchRows,
+      maximumRows: loaded.config.preparation.maximumRows,
+      maximumBytes: loaded.config.preparation.maximumBytes,
+      diskHeadroomBytes: loaded.config.preparation.diskHeadroomBytes,
+    },
+    assets: sourcePolicy.assetReader
+      ? streamApprovedSupabaseAssets({
+          baseUrl:
+            process.env[sourcePolicy.assetReader.baseUrlEnvironmentVariable],
+          token: process.env[sourcePolicy.assetReader.tokenEnvironmentVariable],
+          declarations: sourcePolicy.assets,
+          maximumObjects: sourcePolicy.assetReader.maximumObjects,
+          maximumObjectBytes: sourcePolicy.assetReader.maximumObjectBytes,
+          maximumTotalBytes: sourcePolicy.assetReader.maximumTotalBytes,
+        })
+      : [],
+  });
+};
+
+export const buildRefreshWorkflowPlan = async (planOptions) => {
+  const [{ loaded, sourcePolicy, sourcePolicyBytes }, topology] =
+    await Promise.all([
+      loadPreparationContext(planOptions),
+      loadRuntimeTopology(planOptions),
+    ]);
+  const hashFile = async (path) =>
+    path
+      ? createHash("sha256")
+          .update(await readFile(path))
+          .digest("hex")
+      : null;
+  const [
+    currentBaseline,
+    sourceAccessReceipt,
+    replacementCleanup,
+    privacyPolicySha256,
+    runtimeConfigurations,
+  ] = await Promise.all([
+    verifyActiveBaseline({ artifactRoot: loaded.paths.artifactDirectory }),
+    readFile(
+      join(loaded.paths.artifactDirectory, "source-access-receipt.json"),
+      "utf8",
+    ).then(JSON.parse),
+    planBaselineReplacementPrune({
+      artifactRoot: loaded.paths.artifactDirectory,
+      retain: loaded.config.cleanup.retainBaselineGenerations,
+    }),
+    hashFile(loaded.paths.sanitizationPolicy),
+    Promise.all(
+      topology.targets.map(async (target) => ({
+        target: target.name,
+        configSha256: await hashFile(target.configPath),
+        runtimePolicySha256: await hashFile(target.paths.runtimePolicy),
+        runtimeAdapterSha256: await hashFile(target.paths.runtimeAdapter),
+        localServiceConfigSha256: await hashFile(target.paths.rehearsalConfig),
+      })),
+    ),
+  ]);
+  if (
+    sourceAccessReceipt.targetFingerprint !== sourcePolicy.targetFingerprint ||
+    !/^[a-f0-9]{64}$/u.test(sourceAccessReceipt.planDigest ?? "")
+  ) {
+    throw new Error(
+      "The source-access receipt does not match the selected refresh policy.",
+    );
+  }
+  const sourceReaderExpiry = new Date(sourceAccessReceipt.expiresAt).valueOf();
+  if (
+    !Number.isFinite(sourceReaderExpiry) ||
+    sourceReaderExpiry <= Date.now()
+  ) {
+    throw new Error(
+      "The temporary source reader has expired. Preview and apply source access again before refreshing.",
+    );
+  }
+  const review = {
+    planVersion: 1,
+    operation: "refresh-and-replace-local-copy",
+    currentBaseline: currentBaseline.generationId,
+    source: {
+      targetFingerprint: sourcePolicy.targetFingerprint,
+      accessPlanDigest: sourceAccessReceipt.planDigest,
+      readerExpiresAt: sourceAccessReceipt.expiresAt,
+      sourcePolicySha256: createHash("sha256")
+        .update(sourcePolicyBytes)
+        .digest("hex"),
+      privacyPolicySha256,
+    },
+    runtimeConfigurations,
+    runtimeTargets: topology.targets.map((target) => target.name),
+    dependentPreparations: topology.dependents.flatMap((target) =>
+      target.declaration.prepareCommand
+        ? [{ target: target.name, command: target.declaration.prepareCommand }]
+        : [],
+    ),
+    retention: {
+      generations: loaded.config.cleanup.retainBaselineGenerations,
+      removeAfterReplacement: replacementCleanup.removedAfterReplacement,
+      keepFromCurrent: replacementCleanup.retainedAfterReplacement,
+    },
+    steps: [
+      "build and verify a new immutable baseline beside the current baseline",
+      "activate the new baseline only after verification",
+      "discard runtime edits and reset the complete local runtime stack",
+      "run configured dependent preparation commands",
+      "remove only the old baseline generations listed in this plan",
+    ],
+  };
+  return {
+    loaded,
+    topology,
+    plan: {
+      review,
+      digest: createHash("sha256")
+        .update(`${JSON.stringify(review, null, "\t")}\n`)
+        .digest("hex"),
+    },
+  };
+};
+
+export const createRefreshWorkflow =
+  ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment }) =>
+  async ({ flags, planOptions }) => {
+    const context = await buildRefreshWorkflowPlan(planOptions);
+    if (!flags.refreshConfirmation) {
+      return { mode: "preview", plan: context.plan };
+    }
+    if (flags.refreshConfirmation !== context.plan.digest) {
+      throw new Error(
+        `Refresh confirmation does not match this exact plan. Expected ${context.plan.digest}. Nothing changed.`,
+      );
+    }
+    let refreshed;
+    let runtime;
+    let preparations = [];
+    try {
+      refreshed = await runSourceBaselineRefresh({ planOptions });
+      const stack = await runRuntimeStack({
+        command: "reset",
+        flags,
+        planOptions,
+      });
+      runtime = stack.runtime;
+      preparations = prepareDependentTargets({
+        topology: stack.topology,
+        environment: topologyCommandEnvironment(stack.topology),
+      });
+    } catch (error) {
+      if (refreshed) {
+        await activateBaselineGeneration({
+          artifactRoot: context.loaded.paths.artifactDirectory,
+          generationId: context.plan.review.currentBaseline,
+        });
+        try {
+          const rollback = await runRuntimeStack({
+            command: "reset",
+            flags,
+            planOptions,
+          });
+          prepareDependentTargets({
+            topology: rollback.topology,
+            environment: topologyCommandEnvironment(rollback.topology),
+          });
+        } catch (rollbackError) {
+          throw new AggregateError(
+            [error, rollbackError],
+            "The refreshed runtime failed and the previous local runtime could not be restored automatically. The previous immutable baseline is active; run rehearsal reset after correcting the reported problem.",
+          );
+        }
+        throw new Error(
+          "The refreshed runtime failed verification. Rehearsal restored the previous baseline and local runtime.",
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+
+    let cleanup;
+    try {
+      const result = await pruneBaselineGenerations({
+        artifactRoot: context.loaded.paths.artifactDirectory,
+        retain: context.plan.review.retention.generations,
+        expectedRemoved: context.plan.review.retention.removeAfterReplacement,
+      });
+      cleanup = { state: "complete", removed: result.removed };
+    } catch {
+      const remaining = await planBaselineGenerationPrune({
+        artifactRoot: context.loaded.paths.artifactDirectory,
+        retain: context.plan.review.retention.generations,
+      }).catch(() => ({ removed: [] }));
+      cleanup = { state: "incomplete", remaining: remaining.removed.length };
+    }
+    return {
+      mode: "written",
+      plan: context.plan,
+      refreshed,
+      runtime,
+      preparations,
+      cleanup,
+    };
+  };

package/src/cli/terminal.mjs

@@ -0,0 +1,275 @@
+/** Terminal presentation and prompt primitives shared by guided CLI workflows. */
+
+import { createInterface } from "node:readline/promises";
+import * as prompts from "@clack/prompts";
+
+const useColor = (flags) =>
+  !flags.plain &&
+  process.stdout.isTTY &&
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb";
+
+export const terminalStyle = (flags, code, value) =>
+  useColor(flags) ? `\u001B[${code}m${value}\u001B[0m` : value;
+
+export const isHumanTerminal = (flags) =>
+  !flags.json && process.stdin.isTTY && process.stdout.isTTY;
+
+export const useStyledPrompts = (flags) =>
+  isHumanTerminal(flags) && useColor(flags);
+
+export const formatDuration = (durationMs) =>
+  durationMs < 1_000
+    ? `${Math.round(durationMs)}ms`
+    : `${(durationMs / 1_000).toFixed(1)}s`;
+
+export const promptForChoice = async ({
+  message,
+  options,
+  flags = {},
+  optionsAlreadyShown = false,
+}) => {
+  if (useStyledPrompts(flags)) {
+    const selected = await prompts.select({
+      message,
+      maxItems: options.length,
+      options: options.map((option) => ({
+        value: option,
+        label: option.label,
+        hint: option.hint,
+      })),
+    });
+    return prompts.isCancel(selected)
+      ? options.find((option) => option.command === "exit")
+      : selected;
+  }
+  if (!optionsAlreadyShown) {
+    console.log(
+      [
+        "",
+        ...options.map(
+          (option, index) =>
+            `  ${index === 0 ? "›" : " "} ${index + 1}. ${option.label}${option.hint ? ` — ${option.hint}` : ""}`,
+        ),
+        "",
+      ].join("\n"),
+    );
+  }
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    while (true) {
+      const answer = (await prompt.question(`${message} [1]: `)).trim();
+      const selected = answer === "" ? 1 : Number(answer);
+      if (
+        Number.isInteger(selected) &&
+        selected >= 1 &&
+        selected <= options.length
+      ) {
+        return options[selected - 1];
+      }
+      console.log(`Choose a number from 1 to ${options.length}.`);
+    }
+  } finally {
+    prompt.close();
+  }
+};
+
+export const promptForConfirmation = async (
+  message,
+  flags = {},
+  { cancelValue = false } = {},
+) => {
+  if (useStyledPrompts(flags)) {
+    const accepted = await prompts.confirm({ message, initialValue: false });
+    return prompts.isCancel(accepted) ? cancelValue : accepted;
+  }
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const answer = (await prompt.question(`${message} (y/N) `))
+      .trim()
+      .toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    prompt.close();
+  }
+};
+
+export const promptForPath = async ({
+  message,
+  defaultValue,
+  optional = false,
+  flags = {},
+  validate,
+}) => {
+  if (useStyledPrompts(flags)) {
+    const answer = await prompts.text({
+      message,
+      placeholder: defaultValue ?? (optional ? "Leave blank for none" : ""),
+      defaultValue,
+      validate: (value) => {
+        const resolved = String(value || defaultValue || "").trim();
+        if (!optional && !resolved) return "Enter a value.";
+        return resolved && validate ? validate(resolved) : undefined;
+      },
+    });
+    if (prompts.isCancel(answer)) return undefined;
+    return String(answer || defaultValue || "").trim() || undefined;
+  }
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    while (true) {
+      const suffix = defaultValue
+        ? ` [${defaultValue}]`
+        : optional
+          ? ""
+          : " (required)";
+      const answer = (await prompt.question(`${message}${suffix}: `)).trim();
+      const value = answer || defaultValue || "";
+      const invalid = value && validate ? validate(value) : undefined;
+      if (invalid) {
+        console.log(invalid);
+        continue;
+      }
+      if (value || optional) return value || undefined;
+      console.log("Enter a project-relative path.");
+    }
+  } finally {
+    prompt.close();
+  }
+};
+
+export const promptForSelection = async ({ message, options, flags }) => {
+  const selected = await promptForChoice({ message, options, flags });
+  return selected?.value;
+};
+
+export const promptForDiscoveredPath = async ({
+  message,
+  candidates,
+  optional = false,
+  flags,
+}) => {
+  if (candidates.length === 0)
+    return promptForPath({ message, optional, flags });
+  const noneValue = "\0none";
+  const manualValue = "\0manual";
+  const selected = await promptForSelection({
+    message,
+    flags,
+    options: [
+      ...(optional
+        ? [
+            {
+              label: "No storage assets",
+              hint: "Continue without an asset manifest",
+              value: noneValue,
+            },
+          ]
+        : []),
+      ...candidates.map((path) => ({ label: path, value: path })),
+      { label: "Enter another path", value: manualValue },
+    ],
+  });
+  if (!selected || selected === noneValue) return undefined;
+  if (selected !== manualValue) return selected;
+  return promptForPath({ message, optional, flags });
+};
+
+export const promptForMultipleChoice = async ({
+  message,
+  options,
+  initialValues = [],
+  flags,
+}) => {
+  if (useStyledPrompts(flags)) {
+    const selected = await prompts.multiselect({
+      message,
+      options: options.map((option) => ({
+        value: option.value,
+        label: option.label,
+        hint: option.hint,
+      })),
+      initialValues,
+      required: false,
+    });
+    return prompts.isCancel(selected) ? undefined : selected;
+  }
+  const initial = new Set(initialValues);
+  console.log("");
+  console.log(message);
+  for (const [index, option] of options.entries()) {
+    console.log(
+      `  ${index + 1}. ${option.label}${initial.has(option.value) ? " (suggested)" : ""}`,
+    );
+  }
+  const defaultNumbers = options
+    .map((option, index) => (initial.has(option.value) ? index + 1 : undefined))
+    .filter(Boolean)
+    .join(",");
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    while (true) {
+      const suffix = defaultNumbers ? ` [${defaultNumbers}]` : " [none]";
+      const answer = (
+        await prompt.question(
+          `Choose comma-separated numbers, all, or none${suffix}: `,
+        )
+      )
+        .trim()
+        .toLowerCase();
+      if (!answer) return [...initialValues];
+      if (answer === "none") return [];
+      if (answer === "all") return options.map((option) => option.value);
+      const indexes = answer.split(",").map((value) => Number(value.trim()));
+      if (
+        indexes.length > 0 &&
+        indexes.every(
+          (index) =>
+            Number.isInteger(index) && index >= 1 && index <= options.length,
+        )
+      ) {
+        return [...new Set(indexes)].map((index) => options[index - 1].value);
+      }
+      console.log(`Choose numbers from 1 to ${options.length}, all, or none.`);
+    }
+  } finally {
+    prompt.close();
+  }
+};
+
+export const installGuidedExitShortcut = (flags, { beforeExit } = {}) => {
+  let exiting = false;
+  const exit = () => {
+    if (exiting) return;
+    exiting = true;
+    if (process.stdin.isTTY && process.stdin.isRaw)
+      process.stdin.setRawMode(false);
+    beforeExit?.();
+    process.stdout.write("\u001B[?25h");
+    if (useStyledPrompts(flags)) prompts.outro("Rehearsal exited.");
+    else console.log("\nRehearsal exited.");
+    process.exit(0);
+  };
+  const onInput = (chunk) => {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (bytes.includes(0x1a)) exit();
+  };
+  process.stdin.prependListener("data", onInput);
+  process.prependListener("SIGTSTP", exit);
+  return () => {
+    process.stdin.removeListener("data", onInput);
+    process.removeListener("SIGTSTP", exit);
+  };
+};