rahman-resources 1.4.0 → 1.6.0

package/bin/update.mjs

@@ -19,23 +19,26 @@
 //   --force        allow apply even with conflicts (uses each side's last value)
 //   --rr-path P    explicit rr.json path (overrides cwd discovery)
 //   --json         emit machine-readable JSON instead of ASCII
-
-import { existsSync, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+//
+// Module split (kept ≤200 LOC each):
+//   - update-context.mjs  — rr.json/kitab-root resolution + snapshot builders
+//   - update-output.mjs   — ASCII reporter + force-apply / DNA helpers
 
 import kleur from "kleur";
 
 import { merge3, applyMerge } from "../lib/merge3.mjs";
-import { snapshotFromDir } from "../lib/snapshot.mjs";
 import {
-  readDNA,
-  appendLineage,
-  upsertConsumerAdoption,
-} from "../lib/dna.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  resolveContext,
+  buildKitabSnapshot,
+  buildBaseSnapshot,
+  buildConsumerSnapshot,
+} from "./update-context.mjs";
+import {
+  printReport,
+  recordLineage,
+  buildForcedSnapshot,
+  writeForced,
+} from "./update-output.mjs";
 
 /**
  * Entry point invoked by cli.js with the post-`update` argv tail.
@@ -108,287 +111,6 @@ export async function runUpdate(rest) {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Context resolution
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {{
- *   repoRoot: string,
- *   rrPath: string,
- *   rr: any,
- *   consumerName: string,
- *   kitabRoot: string,
- *   kitabSliceDir: string,
- *   consumerSliceDir: string,
- * }} UpdateContext
- */
-
-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
-// ---------------------------------------------------------------------------
-
-async function buildKitabSnapshot(slug, ctx) {
-  return snapshotFromDir(slug, ctx.kitabSliceDir);
-}
-
-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);
-}
-
-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;
-}
-
-// ---------------------------------------------------------------------------
-// Output / DNA / forced-apply helpers
-// ---------------------------------------------------------------------------
-
-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]    ");
-  }
-}
-
-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`,
-      ),
-    );
-  }
-}
-
-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 };
-}
-
-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);
-  }
-}
-
 // ---------------------------------------------------------------------------
 
 function parseFlags(rest) {

package/lib/compose-solver-arbitrate.mjs

@@ -0,0 +1,84 @@
+// compose-solver-arbitrate.mjs — pair-arbitration helper.
+//
+// Split from compose-solver-conflicts.mjs to keep both files ≤200 LOC.
+// Returns a closure that records the arbitration outcome + appends to
+// `proof` for the chosen winner/loser.
+
+/**
+ * Pair-conflict arbitration helper factory. Returns a function that records
+ * the arbitration outcome + appends a `proof` entry.
+ */
+export function makeArbitrator({
+  installed,
+  dependersCount,
+  allConflicts,
+  arbitrations,
+  notes,
+  proof,
+  record,
+}) {
+  /**
+   * @param {string} a
+   * @param {string} b
+   * @param {import("./compose-solver").ConflictType} type
+   * @param {string} detailA
+   * @param {string} detailB
+   */
+  return function arbitratePair(a, b, type, detailA, detailB) {
+    const ca = /** @type {import("./compose-solver").Conflict} */ ({
+      type, slug: a, withSlug: b, detail: detailA, severity: "blocker",
+    });
+    const cb = /** @type {import("./compose-solver").Conflict} */ ({
+      type, slug: b, withSlug: a, detail: detailB, severity: "blocker",
+    });
+    const bothInstalled = installed.has(a) && installed.has(b);
+    if (bothInstalled) {
+      allConflicts.push({ ...ca, severity: "warning", type: "both-installed-conflict" });
+      allConflicts.push({ ...cb, severity: "warning", type: "both-installed-conflict" });
+      notes.set(a, notes.get(a) ?? "both-installed-conflict");
+      notes.set(b, notes.get(b) ?? "both-installed-conflict");
+      proof.push(`! ${a} ↔ ${b}: both already installed — conflict surfaced as warning, neither dropped`);
+      return;
+    }
+    if (installed.has(a) && !installed.has(b)) {
+      record(cb, b);
+      arbitrations.push({
+        conflict: cb, winner: a, loser: b,
+        reason: `"${a}" already installed — installed slice wins`,
+      });
+      proof.push(`- ${b}: arbitrated against ${a} (installed wins)`);
+      return;
+    }
+    if (installed.has(b) && !installed.has(a)) {
+      record(ca, a);
+      arbitrations.push({
+        conflict: ca, winner: b, loser: a,
+        reason: `"${b}" already installed — installed slice wins`,
+      });
+      proof.push(`- ${a}: arbitrated against ${b} (installed wins)`);
+      return;
+    }
+    const depA = dependersCount.get(a) ?? 0;
+    const depB = dependersCount.get(b) ?? 0;
+    let winner, loser, conflictForLoser, reason;
+    if (depA !== depB) {
+      if (depA > depB) {
+        winner = a; loser = b; conflictForLoser = cb;
+        reason = `"${a}" has ${depA} dependers vs "${b}" with ${depB} — most-dependers wins`;
+      } else {
+        winner = b; loser = a; conflictForLoser = ca;
+        reason = `"${b}" has ${depB} dependers vs "${a}" with ${depA} — most-dependers wins`;
+      }
+    } else {
+      const later = a > b ? a : b;
+      const earlier = a > b ? b : a;
+      winner = earlier;
+      loser = later;
+      conflictForLoser = later === a ? ca : cb;
+      reason = `tie at ${depA} dependers — alphabetical tiebreak drops "${later}"`;
+    }
+    record(conflictForLoser, loser);
+    arbitrations.push({ conflict: conflictForLoser, winner, loser, reason });
+    proof.push(`- ${loser}: arbitrated against ${winner} (${reason})`);
+  };
+}

package/lib/compose-solver-conflicts.mjs

@@ -0,0 +1,163 @@
+// compose-solver-conflicts.mjs — auth/table/env/rbac/explicit conflict checks.
+//
+// Extracted from compose-solver.mjs. Pair-arbitration helper lives in
+// compose-solver-arbitrate.mjs; re-exported here so callers keep one
+// conflicts entry point.
+
+export { makeArbitrator } from "./compose-solver-arbitrate.mjs";
+
+/**
+ * Per-candidate surface checks: auth mismatch, table collision (against
+ * existing schema), env missing, rbac (implicit via lookup table).
+ */
+export function runSurfaceChecks({
+  candidateOrder,
+  uncontractedDesired,
+  contracts,
+  state,
+  tablesExisting,
+  envExisting,
+  record,
+}) {
+  for (const slug of candidateOrder) {
+    if (uncontractedDesired.has(slug)) continue;
+    const contract = contracts.get(slug);
+    if (!contract) continue;
+
+    const wantAuth = contract.requires?.auth;
+    if (wantAuth && state.auth && wantAuth !== state.auth && wantAuth !== "none") {
+      record(
+        {
+          type: "auth-mismatch",
+          slug,
+          detail: `Slice requires auth="${wantAuth}" but target rr.json has auth="${state.auth}".`,
+          severity: "blocker",
+        },
+        slug,
+      );
+    }
+
+    const provTables = contract.provides?.tables ?? [];
+    for (const t of provTables) {
+      if (tablesExisting.has(t)) {
+        record(
+          {
+            type: "table-collision",
+            slug,
+            detail: `Table "${t}" already exists in target Convex schema.`,
+            severity: "blocker",
+          },
+          slug,
+        );
+      }
+    }
+
+    const reqEnv = contract.requires?.env ?? [];
+    for (const e of reqEnv) {
+      if (!envExisting.has(e)) {
+        record(
+          {
+            type: "env-missing",
+            slug,
+            detail: `Env var "${e}" required by ${slug} not present in target.`,
+            severity: "warning",
+          },
+          slug,
+        );
+      }
+    }
+  }
+}
+
+/** Build provides-lookup once: Map<slug, { tables: Set, rbac: Set }>. */
+export function buildProvidesLookup(candidateOrder, uncontractedDesired, contracts) {
+  /** @type {Map<string, { tables: Set<string>; rbac: Set<string> }>} */
+  const lookup = new Map();
+  for (const slug of candidateOrder) {
+    if (uncontractedDesired.has(slug)) continue;
+    const c = contracts.get(slug);
+    if (!c) continue;
+    lookup.set(slug, {
+      tables: new Set(c.provides?.tables ?? []),
+      rbac: new Set(c.requires?.rbac ?? []),
+    });
+  }
+  return lookup;
+}
+
+/**
+ * Pairwise scan: detect table collisions (arbitrated) + rbac overlaps
+ * (warning only) across all candidate pairs.
+ */
+export function detectPairwiseCollisions({
+  candidateOrder,
+  lookup,
+  arbitratePair,
+  allConflicts,
+}) {
+  for (let i = 0; i < candidateOrder.length; i++) {
+    for (let j = i + 1; j < candidateOrder.length; j++) {
+      const a = candidateOrder[i];
+      const b = candidateOrder[j];
+      const la = lookup.get(a);
+      const lb = lookup.get(b);
+      if (!la || !lb) continue;
+
+      const tableHits = [];
+      for (const t of la.tables) if (lb.tables.has(t)) tableHits.push(t);
+      if (tableHits.length > 0) {
+        const detail = `Slices "${a}" and "${b}" both declare table${tableHits.length > 1 ? "s" : ""} ${tableHits.map((t) => `"${t}"`).join(", ")}.`;
+        arbitratePair(a, b, "table-collision", detail, detail);
+      }
+      for (const p of la.rbac) {
+        if (lb.rbac.has(p)) {
+          allConflicts.push({
+            type: "rbac-collision",
+            slug: a,
+            withSlug: b,
+            detail: `Slices "${a}" and "${b}" both declare RBAC permission "${p}".`,
+            severity: "warning",
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Explicit `conflicts: ["<other>:<key>.<value>"]` declarations — when the
+ * other slice's `provides[key]` contains `value`, surface as arbitrated
+ * conflict.
+ */
+export function detectExplicitConflicts({
+  candidateOrder,
+  candidateSet,
+  uncontractedDesired,
+  contracts,
+  arbitratePair,
+}) {
+  for (const slug of candidateOrder) {
+    if (uncontractedDesired.has(slug)) continue;
+    const c = contracts.get(slug);
+    if (!c) continue;
+    const conflicts = c.conflicts ?? [];
+    for (const cf of conflicts) {
+      const colon = cf.indexOf(":");
+      const dot = cf.indexOf(".", colon);
+      if (colon < 0 || dot < 0) continue;
+      const otherSlug = cf.slice(0, colon);
+      const key = cf.slice(colon + 1, dot);
+      const value = cf.slice(dot + 1);
+      if (!candidateSet.has(otherSlug)) continue;
+      if (uncontractedDesired.has(otherSlug)) continue;
+      const other = contracts.get(otherSlug);
+      if (!other) continue;
+      const provided = other.provides?.[key];
+      if (Array.isArray(provided) && provided.includes(value)) {
+        const detailA = `Slice "${slug}" declares explicit conflict with "${otherSlug}" on ${key}.${value}.`;
+        const detailB = `Slice "${otherSlug}" is the target of "${slug}"'s explicit conflict on ${key}.${value}.`;
+        arbitratePair(slug, otherSlug, "explicit-conflict", detailA, detailB);
+      }
+    }
+  }
+}

