rahman-resources 1.4.0 → 1.6.0

package/bin/migrate.mjs

@@ -17,9 +17,12 @@
 // Side-effects (only with --write-files):
 //   - Writes ./convex/migrations/<step-id>.ts
 //   - Appends a DNA lineage entry with transforms ["migration-applied", ...].
+//
+// Module split (kept ≤200 LOC each):
+//   - migrate-load.mjs   — contract-loading (current + historic via git show)
+//   - migrate-print.mjs  — ASCII rendering of a MigrationPlan
 
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -27,6 +30,13 @@ import kleur from "kleur";
 
 import { diffContracts, planMigration } from "../lib/migration-plan.mjs";
 import { appendLineage } from "../lib/dna.mjs";
+import {
+  loadCurrentContract,
+  loadHistoricContract,
+  parseFlags,
+  findRepoRoot,
+} from "./migrate-load.mjs";
+import { printPlan } from "./migrate-print.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -111,313 +121,62 @@ export async function runMigrate(rest) {
 
   // 4) Optional write.
   if (writeFiles) {
-    const writeDir = path.join(cwd, "convex", "migrations");
-    mkdirSync(writeDir, { recursive: true });
-    const writtenIds = [];
-    for (const step of plan.steps) {
-      const body = step.artifacts?.convexMigration;
-      if (!body) continue;
-      const file = path.join(writeDir, `${step.id}.ts`);
-      if (existsSync(file) && !forceOverwrite) {
-        process.stderr.write(
-          kleur.red(
-            `migrate: ${path.relative(cwd, file)} already exists. Pass --force-overwrite to replace.\n`,
-          ),
-        );
-        process.exit(1);
-      }
-      writeFileSync(file, body + "\n");
-      writtenIds.push(step.id);
-      if (!asJson) {
-        process.stdout.write(
-          `  ${kleur.green("+")} ${path.relative(cwd, file)}\n`,
-        );
-      }
-    }
+    writePlanFiles({ plan, cwd, forceOverwrite, asJson });
     // 5) Append DNA lineage.
-    if (writtenIds.length > 0) {
-      try {
-        appendLineage(slug, {
-          from: `contract:${slug}@${plan.fromVersion}`,
-          to: `contract:${slug}@${plan.toVersion}`,
-          at: new Date().toISOString(),
-          transforms: ["migration-applied", ...writtenIds],
-        });
-        if (!asJson) {
-          process.stdout.write(
-            kleur.dim(
-              `  lineage: appended "migration-applied" entry to .kitab/lineage/${slug}.dna.json\n`,
-            ),
-          );
-        }
-      } catch (err) {
-        process.stderr.write(
-          kleur.yellow(
-            `  ⚠ lineage append failed (${err.message ?? err}). Files were still written.\n`,
-          ),
-        );
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Contract loading
-// ---------------------------------------------------------------------------
-
-const SLICE_ROOTS = [
-  ["frontend", "slices"],
-  ["template-base", "frontend", "slices"],
-];
-
-function resolveContractPath(repoRoot, slug) {
-  for (const segs of SLICE_ROOTS) {
-    const p = path.join(repoRoot, ...segs, slug, "slice.contract.ts");
-    if (existsSync(p)) return p;
+    appendMigrationLineage({ slug, plan, asJson });
   }
-  return null;
 }
 
-function resolveContractRelPath(repoRoot, slug) {
-  for (const segs of SLICE_ROOTS) {
-    const rel = [...segs, slug, "slice.contract.ts"].join("/");
-    if (existsSync(path.join(repoRoot, rel))) return rel;
-  }
-  return null;
-}
-
-function loadCurrentContract(repoRoot, slug) {
-  const p = resolveContractPath(repoRoot, slug);
-  if (!p) return null;
-  return evalContract(repoRoot, p, null);
-}
-
-/**
- * Resolve the contract at a historic version. Strategy:
- *   1. Try git tags `v<ver>`, `<ver>`, `<slug>-v<ver>` against the contract file.
- *   2. If none have the right version, scan recent commits touching the file
- *      and pick the most recent one whose contract.version === fromVersion.
- */
-function loadHistoricContract(repoRoot, slug, fromVersion) {
-  const rel = resolveContractRelPath(repoRoot, slug);
-  if (!rel) return null;
-
-  const candidates = [`v${fromVersion}`, fromVersion, `${slug}-v${fromVersion}`];
-  for (const ref of candidates) {
-    const text = gitShowFile(repoRoot, ref, rel);
-    if (text) {
-      const c = evalContract(repoRoot, null, text);
-      if (c && c.version === fromVersion) return c;
+function writePlanFiles({ plan, cwd, forceOverwrite, asJson }) {
+  const writeDir = path.join(cwd, "convex", "migrations");
+  mkdirSync(writeDir, { recursive: true });
+  for (const step of plan.steps) {
+    const body = step.artifacts?.convexMigration;
+    if (!body) continue;
+    const file = path.join(writeDir, `${step.id}.ts`);
+    if (existsSync(file) && !forceOverwrite) {
+      process.stderr.write(
+        kleur.red(
+          `migrate: ${path.relative(cwd, file)} already exists. Pass --force-overwrite to replace.\n`,
+        ),
+      );
+      process.exit(1);
     }
-  }
-
-  // Fallback: scan commit history for the file.
-  const log = spawnSync("git", ["log", "--format=%H", "--", rel], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  });
-  if (log.status === 0 && log.stdout) {
-    const hashes = log.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
-    for (const sha of hashes) {
-      const text = gitShowFile(repoRoot, sha, rel);
-      if (!text) continue;
-      const c = evalContract(repoRoot, null, text);
-      if (c && c.version === fromVersion) return c;
+    writeFileSync(file, body + "\n");
+    if (!asJson) {
+      process.stdout.write(
+        `  ${kleur.green("+")} ${path.relative(cwd, file)}\n`,
+      );
     }
   }
-  return null;
 }
 
-function gitShowFile(repoRoot, ref, relPath) {
-  const res = spawnSync("git", ["show", `${ref}:${relPath}`], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  });
-  if (res.status === 0 && typeof res.stdout === "string") return res.stdout;
-  return null;
-}
-
-/**
- * Eval a contract file by spawning `npx tsx` and reading the JSON output.
- * Pass `filePath` (absolute) for the on-disk version OR `inlineText` for a
- * historic version pulled via git show.
- */
-function evalContract(repoRoot, filePath, inlineText) {
-  if (filePath) {
-    const rel = "./" + path.relative(repoRoot, filePath);
-    const code = [
-      `import(${JSON.stringify(rel)})`,
-      `  .then(m => { const c = m.contract || (m.default && m.default.contract); if (!c) { process.exit(2); } process.stdout.write(JSON.stringify(c)); })`,
-      `  .catch((e) => { process.stderr.write(String(e && e.stack || e)); process.exit(3); });`,
-    ].join("\n");
-    const res = spawnSync("npx", ["--no-install", "tsx", "-e", code], {
-      cwd: repoRoot,
-      encoding: "utf8",
-    });
-    if (res.status === 0 && res.stdout) {
-      try {
-        return JSON.parse(res.stdout);
-      } catch {
-        return null;
-      }
-    }
-    return null;
-  }
-
-  // Inline mode: write to a temp file under the kitab root (so its tsconfig +
-  // path aliases resolve) and eval. We use a `.migration-tmp/` folder so the
-  // temp file is colocated with packages/ but easy to ignore.
-  if (typeof inlineText !== "string") return null;
-  const tmpDir = path.join(repoRoot, ".migration-tmp");
-  mkdirSync(tmpDir, { recursive: true });
-  const tmpFile = path.join(
-    tmpDir,
-    `contract-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`,
-  );
+function appendMigrationLineage({ slug, plan, asJson }) {
+  const writtenIds = plan.steps
+    .filter((s) => !!s.artifacts?.convexMigration)
+    .map((s) => s.id);
+  if (writtenIds.length === 0) return;
   try {
-    // Rewrite the import path back to the absolute kitab `contract` module so
-    // `../../../packages/cli/lib/contract` (from a historic file pulled via
-    // git show) keeps resolving after we move it to a different directory.
-    const adjusted = adjustContractImport(inlineText, repoRoot, tmpDir);
-    writeFileSync(tmpFile, adjusted);
-    return evalContract(repoRoot, tmpFile, null);
-  } finally {
-    try {
-      if (existsSync(tmpFile)) unlinkSync(tmpFile);
-    } catch {
-      // ignore
+    appendLineage(slug, {
+      from: `contract:${slug}@${plan.fromVersion}`,
+      to: `contract:${slug}@${plan.toVersion}`,
+      at: new Date().toISOString(),
+      transforms: ["migration-applied", ...writtenIds],
+    });
+    if (!asJson) {
+      process.stdout.write(
+        kleur.dim(
+          `  lineage: appended "migration-applied" entry to .kitab/lineage/${slug}.dna.json\n`,
+        ),
+      );
     }
-  }
-}
-
-/**
- * Replace any `from "..contract"` import in the contract body with an
- * absolute path so the temp-file copy still resolves the same module.
- */
-function adjustContractImport(text, repoRoot, tmpDir) {
-  const contractMod = path.join(repoRoot, "packages", "cli", "lib", "contract");
-  const relFromTmp = path
-    .relative(tmpDir, contractMod)
-    .split(path.sep)
-    .join("/");
-  // Match imports ending in /contract or /contract.ts (with or without .ts).
-  return text.replace(
-    /from\s+["'][^"']*\/contract(?:\.ts)?["']/g,
-    `from "${relFromTmp}"`,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Presentation
-// ---------------------------------------------------------------------------
-
-function printPlan(plan, _ctx) {
-  const head = plan.summary.totalSteps === 0
-    ? kleur.green("✓ no migration needed")
-    : kleur.bold(`→ ${plan.slug}: v${plan.fromVersion} → v${plan.toVersion}`);
-  process.stdout.write(`\n${head}\n\n`);
-
-  if (plan.summary.totalSteps === 0) {
-    process.stdout.write(kleur.dim("  (contracts are equivalent — nothing to migrate)\n\n"));
-    return;
-  }
-
-  // Header row.
-  const cols = ["id", "kind", "risk", "rev", "description"];
-  const widths = [28, 26, 6, 4, 50];
-  const sep =
-    "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+\n";
-  const row = (vals) =>
-    "|" +
-    vals
-      .map((v, i) => " " + String(v).padEnd(widths[i]).slice(0, widths[i]) + " ")
-      .join("|") +
-    "|\n";
-
-  process.stdout.write(sep);
-  process.stdout.write(row(cols));
-  process.stdout.write(sep);
-  for (const step of plan.steps) {
-    process.stdout.write(
-      row([
-        step.id,
-        step.kind,
-        step.risk,
-        step.reversible ? "yes" : "NO",
-        step.description.replace(/\s+/g, " ").slice(0, widths[4]),
-      ]),
+  } catch (err) {
+    process.stderr.write(
+      kleur.yellow(
+        `  ⚠ lineage append failed (${err.message ?? err}). Files were still written.\n`,
+      ),
     );
   }
-  process.stdout.write(sep);
-
-  // Per-step detail.
-  for (const step of plan.steps) {
-    process.stdout.write(`\n${kleur.bold(step.id)} ${kleur.dim("(" + step.kind + ")")}\n`);
-    process.stdout.write(`  ${step.description}\n`);
-    if (step.artifacts.note) {
-      process.stdout.write(`  ${kleur.dim("note:")} ${step.artifacts.note}\n`);
-    }
-    if (step.artifacts.envExample) {
-      process.stdout.write(`  ${kleur.dim(".env.example:")} ${step.artifacts.envExample}\n`);
-    }
-  }
-
-  process.stdout.write(
-    `\n${kleur.bold("summary")}: ${plan.summary.totalSteps} step(s) — ` +
-      `${kleur.red(plan.summary.highRisk + " high-risk")}, ` +
-      `${kleur.yellow(plan.summary.irreversible + " irreversible")}\n`,
-  );
-
-  if (plan.warnings.length > 0) {
-    process.stdout.write(`\n${kleur.bold("warnings:")}\n`);
-    for (const w of plan.warnings) {
-      process.stdout.write(`  ${kleur.yellow("⚠")} ${w}\n`);
-    }
-  }
-  process.stdout.write(
-    `\n${kleur.dim(
-      "pass --json for machine-readable output, --write-files to materialize convex/migrations/.",
-    )}\n\n`,
-  );
 }
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function parseFlags(rest) {
-  const positional = [];
-  const flags = {};
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      const next = rest[i + 1];
-      if (next && !next.startsWith("--")) {
-        flags[key] = next;
-        i++;
-      } else {
-        flags[key] = true;
-      }
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, flags };
-}
-
-function findRepoRoot(start) {
-  let dir = start;
-  for (let i = 0; i < 8; i++) {
-    if (
-      existsSync(path.join(dir, "packages")) &&
-      existsSync(path.join(dir, "package.json"))
-    ) {
-      return dir;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return process.cwd();
-}
+// parseFlags + findRepoRoot live in migrate-load.mjs (single-source helpers).

package/bin/update-context.mjs

@@ -0,0 +1,184 @@
+// update-context.mjs — rr.json / kitab-root / consumer-slice-dir resolution
+// + snapshot builders for `rr update`.
+//
+// Extracted from update.mjs.
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { snapshotFromDir } from "../lib/snapshot.mjs";
+import { readDNA } from "../lib/dna.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @typedef {{
+ *   repoRoot: string,
+ *   rrPath: string,
+ *   rr: any,
+ *   consumerName: string,
+ *   kitabRoot: string,
+ *   kitabSliceDir: string,
+ *   consumerSliceDir: string,
+ * }} UpdateContext
+ */
+
+export function resolveContext(slug, explicitRrPath) {
+  // The kitab repo lives above packages/cli/bin/.
+  const kitabRoot = findKitabRoot();
+  const kitabSliceDir = path.join(kitabRoot, "frontend", "slices", slug);
+  if (!existsSync(kitabSliceDir)) {
+    throw new Error(
+      `update: kitab slice not found at ${kitabSliceDir}. (Did you mean a different slug?)`,
+    );
+  }
+
+  const rrPath = explicitRrPath ? path.resolve(explicitRrPath) : path.resolve(process.cwd(), "rr.json");
+  if (!existsSync(rrPath)) {
+    throw new Error(
+      `update: rr.json not found at ${rrPath}. Pass --rr-path or run from a consumer project.`,
+    );
+  }
+  const rr = JSON.parse(readFileSync(rrPath, "utf8"));
+
+  const consumerName = inferConsumerName(rr, rrPath);
+  const consumerSliceDir = resolveConsumerSliceDir(rr, rrPath, slug);
+
+  return {
+    repoRoot: kitabRoot,
+    rrPath,
+    rr,
+    consumerName,
+    kitabRoot,
+    kitabSliceDir,
+    consumerSliceDir,
+  };
+}
+
+function findKitabRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    if (
+      existsSync(path.join(dir, "packages")) &&
+      existsSync(path.join(dir, "frontend", "slices"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+function inferConsumerName(rr, rrPath) {
+  if (rr?.consumer && typeof rr.consumer === "string") return rr.consumer;
+  if (rr?.template?.slug && typeof rr.template.slug === "string") {
+    return rr.template.slug;
+  }
+  return path.basename(path.dirname(rrPath));
+}
+
+function resolveConsumerSliceDir(rr, rrPath, slug) {
+  const rrDir = path.dirname(rrPath);
+  // Honor a slice-root override if present in rr.json, else default to
+  // frontend/slices/<slug>/ — matches the kitab convention.
+  const sliceRoot =
+    rr?.layout?.sliceRoot && typeof rr.layout.sliceRoot === "string"
+      ? rr.layout.sliceRoot
+      : "frontend/slices";
+  return path.resolve(rrDir, sliceRoot, slug);
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot builders
+// ---------------------------------------------------------------------------
+
+export async function buildKitabSnapshot(slug, ctx) {
+  return snapshotFromDir(slug, ctx.kitabSliceDir);
+}
+
+export async function buildConsumerSnapshot(slug, ctx) {
+  if (!existsSync(ctx.consumerSliceDir)) {
+    // First-time sync — consumer has no copy yet; treat as empty snapshot.
+    return { slug, version: "0.0.0", files: {} };
+  }
+  return snapshotFromDir(slug, ctx.consumerSliceDir);
+}
+
+export async function buildBaseSnapshot(slug, ctx, kitabSnap) {
+  // First-time sync (no DNA) → use kitab tip as base.
+  const dna = readDNA(slug);
+  const consumerAd = dna?.consumers?.[ctx.consumerName];
+  if (!consumerAd?.version) {
+    return cloneSnap(kitabSnap);
+  }
+
+  // Look up the commit by version tag, fall back to the most-recent commit
+  // touching the slice path.
+  const ref = findCommitForVersion(ctx.kitabRoot, slug, consumerAd.version);
+  if (!ref) return cloneSnap(kitabSnap);
+
+  const files = readSliceAtRef(ctx.kitabRoot, slug, ref);
+  // Snapshot at base ref typically lacks a parsed contract — that's OK; the
+  // merge algorithm treats it as no-membership, which mirrors "base had none".
+  return { slug, version: consumerAd.version, files };
+}
+
+function cloneSnap(snap) {
+  return {
+    slug: snap.slug,
+    version: snap.version,
+    files: { ...snap.files },
+    ...(snap.contract ? { contract: JSON.parse(JSON.stringify(snap.contract)) } : {}),
+  };
+}
+
+/** Try `git rev-list -1 <tag>` then `git log -1 --format=%H -- <slicePath>`. */
+function findCommitForVersion(repo, slug, version) {
+  const sliceRel = `frontend/slices/${slug}`;
+  for (const tag of [version, `v${version}`, `${slug}@${version}`]) {
+    const r = spawnSync("git", ["rev-list", "-1", tag], {
+      cwd: repo,
+      encoding: "utf8",
+    });
+    if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
+  }
+  // Fallback: most-recent commit touching the slice path.
+  const r = spawnSync(
+    "git",
+    ["log", "-1", "--format=%H", "main", "--", sliceRel],
+    { cwd: repo, encoding: "utf8" },
+  );
+  if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
+  return null;
+}
+
+/** Read every tracked file under frontend/slices/<slug>/ at `ref` into a map. */
+function readSliceAtRef(repo, slug, ref) {
+  const sliceRel = `frontend/slices/${slug}`;
+  const ls = spawnSync(
+    "git",
+    ["ls-tree", "-r", "--name-only", ref, "--", sliceRel],
+    { cwd: repo, encoding: "utf8" },
+  );
+  /** @type {Record<string,string>} */
+  const out = {};
+  if (ls.status !== 0) return out;
+  const lines = ls.stdout.split("\n").filter(Boolean);
+  for (const line of lines) {
+    const rel = line.startsWith(sliceRel + "/")
+      ? line.slice(sliceRel.length + 1)
+      : line;
+    // Skip files we don't snapshot (binary etc).
+    if (!/\.(ts|tsx|mjs|js|jsx|json|md|css)$/.test(rel)) continue;
+    const show = spawnSync("git", ["show", `${ref}:${line}`], {
+      cwd: repo,
+      encoding: "utf8",
+    });
+    if (show.status === 0) out[rel] = show.stdout;
+  }
+  return out;
+}

package/bin/update-output.mjs

@@ -0,0 +1,110 @@
+// update-output.mjs — ASCII reporter + force-apply / DNA helpers for
+// `rr update`. Extracted from update.mjs.
+
+import path from "node:path";
+import kleur from "kleur";
+
+import { appendLineage, readDNA, upsertConsumerAdoption } from "../lib/dna.mjs";
+
+export function printReport(report, ctx) {
+  const s = report.summary;
+  process.stdout.write(
+    `\n${kleur.bold("3-way merge")} — ${kleur.cyan(report.slug)} ` +
+      kleur.dim(`(consumer: ${ctx.consumerName})`) +
+      "\n",
+  );
+  process.stdout.write(
+    `  ${kleur.green("auto-merged:")} ${s.autoMerged}  ` +
+      `${kleur.green("kitab-clean:")} ${s.kitabWinsClean}  ` +
+      `${kleur.yellow("consumer-clean:")} ${s.consumerWinsClean}  ` +
+      `${kleur.red("conflicts:")} ${s.conflicts}  ` +
+      `${kleur.dim("identical:")} ${s.identical}\n`,
+  );
+  process.stdout.write(
+    `  ${kleur.bold("drift after merge:")} ${formatDrift(report.driftAfterMerge)}\n`,
+  );
+
+  const nonIdentical = report.outcomes.filter((o) => o.kind !== "identical");
+  if (nonIdentical.length > 0) {
+    process.stdout.write(`\n${kleur.bold("Outcomes")}\n`);
+    for (const o of nonIdentical) {
+      const tag = kindTag(o.kind);
+      process.stdout.write(`  ${tag}  ${o.element}${o.conflictHint ? kleur.dim(`  — ${o.conflictHint}`) : ""}\n`);
+    }
+  }
+  process.stdout.write("\n");
+}
+
+function formatDrift(d) {
+  if (d >= 40) return kleur.red(`${d}%`);
+  if (d >= 15) return kleur.yellow(`${d}%`);
+  return kleur.green(`${d}%`);
+}
+
+function kindTag(k) {
+  switch (k) {
+    case "auto-merged":
+      return kleur.green("[auto]    ");
+    case "kitab-wins-clean":
+      return kleur.green("[kitab]   ");
+    case "consumer-wins-clean":
+      return kleur.yellow("[consumer]");
+    case "conflict":
+      return kleur.red("[conflict]");
+    default:
+      return kleur.dim("[same]    ");
+  }
+}
+
+export function recordLineage(slug, ctx, report) {
+  const at = new Date().toISOString();
+  try {
+    appendLineage(slug, {
+      from: `kitab:frontend/slices/${slug}`,
+      to: `consumer:${ctx.consumerName}`,
+      at,
+      transforms: ["3-way-merge", "consumer-sync"],
+      actor: "rr update",
+    });
+    const dna = readDNA(slug);
+    const existing = dna?.consumers?.[ctx.consumerName];
+    upsertConsumerAdoption(slug, ctx.consumerName, {
+      adopted_at: existing?.adopted_at ?? at,
+      version: report.mergedSnapshot?.version ?? existing?.version ?? "0.0.0",
+      drift_score: report.driftAfterMerge,
+      last_synced_at: at,
+    });
+  } catch (err) {
+    process.stderr.write(
+      kleur.yellow(
+        `  (could not update DNA lineage: ${err.message ?? err})\n`,
+      ),
+    );
+  }
+}
+
+export function buildForcedSnapshot(report, kitabSnap) {
+  /** @type {Record<string,string>} */
+  const files = {};
+  for (const o of report.outcomes) {
+    if (!o.element.startsWith("files/")) continue;
+    const rel = o.element.slice("files/".length);
+    if (o.kind === "conflict") {
+      // On force-apply, prefer kitab value (or consumer if kitab dropped).
+      const v = o.kitabValue ?? o.consumerValue;
+      if (v != null) files[rel] = /** @type {string} */ (v);
+    } else if (o.mergedValue != null) {
+      files[rel] = /** @type {string} */ (o.mergedValue);
+    }
+  }
+  return { slug: kitabSnap.slug, version: kitabSnap.version, files };
+}
+
+export async function writeForced(snap, targetDir) {
+  const { mkdir, writeFile } = await import("node:fs/promises");
+  for (const [rel, content] of Object.entries(snap.files)) {
+    const dest = path.join(targetDir, rel);
+    await mkdir(path.dirname(dest), { recursive: true });
+    await writeFile(dest, content);
+  }
+}