rahman-resources 1.4.0 → 1.6.0

package/lib/contract.ts

@@ -1,201 +1,35 @@
 /**
- * Slice Composition Compiler — Phase A: Typed contract DSL.
+ * Slice Composition Compiler — Phase A: typed contract DSL.
  *
- * This module exposes the {@link defineSliceContract} factory plus the
- * supporting type vocabulary. A slice contract is the typed, code-shaped
- * sibling of the legacy `slice.manifest.json`. Both coexist during the
- * migration; new slices should ship a contract while keeping the JSON
- * manifest for back-compat with the npm CLI manifest pipeline.
+ * Re-exports the type vocabulary from {@link ./contract-types} and the
+ * runtime-checked {@link defineSliceContract} factory. The actual invariant
+ * blocks live in {@link ./contract-validate} so each module stays ≤200 LOC.
  *
  * @module packages/cli/lib/contract
  */
 
-// ---------------------------------------------------------------------------
-// Primitive vocabulary
-// ---------------------------------------------------------------------------
-
-/**
- * Identity providers the kitab knows about.
- *
- * The kitab itself only ships `convex` (see CLAUDE.md "NO Clerk"). The other
- * literals exist so consumer projects forking the contract DSL can target
- * a different provider without losing type safety.
- */
-export type AuthProvider = "convex" | "clerk" | "next-auth" | "none";
-
-/**
- * RBAC permission string in `domain.action` shape — e.g. `"payment.refund"`.
- *
- * Enforced at compile time via a template-literal type, and at runtime by
- * {@link defineSliceContract}. The runtime check rejects empty segments and
- * any value with more than one dot.
- */
-export type RBACPermission = `${string}.${string}`;
-
-// ---------------------------------------------------------------------------
-// `requires` block
-// ---------------------------------------------------------------------------
-
-/**
- * Convex table-namespace declaration for a slice.
- *
- * Every Convex table the slice owns must start with {@link prefix}. Operator
- * decision 2026-05-12 mandates per-provider prefixes (e.g. `doku_`, `midtrans_`)
- * to prevent the historical `paymentOrders` collision between sibling
- * payment slices.
- */
-export interface ConvexNamespace {
-  /** Required prefix — e.g. `"doku_"`. Must match `/^[a-z][a-z0-9_]*_$/`. */
-  prefix: string;
-  /** Tables this slice declares. Every entry must start with {@link prefix}. */
-  tables: string[];
-}
-
-/**
- * Capabilities a slice REQUIRES the host application to satisfy before it
- * can be composed in.
- */
-export interface SliceContractRequires {
-  /** Identity provider the slice expects. Omit when slice is auth-agnostic. */
-  auth?: AuthProvider;
-  /** RBAC permission strings the slice will call `requirePermission(...)` with. */
-  rbac?: RBACPermission[];
-  /** Env var names (server scope). Validators read this for `.env.example` drift checks. */
-  env?: string[];
-  /** Convex table namespace the slice owns. */
-  convex?: ConvexNamespace;
-  /** Other slice ids that must be installed first. */
-  deps?: string[];
-}
-
-// ---------------------------------------------------------------------------
-// `provides` block
-// ---------------------------------------------------------------------------
-
-/**
- * Surface area a slice exposes to the host application + downstream slices.
- *
- * All arrays are optional. Empty / omitted means "nothing exposed in that
- * category". The keys must match the literal segment of a conflict path —
- * `tables`, `routes`, `hooks`, `events`, `components`.
- */
-export interface SliceContractProvides {
-  /** Next.js route paths the slice mounts — e.g. `["/sign-in", "/sign-out"]`. */
-  routes?: string[];
-  /** Public hook export names — e.g. `["useDokuCheckout"]`. */
-  hooks?: string[];
-  /** Convex table names. Must match `requires.convex.prefix` if that is set. */
-  tables?: string[];
-  /** Event-bus event names the slice emits — e.g. `["payment.captured"]`. */
-  events?: string[];
-  /** Public component exports — e.g. `["DokuCheckoutButton"]`. */
-  components?: string[];
-}
-
-// ---------------------------------------------------------------------------
-// `bidir` block — Wave N+3 (Bidirectional Sync Detection Layer)
-// ---------------------------------------------------------------------------
-
-/**
- * How the kitab treats sync between this slice and consumer copies.
- *
- * - `auto-pr`: when `rr scan-consumers` sees an `up-needed` verdict on a
- *   consumer's `.kitab.json`, the operator workflow auto-opens a PR against
- *   the kitab. Reserved for slices with strict generalisation gates.
- * - `notify`: surface in the scan report; no auto-action.
- * - `manual`: default — operator picks up via `/rr-prep` + `/rr-send`.
- * - `frozen`: kitab refuses both UP and DOWN sync. Lock for retired slices.
- */
-export type SliceSyncPolicy = "auto-pr" | "notify" | "manual" | "frozen";
-
-/**
- * Generalisation level a consumer-side `.kitab.json` MUST claim before
- * `rr-send` accepts the push back into the kitab.
- *
- * - `portable`: no consumer-specific business terms baked in. UP-sync allowed.
- * - `needs-adapter`: requires a thin adapter wired by the consumer; UP-sync
- *   blocked until blockers are addressed (or the contract drops the slice
- *   to `consumer-locked`).
- * - `consumer-locked`: contains business-specific logic that cannot be
- *   generalised. Only DOWN-sync allowed.
- */
-export type GeneralizationLevel =
-  | "portable"
-  | "needs-adapter"
-  | "consumer-locked";
-
-/**
- * Generalisation contract — what the audit-bp `forbiddenTerms` rule scans
- * for, and which props the consumer MUST inject.
- */
-export interface SliceGeneralization {
-  level: GeneralizationLevel;
-  /**
-   * Identifiers / business terms that MUST NOT appear in the slice source
-   * tree. Audit-bp scans .ts/.tsx files. Empty when the slice is generic.
-   */
-  forbiddenTerms?: string[];
-  /**
-   * Props the consumer must inject for the slice to remain portable —
-   * e.g. `["basePath", "labels", "permission"]`.
-   */
-  requiredProps?: string[];
-}
-
-/**
- * Bidirectional sync block. Optional, additive — slices without it default to
- * `{ syncPolicy: "manual", generalization: { level: "portable" } }` for
- * legacy compatibility with Wave N+1 contracts.
- */
-export interface SliceBidirContract {
-  syncPolicy: SliceSyncPolicy;
-  generalization: SliceGeneralization;
-}
-
-// ---------------------------------------------------------------------------
-// Top-level contract
-// ---------------------------------------------------------------------------
-
-/**
- * The full Phase-A slice contract shape.
- *
- * @see {@link defineSliceContract} for the runtime-checked constructor.
- */
-export interface SliceContract {
-  /** Slice slug — kebab-case, matches the folder name. */
-  id: string;
-  /** Semver — `MAJOR.MINOR.PATCH`, optional `-prerelease` and `+build`. */
-  version: string;
-  /** Host requirements. */
-  requires: SliceContractRequires;
-  /** Surface exposed to the host. */
-  provides: SliceContractProvides;
-  /**
-   * Known incompatibilities — `"<slug>:<provides-key>.<value>"`.
-   *
-   * Example: `"midtrans-payment:tables.paymentOrders"` declares that this
-   * slice collides with `midtrans-payment` over the `paymentOrders` table.
-   * The validator surfaces this as a P0 finding when both slices are
-   * composed into the same app.
-   */
-  conflicts?: string[];
-  /** Map of previous-version → migration script id. */
-  migrationFrom?: Record<string, string>;
-  /** Wave N+3 — bidirectional sync policy + generalisation gate. */
-  bidir?: SliceBidirContract;
-}
-
-// ---------------------------------------------------------------------------
-// Runtime regexes
-// ---------------------------------------------------------------------------
-
-const KEBAB_CASE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-// Plain semver — also tolerates pre-release + build metadata.
-const SEMVER =
-  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-const PREFIX = /^[a-z][a-z0-9_]*_$/;
-const CONFLICT = /^[a-z][a-z0-9-]*:(routes|hooks|tables|events|components)\.[A-Za-z0-9_\-\/]+$/;
-const PERMISSION = /^[^.]+\.[^.]+$/;
+import type { SliceContract } from "./contract-types";
+import {
+  validateHeader,
+  validateRbac,
+  validateConvex,
+  validateBidir,
+  validateConflicts,
+} from "./contract-validate";
+
+// Re-export the full type surface so existing imports keep working.
+export type {
+  AuthProvider,
+  RBACPermission,
+  ConvexNamespace,
+  SliceContractRequires,
+  SliceContractProvides,
+  SliceSyncPolicy,
+  GeneralizationLevel,
+  SliceGeneralization,
+  SliceBidirContract,
+  SliceContract,
+} from "./contract-types";
 
 // ---------------------------------------------------------------------------
 // Factory
