rahman-resources 0.12.0 → 0.13.0

package/bin/cli.js

@@ -33,6 +33,7 @@ import { runGraph } from "./graph.mjs";
 import { runCompose, preflight as composePreflight } from "./compose.mjs";
 import { runUpdate as runUpdate3Way } from "./update.mjs";
 import { runMigrate } from "./migrate.mjs";
+import { runScan } from "./scan-consumers.mjs";
 
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -86,6 +87,9 @@ async function main() {
       return runCompose(rest);
     case "migrate":
       return runMigrate(rest);
+    case "scan-consumers":
+    case "scan":
+      return runScan(rest);
     case "mcp":
       return runMcpHint();
     case undefined:

package/bin/scan-consumers.mjs

@@ -0,0 +1,301 @@
+// Wave N+3 — `rr scan-consumers` CLI.
+//
+// Walks one or more consumer repos, reads each slice's `.kitab.json`, and
+// diffs against the kitab's `frontend/slices/<slug>/slice.contract.ts`
+// version. Prints a human ASCII table or `--json` for CI / MCP wiring.
+//
+// Usage:
+//   npx rahman-resources scan-consumers --path /home/rahman/projects/CareerPack
+//   npx rahman-resources scan-consumers --all
+//   npx rahman-resources scan-consumers --consumer careerpack --json
+
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  walkConsumerSlices,
+  diffSlice,
+} from "../lib/consumer-manifest.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Kitab repo root resolved relative to this file's location: bin/ → cli → packages → repo
+const KITAB_ROOT = resolve(__dirname, "..", "..", "..");
+
+/**
+ * Default consumer registry. Edit when adding new consumers. Paths are
+ * absolute on the operator workstation; CI invocation overrides via --path.
+ */
+export const DEFAULT_CONSUMERS = [
+  { name: "careerpack", path: "/home/rahman/projects/CareerPack" },
+  { name: "notion", path: "/home/rahman/projects/notion-page-clone" },
+  { name: "rahmanef", path: "/home/rahman/projects/rahmanef.com" },
+  { name: "content", path: "/home/rahman/projects/content-rahmanef-com" },
+  { name: "superspace", path: "/home/rahman/projects/superspace" },
+  { name: "cescadesigns", path: "/home/rahman/projects/cescadesigns" },
+];
+
+const COLOR = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+  blue: "\x1b[34m",
+};
+function color(c, str, jsonMode) {
+  return process.stdout.isTTY && !jsonMode ? `${COLOR[c]}${str}${COLOR.reset}` : str;
+}
+
+const ID_RE = /\bid\s*:\s*["']([a-z][a-z0-9-]*)["']/;
+const VERSION_RE = /\bversion\s*:\s*["'](\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)["']/;
+
+/**
+ * Read all kitab contracts as {slug → version} via regex extraction.
+ * Skips folders without a contract file (drift scanner separately reports
+ * those — we only need version data here).
+ */
+async function readKitabContractVersions() {
+  const slicesDir = join(KITAB_ROOT, "frontend", "slices");
+  const entries = await readdir(slicesDir, { withFileTypes: true });
+  const out = new Map();
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith("_")) continue;
+    const contractPath = join(slicesDir, e.name, "slice.contract.ts");
+    if (!existsSync(contractPath)) continue;
+    try {
+      const src = await readFile(contractPath, "utf8");
+      const idMatch = src.match(ID_RE);
+      const verMatch = src.match(VERSION_RE);
+      if (!idMatch || !verMatch) continue;
+      out.set(idMatch[1], verMatch[1]);
+    } catch {
+      // skip
+    }
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const args = { paths: [], consumers: [], all: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--path") {
+      args.paths.push(argv[++i]);
+    } else if (a === "--consumer") {
+      args.consumers.push(argv[++i]);
+    } else if (a === "--all") {
+      args.all = true;
+    } else if (a === "--json") {
+      args.json = true;
+    } else if (a === "-h" || a === "--help") {
+      args.help = true;
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown flag: ${a}`);
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+Usage: rahman-resources scan-consumers [options]
+
+Detect bidirectional sync state between the kitab and consumer repos by
+reading each consumer slice's .kitab.json and diffing vs the kitab contract
+version.
+
+Options:
+  --path <dir>            Scan one consumer repo at this path. Repeatable.
+  --consumer <name>       Scan a registered consumer by name (see DEFAULT_CONSUMERS).
+                          Repeatable.
+  --all                   Scan every registered consumer.
+  --json                  Machine-readable JSON output.
+  -h, --help              Print this help.
+
+Default if no flag given: --all.
+
+Exit code:
+  0  no UP-sync needed (DOWN-sync surfaced as info, not error)
+  1  at least one consumer slice is up-needed/diverged AND policy != frozen
+  2  malformed manifest in some consumer (also exits 1)
+`);
+}
+
+function resolveTargets(args) {
+  const targets = [];
+  for (const p of args.paths) {
+    targets.push({ name: p, path: resolve(p) });
+  }
+  for (const cname of args.consumers) {
+    const found = DEFAULT_CONSUMERS.find((c) => c.name === cname);
+    if (!found) {
+      throw new Error(`unknown consumer "${cname}" — registered: ${DEFAULT_CONSUMERS.map((c) => c.name).join(", ")}`);
+    }
+    targets.push({ name: found.name, path: found.path });
+  }
+  if (args.all || (targets.length === 0 && !args.help)) {
+    for (const c of DEFAULT_CONSUMERS) {
+      if (!targets.find((t) => t.path === c.path)) targets.push(c);
+    }
+  }
+  return targets;
+}
+
+function verdictTone(v) {
+  switch (v) {
+    case "in-sync":
+      return "green";
+    case "up-needed":
+      return "blue";
+    case "down-needed":
+      return "yellow";
+    case "diverged":
+      return "red";
+    case "consumer-only":
+      return "cyan";
+    case "kitab-only":
+      return "dim";
+    default:
+      return "reset";
+  }
+}
+
+function pad(s, w) {
+  const str = String(s);
+  if (str.length >= w) return str;
+  return str + " ".repeat(w - str.length);
+}
+
+async function scanOne(target, kitabVersions) {
+  if (!existsSync(target.path)) {
+    return { name: target.name, path: target.path, error: "path does not exist" };
+  }
+  const walked = await walkConsumerSlices(target.path);
+  const diffs = [];
+  const errors = [];
+  const seen = new Set();
+  for (const w of walked) {
+    if (w.error) {
+      errors.push({ dir: w.dir, message: w.error });
+      continue;
+    }
+    const slug = w.manifest.kitabSlug;
+    seen.add(slug);
+    const kv = kitabVersions.get(slug) ?? null;
+    diffs.push(diffSlice({ slug, manifest: w.manifest, kitabVersion: kv }));
+  }
+  // Surface kitab-only slices the consumer hasn't adopted at all.
+  for (const [slug, version] of kitabVersions) {
+    if (!seen.has(slug)) {
+      diffs.push(diffSlice({ slug, manifest: null, kitabVersion: version }));
+    }
+  }
+  diffs.sort((a, b) => a.slug.localeCompare(b.slug));
+  return { name: target.name, path: target.path, diffs, errors };
+}
+
+export async function runScan(argv = []) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    console.error(color("red", err.message, false));
+    process.exit(2);
+  }
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+  const targets = resolveTargets(args);
+  const kitabVersions = await readKitabContractVersions();
+  const reports = await Promise.all(targets.map((t) => scanOne(t, kitabVersions)));
+
+  let upNeeded = 0;
+  let parseErrors = 0;
+  for (const r of reports) {
+    if (r.error) continue;
+    parseErrors += r.errors?.length ?? 0;
+    for (const d of r.diffs ?? []) {
+      if (d.direction === "up-needed" || d.direction === "diverged") upNeeded++;
+    }
+  }
+
+  if (args.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          kitabRoot: KITAB_ROOT,
+          kitabContracts: kitabVersions.size,
+          targets: reports,
+          upNeeded,
+          parseErrors,
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(upNeeded > 0 || parseErrors > 0 ? 1 : 0);
+  }
+
+  console.log(color("cyan", "\n== consumer sync scan ==", false));
+  console.log(color("dim", `kitab root: ${KITAB_ROOT}  (${kitabVersions.size} contracts)`, false));
+  for (const r of reports) {
+    console.log("");
+    console.log(color("cyan", `▸ ${r.name}`, false), color("dim", r.path, false));
+    if (r.error) {
+      console.log("  " + color("red", `error: ${r.error}`, false));
+      continue;
+    }
+    if (r.errors?.length) {
+      for (const e of r.errors) {
+        console.log("  " + color("red", `parse error @ ${e.dir}: ${e.message}`, false));
+      }
+    }
+    if (r.diffs.length === 0) {
+      console.log("  " + color("dim", "(no slices found)", false));
+      continue;
+    }
+    const headers = ["slug", "kitab", "consumer", "verdict", "actions"];
+    const rows = r.diffs.map((d) => [
+      d.slug,
+      d.kitabVersion ?? "—",
+      d.consumerVersion ?? "—",
+      d.direction,
+      d.allowedActions.length ? d.allowedActions.join(",") : "—",
+    ]);
+    const widths = headers.map((h, i) =>
+      Math.max(h.length, ...rows.map((r) => String(r[i]).length)),
+    );
+    console.log("  " + headers.map((h, i) => pad(h, widths[i])).join("  "));
+    console.log("  " + widths.map((w) => "-".repeat(w)).join("  "));
+    for (let i = 0; i < rows.length; i++) {
+      const d = r.diffs[i];
+      const tone = verdictTone(d.direction);
+      const cells = rows[i].map((c, ci) => pad(c, widths[ci]));
+      cells[3] = color(tone, cells[3], false);
+      console.log("  " + cells.join("  "));
+    }
+  }
+  console.log("");
+  console.log(
+    color("cyan", "Summary:", false),
+    `${reports.length} consumer(s) · ` +
+      color(upNeeded > 0 ? "blue" : "green", `${upNeeded} up-needed/diverged`, false) +
+      ` · ` +
+      color(parseErrors > 0 ? "red" : "green", `${parseErrors} parse error(s)`, false),
+  );
+  console.log("");
+  process.exit(upNeeded > 0 || parseErrors > 0 ? 1 : 0);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__filename);
+if (isMain) {
+  runScan(process.argv.slice(2)).catch((err) => {
+    console.error(`scan-consumers crashed: ${err.stack || err}`);
+    process.exit(2);
+  });
+}