package/lib/compose-solver-loader.mjs

@@ -0,0 +1,79 @@
+// compose-solver-loader.mjs — contract discovery + tsx-eval loader.
+//
+// Split out from compose-solver.mjs to keep the pure solver < 200 LOC.
+// I/O entry point only — discovers `slice.contract.ts` under known slice
+// roots and shells out to `npx tsx` to JSON-serialize each export.
+
+import { readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const SLICE_ROOT_GLOBS = [
+  ["frontend", "slices"],
+  ["template-base", "frontend", "slices"],
+];
+
+/**
+ * Discover every `slice.contract.ts` under the kitab's known slice roots and
+ * load them via `npx tsx`. Returns a Map<slug, SliceContract>. Contracts that
+ * fail to load are silently skipped so a single broken file doesn't take
+ * down the whole solver — `npm run validate:contracts` is the place to surface
+ * those errors.
+ *
+ * @param {string} repoRoot Absolute path to the kitab repo root.
+ * @returns {Promise<Map<string, import("./contract").SliceContract>>}
+ */
+export async function loadAllContracts(repoRoot) {
+  /** @type {Map<string, import("./contract").SliceContract>} */
+  const out = new Map();
+  const sliceFiles = await discoverContractFiles(repoRoot);
+  for (const filePath of sliceFiles) {
+    const contract = loadContractFile(repoRoot, filePath);
+    if (contract && typeof contract.id === "string") {
+      out.set(contract.id, contract);
+    }
+  }
+  return out;
+}
+
+async function discoverContractFiles(repoRoot) {
+  const found = [];
+  for (const segs of SLICE_ROOT_GLOBS) {
+    const root = path.join(repoRoot, ...segs);
+    if (!existsSync(root)) continue;
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith("_")) continue;
+      const filePath = path.join(root, entry.name, "slice.contract.ts");
+      if (existsSync(filePath)) found.push(filePath);
+    }
+  }
+  return found;
+}
+
+/**
+ * Dynamic-import a .ts contract file via `npx tsx -e` and JSON.parse the
+ * stringified `contract` export. Returns null on any failure.
+ */
+function loadContractFile(repoRoot, 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(() => 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;
+}