@@ -225,132 +59,10 @@ const PERMISSION = /^[^.]+\.[^.]+$/;
  * @returns The exact same object reference, narrowed to {@link SliceContract}.
  */
 export function defineSliceContract(c: SliceContract): SliceContract {
-  if (!c || typeof c !== "object") {
-    throw new Error("defineSliceContract: expected an object, got " + typeof c);
-  }
-  if (typeof c.id !== "string" || !KEBAB_CASE.test(c.id)) {
-    throw new Error(`defineSliceContract: id "${String(c.id)}" must be kebab-case`);
-  }
-  if (typeof c.version !== "string" || !SEMVER.test(c.version)) {
-    throw new Error(`defineSliceContract(${c.id}): version "${String(c.version)}" is not semver`);
-  }
-  if (!c.requires || typeof c.requires !== "object") {
-    throw new Error(`defineSliceContract(${c.id}): requires must be an object`);
-  }
-  if (!c.provides || typeof c.provides !== "object") {
-    throw new Error(`defineSliceContract(${c.id}): provides must be an object`);
-  }
-
-  // RBAC
-  if (c.requires.rbac) {
-    if (!Array.isArray(c.requires.rbac)) {
-      throw new Error(`defineSliceContract(${c.id}): requires.rbac must be an array`);
-    }
-    for (const p of c.requires.rbac) {
-      if (typeof p !== "string" || !PERMISSION.test(p)) {
-        throw new Error(
-          `defineSliceContract(${c.id}): rbac entry "${String(p)}" must be "<domain>.<action>"`,
-        );
-      }
-    }
-  }
-
-  // Convex prefix invariants
-  const cx = c.requires.convex;
-  if (cx) {
-    if (typeof cx.prefix !== "string" || !PREFIX.test(cx.prefix)) {
-      throw new Error(
-        `defineSliceContract(${c.id}): convex.prefix "${String(cx.prefix)}" must match /^[a-z][a-z0-9_]*_$/`,
-      );
-    }
-    if (!Array.isArray(cx.tables)) {
-      throw new Error(`defineSliceContract(${c.id}): convex.tables must be an array`);
-    }
-    for (const t of cx.tables) {
-      if (typeof t !== "string" || !t.startsWith(cx.prefix)) {
-        throw new Error(
-          `defineSliceContract(${c.id}): convex.tables entry "${String(t)}" must start with prefix "${cx.prefix}"`,
-        );
-      }
-    }
-    if (Array.isArray(c.provides.tables)) {
-      for (const t of c.provides.tables) {
-        if (typeof t !== "string" || !t.startsWith(cx.prefix)) {
-          throw new Error(
-            `defineSliceContract(${c.id}): provides.tables entry "${String(t)}" must start with prefix "${cx.prefix}"`,
-          );
-        }
-      }
-    }
-  }
-
-  // bidir block — Wave N+3
-  if (c.bidir !== undefined) {
-    if (!c.bidir || typeof c.bidir !== "object") {
-      throw new Error(`defineSliceContract(${c.id}): bidir must be an object`);
-    }
-    const policies = ["auto-pr", "notify", "manual", "frozen"];
-    if (!policies.includes(c.bidir.syncPolicy)) {
-      throw new Error(
-        `defineSliceContract(${c.id}): bidir.syncPolicy "${String(c.bidir.syncPolicy)}" must be one of ${policies.join("|")}`,
-      );
-    }
-    if (!c.bidir.generalization || typeof c.bidir.generalization !== "object") {
-      throw new Error(
-        `defineSliceContract(${c.id}): bidir.generalization must be an object`,
-      );
-    }
-    const levels = ["portable", "needs-adapter", "consumer-locked"];
-    if (!levels.includes(c.bidir.generalization.level)) {
-      throw new Error(
-        `defineSliceContract(${c.id}): bidir.generalization.level "${String(c.bidir.generalization.level)}" must be one of ${levels.join("|")}`,
-      );
-    }
-    const ft = c.bidir.generalization.forbiddenTerms;
-    if (ft !== undefined) {
-      if (!Array.isArray(ft)) {
-        throw new Error(
-          `defineSliceContract(${c.id}): bidir.generalization.forbiddenTerms must be an array`,
-        );
-      }
-      for (const t of ft) {
-        if (typeof t !== "string" || t.length === 0) {
-          throw new Error(
-            `defineSliceContract(${c.id}): bidir.generalization.forbiddenTerms entries must be non-empty strings`,
-          );
-        }
-      }
-    }
-    const rp = c.bidir.generalization.requiredProps;
-    if (rp !== undefined) {
-      if (!Array.isArray(rp)) {
-        throw new Error(
-          `defineSliceContract(${c.id}): bidir.generalization.requiredProps must be an array`,
-        );
-      }
-      for (const p of rp) {
-        if (typeof p !== "string" || p.length === 0) {
-          throw new Error(
-            `defineSliceContract(${c.id}): bidir.generalization.requiredProps entries must be non-empty strings`,
-          );
-        }
-      }
-    }
-  }
-
-  // Conflicts
-  if (c.conflicts) {
-    if (!Array.isArray(c.conflicts)) {
-      throw new Error(`defineSliceContract(${c.id}): conflicts must be an array`);
-    }
-    for (const cf of c.conflicts) {
-      if (typeof cf !== "string" || !CONFLICT.test(cf)) {
-        throw new Error(
-          `defineSliceContract(${c.id}): conflicts entry "${String(cf)}" must match "<slug>:<routes|hooks|tables|events|components>.<value>"`,
-        );
-      }
-    }
-  }
-
+  validateHeader(c);
+  validateRbac(c);
+  validateConvex(c);
+  validateBidir(c);
+  validateConflicts(c);
   return c;
 }

