takt-marp 0.1.0

package/scripts/takt-marp-build-slide-artifact.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import path from "node:path";
+import {
+  formatError,
+  parseArgs,
+  SlideWorkflowError,
+} from "./lib/takt-marp-slide-workflow.mjs";
+import { runtimeExecutablePath } from "./lib/takt-marp-runtime-context.mjs";
+
+const ARTIFACT_OPTIONS = Object.freeze({
+  html: ["--html"],
+  pdf: ["--pdf", "--html"],
+  pptx: ["--pptx", "--html"],
+});
+
+function usage() {
+  return [
+    "Usage: node scripts/takt-marp-build-slide-artifact.mjs <html|pdf|pptx> [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
+    "",
+    "When deck is omitted, all slides/*/SLIDES.md files are built.",
+    "",
+    "Examples:",
+    "  npm run build:pdf -- my-talk",
+    "  npm run build:html -- slides/my-talk",
+    "  npm run build:pptx -- slides/my-talk/SLIDES.md",
+  ].join("\n");
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+
+  const [artifact, target] = positional;
+  if (!ARTIFACT_OPTIONS[artifact]) {
+    throw new SlideWorkflowError(usage(), "INVALID_ARGS");
+  }
+
+  const targets = await resolveBuildTargets(target);
+  for (const item of targets) {
+    await buildArtifact(artifact, item);
+  }
+}
+
+async function resolveBuildTargets(target) {
+  if (!target) {
+    return listDecksWithSlides();
+  }
+  return [resolveBuildTarget(target)];
+}
+
+async function listDecksWithSlides() {
+  const slidesRoot = path.join(process.cwd(), "slides");
+  const entries = await readdir(slidesRoot, { withFileTypes: true });
+  const targets = entries
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => existsSync(path.join(slidesRoot, entry.name, "SLIDES.md")))
+    .map((entry) => resolveBuildTarget(entry.name))
+    .sort((left, right) => left.deckName.localeCompare(right.deckName));
+
+  if (targets.length === 0) {
+    throw new SlideWorkflowError("No slides/*/SLIDES.md files found.", "SLIDES_NOT_FOUND");
+  }
+  return targets;
+}
+
+function resolveBuildTarget(target) {
+  if (!target || path.isAbsolute(target)) {
+    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
+  }
+
+  const normalized = path.posix.normalize(target.replaceAll(path.sep, "/"));
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
+  }
+
+  const parts = normalized.split("/");
+  const deckName = deckNameFromParts(parts, target);
+  const deckPath = path.join(process.cwd(), "slides", deckName);
+  const slidesPath = path.join(deckPath, "SLIDES.md");
+  if (!existsSync(slidesPath)) {
+    throw new SlideWorkflowError(`SLIDES.md not found: slides/${deckName}/SLIDES.md`, "SLIDES_NOT_FOUND");
+  }
+
+  return Object.freeze({
+    deckName,
+    slidesPath,
+    distPath: path.join(process.cwd(), "dist", deckName),
+  });
+}
+
+function deckNameFromParts(parts, original) {
+  if (parts.length === 1 && parts[0] && !parts[0].endsWith(".md")) {
+    return parts[0];
+  }
+  if (parts.length === 2 && parts[0] === "slides" && parts[1] && !parts[1].endsWith(".md")) {
+    return parts[1];
+  }
+  if (parts.length === 3 && parts[0] === "slides" && parts[1] && parts[2] === "SLIDES.md") {
+    return parts[1];
+  }
+  throw new SlideWorkflowError(
+    `Invalid deck target '${original}'. Expected deck, slides/<deck>, or slides/<deck>/SLIDES.md.`,
+    "INVALID_TARGET",
+  );
+}
+
+async function buildArtifact(artifact, target) {
+  await mkdir(target.distPath, { recursive: true });
+  const outputPath = path.join(target.distPath, `SLIDES.${artifact}`);
+  const marpPath = runtimeExecutablePath("marp");
+  const args = [
+    target.slidesPath,
+    ...ARTIFACT_OPTIONS[artifact],
+    "--allow-local-files",
+    "--output",
+    outputPath,
+  ];
+  const code = await run(marpPath, args);
+  if (code !== 0) {
+    throw new SlideWorkflowError(`Marp failed for slides/${target.deckName}/SLIDES.md`, "MARP_BUILD_FAILED");
+  }
+}
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      shell: process.platform === "win32",
+      stdio: "inherit",
+    });
+    child.on("error", (error) => {
+      reject(
+        new SlideWorkflowError(
+          `Failed to start Marp executable: ${command}. Run npm install and verify the @marp-team/marp-cli devDependency. ${error.message}`,
+          "MARP_EXECUTABLE_MISSING",
+        ),
+      );
+    });
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+main().catch((error) => {
+  console.error(formatError(error));
+  process.exit(1);
+});