package/lib/consumer-manifest.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Wave N+3 — Bidirectional Sync Detection Layer (BSDL).
+ *
+ * Consumer-side manifest contract: every slice copy in a consumer repo
+ * (CareerPack / notion / rahmanef / content / superspace / cescadesigns)
+ * declares which kitab slug + version it adopted, what the consumer-local
+ * version is, what sync direction is allowed, and how generalised the
+ * consumer-local copy is.
+ *
+ * The kitab `rr scan-consumers` command reads these and surfaces what
+ * needs UP-sync (`rr-send`) vs DOWN-sync (`rr update`).
+ *
+ * @module packages/cli/lib/consumer-manifest
+ */
+
+export type SyncDirection =
+  | "bidirectional"
+  | "down-only"
+  | "up-only"
+  | "frozen";
+
+export type GeneralizationStatus =
+  | "portable"
+  | "needs-adapter"
+  | "consumer-locked";
+
+export type SyncDirectionVerdict =
+  | "in-sync"
+  | "up-needed"
+  | "down-needed"
+  | "diverged"
+  | "consumer-only"
+  | "kitab-only";
+
+export interface ConsumerGeneralization {
+  /**
+   * Portable: the slice is fully generic and `rr-send` will accept it.
+   * needs-adapter: requires a thin adapter to plug consumer-specific
+   *   props/labels/routes — kitab can ingest if blockers are addressed.
+   * consumer-locked: contains business-specific logic that cannot be
+   *   generalised — UP-sync rejected; only DOWN-sync allowed.
+   */
+  status: GeneralizationStatus;
+  /** ISO date — when the audit ran. */
+  auditedAt: string;
+  /** Human-readable reasons preventing portability. Empty when portable. */
+  blockers: string[];
+}
+
+export interface ConsumerManifest {
+  $schema?: string;
+  /** Kebab-case slug — must match a kitab `slice.contract.ts` `id`. */
+  kitabSlug: string;
+  /** Semver of the kitab version this copy was last pulled from. */
+  kitabVersion: string;
+  /** Semver of the consumer-local divergence. Bump after each local edit. */
+  consumerVersion: string;
+  syncDirection: SyncDirection;
+  generalization: ConsumerGeneralization;
+  /** ISO timestamp of last successful `rr update --apply`. */
+  lastPullAt: string | null;
+  /** ISO timestamp of last successful `/rr-send`. */
+  lastPushAt: string | null;
+}
+
+export interface SyncDiff {
+  slug: string;
+  /** Kitab contract version, or null if slice not in kitab. */
+  kitabVersion: string | null;
+  /** Consumer manifest version, or null if no manifest in consumer. */
+  consumerVersion: string | null;
+  direction: SyncDirectionVerdict;
+  blockers: string[];
+  generalization: GeneralizationStatus | null;
+  /** Allowed sync directions per the manifest, narrowed by verdict. */
+  allowedActions: ("rr-send" | "rr-update")[];
+}
+
+export interface WalkedSlice {
+  /** Absolute path to the slice dir inside the consumer repo. */
+  dir: string;
+  /** Parsed manifest, or undefined if read failed. */
+  manifest?: ConsumerManifest;
+  /** Error message if manifest existed but failed validation. */
+  error?: string;
+}
+
+export function validateConsumerManifest(m: unknown): string[];
+export function readConsumerManifest(filepath: string): Promise<ConsumerManifest>;
+export function writeConsumerManifest(
+  filepath: string,
+  m: ConsumerManifest,
+): Promise<void>;
+export function diffSlice(input: {
+  slug: string;
+  manifest: ConsumerManifest | null;
+  kitabVersion: string | null;
+}): SyncDiff;
+export function walkConsumerSlices(consumerRoot: string): Promise<WalkedSlice[]>;
+export function compareSemver(a: string, b: string): number;