package/lib/dna-graph.mjs

@@ -0,0 +1,53 @@
+// dna-graph.mjs — lineage graph builder.
+//
+// Extracted from dna.mjs. Reads all DNA files via `listAllDNA` and produces
+// a node/edge graph keyed by source / slice / consumer.
+
+import { listAllDNA } from "./dna.mjs";
+
+/** @returns {import("./dna").LineageGraph} */
+export function buildLineageGraph() {
+  const all = listAllDNA();
+  /** @type {Map<string, import("./dna").LineageGraphNode>} */
+  const nodes = new Map();
+  /** @type {import("./dna").LineageGraphEdge[]} */
+  const edges = [];
+
+  function addNode(id, type) {
+    if (!nodes.has(id)) nodes.set(id, { id, type });
+  }
+
+  for (const dna of all) {
+    const sliceId = `slice:${dna.id}`;
+    addNode(sliceId, "slice");
+
+    // lineage edges: source → slice
+    for (const entry of dna.lineage ?? []) {
+      const sourceId = `source:${entry.from}`;
+      addNode(sourceId, "source");
+      // If `to` looks like a different slice / kitab tag, prefer the slice node;
+      // otherwise treat `to` as the kitab itself and target the slice node.
+      const targetId = entry.to && entry.to.startsWith("kitab:") ? sliceId : sliceId;
+      edges.push({
+        from: sourceId,
+        to: targetId,
+        transforms: entry.transforms,
+        at: entry.at,
+      });
+    }
+
+    // consumer edges: slice → consumer
+    for (const [consumerName, adoption] of Object.entries(dna.consumers ?? {})) {
+      const consumerId = `consumer:${consumerName}`;
+      addNode(consumerId, "consumer");
+      edges.push({
+        from: sliceId,
+        to: consumerId,
+        transforms: [`drift:${adoption.drift_score}`, `v${adoption.version}`],
+        at: adoption.adopted_at,
+      });
+    }
+  }
+
+  return { nodes: [...nodes.values()], edges };
+}

