rahman-resources 0.9.2 → 0.12.0

package/bin/update.mjs

@@ -0,0 +1,413 @@
+// `rr update <slug>` — bidirectional sync: pull the latest kitab version of a
+// slice into the consumer's local copy via 3-way semantic merge.
+//
+// Flow:
+//   1. Locate the kitab repo root + consumer slice dir (from rr.json install
+//      records).
+//   2. Build a base snapshot from the lineage-pinned kitab commit (via git
+//      show), falling back to the kitab tip when there's no DNA entry yet.
+//   3. Build a kitab-tip snapshot from frontend/slices/<slug>/.
+//   4. Build a consumer snapshot from the local slice dir.
+//   5. Run merge3() — print the summary + outcomes table.
+//   6. If --apply, applyMerge() to the consumer dir; refuse when conflicts
+//      remain unless --force.
+//   7. Append a "3-way-merge" lineage entry and upsert the consumer's
+//      `drift_score = report.driftAfterMerge`.
+//
+// Flags:
+//   --apply        write merged files to consumer dir (otherwise dry preview)
+//   --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";
+
+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));
+
+/**
+ * Entry point invoked by cli.js with the post-`update` argv tail.
+ * @param {string[]} rest
+ */
+export async function runUpdate(rest) {
+  const { positional, flags } = parseFlags(rest);
+  const slug = positional[0];
+  if (!slug) {
+    process.stderr.write(
+      kleur.red("Usage: rahman-resources update <slug> [--apply] [--force] [--rr-path P] [--json]\n"),
+    );
+    process.exit(1);
+  }
+
+  const asJson = !!flags.json;
+  const apply = !!flags.apply;
+  const force = !!flags.force;
+  const rrPath = typeof flags["rr-path"] === "string" ? flags["rr-path"] : null;
+
+  const ctx = resolveContext(slug, rrPath);
+
+  const kitabSnap = await buildKitabSnapshot(slug, ctx);
+  const baseSnap = await buildBaseSnapshot(slug, ctx, kitabSnap);
+  const consumerSnap = await buildConsumerSnapshot(slug, ctx);
+
+  const report = merge3({ base: baseSnap, kitab: kitabSnap, consumer: consumerSnap });
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    printReport(report, ctx);
+  }
+
+  const hasConflicts = report.summary.conflicts > 0;
+  if (apply) {
+    if (hasConflicts && !force) {
+      if (!asJson) {
+        process.stderr.write(
+          kleur.red(
+            `\n✖ Refusing to apply — ${report.summary.conflicts} conflict(s) remain. Resolve them or pass --force.\n`,
+          ),
+        );
+      }
+      process.exit(1);
+    }
+    const targetDir = ctx.consumerSliceDir;
+    if (hasConflicts && force) {
+      // Build a forced snapshot — prefer kitab on conflicts (matches "pull
+      // kitab" semantics; consumer can revert manually after).
+      const forced = buildForcedSnapshot(report, kitabSnap);
+      // Write files directly, bypassing applyMerge's conflict guard.
+      await writeForced(forced, targetDir);
+    } else {
+      await applyMerge(report, targetDir);
+    }
+    if (!asJson) {
+      process.stdout.write(kleur.green(`\n✓ Applied merged files to ${ctx.consumerSliceDir}\n`));
+    }
+  }
+
+  // Update DNA lineage — only when we actually applied OR when explicitly
+  // asked via --json (machine flows record every sync attempt).
+  if (apply || asJson) {
+    recordLineage(slug, ctx, report);
+  }
+
+  if (hasConflicts && !force) {
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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) {
+  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 };
+}

package/lib/compose-solver.d.ts