package/lib/consumer-manifest.mjs

@@ -0,0 +1,216 @@
+// Wave N+3 — Bidirectional Sync Detection Layer (BSDL).
+//
+// Consumer-side `.kitab.json` schema, reader/writer, semver compare, and the
+// per-slice sync diff used by `rr scan-consumers`. See d.ts for the full type
+// vocabulary and docs/consumer-manifest.md for the design rationale.
+
+import { readFile, writeFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const KEBAB_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const SEMVER_RE =
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2}))?$/;
+
+const SYNC_DIRECTIONS = new Set([
+  "bidirectional",
+  "down-only",
+  "up-only",
+  "frozen",
+]);
+const GENERALIZATION_STATUS = new Set([
+  "portable",
+  "needs-adapter",
+  "consumer-locked",
+]);
+
+export function validateConsumerManifest(m) {
+  const errors = [];
+  if (!m || typeof m !== "object") {
+    errors.push("manifest must be a non-null object");
+    return errors;
+  }
+  if (typeof m.kitabSlug !== "string" || !KEBAB_RE.test(m.kitabSlug)) {
+    errors.push(`kitabSlug "${String(m.kitabSlug)}" must be kebab-case`);
+  }
+  if (typeof m.kitabVersion !== "string" || !SEMVER_RE.test(m.kitabVersion)) {
+    errors.push(`kitabVersion "${String(m.kitabVersion)}" must be semver`);
+  }
+  if (
+    typeof m.consumerVersion !== "string" ||
+    !SEMVER_RE.test(m.consumerVersion)
+  ) {
+    errors.push(
+      `consumerVersion "${String(m.consumerVersion)}" must be semver`,
+    );
+  }
+  if (!SYNC_DIRECTIONS.has(m.syncDirection)) {
+    errors.push(
+      `syncDirection "${String(m.syncDirection)}" must be one of bidirectional|down-only|up-only|frozen`,
+    );
+  }
+  if (!m.generalization || typeof m.generalization !== "object") {
+    errors.push("generalization must be an object");
+  } else {
+    const g = m.generalization;
+    if (!GENERALIZATION_STATUS.has(g.status)) {
+      errors.push(
+        `generalization.status "${String(g.status)}" must be portable|needs-adapter|consumer-locked`,
+      );
+    }
+    if (typeof g.auditedAt !== "string" || !ISO_RE.test(g.auditedAt)) {
+      errors.push(
+        `generalization.auditedAt "${String(g.auditedAt)}" must be ISO date`,
+      );
+    }
+    if (!Array.isArray(g.blockers)) {
+      errors.push("generalization.blockers must be an array of strings");
+    } else {
+      for (const b of g.blockers) {
+        if (typeof b !== "string") {
+          errors.push(`generalization.blockers entry must be string, got ${typeof b}`);
+        }
+      }
+    }
+    if (g.status !== "portable" && (!Array.isArray(g.blockers) || g.blockers.length === 0)) {
+      errors.push(
+        `generalization.status "${g.status}" requires at least one entry in blockers[]`,
+      );
+    }
+  }
+  if (m.lastPullAt !== null && (typeof m.lastPullAt !== "string" || !ISO_RE.test(m.lastPullAt))) {
+    errors.push(`lastPullAt must be null or ISO timestamp`);
+  }
+  if (m.lastPushAt !== null && (typeof m.lastPushAt !== "string" || !ISO_RE.test(m.lastPushAt))) {
+    errors.push(`lastPushAt must be null or ISO timestamp`);
+  }
+  return errors;
+}
+
+export async function readConsumerManifest(filepath) {
+  const raw = await readFile(filepath, "utf8");
+  let m;
+  try {
+    m = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${filepath}: invalid JSON — ${err.message}`);
+  }
+  const errors = validateConsumerManifest(m);
+  if (errors.length > 0) {
+    throw new Error(`${filepath}: ${errors.join("; ")}`);
+  }
+  return m;
+}
+
+export async function writeConsumerManifest(filepath, m) {
+  const errors = validateConsumerManifest(m);
+  if (errors.length > 0) {
+    throw new Error(`refusing to write invalid manifest: ${errors.join("; ")}`);
+  }
+  const ordered = {
+    $schema: m.$schema ?? "https://resource.rahmanef.com/schemas/kitab-consumer.json",
+    kitabSlug: m.kitabSlug,
+    kitabVersion: m.kitabVersion,
+    consumerVersion: m.consumerVersion,
+    syncDirection: m.syncDirection,
+    generalization: m.generalization,
+    lastPullAt: m.lastPullAt,
+    lastPushAt: m.lastPushAt,
+  };
+  await writeFile(filepath, JSON.stringify(ordered, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Compare two semvers. Returns -1, 0, or 1. Pre-release tags ignored
+ * (compared on MAJOR.MINOR.PATCH only — sufficient for sync direction
+ * decisions; consumers shouldn't be depending on pre-release ordering for
+ * cross-repo sync gates).
+ */
+export function compareSemver(a, b) {
+  const pa = String(a).split(/[.+-]/).slice(0, 3).map((n) => parseInt(n, 10));
+  const pb = String(b).split(/[.+-]/).slice(0, 3).map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (av !== bv) return av < bv ? -1 : 1;
+  }
+  return 0;
+}
+
+function allowedActionsFor(verdict, manifest) {
+  if (!manifest) return [];
+  const dir = manifest.syncDirection;
+  if (dir === "frozen") return [];
+  const actions = [];
+  if ((verdict === "up-needed" || verdict === "diverged") && (dir === "bidirectional" || dir === "up-only")) {
+    if (manifest.generalization.status === "portable") actions.push("rr-send");
+  }
+  if ((verdict === "down-needed" || verdict === "diverged") && (dir === "bidirectional" || dir === "down-only")) {
+    actions.push("rr-update");
+  }
+  return actions;
+}
+
+export function diffSlice({ slug, manifest, kitabVersion }) {
+  if (manifest && !kitabVersion) {
+    return {
+      slug,
+      kitabVersion: null,
+      consumerVersion: manifest.consumerVersion,
+      direction: "consumer-only",
+      blockers: manifest.generalization.blockers,
+      generalization: manifest.generalization.status,
+      allowedActions: manifest.generalization.status === "portable" ? ["rr-send"] : [],
+    };
+  }
+  if (!manifest && kitabVersion) {
+    return {
+      slug,
+      kitabVersion,
+      consumerVersion: null,
+      direction: "kitab-only",
+      blockers: [],
+      generalization: null,
+      allowedActions: ["rr-update"],
+    };
+  }
+  if (!manifest) {
+    return null;
+  }
+  const consumerCmpKitab = compareSemver(manifest.consumerVersion, manifest.kitabVersion);
+  const kitabCmpAdopted = compareSemver(kitabVersion, manifest.kitabVersion);
+  let direction;
+  if (consumerCmpKitab > 0 && kitabCmpAdopted > 0) direction = "diverged";
+  else if (consumerCmpKitab > 0) direction = "up-needed";
+  else if (kitabCmpAdopted > 0) direction = "down-needed";
+  else direction = "in-sync";
+  return {
+    slug,
+    kitabVersion,
+    consumerVersion: manifest.consumerVersion,
+    direction,
+    blockers: manifest.generalization.blockers,
+    generalization: manifest.generalization.status,
+    allowedActions: allowedActionsFor(direction, manifest),
+  };
+}
+
+export async function walkConsumerSlices(consumerRoot) {
+  const slicesDir = join(consumerRoot, "frontend", "slices");
+  if (!existsSync(slicesDir)) return [];
+  const out = [];
+  const entries = await readdir(slicesDir, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith("_")) continue;
+    const manifestPath = join(slicesDir, e.name, ".kitab.json");
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const m = await readConsumerManifest(manifestPath);
+      out.push({ dir: join(slicesDir, e.name), manifest: m });
+    } catch (err) {
+      out.push({ dir: join(slicesDir, e.name), error: err.message });
+    }
+  }
+  return out;
+}

package/lib/consumer-manifest.test.mjs

@@ -0,0 +1,253 @@
+// Wave N+3 — consumer-manifest test suite.
+//
+// Covers: schema validation, semver compare, diffSlice verdict matrix,
+// allowedActions gating by syncDirection + generalization, walkConsumerSlices
+// against a fixture tree.
+
+import { describe, it, expect } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  validateConsumerManifest,
+  compareSemver,
+  diffSlice,
+  walkConsumerSlices,
+  readConsumerManifest,
+  writeConsumerManifest,
+} from "./consumer-manifest.mjs";
+
+function baseManifest(over = {}) {
+  return {
+    kitabSlug: "comments",
+    kitabVersion: "0.1.0",
+    consumerVersion: "0.1.0",
+    syncDirection: "bidirectional",
+    generalization: {
+      status: "portable",
+      auditedAt: "2026-05-15",
+      blockers: [],
+    },
+    lastPullAt: null,
+    lastPushAt: null,
+    ...over,
+  };
+}
+
+describe("validateConsumerManifest", () => {
+  it("accepts a minimal valid manifest", () => {
+    expect(validateConsumerManifest(baseManifest())).toEqual([]);
+  });
+
+  it("rejects non-kebab slug", () => {
+    const errs = validateConsumerManifest(baseManifest({ kitabSlug: "Bad_Slug" }));
+    expect(errs.some((e) => e.includes("kebab-case"))).toBe(true);
+  });
+
+  it("rejects non-semver versions", () => {
+    const errs = validateConsumerManifest(baseManifest({ kitabVersion: "v0.1" }));
+    expect(errs.some((e) => e.includes("semver"))).toBe(true);
+  });
+
+  it("rejects unknown syncDirection", () => {
+    const errs = validateConsumerManifest(baseManifest({ syncDirection: "loose" }));
+    expect(errs.some((e) => e.includes("syncDirection"))).toBe(true);
+  });
+
+  it("requires blockers when status != portable", () => {
+    const errs = validateConsumerManifest(
+      baseManifest({
+        generalization: {
+          status: "needs-adapter",
+          auditedAt: "2026-05-15",
+          blockers: [],
+        },
+      }),
+    );
+    expect(errs.some((e) => e.includes("blockers"))).toBe(true);
+  });
+
+  it("accepts non-portable status with blockers populated", () => {
+    expect(
+      validateConsumerManifest(
+        baseManifest({
+          generalization: {
+            status: "consumer-locked",
+            auditedAt: "2026-05-15",
+            blockers: ["hardcoded business term"],
+          },
+        }),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("compareSemver", () => {
+  it("orders MAJOR.MINOR.PATCH correctly", () => {
+    expect(compareSemver("0.1.0", "0.1.0")).toBe(0);
+    expect(compareSemver("0.1.1", "0.1.0")).toBe(1);
+    expect(compareSemver("0.1.0", "0.1.1")).toBe(-1);
+    expect(compareSemver("1.0.0", "0.99.99")).toBe(1);
+  });
+
+  it("strips pre-release/build tags", () => {
+    expect(compareSemver("0.1.0-beta", "0.1.0+build")).toBe(0);
+  });
+});
+
+describe("diffSlice verdicts", () => {
+  it("in-sync when all versions match", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest(),
+      kitabVersion: "0.1.0",
+    });
+    expect(r.direction).toBe("in-sync");
+    expect(r.allowedActions).toEqual([]);
+  });
+
+  it("up-needed when consumer ahead", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({ consumerVersion: "0.1.3" }),
+      kitabVersion: "0.1.0",
+    });
+    expect(r.direction).toBe("up-needed");
+    expect(r.allowedActions).toContain("rr-send");
+  });
+
+  it("down-needed when kitab ahead", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({ consumerVersion: "0.1.0", kitabVersion: "0.1.0" }),
+      kitabVersion: "0.2.0",
+    });
+    expect(r.direction).toBe("down-needed");
+    expect(r.allowedActions).toContain("rr-update");
+  });
+
+  it("diverged when both ahead", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({ consumerVersion: "0.1.5", kitabVersion: "0.1.0" }),
+      kitabVersion: "0.2.0",
+    });
+    expect(r.direction).toBe("diverged");
+    expect(r.allowedActions).toContain("rr-send");
+    expect(r.allowedActions).toContain("rr-update");
+  });
+
+  it("kitab-only when no consumer manifest", () => {
+    const r = diffSlice({ slug: "comments", manifest: null, kitabVersion: "0.1.0" });
+    expect(r.direction).toBe("kitab-only");
+    expect(r.allowedActions).toEqual(["rr-update"]);
+  });
+
+  it("consumer-only when not in kitab", () => {
+    const r = diffSlice({
+      slug: "ghost",
+      manifest: baseManifest({ kitabSlug: "ghost" }),
+      kitabVersion: null,
+    });
+    expect(r.direction).toBe("consumer-only");
+    expect(r.allowedActions).toEqual(["rr-send"]);
+  });
+
+  it("frozen syncDirection blocks all actions", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({
+        consumerVersion: "0.1.5",
+        syncDirection: "frozen",
+      }),
+      kitabVersion: "0.2.0",
+    });
+    expect(r.direction).toBe("diverged");
+    expect(r.allowedActions).toEqual([]);
+  });
+
+  it("consumer-locked status blocks rr-send", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({
+        consumerVersion: "0.1.5",
+        generalization: {
+          status: "consumer-locked",
+          auditedAt: "2026-05-15",
+          blockers: ["business-specific table"],
+        },
+      }),
+      kitabVersion: "0.1.0",
+    });
+    expect(r.direction).toBe("up-needed");
+    expect(r.allowedActions).not.toContain("rr-send");
+  });
+
+  it("down-only direction blocks rr-send even when up-needed", () => {
+    const r = diffSlice({
+      slug: "comments",
+      manifest: baseManifest({
+        consumerVersion: "0.1.5",
+        syncDirection: "down-only",
+      }),
+      kitabVersion: "0.1.0",
+    });
+    expect(r.direction).toBe("up-needed");
+    expect(r.allowedActions).not.toContain("rr-send");
+  });
+});
+
+describe("walkConsumerSlices + read/write round-trip", () => {
+  it("reads valid manifests and surfaces parse errors per slice", async () => {
+    const root = await mkdtemp(join(tmpdir(), "rr-bsdl-"));
+    try {
+      const slicesDir = join(root, "frontend", "slices");
+      await mkdir(join(slicesDir, "comments"), { recursive: true });
+      await mkdir(join(slicesDir, "broken"), { recursive: true });
+      await mkdir(join(slicesDir, "no-manifest"), { recursive: true });
+      await mkdir(join(slicesDir, "_internal"), { recursive: true });
+
+      await writeConsumerManifest(
+        join(slicesDir, "comments", ".kitab.json"),
+        baseManifest({ kitabSlug: "comments" }),
+      );
+      // _internal also has a manifest but should be skipped (underscore prefix)
+      await writeFile(
+        join(slicesDir, "_internal", ".kitab.json"),
+        JSON.stringify(baseManifest({ kitabSlug: "internal" })),
+      );
+      await writeFile(
+        join(slicesDir, "broken", ".kitab.json"),
+        '{"not": "valid"}',
+      );
+
+      const walked = await walkConsumerSlices(root);
+      const slugs = walked.map((w) => w.dir.split("/").pop()).sort();
+      expect(slugs).toEqual(["broken", "comments"]);
+      const broken = walked.find((w) => w.dir.endsWith("broken"));
+      expect(broken.error).toBeDefined();
+      const ok = walked.find((w) => w.dir.endsWith("comments"));
+      expect(ok.manifest?.kitabSlug).toBe("comments");
+
+      const round = await readConsumerManifest(
+        join(slicesDir, "comments", ".kitab.json"),
+      );
+      expect(round.kitabSlug).toBe("comments");
+      expect(round.$schema).toBe(
+        "https://resource.rahmanef.com/schemas/kitab-consumer.json",
+      );
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("returns empty when no slices dir", async () => {
+    const root = await mkdtemp(join(tmpdir(), "rr-bsdl-empty-"));
+    try {
+      const walked = await walkConsumerSlices(root);
+      expect(walked).toEqual([]);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/lib/contract.ts

@@ -92,6 +92,66 @@ export interface SliceContractProvides {
   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
 // ---------------------------------------------------------------------------
@@ -121,6 +181,8 @@ export interface SliceContract {
   conflicts?: string[];
   /** Map of previous-version → migration script id. */
   migrationFrom?: Record<string, string>;
+  /** Wave N+3 — bidirectional sync policy + generalisation gate. */
+  bidir?: SliceBidirContract;
 }
 
 // ---------------------------------------------------------------------------
@@ -222,6 +284,60 @@ export function defineSliceContract(c: SliceContract): SliceContract {
     }
   }
 
+  // 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)) {

package/lib/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 2,
-  "generatedAt": "2026-05-15T03:23:22.231Z",
+  "generatedAt": "2026-05-15T05:11:02.213Z",
   "repo": "rahmanef63/resource-site",
   "branch": "main",
   "layouts": [
@@ -1273,6 +1273,24 @@
         "anthropic",
         "metadata-generator"
       ]
+    },
+    {
+      "slug": "document-checklist",
+      "title": "Document Checklist — Job-Search Doc Tracker",
+      "category": "content",
+      "description": "Track required job-search documents (CV, KTP, ijazah, etc.) with country-scoped seed templates and per-user completion state. Ships an Indonesian default checklist. Toggle completed + notes + expiry per item.",
+      "source": "rahmanef63/CareerPack",
+      "install": "npx rahman-resources add document-checklist",
+      "npmPackages": [],
+      "exampleCode": "",
+      "agentRecipe": "Run `rr add document-checklist`. Wire <DocumentChecklist bindings={{ current, seed, updateStatus }} countryTemplateSlot={<CountryTemplateCard bindings={{ templates, getTemplate, instantiate }} />} /> — bindings sourced from api.features['document-checklist'].* queries/mutations.",
+      "tags": [
+        "career",
+        "documents",
+        "checklist",
+        "job-search",
+        "indonesia"
+      ]
     }
   ],
   "slices": [
@@ -2152,6 +2170,53 @@
         "metadata-generator"
       ],
       "agentRecipe": "Run `rr add seo`. Call seo.generate from server actions or admin mutations. Cost guard rate-limits per-user within 24h via callsInWindow query."
+    },
+    {
+      "slug": "document-checklist",
+      "title": "Document Checklist — Job-Search Doc Tracker",
+      "category": "content",
+      "kind": "full",
+      "version": "0.1.0",
+      "description": "Track required job-search documents (CV, KTP, ijazah, etc.) with country-scoped seed templates and per-user completion state. Ships an Indonesian default checklist. Toggle completed + notes + expiry per item.",
+      "source": "rahmanef63/CareerPack",
+      "slicePath": "frontend/slices/document-checklist",
+      "convexPaths": [
+        "convex/features/document-checklist"
+      ],
+      "npm": [
+        "lucide-react"
+      ],
+      "shadcn": [
+        "badge",
+        "button",
+        "card",
+        "dialog",
+        "label",
+        "popover",
+        "calendar",
+        "progress",
+        "scroll-area",
+        "skeleton",
+        "tabs",
+        "textarea"
+      ],
+      "env": [],
+      "peers": [
+        {
+          "slug": "convex-auth",
+          "range": "^0.1",
+          "reason": "Auth identity for user-scoped checklist state."
+        }
+      ],
+      "providers": [],
+      "tags": [
+        "career",
+        "documents",
+        "checklist",
+        "job-search",
+        "indonesia"
+      ],
+      "agentRecipe": "Run `rr add document-checklist`. Wire <DocumentChecklist bindings={{ current, seed, updateStatus }} countryTemplateSlot={<CountryTemplateCard bindings={{ templates, getTemplate, instantiate }} />} /> — bindings sourced from api.features['document-checklist'].* queries/mutations."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rahman-resources",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Scaffolder + installer for Rahman Resources kitab — npx rahman-resources init/add/lift/scaffold-slice/publish-slice. Tier-3 portable feature slices + manifest + skills + CRUD workflows.",
   "type": "module",
   "license": "MIT",