package/lib/dna.mjs

@@ -14,6 +14,10 @@
 // at fs.promises — the consumers (CLI + MCP) are both single-shot processes
 // where async I/O adds noise without buying parallelism. The d.ts mirrors
 // this signature exactly.
+//
+// `buildLineageGraph` lives in dna-graph.mjs and is re-exported below so
+// existing imports (`import { buildLineageGraph } from "../lib/dna.mjs"`)
+// keep working.
 
 import {
   existsSync,
@@ -136,52 +140,7 @@ export function listAllDNA() {
   return out;
 }
 
-/** @returns {import("./dna").LineageGraph} */
-export function buildLineageGraph() {
-  const all = listAllDNA();
-  /** @type {Map<string, import("./dna").LineageGraphNode>} */
-  const nodes = new Map();
-  /** @type {import("./dna").LineageGraphEdge[]} */
-  const edges = [];
-
-  function addNode(id, type) {
-    if (!nodes.has(id)) nodes.set(id, { id, type });
-  }
-
-  for (const dna of all) {
-    const sliceId = `slice:${dna.id}`;
-    addNode(sliceId, "slice");
-
-    // lineage edges: source → slice
-    for (const entry of dna.lineage ?? []) {
-      const sourceId = `source:${entry.from}`;
-      addNode(sourceId, "source");
-      // If `to` looks like a different slice / kitab tag, prefer the slice node;
-      // otherwise treat `to` as the kitab itself and target the slice node.
-      const targetId = entry.to && entry.to.startsWith("kitab:") ? sliceId : sliceId;
-      edges.push({
-        from: sourceId,
-        to: targetId,
-        transforms: entry.transforms,
-        at: entry.at,
-      });
-    }
-
-    // consumer edges: slice → consumer
-    for (const [consumerName, adoption] of Object.entries(dna.consumers ?? {})) {
-      const consumerId = `consumer:${consumerName}`;
-      addNode(consumerId, "consumer");
-      edges.push({
-        from: sliceId,
-        to: consumerId,
-        transforms: [`drift:${adoption.drift_score}`, `v${adoption.version}`],
-        at: adoption.adopted_at,
-      });
-    }
-  }
-
-  return { nodes: [...nodes.values()], edges };
-}
+export { buildLineageGraph } from "./dna-graph.mjs";
 
 // ─── helpers ──────────────────────────────────────────────────────────────
 

package/lib/env-augment.mjs

@@ -0,0 +1,116 @@
+// env-augment.mjs — append slice env requirements to consumer .env.example.
+//
+// Invoked from `npx rr add <slice>` after slice files land. Idempotent:
+// re-running `add` does not duplicate entries. Never creates .env.example
+// (consumer may not want one); warns and skips instead. Never touches
+// .env.local (operator-only).
+//
+// Reads env requirements from the manifest entry passed in by the CLI
+// (already normalised from slice.json `deps.env` + contract `requires.env`
+// at sync time). Shape: `{ name, scope?, required?, description? }`.
+//
+// Contract: see CLAUDE.md "augmentConsumerEnv contract". Function ≤200 LOC.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import kleur from "kleur";
+
+/**
+ * @param {{ slug: string, env?: Array<{ name: string, scope?: string, required?: boolean, description?: string }> }} slice
+ * @param {string} target  absolute path to consumer project root
+ */
+export function augmentConsumerEnv(slice, target) {
+  const envList = Array.isArray(slice?.env) ? slice.env : [];
+  if (envList.length === 0) {
+    return;
+  }
+
+  const envFile = path.join(target, ".env.example");
+  if (!existsSync(envFile)) {
+    console.log(
+      kleur.yellow(
+        `  ⚠ .env.example not found in ${target} — skipping env augment.`,
+      ),
+    );
+    console.log(
+      kleur.dim(
+        `    Required env for ${slice.slug}: ${envList
+          .map((e) => prefixName(e))
+          .join(", ")}`,
+      ),
+    );
+    return;
+  }
+
+  const existing = readFileSync(envFile, "utf8");
+  const present = parseExistingNames(existing);
+
+  const missing = envList.filter((e) => !present.has(prefixName(e)));
+  if (missing.length === 0) {
+    console.log(kleur.dim(`  (no new env to add to .env.example)`));
+    return;
+  }
+
+  const block = renderBlock(slice.slug, missing);
+  const sep = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  writeFileSync(envFile, existing + sep + block, "utf8");
+
+  console.log(
+    kleur.green(
+      `  ✓ appended ${missing.length} env var(s) to .env.example`,
+    ),
+  );
+  for (const e of missing) {
+    console.log(
+      kleur.dim(
+        `    + ${prefixName(e)}${e.required ? "" : "  (optional)"}`,
+      ),
+    );
+  }
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+function prefixName(e) {
+  // `scope: "next-public"` means the consumer reads it via `process.env` on
+  // the client, so it needs the NEXT_PUBLIC_ prefix to be exposed.
+  return e.scope === "next-public" && !e.name.startsWith("NEXT_PUBLIC_")
+    ? `NEXT_PUBLIC_${e.name}`
+    : e.name;
+}
+
+function parseExistingNames(text) {
+  const set = new Set();
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    // Strip an optional `export ` prefix.
+    const lhs = line.slice(0, eq).replace(/^export\s+/, "").trim();
+    if (lhs) set.add(lhs);
+  }
+  return set;
+}
+
+function renderBlock(slug, entries) {
+  const lines = [];
+  lines.push("");
+  lines.push(`# ─── ${slug} ───`);
+  for (const e of entries) {
+    const name = prefixName(e);
+    const tag =
+      e.required === false ? "optional" : e.required ? "required" : null;
+    const meta = [e.scope, tag].filter(Boolean).join(", ");
+    if (e.description) {
+      lines.push(`# ${e.description}${meta ? `  (${meta})` : ""}`);
+    } else if (meta) {
+      lines.push(`# ${meta}`);
+    }
+    // Secrets get an empty placeholder — never a fake value.
+    lines.push(`${name}=`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}