@decocms/blocks-cli 7.44.0 → 7.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.44.0",
+  "version": "7.46.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -17,7 +17,8 @@
     "deco-audit-observability": "./scripts/audit-observability-config.ts",
     "deco-migrate-blocks-to-kv": "./scripts/migrate-blocks-to-kv.ts",
     "deco-sync-blocks-to-kv": "./scripts/sync-blocks-to-kv.ts",
-    "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts"
+    "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts",
+    "deco-reconcile": "./scripts/reconcile.ts"
   },
   "//exports": "Deliberately narrow. ./generate is the ONE public module entry (unified orchestrator); ./generate-blocks stays only because @decocms/tanstack's vite plugin tsImports it (readBlockDelta + programmatic generateBlocks) — each surviving entry must name its consumer here. The other scripts remain shipped FILES (the orchestrator spawns them; sites' existing `tsx node_modules/@decocms/blocks-cli/scripts/generate-*.ts` invocations keep working) but are internal implementation details of ./generate, not module subpaths. CLIs are exposed via bin, not exports.",
   "exports": {
@@ -31,7 +32,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.44.0",
+    "@decocms/blocks": "7.46.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/delete-sets.ts

@@ -0,0 +1,75 @@
+/**
+ * The paths the migration deletes outright. Single source of truth: `decideAction`
+ * (phase-analyze) decides with them, and `deco-reconcile` filters with them — an
+ * upstream change to a file the migration deleted has no target equivalent, so
+ * reporting it just makes the agent consider migrating a file that must not exist.
+ *
+ * Only the unambiguous sets live here. Rules that are conditional on context
+ * (routes/ and apps/ are rescaffolded, root-level docs) stay in `decideAction`:
+ * reconcile must stay conservative, since dropping a real upstream change is a
+ * worse failure than showing one file too many.
+ */
+
+/** Files that are generated and should be deleted */
+export const GENERATED_FILES = new Set([
+  "fresh.gen.ts",
+  "manifest.gen.ts",
+  "fresh.config.ts",
+]);
+
+/** SDK files that have framework equivalents or are scaffolded fresh */
+export const SDK_DELETE = new Set([
+  "sdk/clx.ts",
+  "sdk/useId.ts",
+  // sdk/useOffer.ts — kept: sites often customize offer logic
+  // sdk/useVariantPossiblities.ts — kept: sites often customize variant logic
+  "sdk/usePlatform.tsx",
+  "sdk/signal.ts",
+  "sdk/format.ts",
+]);
+
+/** Component files that are scaffolded fresh (old versions must not overwrite) */
+export const COMPONENT_DELETE = new Set([
+  "components/ui/Image.tsx",
+  "components/ui/Picture.tsx",
+  "components/ui/Video.tsx",
+]);
+
+/** Loaders that depend on deleted admin tooling */
+export const LOADER_DELETE = new Set([
+  "loaders/availableIcons.ts",
+  "loaders/icons.ts",
+]);
+
+/** Root config/infra files to delete */
+export const ROOT_DELETE = new Set([
+  "main.ts",
+  "dev.ts",
+  "deno.json",
+  "deno.lock",
+  "tailwind.css",
+  "tailwind.config.ts",
+  "runtime.ts",
+  "constants.ts",
+  "fresh.gen.ts",
+  "manifest.gen.ts",
+  "fresh.config.ts",
+  "browserslist",
+  "bw_stats.json",
+  "islands.ts",
+]);
+
+/** Static files that are code/tooling, not assets — should be deleted */
+export const STATIC_DELETE = new Set([
+  "static/adminIcons.ts",
+  "static/generate-icons.ts",
+  "static/tailwind.css",
+]);
+
+/** True when the migration deletes this source path outright. */
+export function isDeletedByMigration(relPath: string): boolean {
+  return GENERATED_FILES.has(relPath) || ROOT_DELETE.has(relPath) ||
+    SDK_DELETE.has(relPath) || COMPONENT_DELETE.has(relPath) ||
+    LOADER_DELETE.has(relPath) || STATIC_DELETE.has(relPath) ||
+    relPath.startsWith("sdk/cart/") || relPath.startsWith("apps/deco/");
+}

package/scripts/migrate/phase-analyze.ts

@@ -11,6 +11,14 @@ import { extractSectionMetadata } from "./analyzers/section-metadata";
 import { classifyIslands } from "./analyzers/island-classifier";
 import { inventoryLoaders } from "./analyzers/loader-inventory";
 import { extractTailwindConfig } from "./analyzers/tailwind-config";
+import {
+  COMPONENT_DELETE,
+  GENERATED_FILES,
+  LOADER_DELETE,
+  ROOT_DELETE,
+  SDK_DELETE,
+  STATIC_DELETE,
+} from "./delete-sets";
 
 const PATTERN_DETECTORS: Array<[DetectedPattern, RegExp]> = [
   ["preact-hooks", /from\s+["']preact\/hooks["']/],
@@ -78,61 +86,6 @@ const SKIP_FILES = new Set([
   "bun.lockb",
 ]);
 
-/** Files that are generated and should be deleted */
-const GENERATED_FILES = new Set([
-  "fresh.gen.ts",
-  "manifest.gen.ts",
-  "fresh.config.ts",
-]);
-
-/** SDK files that have framework equivalents or are scaffolded fresh */
-const SDK_DELETE = new Set([
-  "sdk/clx.ts",
-  "sdk/useId.ts",
-  // sdk/useOffer.ts — kept: sites often customize offer logic
-  // sdk/useVariantPossiblities.ts — kept: sites often customize variant logic
-  "sdk/usePlatform.tsx",
-  "sdk/signal.ts",
-  "sdk/format.ts",
-]);
-
-/** Component files that are scaffolded fresh (old versions must not overwrite) */
-const COMPONENT_DELETE = new Set([
-  "components/ui/Image.tsx",
-  "components/ui/Picture.tsx",
-  "components/ui/Video.tsx",
-]);
-
-/** Loaders that depend on deleted admin tooling */
-const LOADER_DELETE = new Set([
-  "loaders/availableIcons.ts",
-  "loaders/icons.ts",
-]);
-
-/** Root config/infra files to delete */
-const ROOT_DELETE = new Set([
-  "main.ts",
-  "dev.ts",
-  "deno.json",
-  "deno.lock",
-  "tailwind.css",
-  "tailwind.config.ts",
-  "runtime.ts",
-  "constants.ts",
-  "fresh.gen.ts",
-  "manifest.gen.ts",
-  "fresh.config.ts",
-  "browserslist",
-  "bw_stats.json",
-  "islands.ts",
-]);
-
-/** Static files that are code/tooling, not assets — should be deleted */
-const STATIC_DELETE = new Set([
-  "static/adminIcons.ts",
-  "static/generate-icons.ts",
-  "static/tailwind.css",
-]);
 
 /**
  * Scan file content for inline npm: imports and return { name: version } pairs.

package/scripts/reconcile.test.ts

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  detectTargetSnapshot,
+  isSkipped,
+  parseNameStatus,
+  type ReconcileManifest,
+  targetCandidates,
+} from "./reconcile";
+
+describe("parseNameStatus", () => {
+  it("splits plain and rename entries", () => {
+    expect(parseNameStatus("M\tsections/A.tsx\nR094\tislands/B.tsx\tislands/C.tsx\n"))
+      .toEqual([
+        { status: "M", path: "sections/A.tsx" },
+        { status: "R094", path: "islands/C.tsx", oldPath: "islands/B.tsx" },
+      ]);
+  });
+});
+
+describe("isSkipped", () => {
+  it("drops CMS content, lockfiles and binaries but keeps source", () => {
+    expect(isSkipped(".deco/blocks/pages-home.json")).toBe(true);
+    expect(isSkipped("deno.lock")).toBe(true);
+    expect(isSkipped("static/logo.png")).toBe(true);
+    expect(isSkipped("sections/Header.tsx")).toBe(false);
+  });
+
+  it("drops what the migration deletes — no target file to port into", () => {
+    expect(isSkipped("fresh.gen.ts")).toBe(true);
+    expect(isSkipped("manifest.gen.ts")).toBe(true);
+    expect(isSkipped("deno.json")).toBe(true);
+    expect(isSkipped("sdk/cart/vtex.ts")).toBe(true);
+    // routes/ is rescaffolded but a NEW upstream route is a real change — keep it.
+    expect(isSkipped("routes/blog.tsx")).toBe(false);
+    expect(isSkipped("redirects.csv")).toBe(false);
+  });
+});
+
+describe("targetCandidates", () => {
+  it("ranks the conventional guess first, keeps other basename matches", () => {
+    const byBasename = new Map([
+      ["Cart.tsx", ["src/sections/Cart.tsx", "src/components/Cart.tsx"]],
+    ]);
+    expect(targetCandidates("islands/Cart.tsx", byBasename)).toEqual([
+      "src/components/Cart.tsx",
+      "src/sections/Cart.tsx",
+    ]);
+  });
+
+  it("returns nothing when the file does not exist on the target", () => {
+    expect(targetCandidates("sections/New.tsx", new Map())).toEqual([]);
+  });
+});
+
+describe("detectTargetSnapshot", () => {
+  it("takes the OLDEST add — git log is newest-first, re-adds must not win", () => {
+    expect(detectTargetSnapshot("bbb\naaa\n")).toBe("aaa");
+    expect(detectTargetSnapshot("")).toBeUndefined();
+  });
+});
+
+describe("reconcile end to end", () => {
+  let tmp: string;
+  const git = (cwd: string, ...args: string[]) =>
+    execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8" }).trim();
+
+  const write = (repo: string, rel: string, body: string) => {
+    fs.mkdirSync(path.join(repo, path.dirname(rel)), { recursive: true });
+    fs.writeFileSync(path.join(repo, rel), body);
+  };
+  const commit = (repo: string, msg: string) => {
+    git(repo, "add", "-A");
+    git(repo, "commit", "-m", msg);
+    return git(repo, "rev-parse", "HEAD");
+  };
+  const init = (name: string) => {
+    const repo = path.join(tmp, name);
+    fs.mkdirSync(repo, { recursive: true });
+    git(repo, "init", "-q", "-b", "main");
+    git(repo, "config", "user.email", "t@t.t");
+    git(repo, "config", "user.name", "t");
+    return repo;
+  };
+
+  beforeEach(() => {
+    // realpath: macOS /var → /private/var, which git resolves and we compare against.
+    tmp = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "reconcile-"));
+  });
+  afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it("auto-detects the target snapshot, emits one patch per file, flags hand-fixes", () => {
+    const source = init("source");
+    write(source, "sections/Header.tsx", "export default () => <h1>a</h1>;\n");
+    write(source, "sections/Footer.tsx", "export default () => <footer/>;\n");
+    write(source, "deno.lock", "{}\n");
+    const snapshot = commit(source, "cut");
+
+    write(source, "sections/Header.tsx", "export default () => <h1>b</h1>;\n");
+    write(source, "sections/Footer.tsx", "export default () => <footer id='f'/>;\n");
+    write(source, "deno.lock", '{"v":2}\n');
+    const sourceHead = commit(source, "upstream work");
+
+    const target = init("target");
+    write(target, "src/sections/Header.tsx", "export default () => <h1>a</h1>;\n");
+    // The island/section re-export pair — Header has TWO target candidates.
+    write(target, "src/components/Header.tsx", "export default () => <h1>a</h1>;\n");
+    write(target, "src/sections/Footer.tsx", "export default () => <footer/>;\n");
+    // The marker deco-migrate leaves behind — this is what auto-detection finds.
+    write(target, "MIGRATION_REPORT.md", "# Migration\n");
+    const targetSnapshot = commit(target, "migrate to tanstack");
+
+    // One hand-fix touching both candidates → must count as ONE collision.
+    write(target, "src/sections/Header.tsx", "export default () => <h1>a fixed</h1>;\n");
+    write(target, "src/components/Header.tsx", "export default () => <h1>a fixed</h1>;\n");
+    commit(target, "fix: codemod ate the heading");
+
+    const out = path.join(tmp, "out");
+    execFileSync(
+      path.join(__dirname, "../../../node_modules/.bin/tsx"),
+      [
+        path.join(__dirname, "reconcile.ts"),
+        "--source", source,
+        "--target", target,
+        "--snapshot", snapshot,
+        // no --target-snapshot: exercise the MIGRATION_REPORT.md auto-detection
+        "--out", out,
+      ],
+      { encoding: "utf8" },
+    );
+
+    const manifest: ReconcileManifest = JSON.parse(
+      fs.readFileSync(path.join(out, "manifest.json"), "utf8"),
+    );
+
+    expect(manifest.sourceHead).toBe(sourceHead);
+    expect(manifest.targetSnapshot).toBe(targetSnapshot);
+    // deno.lock filtered out.
+    expect(manifest.files.map((f) => f.sourcePath).sort()).toEqual([
+      "sections/Footer.tsx",
+      "sections/Header.tsx",
+    ]);
+
+    const header = manifest.files.find((f) => f.sourcePath === "sections/Header.tsx")!;
+    expect(header.targetCandidates).toEqual([
+      "src/sections/Header.tsx", // conventional guess ranks first
+      "src/components/Header.tsx",
+    ]);
+    expect(header.collision).toHaveLength(1); // deduped by SHA, not 2
+    expect(header.collision[0]).toContain("codemod ate the heading");
+    expect(fs.readFileSync(path.join(out, header.patch), "utf8")).toContain("<h1>b</h1>");
+
+    const footer = manifest.files.find((f) => f.sourcePath === "sections/Footer.tsx")!;
+    expect(footer.collision).toEqual([]);
+    expect(footer.done).toBe(false);
+
+    expect(fs.readFileSync(path.join(out, "INDEX.md"), "utf8")).toContain(sourceHead);
+  });
+});

package/scripts/reconcile.ts

@@ -0,0 +1,301 @@
+#!/usr/bin/env tsx
+/**
+ * Snapshot reconcile — produces a per-file diff of everything that landed on the
+ * Fresh/Deno SOURCE repo since the migration cut, plus the context an agent needs
+ * to port each change into the already-migrated TanStack TARGET repo.
+ *
+ * Migrations take weeks. During that window the source team keeps shipping and
+ * the migration team hand-fixes what the codemod got wrong. Reconciling is a
+ * REBASE, not a re-migration: re-running `deco-migrate` over the tree overwrites
+ * the hand-fixes. So this script makes NO judgement and writes NOTHING to the
+ * target — it emits one patch per file and lets the agent (see the
+ * `deco-reconcile-snapshot` skill) work them one at a time.
+ *
+ * Usage:
+ *   npx -p @decocms/blocks-cli deco-reconcile \
+ *     --source ../site-fresh --target ../site-tanstack --snapshot <cut sha>
+ *
+ * Options:
+ *   --source <dir>           Fresh/Deno repo checkout (required)
+ *   --target <dir>           Migrated TanStack repo checkout (required)
+ *   --snapshot <sha>         Last reconciled source commit — the cut (required)
+ *   --target-snapshot <sha>  The migration commit on the target. Defaults to the
+ *                            commit that added MIGRATION_REPORT.md, else HEAD.
+ *                            Everything after it counts as a hand-fix, so a wrong
+ *                            value silently empties the collision list.
+ *   --out <dir>              Output dir (default: <target>/.reconcile/<sourceHead:7>)
+ *   --verbose                Log every file
+ *   --help, -h               Show this help
+ *
+ * Output: <out>/manifest.json (machine, also the resume state via `done`),
+ *         <out>/INDEX.md (human), <out>/patches/NNN-<slug>.patch (one per file).
+ *
+ * Exit codes: 0 ok; 2 bad args / git failure.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import { isDeletedByMigration } from "./migrate/delete-sets";
+import * as path from "node:path";
+
+/** Paths whose upstream changes never reconcile into the target. */
+const SKIP = [
+  /^\.deco\//, // CMS content — syncs through its own channel
+  /^\.github\//, // target has its own scaffolded workflows
+  /^_fresh\//,
+  /(^|\/)(deno\.lock|package-lock\.json|bun\.lock|bun\.lockb|yarn\.lock)$/,
+  /\.(png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|mp4|webm|pdf|zip)$/i,
+];
+
+export interface ReconcileFile {
+  /** git --name-status letter: A/M/D/R… */
+  status: string;
+  sourcePath: string;
+  /** Previous path, for renames only. */
+  oldPath?: string;
+  /** Patch file, relative to the output dir. */
+  patch: string;
+  /** Where this MIGHT live on the target. Candidates, not a verdict. */
+  targetCandidates: string[];
+  /** Target commits touching a candidate since the migration commit. */
+  collision: string[];
+  done: boolean;
+}
+
+export interface ReconcileManifest {
+  source: string;
+  target: string;
+  snapshot: string;
+  /** Feed this back as --snapshot on the next round. */
+  sourceHead: string;
+  targetSnapshot: string;
+  files: ReconcileFile[];
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+function slug(p: string): string {
+  return p.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+}
+
+/** Parse `git diff --name-status -M` output. Renames carry two tab-separated paths. */
+export function parseNameStatus(
+  out: string,
+): Array<{ status: string; path: string; oldPath?: string }> {
+  return out.split("\n").filter(Boolean).map((line) => {
+    const [status, a, b] = line.split("\t");
+    return b ? { status, path: b, oldPath: a } : { status, path: a };
+  });
+}
+
+export function isSkipped(relPath: string): boolean {
+  return SKIP.some((re) => re.test(relPath)) || isDeletedByMigration(relPath);
+}
+
+/**
+ * Guess where a source file lives on the target. The migration moved things
+ * around (islands/→src/components/, static/→public/, sections stay under src/),
+ * so this is basename matching plus the conventional `src/` prefix — deliberately
+ * a shortlist for the agent to confirm against the target tree, not a mapping.
+ */
+export function targetCandidates(
+  relPath: string,
+  byBasename: Map<string, string[]>,
+): string[] {
+  const guesses = [
+    `src/${relPath}`,
+    `src/${relPath.replace(/^islands\//, "components/")}`,
+    relPath.replace(/^static\//, "public/"),
+  ];
+  const found = byBasename.get(path.basename(relPath)) ?? [];
+  // Only real target paths survive; the guesses just rank the likely one first.
+  return [...new Set([...guesses.filter((g) => found.includes(g)), ...found])];
+}
+
+function usage(msg?: string): never {
+  if (msg) console.error(`error: ${msg}\n`);
+  console.error(
+    "usage: deco-reconcile --source <dir> --target <dir> --snapshot <sha> [--target-snapshot <sha>] [--out <dir>] [--verbose]",
+  );
+  process.exit(msg ? 2 : 0);
+}
+
+/**
+ * The migration commit on the target — everything after it is a hand-fix.
+ * `deco-migrate` leaves no provenance except MIGRATION_REPORT.md, so the commit
+ * that added it is the marker. No marker: fall back to HEAD, which makes every
+ * collision range empty — loudly, because a silent empty list reads as "nobody
+ * touched anything" and that is exactly the wrong thing to believe.
+ */
+export function detectTargetSnapshot(log: string): string | undefined {
+  return log.split("\n").filter(Boolean).pop();
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) usage();
+  const flag = (name: string) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const verbose = argv.includes("--verbose");
+
+  const source = flag("source");
+  const target = flag("target");
+  const snapshot = flag("snapshot");
+  if (!source || !target || !snapshot) {
+    usage("--source, --target and --snapshot are all required");
+  }
+
+  const targetSnapshot = flag("target-snapshot") ??
+    detectTargetSnapshot(
+      git(target, [
+        "log",
+        "--diff-filter=A",
+        "--format=%H",
+        "--",
+        "MIGRATION_REPORT.md",
+      ]),
+    ) ?? git(target, ["rev-parse", "HEAD"]).trim();
+  if (!flag("target-snapshot")) {
+    console.log(
+      `--target-snapshot not given, using ${targetSnapshot.slice(0, 7)} (${
+        git(target, ["log", "-1", "--format=%s", targetSnapshot]).trim()
+      })`,
+    );
+  }
+
+  const sourceHead = git(source, ["rev-parse", "HEAD"]).trim();
+  if (sourceHead === git(source, ["rev-parse", snapshot]).trim()) {
+    console.log("Nothing to reconcile — source HEAD is already the snapshot.");
+    return;
+  }
+
+  const outDir = flag("out") ??
+    path.join(target, ".reconcile", sourceHead.slice(0, 7));
+  fs.mkdirSync(path.join(outDir, "patches"), { recursive: true });
+
+  const byBasename = new Map<string, string[]>();
+  for (const p of git(target, ["ls-files"]).split("\n").filter(Boolean)) {
+    const key = path.basename(p);
+    byBasename.set(key, [...(byBasename.get(key) ?? []), p]);
+  }
+
+  // Submodules (mode 160000) diff as a one-line gitlink bump — no source to port.
+  const submodules = new Set(
+    git(source, ["ls-files", "--stage"]).split("\n")
+      .filter((l) => l.startsWith("160000"))
+      .map((l) => l.split("\t")[1]),
+  );
+
+  const changes = parseNameStatus(
+    git(source, ["diff", "--name-status", "-M", `${snapshot}..${sourceHead}`]),
+  );
+  const files: ReconcileFile[] = [];
+
+  for (const change of changes) {
+    if (isSkipped(change.path) || submodules.has(change.path)) {
+      if (verbose) console.log(`  skip  ${change.path}`);
+      continue;
+    }
+    const n = String(files.length + 1).padStart(3, "0");
+    const patch = `patches/${n}-${slug(change.path)}.patch`;
+    fs.writeFileSync(
+      path.join(outDir, patch),
+      git(source, [
+        "diff",
+        "-M",
+        `${snapshot}..${sourceHead}`,
+        "--",
+        ...(change.oldPath ? [change.oldPath, change.path] : [change.path]),
+      ]),
+    );
+
+    const candidates = targetCandidates(change.path, byBasename);
+    // A target file touched since the migration commit is a hand-fix. The agent
+    // must reconcile hunk by hunk instead of applying the upstream change whole.
+    // Deduped by SHA: one commit touching two candidates (the island/section
+    // re-export pair) is one hand-fix, not two — an inflated count misreads the
+    // "does this fit one human review sitting" gate.
+    const bySha = new Map<string, string>();
+    for (const c of candidates) {
+      for (
+        const line of git(target, [
+          "log",
+          "--format=%h %s",
+          `${targetSnapshot}..HEAD`,
+          "--",
+          c,
+        ]).split("\n").filter(Boolean)
+      ) {
+        const sha = line.split(" ")[0];
+        if (!bySha.has(sha)) bySha.set(sha, `${c}: ${line}`);
+      }
+    }
+    const collision = [...bySha.values()];
+
+    files.push({
+      status: change.status,
+      sourcePath: change.path,
+      oldPath: change.oldPath,
+      patch,
+      targetCandidates: candidates,
+      collision,
+      done: false,
+    });
+    if (verbose) {
+      console.log(
+        `  ${change.status.padEnd(4)} ${change.path} → ${
+          candidates.join(", ") || "(no target match — new file?)"
+        }${collision.length ? `  [COLLISION x${collision.length}]` : ""}`,
+      );
+    }
+  }
+
+  const manifest: ReconcileManifest = {
+    source,
+    target,
+    snapshot,
+    sourceHead,
+    targetSnapshot,
+    files,
+  };
+  fs.writeFileSync(
+    path.join(outDir, "manifest.json"),
+    JSON.stringify(manifest, null, 2) + "\n",
+  );
+
+  const collided = files.filter((f) => f.collision.length);
+  fs.writeFileSync(
+    path.join(outDir, "INDEX.md"),
+    [
+      `# Reconcile ${snapshot.slice(0, 7)}..${sourceHead.slice(0, 7)}`,
+      "",
+      `SOURCE_HEAD \`${sourceHead}\` — feed this back as \`--snapshot\` next round.`,
+      "",
+      `Target snapshot \`${targetSnapshot}\` — commits after it count as hand-fixes.`,
+      "",
+      `${files.length} files, ${collided.length} with collisions.`,
+      "",
+      "| # | status | source | target candidates | collision |",
+      "|---|---|---|---|---|",
+      ...files.map((f, i) =>
+        `| ${i + 1} | ${f.status} | \`${f.sourcePath}\` | ${
+          f.targetCandidates.map((c) => `\`${c}\``).join("<br>") || "—"
+        } | ${f.collision.length || ""} |`
+      ),
+      "",
+    ].join("\n"),
+  );
+
+  console.log(
+    `${files.length} files (${collided.length} colliding) → ${outDir}\nSOURCE_HEAD ${sourceHead}`,
+  );
+}
+
+if (process.argv[1] && /reconcile\.ts$/.test(process.argv[1])) main();