@@ -0,0 +1,179 @@
+// Type definitions for the slice compose solver (Phase B).
+// Runtime in compose-solver.mjs; this file is hand-authored types for
+// tsc/IDE consumers. Mirrors the Phase C `dna.d.ts` convention since
+// `packages/**` is excluded from the root tsconfig.
+
+import type { SliceContract } from "./contract";
+
+/**
+ * The relevant slice of a project's `rr.json` (plus optional ambient
+ * data the solver needs but the schema doesn't yet codify).
+ *
+ * Every field is optional — an empty {} is the canonical "nothing
+ * pre-existing" state. The CLI dispatcher fills these from the parsed
+ * rr.json plus any environment scans.
+ */
+export interface RrJsonState {
+  /**
+   * Target identity provider. Mapped from `rr.json#/auth.provider`
+   * ("convex-auth" → "convex") by the CLI dispatcher before passing in.
+   */
+  auth?: "convex" | "clerk" | "next-auth" | "none";
+  /** Env vars already set in target (e.g. parsed from `.env.example`). */
+  envExisting?: string[];
+  /** RBAC permissions already in target — e.g. "user.read". */
+  rbacRolesExisting?: string[];
+  /** Slugs already installed (mirrors `rr.json#/slices` + `/features`). */
+  slicesInstalled?: string[];
+  /** Convex table names already in target schema. */
+  convexTablesExisting?: string[];
+  /**
+   * When `true` (default), a desired slug with no registered contract is
+   * surfaced as an `uncontracted` warning and accepted with a `note`. When
+   * `false` (e.g. `--strict`), it becomes a blocker `missing-dep`. Useful for
+   * gradual migrations where most slices are still un-contracted.
+   */
+  allowUnknownSlices?: boolean;
+}
+
+/** Input bundle for {@link compose}. */
+export interface ComposeRequest {
+  state: RrJsonState;
+  /** Slice slugs the user wants to add. */
+  desired: string[];
+  /**
+   * When true (default), the solver pulls in transitive `requires.deps[]`.
+   * Set to false to disable BFS dep resolution (CLI `--no-deps`).
+   */
+  resolveDeps?: boolean;
+}
+
+/**
+ * Discriminator for {@link Conflict.type}.
+ *
+ * - `auth-mismatch` — slice requires auth X, target has Y. **blocker**.
+ * - `table-collision` — same table declared by 2 candidates, OR slice
+ *   declares a table already in `state.convexTablesExisting`. **blocker**
+ *   (between two new candidates → arbitrated, not reject-both).
+ * - `rbac-collision` — 2 candidates declare same RBAC permission.
+ *   **warning** — operator can decide if sharing is OK.
+ * - `missing-dep` — slice declares `requires.deps[X]` but X is neither
+ *   in the candidate set nor in `state.slicesInstalled`. **blocker**.
+ *   ALSO emitted for desired slugs whose contract is unknown **only in
+ *   strict mode** (`state.allowUnknownSlices === false`).
+ * - `env-missing` — `requires.env[]` ⊄ `state.envExisting`. **warning**.
+ * - `explicit-conflict` — slice's `conflicts: ["<other>:<key>.<value>"]`
+ *   matched `<other>`'s `provides.<key>` when both are in the candidate
+ *   set. **blocker** (arbitrated, not reject-both).
+ * - `uncontracted` — desired slug had no registered contract while
+ *   `state.allowUnknownSlices` was true. **warning** — the slice is
+ *   accepted but its surface is not inspected.
+ * - `both-installed-conflict` — an explicit-conflict / table-collision
+ *   surfaced between two slices BOTH already in `state.slicesInstalled`.
+ *   **warning** — neither is dropped, operator is told to clean up.
+ */
+export type ConflictType =
+  | "auth-mismatch"
+  | "table-collision"
+  | "rbac-collision"
+  | "missing-dep"
+  | "env-missing"
+  | "explicit-conflict"
+  | "uncontracted"
+  | "both-installed-conflict";
+
+/** A single conflict finding, surfaced in {@link ComposeResult.conflicts}. */
+export interface Conflict {
+  type: ConflictType;
+  /** The slug this finding is anchored on. */
+  slug: string;
+  /** Human-readable explanation. */
+  detail: string;
+  /** When the conflict is between two slices, the other slug. */
+  withSlug?: string;
+  /**
+   * `"blocker"` causes the slice to be rejected.
+   * `"warning"` is informational and never blocks acceptance.
+   */
+  severity: "blocker" | "warning";
+}
+
+/**
+ * A single arbitration decision — when two candidates collide the solver
+ * ranks them by "most dependers wins" and drops the loser.
+ */
+export interface Arbitration {
+  /** The conflict that triggered the arbitration. */
+  conflict: Conflict;
+  /** Slug that survived. */
+  winner: string;
+  /** Slug that was dropped. */
+  loser: string;
+  /** Why this side won (dep-count + tie-break note). */
+  reason: string;
+}
+
+/** Output bundle from {@link compose}. */
+export interface ComposeResult {
+  /** Slugs the solver would install (in BFS-discovery order). */
+  accepted: string[];
+  /** Slugs the solver rejected, with the reasons attached. */
+  rejected: { slug: string; reasons: Conflict[]; note?: string }[];
+  /** All conflicts surfaced, including warning-level. */
+  conflicts: Conflict[];
+  /** Union of `requires.env` from accepted slices not in `state.envExisting`. */
+  envMissing: string[];
+  /** Union of `requires.rbac` from accepted slices not in `state.rbacRolesExisting`. */
+  rbacToCreate: string[];
+  /** Per-slice table additions, useful for printing schema previews. */
+  tablesAdded: { slug: string; tables: string[] }[];
+  /** Human-readable trace of every decision the solver made. */
+  proof: string[];
+  /**
+   * Conflict arbitration outcomes — populated when two new candidates collide
+   * and the solver picks a winner via dep-count ranking. Omitted when no such
+   * arbitration was needed.
+   */
+  arbitrations?: Arbitration[];
+  /**
+   * Per-slice notes (e.g. "uncontracted", "both-installed-conflict") attached
+   * to the corresponding `accepted` slug. Keyed by slug.
+   */
+  notes?: Record<string, string>;
+}
+
+/**
+ * Discover every `slice.contract.ts` under `<repoRoot>/frontend/slices/` and
+ * `<repoRoot>/template-base/frontend/slices/`, then dynamic-import each via
+ * tsx and return them keyed by `contract.id`. Contracts whose loader throws
+ * are silently skipped (a future iteration may surface them).
+ */
+export function loadAllContracts(
+  repoRoot: string,
+): Promise<Map<string, SliceContract>>;
+
+/**
+ * Greedy compose solver. Pure — no I/O. Returns a fresh {@link ComposeResult};
+ * does not mutate `req` or `contracts`.
+ *
+ * Algorithm: BFS resolve transitive deps (visited-set; throws on cycle with
+ * the full path in the message), then run conflict checks against state +
+ * sibling candidates. When a `table-collision` or `explicit-conflict` between
+ * two candidates is detected, the solver ranks them by dependers-count and
+ * drops the loser only (records an `Arbitration` entry). Slugs already in
+ * `state.slicesInstalled` win against new candidates; if BOTH sides of a
+ * conflict are installed, neither is dropped — instead a `both-installed-
+ * conflict` warning is surfaced.
+ *
+ * Un-contracted slugs in `desired` are accepted with an `uncontracted`
+ * warning when `state.allowUnknownSlices` is true (the default). Set it to
+ * false (or pass `--strict` from the CLI) to escalate them to blocker
+ * `missing-dep`.
+ *
+ * @throws Error when a dep cycle is detected — message includes the full
+ *   cycle path, e.g. `"dependency cycle detected: a → b → c → a"`.
+ */
+export function compose(
+  req: ComposeRequest,
+  contracts: Map<string, SliceContract>,
+): ComposeResult;