rahman-resources 0.9.2 → 0.12.0

package/lib/contract.ts

@@ -0,0 +1,240 @@
+/**
+ * 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.
+ *
+ * @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[];
+}
+
+// ---------------------------------------------------------------------------
+// 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>;
+}
+
+// ---------------------------------------------------------------------------
+// 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 = /^[^.]+\.[^.]+$/;
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Identity factory that runtime-validates a {@link SliceContract}.
+ *
+ * Throws a descriptive {@link Error} when the contract violates any of the
+ * Phase-A invariants:
+ *
+ * - `id` must be kebab-case (`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`).
+ * - `version` must be semver.
+ * - When `requires.convex` is set, every `requires.convex.tables[i]` must
+ *   start with `requires.convex.prefix`.
+ * - When `requires.convex` is set and `provides.tables` is non-empty, every
+ *   `provides.tables[i]` must start with `requires.convex.prefix`.
+ * - Each `conflicts[i]` must match
+ *   `<kebab-slug>:<routes|hooks|tables|events|components>.<value>`.
+ * - Each `requires.rbac[i]` must be a `domain.action` pair (exactly one dot,
+ *   non-empty halves).
+ *
+ * Returns the contract object unchanged so callers can write
+ * `export const contract = defineSliceContract({ ... })`.
+ *
+ * @param c The contract to validate.
+ * @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}"`,
+          );
+        }
+      }
+    }
+  }
+
+  // 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>"`,
+        );
+      }
+    }
+  }
+
+  return c;
+}

package/lib/dna.d.ts

@@ -0,0 +1,65 @@
+// Type definitions for the slice-DNA lineage tracker.
+// Runtime in dna.mjs; this file is hand-authored types for tsc/ide consumers.
+
+export interface LineageEntry {
+  /** "<sourceRepo>:<path>" — e.g. "superspace:frontend/slices/auth". */
+  from: string;
+  /** Optional destination, e.g. "kitab:0.7.0" or "careerpack:adopt". */
+  to?: string;
+  /** ISO 8601 UTC timestamp. */
+  at: string;
+  /** Transform tags applied during the harvest (e.g. "alias-rewrite", "clerk-strip"). */
+  transforms: string[];
+  /** Human/agent that triggered the lineage entry. */
+  actor?: string;
+}
+
+export interface ConsumerAdoption {
+  adopted_at: string;
+  version: string;
+  /** 0-100, computed from file diff between kitab and consumer. */
+  drift_score: number;
+  last_synced_at?: string;
+}
+
+export interface SliceDNA {
+  /** Slice slug, kebab-case. */
+  id: string;
+  created_at: string;
+  lineage: LineageEntry[];
+  /** Keyed by consumer name (notion, superspace, careerpack, content, rahmanef, cescadesigns). */
+  consumers: Record<string, ConsumerAdoption>;
+}
+
+export interface LineageGraphNode {
+  id: string;
+  type: "slice" | "consumer" | "source";
+}
+
+export interface LineageGraphEdge {
+  from: string;
+  to: string;
+  transforms?: string[];
+  at: string;
+}
+
+export interface LineageGraph {
+  nodes: LineageGraphNode[];
+  edges: LineageGraphEdge[];
+}
+
+export function readDNA(slug: string): SliceDNA | null;
+export function writeDNA(dna: SliceDNA): void;
+export function appendLineage(slug: string, entry: LineageEntry): SliceDNA;
+export function upsertConsumerAdoption(
+  slug: string,
+  consumer: string,
+  adoption: ConsumerAdoption,
+): SliceDNA;
+export function listAllDNA(): SliceDNA[];
+export function buildLineageGraph(): LineageGraph;
+
+/** Resolve the absolute path to `.kitab/lineage/`. */
+export function getLineageDir(): string;
+/** Resolve the absolute path to `.kitab/lineage/<slug>.dna.json`. */
+export function getDNAPath(slug: string): string;

package/lib/dna.mjs

