rahman-resources 1.13.2 → 1.14.0

package/lib/slice-schema.json

@@ -171,6 +171,10 @@
               "range": {
                 "type": "string"
               },
+              "optional": {
+                "type": "boolean",
+                "description": "Peer is optional — slice degrades gracefully without it (e.g. a swappable payment provider)."
+              },
               "reason": {
                 "type": "string"
               }
@@ -311,6 +315,10 @@
     "deprecated": {
       "type": "string",
       "description": "Successor slug. This slice was merged into the named slice as variants; install resolves there via manifest.aliases."
+    },
+    "contract": {
+      "type": "object",
+      "description": "Folded Phase-A composition contract (Phase 2 hybrid fold, 2026-06-21): requires/provides/conflicts/migrationFrom/generalization moved from slice.contract.ts. id+version omitted (== slug/version). requires.deps is verbatim pending per-slice normalization, so this is intentionally loose; strict invariants move to validate-slice when the .ts is retired."
     }
   }
 }

package/lib/snapshot.mjs

@@ -1,13 +1,12 @@
 // snapshot.mjs — build a SliceSnapshot from a slice directory.
 //
 // Walks the directory recursively, keeps only typical slice file extensions,
-// reads `slice.contract.ts` when present and parses it (via `tsx` if
-// available, regex fallback otherwise). Skips node_modules, .kitab, and
-// dotfiles to keep snapshots stable across machines.
+// and reads the folded composition contract from slice.json (`contract` block,
+// id/version reattached from the slice.json scalars). Skips node_modules,
+// .kitab, and dotfiles to keep snapshots stable across machines.
 
 import { readdir, readFile, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import path from "node:path";
 
 const INCLUDED_EXT = new Set([".ts", ".tsx", ".mjs", ".js", ".jsx", ".json", ".md", ".css"]);
@@ -33,18 +32,18 @@ export async function snapshotFromDir(slug, dir) {
   const files = {};
   await walk(dir, dir, files);
 
+  // The composition contract is folded into slice.json (`contract` block) since
+  // Phase 2; reattach id/version from the slice.json scalars to keep the same
+  // SliceContract shape the old slice.contract.ts exported.
   let contract;
-  const contractPath = path.join(dir, "slice.contract.ts");
-  if (existsSync(contractPath)) {
-    contract = loadContract(contractPath) ?? regexLoadContract(await readFile(contractPath, "utf8"));
-  }
-
-  // Version preference: contract.version → slice.json.version → "0.0.0".
-  let version = contract?.version ?? "0.0.0";
-  if (!contract?.version && files["slice.json"]) {
+  let version = "0.0.0";
+  if (files["slice.json"]) {
     try {
       const meta = JSON.parse(files["slice.json"]);
       if (typeof meta.version === "string") version = meta.version;
+      if (meta.contract && typeof meta.contract === "object") {
+        contract = { id: meta.slug, version: meta.version, ...meta.contract };
+      }
     } catch {
       /* ignore */
     }
@@ -79,48 +78,3 @@ async function walk(root, dir, out) {
     out[rel] = await readFile(full, "utf8");
   }
 }
-
-/**
- * Mirror of validate-contract.mjs's tsx loader. Returns the parsed contract
- * or undefined on failure.
- */
-function loadContract(filePath) {
-  const code = [
-    `import(${JSON.stringify(filePath)})`,
-    `  .then(m => { const c = m.contract || (m.default && m.default.contract); if (!c) { process.exit(2); } process.stdout.write(JSON.stringify(c)); })`,
-    `  .catch(e => { process.stderr.write(String(e && e.message || e)); process.exit(3); });`,
-  ].join("\n");
-  try {
-    const res = spawnSync("npx", ["--no-install", "tsx", "-e", code], {
-      encoding: "utf8",
-    });
-    if (res.status === 0 && res.stdout) {
-      return JSON.parse(res.stdout);
-    }
-  } catch {
-    /* tsx missing or failed */
-  }
-  return undefined;
-}
-
-/**
- * Best-effort regex fallback: extract the literal-ish object passed to
- * `defineSliceContract({ ... })`. We can't fully parse TS, but for the kitab's
- * contracts (small static literals) a JSON5-ish coerce works for the basic
- * shape we need here.
- */
-function regexLoadContract(src) {
-  const m = src.match(/defineSliceContract\s*\(\s*(\{[\s\S]*?\})\s*\)\s*;?\s*$/m);
-  if (!m) return undefined;
-  // Replace single quotes, strip trailing commas, quote keys.
-  const body = m[1]
-    .replace(/'([^'\\]*)'/g, '"$1"')
-    .replace(/,(\s*[}\]])/g, "$1")
-    .replace(/([{,]\s*)([A-Za-z_$][A-Za-z0-9_$]*)\s*:/g, '$1"$2":')
-    .replace(/\/\/.*$/gm, "");
-  try {
-    return JSON.parse(body);
-  } catch {
-    return undefined;
-  }
-}

package/lib/starter/_README.md

@@ -1,6 +1,6 @@
 # __APP_NAME__
 
-Scaffolded with [`rahman-resources`](https://www.npmjs.com/package/rahman-resources) — Next 16 + React 19 + Convex (self-hosted) + Tailwind 4 + shadcn/ui.
+Scaffolded with [`rahman-resources`](https://www.npmjs.com/package/rahman-resources) — Next 16 + React 19 + Convex + Tailwind 4 + shadcn/ui.
 
 ## Setup
 
@@ -11,21 +11,44 @@ npx convex dev --once                 # generates convex/_generated
 npm run dev
 ```
 
-## Add a layout / recipe / feature
+## Add a slice
+
+Browse the live showcase — the [Grand Tour](https://resource.rahmanef.com/tour) —
+where every slice is mounted live with its `add` command. Then:
 
 ```bash
 npx rahman-resources list
 npx rahman-resources info <slug>
-npx rahman-resources add personal-brand-os .   # full-app template (T1)
-npx rahman-resources add ai-sdk-openrouter .   # feature (npm install)
+npx rahman-resources add landing-sections .    # marketing sections (hero/pricing/faq/blog…)
+npx rahman-resources add ai-chat .             # AI chat workbench
+npx rahman-resources add appshell .            # windowed web-OS shell
 ```
 
+> rr is a **slice picker**: each `add` copies files into `slices/<slug>/`, which
+> you own and edit. The showcase at `/tour` is Convex-free (localStorage demo
+> adapters); your app wires the slice into your own backend.
+
+## Deploy — Vercel + Convex Cloud
+
+`vercel.json` sets `buildCommand: npm run build:auto`, which adapts to your env:
+
+| `CONVEX_DEPLOY_KEY` | What `build:auto` runs |
+|---|---|
+| **set** | `setup-auth` (one-time `@convex-dev/auth` keys) → `convex deploy --cmd 'next build'` — deploys functions to Convex Cloud, codegens `convex/_generated`, and injects `NEXT_PUBLIC_CONVEX_URL` into the build. |
+| **unset** | plain `next build` — zero-config deploy of the scaffold as-is (no backend wired yet). |
+
+So a fresh deploy is green either way: set `CONVEX_DEPLOY_KEY` in Vercel for the
+full Cloud-backed app, or leave it unset to ship the static scaffold first.
+
+> **Self-hosted (Docker/Dokploy):** commit `convex/_generated` so the container
+> typecheck/build runs without codegen — see `.gitignore`. (Vercel + Convex Cloud
+> needs no commit; `build:auto` codegens during deploy.)
+
 ## Hard rules
 
 - **NO Clerk.** Auth = `@convex-dev/auth`.
 - **shadcn primitives only** — no raw `<dialog>`, `<input type=date|file>`.
 - Use `proxy.ts` (not `middleware.ts`) on Next 16.
-- `convex/_generated` MUST be committed before deploy.
 
 ## Stack
 
@@ -33,5 +56,5 @@ npx rahman-resources add ai-sdk-openrouter .   # feature (npm install)
 |---|---|
 | Framework | Next.js 16 (App Router + cacheComponents) |
 | UI | React 19 + Tailwind 4 + shadcn |
-| Backend | Convex (self-hosted compatible) |
+| Backend | Convex (Cloud or self-hosted) |
 | Auth | `@convex-dev/auth` (Password provider by default) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rahman-resources",
-  "version": "1.13.2",
+  "version": "1.14.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",
@@ -29,12 +29,12 @@
     "gen": "node scripts/gen-manifest.mjs",
     "validate": "node scripts/validate.mjs",
     "validate:slices": "node scripts/validate-slice.mjs",
-    "validate:parity": "node scripts/validate-slice-parity.mjs",
+    "validate:parity": "node ../../scripts/features/gen-slice-catalog.mjs --check",
     "validate:structure": "node scripts/validate-structure.mjs",
-    "validate:all": "node scripts/validate.mjs && node scripts/validate-slice.mjs --check && node scripts/validate-slice-parity.mjs && node scripts/validate-structure.mjs",
+    "validate:all": "node scripts/validate.mjs && node scripts/validate-slice.mjs --check && node ../../scripts/features/gen-slice-catalog.mjs --check && node scripts/validate-structure.mjs",
     "sync:skills": "node scripts/sync-skills.mjs",
     "sync:skills:check": "node scripts/sync-skills.mjs --check",
-    "prepublishOnly": "node scripts/sync-skills.mjs --check && node scripts/validate.mjs && node scripts/validate-slice.mjs --check && node scripts/validate-slice-parity.mjs && node scripts/validate-structure.mjs"
+    "prepublishOnly": "node scripts/sync-skills.mjs --check && node scripts/validate.mjs && node scripts/validate-slice.mjs --check && node ../../scripts/features/gen-slice-catalog.mjs --check && node scripts/validate-structure.mjs"
   },
   "dependencies": {
     "kleur": "^4.1.5",