rahman-resources 1.13.0 → 1.13.2

package/lib/manifest.json

@@ -1987,7 +1987,7 @@
       "install": "npx rahman-resources add user-management",
       "npmPackages": [],
       "exampleCode": "",
-      "agentRecipe": "Run `npx rr add user-management` (pulls rbac-roles + convex-auth). Frontend: <MembersPanel members={useQuery(api[\"features/user-management/query\"].listMembers,{tenantId})} roles={ROLE_PRESETS.map(r=>({slug:r.slug,name:r.name,color:r.color}))} currentPerms={actorPerms} onUpdateRole={useMutation(...updateMemberRole)} onRemove={useMutation(...removeMember)} onInvite={openInvite} />. Wire roles + currentPerms from rbac-roles at the app level — the slice itself imports no other slice. Convex: spread userManagementTables; listMembers/mutations gate via rbac-roles requirePermission.",
+      "agentRecipe": "Run `npx rr add user-management` (pulls rbac-roles + convex-auth). Frontend: <MembersPanel members={useQuery(api[\"features/user_management/query\"].listMembers,{tenantId})} roles={ROLE_PRESETS.map(r=>({slug:r.slug,name:r.name,color:r.color}))} currentPerms={actorPerms} onUpdateRole={useMutation(...updateMemberRole)} onRemove={useMutation(...removeMember)} onInvite={openInvite} />. Wire roles + currentPerms from rbac-roles at the app level — the slice itself imports no other slice. Convex: spread userManagementTables; listMembers/mutations gate via rbac-roles requirePermission.",
       "tags": [
         "user-management",
         "members",
@@ -3915,7 +3915,7 @@
       "source": "superspace",
       "slicePath": "frontend/slices/rbac-roles",
       "convexPaths": [
-        "convex/features/rbac-roles"
+        "convex/features/rbac_roles"
       ],
       "npm": [],
       "shadcn": [
@@ -3959,7 +3959,7 @@
       "source": "superspace",
       "slicePath": "frontend/slices/user-management",
       "convexPaths": [
-        "convex/features/user-management"
+        "convex/features/user_management"
       ],
       "npm": [],
       "shadcn": [
@@ -4001,7 +4001,7 @@
         "convex",
         "no-clerk"
       ],
-      "agentRecipe": "Run `npx rr add user-management` (pulls rbac-roles + convex-auth). Frontend: <MembersPanel members={useQuery(api[\"features/user-management/query\"].listMembers,{tenantId})} roles={ROLE_PRESETS.map(r=>({slug:r.slug,name:r.name,color:r.color}))} currentPerms={actorPerms} onUpdateRole={useMutation(...updateMemberRole)} onRemove={useMutation(...removeMember)} onInvite={openInvite} />. Wire roles + currentPerms from rbac-roles at the app level — the slice itself imports no other slice. Convex: spread userManagementTables; listMembers/mutations gate via rbac-roles requirePermission."
+      "agentRecipe": "Run `npx rr add user-management` (pulls rbac-roles + convex-auth). Frontend: <MembersPanel members={useQuery(api[\"features/user_management/query\"].listMembers,{tenantId})} roles={ROLE_PRESETS.map(r=>({slug:r.slug,name:r.name,color:r.color}))} currentPerms={actorPerms} onUpdateRole={useMutation(...updateMemberRole)} onRemove={useMutation(...removeMember)} onInvite={openInvite} />. Wire roles + currentPerms from rbac-roles at the app level — the slice itself imports no other slice. Convex: spread userManagementTables; listMembers/mutations gate via rbac-roles requirePermission."
     },
     {
       "slug": "admin-panel",
@@ -4160,7 +4160,7 @@
       "source": "rahmanef.com",
       "slicePath": "frontend/slices/rate-limit",
       "convexPaths": [
-        "convex/features/rate-limit"
+        "convex/features/rate_limit"
       ],
       "npm": [],
       "shadcn": [],
@@ -4263,7 +4263,7 @@
       "source": "rahmanef.com",
       "slicePath": "frontend/slices/create-your-mcp",
       "convexPaths": [
-        "convex/features/create-your-mcp"
+        "convex/features/create_your_mcp"
       ],
       "npm": [],
       "shadcn": [],

package/lib/post-init.mjs

@@ -11,14 +11,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
-import { DEFAULT_RR, writeRr, buildRr } from "./rr.mjs";
-
-const RR_ALIASES_TO_TSCONFIG = {
-  // alias -> tsconfig key target relative-path
-  "@/components/templates/_shared": "components/templates/_shared",
-  "@/components/templates": "components/templates",
-  "@/features": "features",
-};
+import { writeRr, buildRr } from "./rr.mjs";
 
 export function runPostInit(targetDir, opts = {}) {
   const out = { changed: [], skipped: [] };

package/lib/starter/scripts/smoke-test.mjs

@@ -25,27 +25,27 @@ const required = [
   "scripts/setup-auth.mjs",
   "lib/headless-core/version.ts",
 ];
-for (const f of required) (existsSync(f) ? ok(f) : bad(`missing ${f}`));
+for (const f of required) { if (existsSync(f)) ok(f); else bad(`missing ${f}`); }
 
 console.log("\n● Manifest + scripts");
 try {
   const v = JSON.parse(readFileSync("version.json", "utf8"));
-  v.version && v.core ? ok(`version.json (v${v.version})`) : bad("version.json missing version/core");
+  if (v.version && v.core) ok(`version.json (v${v.version})`); else bad("version.json missing version/core");
 } catch { bad("version.json invalid JSON"); }
 try {
   const pkg = JSON.parse(readFileSync("package.json", "utf8"));
-  pkg.scripts?.["build:auto"] ? ok("package.json build:auto present") : bad("package.json missing build:auto");
+  if (pkg.scripts?.["build:auto"]) ok("package.json build:auto present"); else bad("package.json missing build:auto");
 } catch { bad("package.json invalid"); }
 try {
   const vc = JSON.parse(readFileSync("vercel.json", "utf8"));
-  /build:auto/.test(vc.buildCommand ?? "") ? ok("vercel.json buildCommand -> build:auto") : bad("vercel.json buildCommand wrong");
+  if (/build:auto/.test(vc.buildCommand ?? "")) ok("vercel.json buildCommand -> build:auto"); else bad("vercel.json buildCommand wrong");
 } catch { bad("vercel.json invalid"); }
 
 console.log("\n● Env documentation");
 try {
   const env = readFileSync(".env.example", "utf8");
   for (const k of ["NEXT_PUBLIC_CONVEX_URL", "CONVEX_DEPLOY_KEY"])
-    (env.includes(k) ? ok(`.env.example documents ${k}`) : bad(`.env.example missing ${k}`));
+    { if (env.includes(k)) ok(`.env.example documents ${k}`); else bad(`.env.example missing ${k}`); }
 } catch { bad(".env.example unreadable"); }
 
 function run(label, cmd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rahman-resources",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Rahman Resources (rr) — shadcn-style installer for vertical slices. `npx resources add <slug>` copies slice into your project's `slices/<slug>/`. You own the files.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,7 @@
   "files": [
     "bin",
     "lib",
+    "!lib/**/*.test.mjs",
     "README.md"
   ],
   "engines": {
@@ -44,7 +45,6 @@
   },
   "keywords": [
     "rahman",
-    "kitab",
     "template",
     "installer",
     "nextjs",

package/lib/compose-solver.test.mjs

@@ -1,483 +0,0 @@
-// Vitest suite for the Phase B compose solver.
-// Uses synthetic in-memory contracts so the tests are independent of the
-// real frontend/slices/*/slice.contract.ts files. The loader is exercised
-// indirectly by the CLI smoke test in the worktree-verify step.
-
-import { describe, expect, it } from "vitest";
-import { compose } from "./compose-solver.mjs";
-
-/**
- * Tiny helper — build a Map of slug → contract from an array of inline
- * contract objects so each test reads as a single scenario block.
- */
-function makeContracts(arr) {
-  return new Map(arr.map((c) => [c.id, c]));
-}
-
-describe("compose() — empty + happy paths", () => {
-  it("empty desired → empty accepted/rejected/conflicts", () => {
-    const result = compose(
-      { state: {}, desired: [] },
-      makeContracts([]),
-    );
-    expect(result.accepted).toEqual([]);
-    expect(result.rejected).toEqual([]);
-    expect(result.conflicts).toEqual([]);
-    expect(result.envMissing).toEqual([]);
-    expect(result.rbacToCreate).toEqual([]);
-    expect(result.tablesAdded).toEqual([]);
-    expect(result.proof).toEqual([]);
-  });
-
-  it("single slice, no conflicts → accepted", () => {
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["mdx-blog"] },
-      makeContracts([
-        {
-          id: "mdx-blog",
-          version: "0.1.0",
-          requires: {},
-          provides: { routes: ["/blog"] },
-        },
-      ]),
-    );
-    expect(result.accepted).toEqual(["mdx-blog"]);
-    expect(result.rejected).toEqual([]);
-    expect(result.conflicts.filter((c) => c.severity === "blocker")).toEqual([]);
-    expect(result.proof.some((l) => l.startsWith("+ mdx-blog"))).toBe(true);
-  });
-});
-
-describe("compose() — auth-mismatch", () => {
-  it("slice wants convex but target has clerk → blocker", () => {
-    const result = compose(
-      { state: { auth: "clerk" }, desired: ["convex-auth"] },
-      makeContracts([
-        {
-          id: "convex-auth",
-          version: "0.1.0",
-          requires: { auth: "convex" },
-          provides: {},
-        },
-      ]),
-    );
-    expect(result.accepted).toEqual([]);
-    expect(result.rejected).toHaveLength(1);
-    expect(result.rejected[0].slug).toBe("convex-auth");
-    const blockers = result.rejected[0].reasons.filter((r) => r.severity === "blocker");
-    expect(blockers.map((b) => b.type)).toContain("auth-mismatch");
-  });
-});
-
-describe("compose() — explicit-conflict (v2 arbitration)", () => {
-  it("doku + midtrans collide on paymentOrders → arbitration drops loser only", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku-payment",
-        version: "0.1.0",
-        requires: {
-          auth: "convex",
-          convex: { prefix: "doku_", tables: ["doku_orders"] },
-        },
-        provides: { tables: ["doku_orders"] },
-        conflicts: ["midtrans-payment:tables.paymentOrders"],
-      },
-      {
-        id: "midtrans-payment",
-        version: "0.1.0",
-        requires: {
-          auth: "convex",
-          convex: { prefix: "midtrans_", tables: ["paymentOrders"] },
-        },
-        provides: { tables: ["paymentOrders"] },
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["doku-payment", "midtrans-payment"] },
-      contracts,
-    );
-    // Equal dependers (0 each) → alphabetical tiebreak drops "midtrans-payment".
-    expect(result.accepted).toEqual(["doku-payment"]);
-    expect(result.rejected.map((r) => r.slug)).toEqual(["midtrans-payment"]);
-    const explicit = result.conflicts.filter((c) => c.type === "explicit-conflict");
-    expect(explicit.length).toBeGreaterThanOrEqual(1);
-    expect(result.arbitrations).toBeDefined();
-    expect(result.arbitrations[0].winner).toBe("doku-payment");
-    expect(result.arbitrations[0].loser).toBe("midtrans-payment");
-  });
-});
-
-describe("compose() — missing dep", () => {
-  it("desired contract not found (strict) → blocker missing-dep", () => {
-    const result = compose(
-      { state: { allowUnknownSlices: false }, desired: ["nonexistent"] },
-      makeContracts([]),
-    );
-    expect(result.accepted).toEqual([]);
-    expect(result.rejected.map((r) => r.slug)).toEqual(["nonexistent"]);
-    expect(result.conflicts[0]?.type).toBe("missing-dep");
-  });
-
-  it("slice deps on unknown slice → blocker missing-dep on parent", () => {
-    const contracts = makeContracts([
-      {
-        id: "child",
-        version: "0.1.0",
-        requires: { deps: ["ghost"] },
-        provides: {},
-      },
-    ]);
-    const result = compose({ state: {}, desired: ["child"] }, contracts);
-    expect(result.accepted).toEqual([]);
-    const blockers = result.conflicts.filter(
-      (c) => c.type === "missing-dep" && c.withSlug === "ghost",
-    );
-    expect(blockers.length).toBe(1);
-  });
-});
-
-describe("compose() — transitive dep resolution", () => {
-  it("desired pulls in dep automatically", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku",
-        version: "0.1.0",
-        requires: { auth: "convex", deps: ["convex-auth"] },
-        provides: {},
-      },
-      {
-        id: "convex-auth",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: {},
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["doku"] },
-      contracts,
-    );
-    expect(result.accepted.sort()).toEqual(["convex-auth", "doku"]);
-    expect(result.proof.some((l) => l.includes("transitive dep"))).toBe(true);
-  });
-});
-
-describe("compose() — installed wins", () => {
-  it("a slice already installed isn't rejected even if it conflicts with a new one", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku-payment",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["doku_orders"] },
-        conflicts: ["midtrans-payment:tables.paymentOrders"],
-      },
-      {
-        id: "midtrans-payment",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["paymentOrders"] },
-      },
-    ]);
-    const result = compose(
-      {
-        state: { auth: "convex", slicesInstalled: ["doku-payment"] },
-        desired: ["doku-payment", "midtrans-payment"],
-      },
-      contracts,
-    );
-    // doku is installed — wins; midtrans gets rejected.
-    expect(result.accepted).toContain("doku-payment");
-    expect(result.rejected.map((r) => r.slug)).toContain("midtrans-payment");
-  });
-});
-
-describe("compose() — cycle detection", () => {
-  it("throws when deps form a cycle", () => {
-    const contracts = makeContracts([
-      { id: "a", version: "0.1.0", requires: { deps: ["b"] }, provides: {} },
-      { id: "b", version: "0.1.0", requires: { deps: ["a"] }, provides: {} },
-    ]);
-    expect(() =>
-      compose({ state: {}, desired: ["a"] }, contracts),
-    ).toThrowError(/cycle/);
-  });
-});
-
-describe("compose() — env warning is non-blocking", () => {
-  it("missing env surfaces as warning but slice is accepted", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku",
-        version: "0.1.0",
-        requires: { auth: "convex", env: ["DOKU_CLIENT_ID"] },
-        provides: {},
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex", envExisting: [] }, desired: ["doku"] },
-      contracts,
-    );
-    expect(result.accepted).toEqual(["doku"]);
-    expect(result.envMissing).toContain("DOKU_CLIENT_ID");
-    const warnings = result.conflicts.filter((c) => c.severity === "warning");
-    expect(warnings.some((w) => w.type === "env-missing")).toBe(true);
-  });
-});
-
-describe("compose() — table collision with target state", () => {
-  it("blocks when slice declares a table already in convexTablesExisting", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["doku_orders"] },
-      },
-    ]);
-    const result = compose(
-      {
-        state: { auth: "convex", convexTablesExisting: ["doku_orders"] },
-        desired: ["doku"],
-      },
-      contracts,
-    );
-    expect(result.accepted).toEqual([]);
-    expect(result.rejected[0].reasons.map((r) => r.type)).toContain(
-      "table-collision",
-    );
-  });
-});
-
-describe("compose() — rbacToCreate aggregation", () => {
-  it("collects rbac perms not already in target", () => {
-    const contracts = makeContracts([
-      {
-        id: "convex-auth",
-        version: "0.1.0",
-        requires: {
-          auth: "convex",
-          rbac: ["auth.sign-in", "auth.sign-out"],
-        },
-        provides: {},
-      },
-    ]);
-    const result = compose(
-      {
-        state: { auth: "convex", rbacRolesExisting: ["auth.sign-in"] },
-        desired: ["convex-auth"],
-      },
-      contracts,
-    );
-    expect(result.accepted).toEqual(["convex-auth"]);
-    expect(result.rbacToCreate).toEqual(["auth.sign-out"]);
-  });
-});
-
-// ─── v2 — arbitration by dependers ──────────────────────────────────────────
-
-describe("compose() — arbitration: most-dependers wins", () => {
-  it("two slices conflict, A has more dependers than B → A accepted, B rejected", () => {
-    // a is pulled in as transitive dep by `client1` and `client2`; b has zero
-    // dependers. They conflict on a shared table → a wins.
-    const contracts = makeContracts([
-      {
-        id: "a",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["shared_table"] },
-      },
-      {
-        id: "b",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["shared_table"] },
-      },
-      {
-        id: "client1",
-        version: "0.1.0",
-        requires: { auth: "convex", deps: ["a"] },
-        provides: {},
-      },
-      {
-        id: "client2",
-        version: "0.1.0",
-        requires: { auth: "convex", deps: ["a"] },
-        provides: {},
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["a", "b", "client1", "client2"] },
-      contracts,
-    );
-    expect(result.accepted).toContain("a");
-    expect(result.accepted).toContain("client1");
-    expect(result.accepted).toContain("client2");
-    expect(result.rejected.map((r) => r.slug)).toEqual(["b"]);
-    expect(result.arbitrations).toBeDefined();
-    expect(result.arbitrations[0].winner).toBe("a");
-    expect(result.arbitrations[0].loser).toBe("b");
-    expect(result.arbitrations[0].reason).toMatch(/dependers/);
-  });
-});
-
-describe("compose() — arbitration: alphabetical tiebreak", () => {
-  it("equal dependers → drop lex-later slug", () => {
-    const contracts = makeContracts([
-      {
-        id: "alpha",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["t"] },
-      },
-      {
-        id: "zeta",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["t"] },
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["alpha", "zeta"] },
-      contracts,
-    );
-    expect(result.accepted).toEqual(["alpha"]);
-    expect(result.rejected.map((r) => r.slug)).toEqual(["zeta"]);
-    expect(result.arbitrations[0].reason).toMatch(/alphabetical/);
-  });
-});
-
-describe("compose() — arbitration: both installed", () => {
-  it("both slices already installed and in conflict → kept with warning, no arbitration drop", () => {
-    const contracts = makeContracts([
-      {
-        id: "a",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["t"] },
-      },
-      {
-        id: "b",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["t"] },
-      },
-    ]);
-    const result = compose(
-      {
-        state: { auth: "convex", slicesInstalled: ["a", "b"] },
-        desired: ["a", "b"],
-      },
-      contracts,
-    );
-    expect(result.accepted.sort()).toEqual(["a", "b"]);
-    expect(result.rejected).toEqual([]);
-    expect(result.arbitrations).toBeUndefined();
-    const both = result.conflicts.filter((c) => c.type === "both-installed-conflict");
-    expect(both.length).toBeGreaterThan(0);
-    expect(both[0].severity).toBe("warning");
-    expect(result.notes?.a).toBe("both-installed-conflict");
-    expect(result.notes?.b).toBe("both-installed-conflict");
-  });
-});
-
-// ─── v2 — uncontracted slices ───────────────────────────────────────────────
-
-describe("compose() — uncontracted slice (default allowUnknownSlices=true)", () => {
-  it("desired slug with no contract → accepted with uncontracted warning", () => {
-    const result = compose(
-      { state: {}, desired: ["nonexistent-slice"] },
-      makeContracts([]),
-    );
-    expect(result.accepted).toEqual(["nonexistent-slice"]);
-    expect(result.rejected).toEqual([]);
-    const warn = result.conflicts.find((c) => c.type === "uncontracted");
-    expect(warn).toBeDefined();
-    expect(warn.severity).toBe("warning");
-    expect(result.notes?.["nonexistent-slice"]).toBe("uncontracted");
-  });
-
-  it("strict mode (allowUnknownSlices: false) flips uncontracted to blocker missing-dep", () => {
-    const result = compose(
-      { state: { allowUnknownSlices: false }, desired: ["nonexistent-slice"] },
-      makeContracts([]),
-    );
-    expect(result.accepted).toEqual([]);
-    expect(result.rejected.map((r) => r.slug)).toEqual(["nonexistent-slice"]);
-    const blocker = result.conflicts.find((c) => c.type === "missing-dep");
-    expect(blocker?.severity).toBe("blocker");
-  });
-});
-
-// ─── v2 — cycle path printing ───────────────────────────────────────────────
-
-describe("compose() — cycle detection prints full path", () => {
-  it("a → b → c → a throws with full cycle in message", () => {
-    const contracts = makeContracts([
-      { id: "a", version: "0.1.0", requires: { deps: ["b"] }, provides: {} },
-      { id: "b", version: "0.1.0", requires: { deps: ["c"] }, provides: {} },
-      { id: "c", version: "0.1.0", requires: { deps: ["a"] }, provides: {} },
-    ]);
-    expect(() => compose({ state: {}, desired: ["a"] }, contracts)).toThrowError(
-      /dependency cycle detected: a → b → c → a/,
-    );
-  });
-});
-
-// ─── v2 — strict mode escalates warnings ────────────────────────────────────
-
-describe("compose() — strict mode flips env-missing warning to blocker", () => {
-  // The solver itself doesn't auto-elevate severity (that's a CLI concern),
-  // but strict-mode state propagation must still surface env-missing so the
-  // CLI wrapper can re-classify. The CLI test (hand-test) covers elevation.
-  it("strict mode still surfaces env-missing — CLI elevates to blocker", () => {
-    const contracts = makeContracts([
-      {
-        id: "doku",
-        version: "0.1.0",
-        requires: { auth: "convex", env: ["DOKU_CLIENT_ID"] },
-        provides: {},
-      },
-    ]);
-    const result = compose(
-      {
-        state: { auth: "convex", envExisting: [], allowUnknownSlices: false },
-        desired: ["doku"],
-      },
-      contracts,
-    );
-    // The slice itself has a registered contract — strict doesn't block it.
-    expect(result.accepted).toEqual(["doku"]);
-    // env-missing is still a warning at the solver layer; CLI will elevate it
-    // when --strict is set.
-    const envWarn = result.conflicts.find((c) => c.type === "env-missing");
-    expect(envWarn).toBeDefined();
-    expect(envWarn.severity).toBe("warning");
-  });
-});
-
-// ─── v2 — pair-collision arbitration on plain table-collision ───────────────
-
-describe("compose() — table-collision arbitration vs reject-both", () => {
-  it("two new candidates with shared table → loser dropped, winner kept", () => {
-    const contracts = makeContracts([
-      {
-        id: "a",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["shared"] },
-      },
-      {
-        id: "b",
-        version: "0.1.0",
-        requires: { auth: "convex" },
-        provides: { tables: ["shared"] },
-      },
-    ]);
-    const result = compose(
-      { state: { auth: "convex" }, desired: ["a", "b"] },
-      contracts,
-    );
-    expect(result.accepted).toEqual(["a"]);
-    expect(result.rejected.map((r) => r.slug)).toEqual(["b"]);
-  });
-});