@@ -0,0 +1,239 @@
+// dna.mjs — slice-DNA lineage tracker (Phase C of the Slice Composition Compiler).
+//
+// Reader/writer for `.kitab/lineage/<slug>.dna.json`. Each DNA file records
+// where a slice came from (lineage[]) and which consumers later adopted it
+// (consumers{}). Types live in dna.d.ts.
+//
+// Runtime contract:
+//   - .kitab/lineage/ lives at the kitab repo root (resolved by walking up
+//     from this file). If the directory doesn't exist, write* creates it.
+//   - Files are pretty-printed JSON, trailing newline. Idempotent re-writes
+//     keep diffs clean.
+//
+// The functions here are deliberately synchronous despite the spec hinting
+// 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.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Walk up from packages/cli/lib/ to the kitab repo root (the directory
+// containing `packages/`). Anchors the .kitab/lineage path regardless of
+// where the CLI is invoked from.
+function findRepoRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(path.join(dir, "packages")) && existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback: assume cwd is the repo root.
+  return process.cwd();
+}
+
+const REPO_ROOT = findRepoRoot();
+
+export function getLineageDir() {
+  return path.join(REPO_ROOT, ".kitab", "lineage");
+}
+
+export function getDNAPath(slug) {
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(slug)) {
+    throw new Error(`dna: invalid slug "${slug}" — must be kebab-case`);
+  }
+  return path.join(getLineageDir(), `${slug}.dna.json`);
+}
+
+function ensureDir() {
+  const d = getLineageDir();
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+}
+
+/** @returns {import("./dna").SliceDNA | null} */
+export function readDNA(slug) {
+  const p = getDNAPath(slug);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    return normalizeDNA(parsed, slug);
+  } catch (err) {
+    throw new Error(`dna: failed to parse ${p}: ${err.message ?? err}`);
+  }
+}
+
+/** @param {import("./dna").SliceDNA} dna */
+export function writeDNA(dna) {
+  if (!dna || typeof dna !== "object" || !dna.id) {
+    throw new Error("dna.writeDNA: dna.id is required");
+  }
+  ensureDir();
+  const normalized = normalizeDNA(dna, dna.id);
+  const p = getDNAPath(normalized.id);
+  writeFileSync(p, JSON.stringify(normalized, null, 2) + "\n");
+}
+
+/** @param {string} slug @param {import("./dna").LineageEntry} entry */
+export function appendLineage(slug, entry) {
+  const existing = readDNA(slug) ?? newDNA(slug);
+  if (!entry || typeof entry !== "object" || !entry.from || !entry.at) {
+    throw new Error("dna.appendLineage: entry.from and entry.at are required");
+  }
+  existing.lineage.push({
+    from: entry.from,
+    to: entry.to,
+    at: entry.at,
+    transforms: Array.isArray(entry.transforms) ? entry.transforms : [],
+    actor: entry.actor,
+  });
+  writeDNA(existing);
+  return existing;
+}
+
+/** @param {string} slug @param {string} consumer @param {import("./dna").ConsumerAdoption} adoption */
+export function upsertConsumerAdoption(slug, consumer, adoption) {
+  if (!consumer) throw new Error("dna.upsertConsumerAdoption: consumer is required");
+  if (!adoption || typeof adoption !== "object") {
+    throw new Error("dna.upsertConsumerAdoption: adoption object is required");
+  }
+  const existing = readDNA(slug) ?? newDNA(slug);
+  existing.consumers[consumer] = {
+    adopted_at: adoption.adopted_at,
+    version: adoption.version,
+    drift_score: clampDrift(adoption.drift_score),
+    last_synced_at: adoption.last_synced_at,
+  };
+  writeDNA(existing);
+  return existing;
+}
+
+/** @returns {import("./dna").SliceDNA[]} */
+export function listAllDNA() {
+  const d = getLineageDir();
+  if (!existsSync(d)) return [];
+  const files = readdirSync(d).filter((f) => f.endsWith(".dna.json"));
+  const out = [];
+  for (const f of files) {
+    const slug = f.replace(/\.dna\.json$/, "");
+    const dna = readDNA(slug);
+    if (dna) out.push(dna);
+  }
+  // Stable ordering — alphabetical by slug.
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  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 };
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+/** Build a fresh DNA shell for a slug. */
+function newDNA(slug) {
+  return {
+    id: slug,
+    created_at: new Date().toISOString(),
+    lineage: [],
+    consumers: {},
+  };
+}
+
+/** Fill in defaults + drop unknown fields. */
+function normalizeDNA(raw, slug) {
+  const out = {
+    id: typeof raw.id === "string" ? raw.id : slug,
+    created_at:
+      typeof raw.created_at === "string" ? raw.created_at : new Date().toISOString(),
+    lineage: [],
+    consumers: {},
+  };
+  if (Array.isArray(raw.lineage)) {
+    for (const e of raw.lineage) {
+      if (!e || typeof e !== "object" || !e.from || !e.at) continue;
+      out.lineage.push({
+        from: String(e.from),
+        to: e.to ? String(e.to) : undefined,
+        at: String(e.at),
+        transforms: Array.isArray(e.transforms) ? e.transforms.map(String) : [],
+        actor: e.actor ? String(e.actor) : undefined,
+      });
+    }
+  }
+  if (raw.consumers && typeof raw.consumers === "object") {
+    for (const [k, v] of Object.entries(raw.consumers)) {
+      if (!v || typeof v !== "object") continue;
+      out.consumers[k] = {
+        adopted_at: String(v.adopted_at ?? ""),
+        version: String(v.version ?? "0.0.0"),
+        drift_score: clampDrift(v.drift_score),
+        last_synced_at: v.last_synced_at ? String(v.last_synced_at) : undefined,
+      };
+    }
+  }
+  return out;
+}
+
+function clampDrift(n) {
+  const x = Number(n);
+  if (!Number.isFinite(x)) return 0;
+  if (x < 0) return 0;
+  if (x > 100) return 100;
+  return Math.round(x);
+}