rahman-resources 0.13.0 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rahman-resources",
-  "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.",
+  "version": "1.2.0",
+  "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",
   "author": "Rahman <casadezian@gmail.com>",
@@ -12,7 +12,9 @@
     "directory": "packages/cli"
   },
   "bin": {
-    "rahman-resources": "bin/cli.js"
+    "rahman-resources": "bin/cli.js",
+    "resources": "bin/cli.js",
+    "rr": "bin/cli.js"
   },
   "files": [
     "bin",

package/bin/scan-consumers.mjs

@@ -1,301 +0,0 @@
-// 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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,216 +0,0 @@
-// 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;
-}