package/lib/merge3.test.mjs

@@ -1,199 +0,0 @@
-// merge3.test.mjs — vitest coverage for the 3-way merge engine.
-//
-// We exercise the file-element and contract-element branches plus the drift
-// arithmetic and the applyMerge guard.
-
-import { describe, it, expect } from "vitest";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import path from "node:path";
-
-import { merge3, applyMerge } from "./merge3.mjs";
-
-/** Tiny snapshot factory keeping the test setup compact. */
-function snap(files = {}, contract, slug = "demo-slice", version = "0.1.0") {
-  return { slug, version, files, contract };
-}
-
-describe("merge3 — file element diffs", () => {
-  it("all identical → all outcomes identical, drift 0", () => {
-    const s = snap({ "page.tsx": "A", "lib.ts": "B" });
-    const r = merge3({ base: s, kitab: s, consumer: s });
-    expect(r.summary.identical).toBe(2);
-    expect(r.summary.conflicts).toBe(0);
-    expect(r.driftAfterMerge).toBe(0);
-    expect(r.mergedSnapshot?.files).toEqual({ "page.tsx": "A", "lib.ts": "B" });
-  });
-
-  it("kitab adds file → auto-merged", () => {
-    const base = snap({ "page.tsx": "A" });
-    const kitab = snap({ "page.tsx": "A", "new.tsx": "N" });
-    const consumer = snap({ "page.tsx": "A" });
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "files/new.tsx");
-    expect(o?.kind).toBe("auto-merged");
-    expect(r.summary.autoMerged).toBe(1);
-    expect(r.mergedSnapshot?.files["new.tsx"]).toBe("N");
-  });
-
-  it("consumer adds file → consumer-wins-clean", () => {
-    const base = snap({ "page.tsx": "A" });
-    const kitab = snap({ "page.tsx": "A" });
-    const consumer = snap({ "page.tsx": "A", "local.tsx": "L" });
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "files/local.tsx");
-    expect(o?.kind).toBe("consumer-wins-clean");
-    expect(r.summary.consumerWinsClean).toBe(1);
-  });
-
-  it("same file changed in both → conflict", () => {
-    const base = snap({ "page.tsx": "A" });
-    const kitab = snap({ "page.tsx": "K" });
-    const consumer = snap({ "page.tsx": "C" });
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "files/page.tsx");
-    expect(o?.kind).toBe("conflict");
-    expect(o?.conflictHint).toMatch(/both kitab and consumer modified/);
-    expect(r.summary.conflicts).toBe(1);
-    expect(r.mergedSnapshot).toBeUndefined();
-  });
-
-  it("kitab removed, consumer modified → conflict", () => {
-    const base = snap({ "old.tsx": "A" });
-    const kitab = snap({});
-    const consumer = snap({ "old.tsx": "patched" });
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "files/old.tsx");
-    expect(o?.kind).toBe("conflict");
-    expect(o?.conflictHint).toMatch(/kitab removed/);
-  });
-});
-
-describe("merge3 — contract surface diffs", () => {
-  const baseContract = {
-    id: "demo-slice",
-    version: "0.1.0",
-    requires: { env: ["FOO"] },
-    provides: { tables: ["t_users"], routes: ["/x"] },
-  };
-
-  it("contract env added in kitab → auto-merged", () => {
-    const base = snap({}, baseContract);
-    const kitab = snap({}, { ...baseContract, requires: { env: ["FOO", "BAR"] } });
-    const consumer = snap({}, baseContract);
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "contract.requires.env:BAR");
-    expect(o?.kind).toBe("auto-merged");
-    expect(r.mergedSnapshot?.contract?.requires?.env).toEqual(["BAR", "FOO"]);
-  });
-
-  it("contract env added in consumer → consumer-wins-clean", () => {
-    const base = snap({}, baseContract);
-    const kitab = snap({}, baseContract);
-    const consumer = snap({}, { ...baseContract, requires: { env: ["FOO", "LOCAL"] } });
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "contract.requires.env:LOCAL");
-    expect(o?.kind).toBe("consumer-wins-clean");
-  });
-
-  it("contract table removed in kitab, kept in consumer → conflict", () => {
-    const base = snap({}, baseContract);
-    const kitab = snap({}, { ...baseContract, provides: { tables: [], routes: ["/x"] } });
-    const consumer = snap({}, baseContract);
-    const r = merge3({ base, kitab, consumer });
-    const o = r.outcomes.find((x) => x.element === "contract.provides.tables:t_users");
-    expect(o?.kind).toBe("conflict");
-    expect(o?.conflictHint).toMatch(/kitab dropped/);
-  });
-});
-
-describe("merge3 — summary, drift, applyMerge", () => {
-  it("mixed: 2 auto-merge + 1 conflict + 3 identical → no mergedSnapshot", () => {
-    const base = snap({ a: "1", b: "2", c: "3", d: "4" });
-    // kitab: changes 'a' and adds 'e' (auto), modifies 'b' (consumer also touches → conflict)
-    const kitab = snap({ a: "1k", b: "2k", c: "3", d: "4", e: "E" });
-    // consumer: modifies 'b' independently. c,d untouched.
-    const consumer = snap({ a: "1", b: "2c", c: "3", d: "4" });
-    const r = merge3({ base, kitab, consumer });
-    expect(r.summary.autoMerged).toBe(2); // a and e
-    expect(r.summary.conflicts).toBe(1); // b
-    expect(r.summary.identical).toBe(2); // c, d
-    expect(r.mergedSnapshot).toBeUndefined();
-  });
-
-  it("driftAfterMerge math: 10 elements, 2 conflicts, 1 consumer-only → 30", () => {
-    // Construct 10 file elements with the exact mix.
-    const baseFiles = {};
-    const kitabFiles = {};
-    const consumerFiles = {};
-    for (let i = 0; i < 7; i++) {
-      // 7 identical
-      baseFiles[`i${i}`] = "x";
-      kitabFiles[`i${i}`] = "x";
-      consumerFiles[`i${i}`] = "x";
-    }
-    // 2 conflicts (both sides edit)
-    for (let i = 0; i < 2; i++) {
-      baseFiles[`c${i}`] = "b";
-      kitabFiles[`c${i}`] = "k";
-      consumerFiles[`c${i}`] = "c";
-    }
-    // 1 consumer-only edit
-    baseFiles["uo"] = "b";
-    kitabFiles["uo"] = "b";
-    consumerFiles["uo"] = "consumer-edit";
-
-    const r = merge3({
-      base: snap(baseFiles),
-      kitab: snap(kitabFiles),
-      consumer: snap(consumerFiles),
-    });
-    expect(r.outcomes.length).toBe(10);
-    expect(r.summary.conflicts).toBe(2);
-    expect(r.summary.consumerWinsClean).toBe(1);
-    expect(r.driftAfterMerge).toBe(30);
-  });
-
-  it("applyMerge throws on a report with conflicts", async () => {
-    const base = snap({ "a.tsx": "A" });
-    const kitab = snap({ "a.tsx": "K" });
-    const consumer = snap({ "a.tsx": "C" });
-    const r = merge3({ base, kitab, consumer });
-    await expect(applyMerge(r, "/tmp/should-not-write")).rejects.toThrow(
-      /refusing to apply/,
-    );
-  });
-
-  it("applyMerge writes merged files to target directory", async () => {
-    const dir = mkdtempSync(path.join(tmpdir(), "merge3-apply-"));
-    try {
-      const base = snap({ "page.tsx": "old" });
-      const kitab = snap({ "page.tsx": "new", "added.tsx": "X" });
-      const consumer = snap({ "page.tsx": "old", "local.tsx": "L" });
-      const r = merge3({ base, kitab, consumer });
-      expect(r.summary.conflicts).toBe(0);
-      await applyMerge(r, dir);
-      expect(readFileSync(path.join(dir, "page.tsx"), "utf8")).toBe("new");
-      expect(readFileSync(path.join(dir, "added.tsx"), "utf8")).toBe("X");
-      expect(readFileSync(path.join(dir, "local.tsx"), "utf8")).toBe("L");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("kitab-only changes with no consumer drift → drift 0 after clean auto-merge", () => {
-    const base = snap({ "a": "1", "b": "2" });
-    const kitab = snap({ "a": "1-new", "b": "2", "c": "3" });
-    const consumer = snap({ "a": "1", "b": "2" });
-    const r = merge3({ base, kitab, consumer });
-    expect(r.driftAfterMerge).toBe(0);
-    expect(r.summary.autoMerged).toBe(2);
-    expect(r.mergedSnapshot).toBeDefined();
-  });
-
-  it("rejects mismatched slugs across snapshots", () => {
-    const a = snap({}, undefined, "alpha");
-    const b = snap({}, undefined, "beta");
-    expect(() => merge3({ base: a, kitab: b, consumer: a })).toThrow(/slug mismatch/);
-  });
-});

package/lib/migration-plan.test.mjs

@@ -1,243 +0,0 @@
-// migration-plan.test.mjs — vitest coverage for the Phase E migration planner.
-
-import { describe, it, expect } from "vitest";
-
-import { diffContracts, planMigration } from "./migration-plan.mjs";
-
-/** Tiny factory so each test only declares the bits it cares about. */
-function makeContract(over = {}) {
-  return {
-    id: "demo",
-    version: "0.1.0",
-    requires: { auth: "convex", env: [], rbac: [] },
-    provides: { tables: [], routes: [] },
-    ...over,
-    requires: { auth: "convex", env: [], rbac: [], ...(over.requires ?? {}) },
-    provides: { tables: [], routes: [], ...(over.provides ?? {}) },
-  };
-}
-
-describe("diffContracts", () => {
-  it("identical contracts produce an empty diff", () => {
-    const c = makeContract({ provides: { tables: ["demo_a"] } });
-    const d = diffContracts(c, c);
-    expect(d.added).toEqual({});
-    expect(d.removed).toEqual({});
-    expect(d.renamed).toEqual({});
-  });
-
-  it("detects added tables", () => {
-    const from = makeContract({ provides: { tables: ["demo_a"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["demo_a", "demo_b"] },
-    });
-    const d = diffContracts(from, to);
-    expect(d.added.tables).toEqual(["demo_b"]);
-    expect(d.removed).toEqual({});
-  });
-
-  it("rename detection requires the migrationFrom marker", () => {
-    const from = makeContract({ provides: { tables: ["old_x"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["new_x"] },
-      // No migrationFrom — must NOT pair up.
-    });
-    const d = diffContracts(from, to);
-    expect(d.renamed.tables).toBeUndefined();
-    expect(d.added.tables).toEqual(["new_x"]);
-    expect(d.removed.tables).toEqual(["old_x"]);
-  });
-
-  it("pairs renames when migrationFrom is set", () => {
-    const from = makeContract({ provides: { tables: ["old_x"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["new_x"] },
-      migrationFrom: { "0.1.0": "rename-2026-05" },
-    });
-    const d = diffContracts(from, to);
-    expect(d.renamed.tables).toEqual([{ from: "old_x", to: "new_x" }]);
-    expect(d.added).toEqual({});
-    expect(d.removed).toEqual({});
-  });
-});
-
-describe("planMigration", () => {
-  it("no-diff (same contract) → empty plan", () => {
-    const c = makeContract({ provides: { tables: ["demo_a"] } });
-    const plan = planMigration(diffContracts(c, c));
-    expect(plan.steps).toEqual([]);
-    expect(plan.summary.totalSteps).toBe(0);
-    expect(plan.summary.highRisk).toBe(0);
-    expect(plan.summary.irreversible).toBe(0);
-    expect(plan.warnings).toEqual([]);
-  });
-
-  it("add 1 table → 1 low-risk reversible step", () => {
-    const from = makeContract({ provides: { tables: ["demo_a"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["demo_a", "demo_b"] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    expect(plan.steps).toHaveLength(1);
-    const step = plan.steps[0];
-    expect(step.kind).toBe("convex-schema-add-table");
-    expect(step.risk).toBe("low");
-    expect(step.reversible).toBe(true);
-    expect(step.artifacts.convexSchema).toContain("demo_b");
-    expect(plan.summary.highRisk).toBe(0);
-  });
-
-  it("drop 1 table → 1 high-risk irreversible step + warning", () => {
-    const from = makeContract({ provides: { tables: ["demo_a"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: [] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    expect(plan.steps).toHaveLength(1);
-    const step = plan.steps[0];
-    expect(step.kind).toBe("convex-schema-drop-table");
-    expect(step.risk).toBe("high");
-    expect(step.reversible).toBe(false);
-    expect(step.artifacts.convexMigration).toContain("demo_a");
-    expect(plan.warnings.length).toBe(1);
-    expect(plan.warnings[0]).toMatch(/irreversible/i);
-    expect(plan.summary.highRisk).toBe(1);
-    expect(plan.summary.irreversible).toBe(1);
-  });
-
-  it("rename detected → 1 rename step (medium risk, reversible)", () => {
-    const from = makeContract({ provides: { tables: ["old_x"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["new_x"] },
-      migrationFrom: { "0.1.0": "rename-2026-05" },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    expect(plan.steps).toHaveLength(1);
-    const step = plan.steps[0];
-    expect(step.kind).toBe("convex-schema-rename-table");
-    expect(step.risk).toBe("medium");
-    expect(step.reversible).toBe(true);
-    expect(step.artifacts.convexMigration).toContain("old_x");
-    expect(step.artifacts.convexMigration).toContain("new_x");
-    expect(plan.summary.highRisk).toBe(0);
-    expect(plan.summary.irreversible).toBe(0);
-  });
-
-  it("multiple env adds emit env-add steps with envExample artifacts", () => {
-    const from = makeContract({ requires: { env: ["A"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      requires: { env: ["A", "B", "C"] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    const envSteps = plan.steps.filter((s) => s.kind === "env-add");
-    expect(envSteps).toHaveLength(2);
-    for (const s of envSteps) {
-      expect(s.artifacts.envExample).toBeDefined();
-      expect(s.risk).toBe("low");
-      expect(s.reversible).toBe(true);
-    }
-  });
-
-  it("rbac add emits step with rbacPatch artifact", () => {
-    const from = makeContract({ requires: { rbac: ["payment.refund"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      requires: { rbac: ["payment.refund", "payment.webhook-process"] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    const rbac = plan.steps.find((s) => s.kind === "rbac-add-permission");
-    expect(rbac).toBeDefined();
-    expect(rbac.artifacts.rbacPatch).toContain("payment.webhook-process");
-  });
-
-  it("mixed: 2 added + 1 dropped table → 3 steps + correct summary", () => {
-    const from = makeContract({ provides: { tables: ["a", "old"] } });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["a", "b", "c"] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    expect(plan.summary.totalSteps).toBe(3);
-    expect(plan.summary.highRisk).toBe(1); // the drop
-    expect(plan.summary.irreversible).toBe(1);
-    const kinds = plan.steps.map((s) => s.kind).sort();
-    expect(kinds).toEqual([
-      "convex-schema-add-table",
-      "convex-schema-add-table",
-      "convex-schema-drop-table",
-    ]);
-  });
-
-  it("summary counts match drops (highRisk + irreversible)", () => {
-    const from = makeContract({
-      provides: { tables: ["x", "y", "z"] },
-    });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: [] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    expect(plan.summary.totalSteps).toBe(3);
-    expect(plan.summary.highRisk).toBe(3);
-    expect(plan.summary.irreversible).toBe(3);
-    expect(plan.warnings.length).toBe(3);
-  });
-
-  it("step ids are unique + ordered (adds precede drops)", () => {
-    const from = makeContract({
-      provides: { tables: ["drop_me"] },
-    });
-    const to = makeContract({
-      version: "0.2.0",
-      provides: { tables: ["added_a", "added_b"] },
-    });
-    const plan = planMigration(diffContracts(from, to));
-    const ids = plan.steps.map((s) => s.id);
-    expect(new Set(ids).size).toBe(ids.length);
-    const kinds = plan.steps.map((s) => s.kind);
-    const firstAdd = kinds.indexOf("convex-schema-add-table");
-    const firstDrop = kinds.indexOf("convex-schema-drop-table");
-    expect(firstAdd).toBeGreaterThanOrEqual(0);
-    expect(firstDrop).toBeGreaterThanOrEqual(0);
-    expect(firstAdd).toBeLessThan(firstDrop);
-  });
-
-  it("doku rename smoke: paymentOrders/paymentWebhookEvents → doku_orders/doku_webhook_events", () => {
-    const from = {
-      id: "doku-payment",
-      version: "0.9.0",
-      requires: { auth: "convex", env: [], rbac: [] },
-      provides: {
-        tables: ["paymentOrders", "paymentWebhookEvents"],
-      },
-    };
-    const to = {
-      id: "doku-payment",
-      version: "0.1.0",
-      requires: { auth: "convex", env: [], rbac: [] },
-      provides: {
-        tables: ["doku_orders", "doku_webhook_events"],
-      },
-      migrationFrom: { "0.9.0": "namespace-rename-2026-05" },
-    };
-    const plan = planMigration(diffContracts(from, to));
-    const renameKinds = plan.steps.filter(
-      (s) => s.kind === "convex-schema-rename-table",
-    );
-    expect(renameKinds).toHaveLength(2);
-    const drops = plan.steps.filter(
-      (s) => s.kind === "convex-schema-drop-table",
-    );
-    expect(drops).toHaveLength(0);
-    // Reverse mapping present in artifacts
-    expect(renameKinds[0].artifacts.convexMigration).toContain("paymentOrders");
-    expect(renameKinds[0].artifacts.convexMigration).toContain("doku_orders");
-  });
-});