rahman-resources 1.13.2 → 1.14.0

package/bin/cli.js

@@ -869,8 +869,12 @@ async function installSkill(slug, target) {
   const dest = path.join(target, ".claude", "skills", slug);
   process.stdout.write(`  ${kleur.cyan(slug.padEnd(20))} ${kleur.dim(`→ .claude/skills/${slug}/`)} ... `);
   if (skill.source === "anthropics") {
-    const emitter = tiged(`${SKILLS_REPO}/${skill.path}`, { cache: false, force: true, verbose: false });
-    await emitter.clone(dest);
+    const source = `${SKILLS_REPO}/${skill.path}`;
+    await cloneWithRetry(
+      () => tiged(source, { cache: false, force: true, verbose: false }),
+      dest,
+      source,
+    );
   } else if (skill.source === "rahman") {
     // Future: ship rahman-authored skills inside this repo. For now, scaffold a stub.
     mkdirSync(dest, { recursive: true });
@@ -1372,14 +1376,49 @@ async function checkGhInstalled() {
 
 // ─── helpers ──────────────────────────────────────────────────────────────
 
+// tiged surfaces raw git/network errors with no recovery hint. Translate the
+// common failure modes into actionable messages, and retry once on transient
+// network errors before giving up.
+async function cloneWithRetry(makeEmitter, dest, source) {
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      await makeEmitter().clone(dest);
+      return;
+    } catch (err) {
+      const msg = String(err?.message ?? err);
+      const transient = /ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|50[234]/i.test(msg);
+      if (transient && attempt === 1) continue; // one silent retry
+      if (/ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET/i.test(msg)) {
+        throw new Error(
+          `Network error fetching ${source}: ${msg}\n  → check your internet connection and retry.`,
+        );
+      }
+      if (/could not find|not found|ENOENT|404/i.test(msg)) {
+        throw new Error(
+          `Could not fetch ${source}: ${msg}\n  → verify the slug exists (run 'list') and the repo/branch is public.`,
+        );
+      }
+      throw new Error(`Failed to fetch ${source}: ${msg}`);
+    }
+  }
+}
+
 async function pull(repoPath, dest) {
-  const emitter = tiged(`${REPO}/${repoPath}#${BRANCH}`, { cache: false, force: true, verbose: false });
-  await emitter.clone(dest);
+  const source = `${REPO}/${repoPath}#${BRANCH}`;
+  await cloneWithRetry(
+    () => tiged(source, { cache: false, force: true, verbose: false }),
+    dest,
+    source,
+  );
 }
 
 async function pullFromRepo(repo, subPath, branch, dest) {
-  const emitter = tiged(`${repo}/${subPath}#${branch}`, { cache: false, force: true, verbose: false });
-  await emitter.clone(dest);
+  const source = `${repo}/${subPath}#${branch}`;
+  await cloneWithRetry(
+    () => tiged(source, { cache: false, force: true, verbose: false }),
+    dest,
+    source,
+  );
 }
 
 function detectPM(target) {

package/bin/migrate-load.mjs

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { loadSliceContract } from "../lib/load-contract.mjs";
 
 export function parseFlags(rest) {
   const positional = [];
@@ -51,26 +52,32 @@ const SLICE_ROOTS = [
   ["template-base", "frontend", "slices"],
 ];
 
-function resolveContractPath(repoRoot, slug) {
+// The CURRENT contract is folded into slice.json — locate the slice dir by its
+// slice.json (the .ts no longer exists in the working tree post-cutover).
+function resolveSliceDir(repoRoot, slug) {
   for (const segs of SLICE_ROOTS) {
-    const p = path.join(repoRoot, ...segs, slug, "slice.contract.ts");
-    if (existsSync(p)) return p;
+    const dir = path.join(repoRoot, ...segs, slug);
+    if (existsSync(path.join(dir, "slice.json"))) return dir;
   }
   return null;
 }
 
+// HISTORIC leg still pulls the OLD slice.contract.ts from git history, so the
+// rel path is the .ts path — but gate on the slice's slice.json existing today
+// (NOT the working-tree .ts, which is gone post-cutover).
 function resolveContractRelPath(repoRoot, slug) {
   for (const segs of SLICE_ROOTS) {
-    const rel = [...segs, slug, "slice.contract.ts"].join("/");
-    if (existsSync(path.join(repoRoot, rel))) return rel;
+    if (existsSync(path.join(repoRoot, ...segs, slug, "slice.json"))) {
+      return [...segs, slug, "slice.contract.ts"].join("/");
+    }
   }
   return null;
 }
 
 export function loadCurrentContract(repoRoot, slug) {
-  const p = resolveContractPath(repoRoot, slug);
-  if (!p) return null;
-  return evalContract(repoRoot, p, null);
+  const dir = resolveSliceDir(repoRoot, slug);
+  if (!dir) return null;
+  return loadSliceContract(dir);
 }
 
 /**

package/bin/migrate.mjs

@@ -80,7 +80,7 @@ export async function runMigrate(rest) {
     process.stderr.write(
       kleur.red(
         `migrate: cannot load current contract for "${slug}". ` +
-          `Expected frontend/slices/${slug}/slice.contract.ts or template-base/frontend/slices/${slug}/slice.contract.ts.\n`,
+          `Expected a contract block in frontend/slices/${slug}/slice.json (or template-base/frontend/slices/${slug}/slice.json).\n`,
       ),
     );
     process.exit(1);

package/lib/compose-solver-loader.mjs

@@ -1,13 +1,14 @@
-// compose-solver-loader.mjs — contract discovery + tsx-eval loader.
+// compose-solver-loader.mjs — contract discovery loader.
 //
 // Split out from compose-solver.mjs to keep the pure solver < 200 LOC.
-// I/O entry point only — discovers `slice.contract.ts` under known slice
-// roots and shells out to `npx tsx` to JSON-serialize each export.
+// I/O entry point only — discovers slices under known roots and reads each
+// folded contract from slice.json (`contract` block) via the shared adapter.
+// No tsx subprocess: the contract lives in slice.json since the Phase-2 fold.
 
 import { readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { loadSliceContract } from "./load-contract.mjs";
 
 const SLICE_ROOT_GLOBS = [
   ["frontend", "slices"],
@@ -15,11 +16,10 @@ const SLICE_ROOT_GLOBS = [
 ];
 
 /**
- * Discover every `slice.contract.ts` under the kitab's known slice roots and
- * load them via `npx tsx`. Returns a Map<slug, SliceContract>. Contracts that
- * fail to load are silently skipped so a single broken file doesn't take
- * down the whole solver — `npm run validate:contracts` is the place to surface
- * those errors.
+ * Discover every slice with a folded contract under the kitab's known slice
+ * roots. Returns a Map<slug, SliceContract>. Slices without a slice.json
+ * contract block are silently skipped so a single uncontracted slice doesn't
+ * take down the solver — `npm run audit:slices` surfaces shape errors.
  *
  * @param {string} repoRoot Absolute path to the kitab repo root.
  * @returns {Promise<Map<string, import("./contract").SliceContract>>}
@@ -27,9 +27,8 @@ const SLICE_ROOT_GLOBS = [
 export async function loadAllContracts(repoRoot) {
   /** @type {Map<string, import("./contract").SliceContract>} */
   const out = new Map();
-  const sliceFiles = await discoverContractFiles(repoRoot);
-  for (const filePath of sliceFiles) {
-    const contract = loadContractFile(repoRoot, filePath);
+  for (const dir of await discoverSliceDirs(repoRoot)) {
+    const contract = loadSliceContract(dir);
     if (contract && typeof contract.id === "string") {
       out.set(contract.id, contract);
     }
@@ -37,7 +36,7 @@ export async function loadAllContracts(repoRoot) {
   return out;
 }
 
-async function discoverContractFiles(repoRoot) {
+async function discoverSliceDirs(repoRoot) {
   const found = [];
   for (const segs of SLICE_ROOT_GLOBS) {
     const root = path.join(repoRoot, ...segs);
@@ -46,34 +45,9 @@ async function discoverContractFiles(repoRoot) {
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (entry.name.startsWith("_")) continue;
-      const filePath = path.join(root, entry.name, "slice.contract.ts");
-      if (existsSync(filePath)) found.push(filePath);
+      const dir = path.join(root, entry.name);
+      if (existsSync(path.join(dir, "slice.json"))) found.push(dir);
     }
   }
   return found;
 }
-
-/**
- * Dynamic-import a .ts contract file via `npx tsx -e` and JSON.parse the
- * stringified `contract` export. Returns null on any failure.
- */
-function loadContractFile(repoRoot, filePath) {
-  const rel = "./" + path.relative(repoRoot, filePath);
-  const code = [
-    `import(${JSON.stringify(rel)})`,
-    `  .then(m => { const c = m.contract || (m.default && m.default.contract); if (!c) { process.exit(2); } process.stdout.write(JSON.stringify(c)); })`,
-    `  .catch(() => process.exit(3));`,
-  ].join("\n");
-  const res = spawnSync("npx", ["--no-install", "tsx", "-e", code], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  });
-  if (res.status === 0 && res.stdout) {
-    try {
-      return JSON.parse(res.stdout);
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}

package/lib/compose-solver-resolve.mjs

@@ -32,7 +32,7 @@ export function buildInitialCandidates({
           {
             type: "uncontracted",
             slug,
-            detail: `Slice "${slug}" has no registered slice.contract.ts — accepted under allowUnknownSlices, but conflict checks are skipped for it.`,
+            detail: `Slice "${slug}" has no registered contract — accepted under allowUnknownSlices, but conflict checks are skipped for it.`,
             severity: "warning",
           },
           slug,
@@ -41,13 +41,13 @@ export function buildInitialCandidates({
         candidateSet.add(slug);
         candidateOrder.push(slug);
         notes.set(slug, "uncontracted");
-        proof.push(`! ${slug}: accepted as uncontracted (no slice.contract.ts; skipping conflict checks)`);
+        proof.push(`! ${slug}: accepted as uncontracted (no contract (slice.json); skipping conflict checks)`);
       } else {
         record(
           {
             type: "missing-dep",
             slug,
-            detail: `Contract not found for "${slug}" — no slice.contract.ts registered (strict mode).`,
+            detail: `Contract not found for "${slug}" — no registered contract (strict mode).`,
             severity: "blocker",
           },
           slug,

package/lib/contract-tools.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { defineSliceContract } from "./contract";
+
+const base = {
+  id: "foo",
+  version: "1.0.0",
+  requires: {},
+  provides: {},
+};
+
+describe("defineSliceContract — provides.tools (agentic surface)", () => {
+  it("accepts tool names prefixed with the slice id", () => {
+    expect(() =>
+      defineSliceContract({
+        ...base,
+        provides: { tools: ["foo.bar", "foo.baz.qux"] },
+      }),
+    ).not.toThrow();
+  });
+
+  it("rejects tool names not prefixed with the slice id", () => {
+    expect(() =>
+      defineSliceContract({
+        ...base,
+        provides: { tools: ["bar.baz"] },
+      }),
+    ).toThrow(/must be prefixed with "foo\."/);
+  });
+
+  it("rejects non-string / empty tool entries", () => {
+    expect(() =>
+      defineSliceContract({
+        ...base,
+        provides: { tools: [""] as string[] },
+      }),
+    ).toThrow(/non-empty strings/);
+  });
+
+  it("allows tools to be omitted (non-agentic slices)", () => {
+    expect(() => defineSliceContract({ ...base })).not.toThrow();
+  });
+
+  it("allows a conflict to reference a tool name", () => {
+    expect(() =>
+      defineSliceContract({
+        ...base,
+        provides: { tools: ["foo.bar"] },
+        conflicts: ["other:tools.foo.bar"],
+      }),
+    ).not.toThrow();
+  });
+});

package/lib/contract-types.ts

@@ -88,6 +88,14 @@ export interface SliceContractProvides {
   events?: string[];
   /** Public component exports — e.g. `["DokuCheckoutButton"]`. */
   components?: string[];
+  /**
+   * Fully-qualified AI tool names the slice exposes as a `ToolCollection`
+   * (`@/shared/agentic`) — e.g. `["image-editor.layer.add"]`. Every entry
+   * MUST be prefixed with the slice id so one agent can aggregate tools from
+   * many slices without collision. A slice is "agentic-ready" iff this is
+   * non-empty.
+   */
+  tools?: string[];
 }
 
 // ---------------------------------------------------------------------------

package/lib/contract-validate.ts

@@ -18,7 +18,7 @@ const KEBAB_CASE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 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 CONFLICT = /^[a-z][a-z0-9-]*:(routes|hooks|tables|events|components|tools)\.[A-Za-z0-9_\-\/.]+$/;
 const PERMISSION = /^[^.]+\.[^.]+$/;
 
 // ---------------------------------------------------------------------------
@@ -131,6 +131,28 @@ export function validateGeneralization(c: SliceContract): void {
   }
 }
 
+export function validateTools(c: SliceContract): void {
+  const tools = c.provides.tools;
+  if (tools === undefined) return;
+  if (!Array.isArray(tools)) {
+    throw new Error(`defineSliceContract(${c.id}): provides.tools must be an array`);
+  }
+  for (const t of tools) {
+    if (typeof t !== "string" || t.length === 0) {
+      throw new Error(
+        `defineSliceContract(${c.id}): provides.tools entries must be non-empty strings`,
+      );
+    }
+    // Every tool name MUST be namespaced to the slice id so one agent can
+    // aggregate collections from many slices without collision.
+    if (!t.startsWith(`${c.id}.`)) {
+      throw new Error(
+        `defineSliceContract(${c.id}): provides.tools entry "${t}" must be prefixed with "${c.id}."`,
+      );
+    }
+  }
+}
+
 export function validateConflicts(c: SliceContract): void {
   if (!c.conflicts) return;
   if (!Array.isArray(c.conflicts)) {

package/lib/contract.ts

@@ -15,6 +15,7 @@ import {
   validateConvex,
   validateGeneralization,
   validateConflicts,
+  validateTools,
 } from "./contract-validate";
 
 // Re-export the full type surface so existing imports keep working.
@@ -62,5 +63,6 @@ export function defineSliceContract(c: SliceContract): SliceContract {
   validateConvex(c);
   validateGeneralization(c);
   validateConflicts(c);
+  validateTools(c);
   return c;
 }

package/lib/load-contract.mjs

@@ -0,0 +1,33 @@
+// load-contract.mjs — read a slice's folded composition contract from its
+// slice.json (Phase 2 SSOT). Replaces parsing slice.contract.ts: the contract
+// payload now lives under slice.json `contract`, with id/version omitted there
+// (they are the slice.json scalars). This adapter reattaches them so callers
+// get the same SliceContract shape the .ts used to export.
+//
+// Returns undefined when the slice has no slice.json or no contract block —
+// callers treat that exactly like a missing slice.contract.ts before.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} sliceDir Absolute path to frontend/slices/<slug>/.
+ * @returns {object|undefined} { id, version, requires?, provides?, conflicts?,
+ *   migrationFrom?, generalization? } or undefined.
+ */
+export function loadSliceContract(sliceDir) {
+  return contractFromJson(path.join(sliceDir, "slice.json"));
+}
+
+/** Same, given a direct path to a slice.json file. */
+export function contractFromJson(jsonPath) {
+  if (!existsSync(jsonPath)) return undefined;
+  let j;
+  try {
+    j = JSON.parse(readFileSync(jsonPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (!j.contract || typeof j.contract !== "object") return undefined;
+  return { id: j.slug, version: j.version, ...j.contract };
+}