package/scripts/takt-marp-check-slide-workflow-state.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import {
+  checkRequiredState,
+  formatError,
+  parseArgs,
+  parseRequiredState,
+  resolveDeckTarget,
+} from "./lib/takt-marp-slide-workflow.mjs";
+
+function usage() {
+  return [
+    "Usage: node scripts/takt-marp-check-slide-workflow-state.mjs <target> --require <command>:<state>[:approved]",
+    "",
+    "Examples:",
+    "  npm run slide:check-state -- \"slides/my-talk\" --require plan:planned:approved",
+    "  npm run slide:check-state -- \"slides/my-talk\" --require polish:polished",
+  ].join("\n");
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+  const [target] = positional;
+  const requirementText = flags.require;
+  if (!target || !requirementText) {
+    throw new Error(usage());
+  }
+
+  const targetInfo = resolveDeckTarget(target);
+  const requirement = parseRequiredState(requirementText);
+  await checkRequiredState(targetInfo, requirement);
+  console.log(`state ok: ${targetInfo.target} ${requirementText}`);
+}
+
+main().catch((error) => {
+  console.error(formatError(error));
+  process.exit(1);
+});

package/scripts/takt-marp-render-slide-workflow-evidence.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  formatError,
+  hasExecutable,
+  parseArgs,
+  resolveDeckTarget,
+} from "./lib/takt-marp-slide-workflow.mjs";
+
+function usage() {
+  return [
+    "Usage: node scripts/takt-marp-render-slide-workflow-evidence.mjs <target> --cycle <n>",
+    "",
+    "Example:",
+    "  npm run slide:render-evidence -- \"slides/my-talk\" --cycle 1",
+  ].join("\n");
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+  const [target] = positional;
+  const cycle = Number(flags.cycle);
+  if (!target || !Number.isInteger(cycle) || cycle < 1) {
+    throw new Error(usage());
+  }
+
+  const targetInfo = resolveDeckTarget(target);
+  const outputRoot = path.join(process.cwd(), ".takt", "render", targetInfo.deckName, `cycle-${cycle}`);
+  await mkdir(outputRoot, { recursive: true });
+
+  const metadata = {
+    deck: targetInfo.deckName,
+    cycle,
+    target: targetInfo.target,
+    html_png: { status: "pending", files: [] },
+    pdf: { status: "pending", file: null },
+    pdf_raster: hasExecutable("pdftoppm")
+      ? { status: "pending", files: [] }
+      : { status: "degraded", reason: "pdftoppm not found", files: [] },
+  };
+
+  const metadataPath = path.join(outputRoot, "metadata.json");
+  const markerPath = path.join(process.cwd(), ".takt", "render", "latest-render-evidence.json");
+  await writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+  await writeFile(
+    markerPath,
+    `${JSON.stringify(
+      {
+        target: targetInfo.target,
+        deck: targetInfo.deckName,
+        cycle,
+        metadata_path: path.relative(process.cwd(), metadataPath).split(path.sep).join("/"),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  console.log(`render evidence metadata written: ${metadataPath}`);
+}
+
+main().catch((error) => {
+  console.error(formatError(error));
+  process.exit(1);
+});

package/scripts/takt-marp-run-slide-workflow.mjs

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { copyFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import {
+  archiveCommandArtifacts,
+  assertCommandPrerequisites,
+  assertTaktExecutableAvailable,
+  assertWorkflowAvailable,
+  cleanGeneratedOutputs,
+  commandSupervisionResult,
+  downstreamCommands,
+  formatError,
+  isSuccessfulCommandState,
+  parseFrontMatter,
+  parseArgs,
+  requireCommand,
+  resolveDeckTarget,
+  SlideWorkflowError,
+  taktExecutablePath,
+} from "./lib/takt-marp-slide-workflow.mjs";
+
+function usage() {
+  return [
+    "Usage: node scripts/takt-marp-run-slide-workflow.mjs <command> <target> [--force] [--provider <name>]",
+    "",
+    "Commands: plan, compose, polish, deliver",
+    "Target: slides/<deck>",
+    "",
+    "Examples:",
+    "  npm run slide:plan -- \"slides/my-talk\"",
+    "  npm run slide:plan -- \"slides/my-talk\" --provider mock",
+    "  npm run slide:compose -- \"slides/my-talk\" --force",
+  ].join("\n");
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+  const [commandArg, target] = positional;
+  const command = requireCommand(commandArg);
+  const targetInfo = resolveDeckTarget(target);
+
+  await assertCommandPrerequisites(targetInfo, command);
+  assertWorkflowAvailable(command);
+  // Keep executable availability in preflight so failed setup cannot invalidate current artifacts.
+  assertTaktExecutableAvailable();
+
+  if (flags.force) {
+    await archiveCommandArtifacts(targetInfo, downstreamCommands(command), "force", { includeApprovals: true });
+    await cleanGeneratedOutputs(targetInfo);
+  } else if (isSuccessfulCommandState(targetInfo, command)) {
+    throw new SlideWorkflowError(
+      `Command '${command}' already reached successful state. Use --force to invalidate and rerun.`,
+      "RERUN_BLOCKED",
+    );
+  } else if ((await commandSupervisionResult(targetInfo, command)) === "rejected") {
+    await archiveCommandArtifacts(targetInfo, [command], "rejected-rerun");
+  }
+
+  await writeCurrentWorkflowTarget(command, targetInfo);
+  const runSnapshotBefore = await snapshotTaktRuns(command);
+  const code = await runTakt(command, targetInfo.target, { provider: flags.provider });
+  if (code !== 0) {
+    process.exitCode = code;
+    return;
+  }
+  await syncTaktReportsToDeck(command, targetInfo, runSnapshotBefore);
+}
+
+async function writeCurrentWorkflowTarget(command, targetInfo) {
+  const markerPath = path.join(process.cwd(), ".takt", "workflow-current-target.json");
+  await mkdir(path.dirname(markerPath), { recursive: true });
+  await writeFile(
+    markerPath,
+    `${JSON.stringify(
+      {
+        command,
+        target: targetInfo.target,
+        deck: targetInfo.deckName,
+        started_at: new Date().toISOString(),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+async function runTakt(command, target, options = {}) {
+  const args = ["--pipeline", "--skip-git", "-w", `takt-marp-slide-${command}`, "-t", target];
+  if (options.provider) {
+    args.push("--provider", options.provider);
+  }
+  const child = spawn(taktExecutablePath(), args, {
+    shell: process.platform === "win32",
+    stdio: "inherit",
+  });
+  const code = await new Promise((resolve, reject) => {
+    child.on("error", (error) => {
+      reject(
+        new SlideWorkflowError(
+          `Failed to start TAKT executable: ${taktExecutablePath()}. Run npm install and verify the takt devDependency. ${error.message}`,
+          "TAKT_EXECUTABLE_MISSING",
+        ),
+      );
+    });
+    child.on("close", resolve);
+  });
+  return code ?? 1;
+}
+
+async function syncTaktReportsToDeck(command, targetInfo, runSnapshotBefore) {
+  const reportsDir = await createdTaktReportsDir(command, targetInfo, runSnapshotBefore);
+  if (!reportsDir) {
+    throw new SlideWorkflowError(
+      `TAKT completed but no matching report directory was found for ${command} ${targetInfo.target}.`,
+      "TAKT_REPORT_SYNC_MISSING",
+    );
+  }
+
+  await mkdir(targetInfo.reviewPath, { recursive: true });
+  const reportNameSet = commandReportNameSet(command);
+  const selectedRun = await selectedRunMetadata(reportsDir, command);
+  const reportCopies = await commandReportCopies(reportsDir, command, reportNameSet, {
+    target: targetInfo.target,
+    workflowRunId: selectedRun.workflow_run_id,
+  });
+  const sourceArtifactCopies = await commandSourceArtifactCopies(reportsDir, command, targetInfo);
+  await replaceDeckSourceArtifacts(sourceArtifactCopies);
+  await replaceDeckReports(targetInfo.reviewPath, reportNameSet, reportCopies);
+}
+
+async function selectedRunMetadata(reportsDir, command) {
+  const reportPath = path.join(reportsDir, `${command}-supervision.md`);
+  const { frontMatter } = parseFrontMatter(await readFile(reportPath, "utf8"));
+  return frontMatter;
+}
+
+function commandReportNameSet(command) {
+  return new Set([
+    `${command}-work.md`,
+    `${command}-review.md`,
+    `${command}-inspect.md`,
+    `${command}-verify.md`,
+    `${command}-fix.md`,
+    `${command}-supervision.md`,
+    `${command}-loop-monitor.md`,
+    `${command}-ai-antipattern-review.md`,
+    `${command}-ai-antipattern-fix.md`,
+  ]);
+}
+
+async function commandReportCopies(reportsDir, command, reportNameSet, selectedRun) {
+  const reportNames = await readdir(reportsDir);
+  const topLevelReportCopies = reportNames
+    .filter((name) => reportNameSet.has(name))
+    .map((reportName) => Object.freeze({ reportName, sourcePath: path.join(reportsDir, reportName) }));
+  return Object.freeze([
+    ...topLevelReportCopies,
+    ...(await aiGateReportCopies(reportsDir, command, selectedRun)),
+  ]);
+}
+
+async function commandSourceArtifactCopies(reportsDir, command, targetInfo) {
+  const sourceArtifactNames = commandSourceArtifactNames(command);
+  const copies = [];
+  for (const artifactName of sourceArtifactNames) {
+    const sourcePath = path.join(reportsDir, artifactName);
+    if (!existsSync(sourcePath)) {
+      throw new SlideWorkflowError(
+        `TAKT completed but required source artifact was not found in reports: ${path.relative(process.cwd(), sourcePath)}`,
+        "TAKT_SOURCE_ARTIFACT_SYNC_MISSING",
+      );
+    }
+    copies.push(Object.freeze({
+      sourcePath,
+      finalPath: path.join(targetInfo.deckPath, artifactName),
+    }));
+  }
+  return Object.freeze(copies);
+}
+
+function commandSourceArtifactNames(command) {
+  if (command === "plan") {
+    return ["brief.normalized.md", "plan.md"];
+  }
+  return [];
+}
+
+async function replaceDeckSourceArtifacts(sourceArtifactCopies) {
+  for (const { sourcePath, finalPath } of sourceArtifactCopies) {
+    await replaceFileAtomically(sourcePath, finalPath);
+  }
+}
+
+async function replaceFileAtomically(sourcePath, finalPath) {
+  await mkdir(path.dirname(finalPath), { recursive: true });
+  const tempSuffix = `${process.pid}-${Date.now()}`;
+  const tempPath = path.join(path.dirname(finalPath), `.${path.basename(finalPath)}.${tempSuffix}.tmp`);
+  const backupPath = path.join(path.dirname(finalPath), `.${path.basename(finalPath)}.${tempSuffix}.bak`);
+  let backupCreated = false;
+  try {
+    await copyFile(sourcePath, tempPath);
+    if (existsSync(finalPath)) {
+      await rename(finalPath, backupPath);
+      backupCreated = true;
+    }
+    await rename(tempPath, finalPath);
+    if (backupCreated && existsSync(backupPath)) {
+      await unlink(backupPath);
+    }
+  } catch (error) {
+    if (existsSync(tempPath)) {
+      await unlink(tempPath);
+    }
+    if (backupCreated) {
+      if (existsSync(finalPath)) {
+        await unlink(finalPath);
+      }
+      if (existsSync(backupPath)) {
+        await rename(backupPath, finalPath);
+      }
+    }
+    throw error;
+  }
+}
+
+async function aiGateReportCopies(reportsDir, command, selectedRun) {
+  const subworkflowsDir = path.join(reportsDir, "subworkflows");
+  if (!existsSync(subworkflowsDir)) {
+    return Object.freeze([]);
+  }
+  const copies = [];
+  const reportSteps = {
+    "ai-antipattern-review.md": "ai_antipattern_review",
+    "ai-antipattern-fix.md": "ai_antipattern_fix",
+  };
+  for (const [reportFileName, step] of Object.entries(reportSteps)) {
+    const sourcePath = await findSingleAiGateReportPath(subworkflowsDir, reportFileName, {
+      command,
+      target: selectedRun.target,
+      workflowRunId: selectedRun.workflowRunId,
+      step,
+    });
+    if (sourcePath) {
+      copies.push(Object.freeze({
+        reportName: `${command}-${reportFileName}`,
+        sourcePath,
+      }));
+    }
+  }
+  return Object.freeze(copies);
+}
+
+async function findSingleAiGateReportPath(rootDir, reportFileName, expected) {
+  const found = [];
+  await collectReportPaths(rootDir, reportFileName, found);
+  const matching = [];
+  for (const reportPath of found) {
+    const report = await matchingAiGateReport(reportPath, expected);
+    if (report) {
+      matching.push(report);
+    }
+  }
+  if (matching.length === 0) {
+    return null;
+  }
+  return [...matching].sort(
+    (left, right) => right.cycle - left.cycle || right.mtimeMs - left.mtimeMs || right.reportPath.localeCompare(left.reportPath),
+  )[0].reportPath;
+}
+
+async function matchingAiGateReport(reportPath, expected) {
+  const { frontMatter } = parseFrontMatter(await readFile(reportPath, "utf8"));
+  if (
+    frontMatter.command === expected.command &&
+    frontMatter.target === expected.target &&
+    frontMatter.workflow_run_id === expected.workflowRunId &&
+    frontMatter.step === expected.step
+  ) {
+    const reportStat = await stat(reportPath);
+    return Object.freeze({
+      reportPath,
+      cycle: Number(frontMatter.cycle ?? 0),
+      mtimeMs: reportStat.mtimeMs,
+    });
+  }
+  return null;
+}
+
+async function collectReportPaths(directory, reportFileName, found) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await collectReportPaths(entryPath, reportFileName, found);
+    } else if (entry.isFile() && entry.name === reportFileName) {
+      found.push(entryPath);
+    }
+  }
+}
+
+async function replaceDeckReports(reviewPath, reportNameSet, reportCopies) {
+  const syncedReportNames = reportCopies.map(({ reportName }) => reportName);
+  const tempReports = [];
+  const backupReports = [];
+  const tempSuffix = `${process.pid}-${Date.now()}`;
+  let replacementStarted = false;
+
+  try {
+    for (const { reportName, sourcePath } of reportCopies) {
+      const tempPath = path.join(reviewPath, `.${reportName}.${tempSuffix}.tmp`);
+      await copyFile(sourcePath, tempPath);
+      tempReports.push({ reportName, tempPath, finalPath: path.join(reviewPath, reportName) });
+    }
+
+    for (const { reportName, finalPath } of tempReports) {
+      if (existsSync(finalPath)) {
+        const backupPath = path.join(reviewPath, `.${reportName}.${tempSuffix}.bak`);
+        await rename(finalPath, backupPath);
+        backupReports.push({ backupPath, finalPath });
+      }
+    }
+
+    replacementStarted = true;
+    for (const { tempPath, finalPath } of tempReports) {
+      await rename(tempPath, finalPath);
+    }
+  } catch (error) {
+    for (const { tempPath } of tempReports) {
+      if (existsSync(tempPath)) {
+        await unlink(tempPath);
+      }
+    }
+    if (replacementStarted) {
+      for (const { finalPath } of tempReports) {
+        if (existsSync(finalPath)) {
+          await unlink(finalPath);
+        }
+      }
+    }
+    for (const { backupPath, finalPath } of backupReports.reverse()) {
+      if (existsSync(backupPath)) {
+        await rename(backupPath, finalPath);
+      }
+    }
+    throw error;
+  }
+
+  for (const { backupPath } of backupReports) {
+    if (existsSync(backupPath)) {
+      await unlink(backupPath);
+    }
+  }
+
+  await cleanStaleDeckReports(reviewPath, reportNameSet, new Set(syncedReportNames));
+}
+
+async function cleanStaleDeckReports(reviewPath, reportNameSet, syncedReportNameSet) {
+  const reportNames = await readdir(reviewPath);
+  for (const reportName of reportNames.filter((name) => reportNameSet.has(name) && !syncedReportNameSet.has(name))) {
+    await unlink(path.join(reviewPath, reportName));
+  }
+}
+
+async function createdTaktReportsDir(command, targetInfo, runSnapshotBefore) {
+  const runsRoot = path.join(process.cwd(), ".takt", "runs");
+  const runNames = (await listTaktRunNames()).sort().reverse();
+  const candidates = [];
+
+  for (const runName of runNames) {
+    const reportsDir = path.join(runsRoot, runName, "reports");
+    const reportPath = path.join(reportsDir, `${command}-supervision.md`);
+    const reportMtime = await reportMtimeIfChangedSinceSnapshot(reportPath, runName, runSnapshotBefore);
+    if (reportMtime !== null && (await reportMatchesSuccessfulTarget(reportPath, command, targetInfo.target))) {
+      candidates.push({ reportsDir, reportMtime });
+    }
+  }
+
+  if (candidates.length === 0) {
+    return null;
+  }
+  if (candidates.length > 1) {
+    throw new SlideWorkflowError(
+      `TAKT completed but multiple matching report directories changed for ${command} ${targetInfo.target}. Refusing to sync an ambiguous run.`,
+      "TAKT_REPORT_SYNC_AMBIGUOUS",
+    );
+  }
+  return candidates[0].reportsDir;
+}
+
+async function snapshotTaktRuns(command) {
+  const runsRoot = path.join(process.cwd(), ".takt", "runs");
+  const snapshot = new Map();
+  for (const runName of await listTaktRunNames()) {
+    const reportPath = path.join(runsRoot, runName, "reports", `${command}-supervision.md`);
+    snapshot.set(runName, existsSync(reportPath) ? (await stat(reportPath)).mtimeMs : null);
+  }
+  return snapshot;
+}
+
+async function reportMtimeIfChangedSinceSnapshot(reportPath, runName, runSnapshotBefore) {
+  if (!existsSync(reportPath)) {
+    return null;
+  }
+  const reportMtime = (await stat(reportPath)).mtimeMs;
+  const previousMtime = runSnapshotBefore.get(runName);
+  return previousMtime === undefined || previousMtime === null || reportMtime > previousMtime ? reportMtime : null;
+}
+
+async function listTaktRunNames() {
+  const runsRoot = path.join(process.cwd(), ".takt", "runs");
+  if (!existsSync(runsRoot)) {
+    return [];
+  }
+  return (await readdir(runsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+
+async function reportMatchesSuccessfulTarget(reportPath, command, target) {
+  if (!existsSync(reportPath)) {
+    return false;
+  }
+  const { frontMatter } = parseFrontMatter(await readFile(reportPath, "utf8"));
+  return frontMatter.command === command && frontMatter.target === target && frontMatter.result === "passed";
+}
+
+main().catch((error) => {
+  console.error(formatError(error));
+  process.exit(1);
+});