rahman-resources 0.2.1 → 0.4.1

package/README.md

@@ -1,18 +1,27 @@
 # rahman-resources
 
-Template installer for the [Rahman Resources kitab](https://github.com/rahmanef63/resource-site).
+Scaffolder + template installer for the [Rahman Resources kitab](https://github.com/rahmanef63/resource-site).
 
-## Usage
+## Quick start
 
 ```bash
-npx rahman-resources add <template> [target-dir]
-pnpm dlx rahman-resources add <template> [target-dir]
+npx rahman-resources init my-app
+cd my-app
+cp .env.example .env.local         # fill NEXT_PUBLIC_CONVEX_URL
+npm install --legacy-peer-deps
+npx convex dev --once               # generates convex/_generated
+npm run dev
 ```
 
-### List templates
+`init` ships a minimal Next 16 + React 19 + Convex + Tailwind 4 + shadcn/ui skeleton (~18 files). Then drop in any layout/recipe/feature with `add`.
+
+## Commands
 
 ```bash
-npx rahman-resources list
+npx rahman-resources init <app-name>             # scaffold fresh project
+npx rahman-resources add <slug> [target-dir]     # drop in a layout/recipe/feature
+npx rahman-resources list [layouts|recipes|features]
+npx rahman-resources info <slug>
 ```
 
 ### Inspect a template
@@ -24,11 +33,11 @@ npx rahman-resources info personal-brand-os
 ### Install into a project
 
 ```bash
-# new project
-mkdir my-app && cd my-app && pnpm init
-npx rahman-resources add personal-brand-os .
+# fresh
+npx rahman-resources init my-app
+cd my-app && npx rahman-resources add personal-brand-os .
 
-# existing project
+# existing
 cd existing-app
 npx rahman-resources add personal-brand-os .
 ```

package/bin/cli.js

@@ -1,44 +1,72 @@
 #!/usr/bin/env node
 // rahman-resources — installer for the Rahman kitab.
 // Usage:
+//   npx rahman-resources init <app-name> [--template <slug>] [--features a,b] [--skills x,y]
 //   npx rahman-resources add <slug> [target-dir]
-//   npx rahman-resources list [layouts|recipes|features]
+//   npx rahman-resources add-skill <slug> [target-dir]
+//   npx rahman-resources list [layouts|recipes|features|skills]
 //   npx rahman-resources info <slug>
+//   npx rahman-resources doctor
+//   npx rahman-resources mcp                # not implemented in CLI; install @rahman-resources/mcp
 
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import kleur from "kleur";
 import tiged from "tiged";
 
+import {
+  readRr,
+  writeRr,
+  rrExists,
+  validateRr,
+  addFeature as rrAddFeature,
+  addSkill as rrAddSkill,
+} from "../lib/rr.mjs";
+import { runPostInit } from "../lib/post-init.mjs";
+
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const manifest = require(path.join(__dirname, "../lib/manifest.json"));
+const skillsInventory = require(path.join(__dirname, "../lib/skills.json"));
 
 const REPO = manifest.repo ?? "rahmanef63/resource-site";
 const BRANCH = manifest.branch ?? "main";
+const SKILLS_REPO = "anthropics/skills";
 
 const KINDS = /** @type {const} */ (["layout", "recipe", "feature"]);
 
 const [, , cmd, ...rest] = process.argv;
 
-main().catch((err) => {
-  console.error(kleur.red("✖"), err.message ?? err);
-  process.exit(1);
-});
+queueMicrotask(() =>
+  main().catch((err) => {
+    console.error(kleur.red("✖"), err.message ?? err);
+    process.exit(1);
+  }),
+);
 
 async function main() {
   switch (cmd) {
+    case "init":
+    case "create":
+    case "new":
+      return runInit(rest);
     case "add":
       return runAdd(rest);
+    case "add-skill":
+      return runAddSkill(rest);
     case "list":
     case "ls":
       return runList(rest);
     case "info":
       return runInfo(rest);
+    case "doctor":
+      return runDoctor(rest);
+    case "mcp":
+      return runMcpHint();
     case undefined:
     case "-h":
     case "--help":
@@ -62,21 +90,58 @@ function printVersion() {
 
 function printHelp() {
   console.log(`
-${kleur.bold("rahman-resources")} — install templates, recipes, and features
+${kleur.bold("rahman-resources")} — scaffold + install templates, recipes, features, Claude skills
 
 ${kleur.bold("Usage:")}
+  npx rahman-resources init <app-name> [--template <slug>] [--features a,b] [--skills x,y]
+                                       [--no-install] [--with-shadcn-reinit]
   npx rahman-resources add <slug> [target-dir]
-  npx rahman-resources list [layouts|recipes|features]
+  npx rahman-resources add-skill <slug> [target-dir]
+  npx rahman-resources list [layouts|recipes|features|skills]
   npx rahman-resources info <slug>
+  npx rahman-resources doctor
+  npx rahman-resources mcp
+
+${kleur.bold("Init flags:")}
+  --no-install            skip 'npm install' step (faster scaffolds; you run it manually)
+  --with-shadcn-reinit    delete starter components.json + run 'npx shadcn init -y -d' (canonical shadcn flow)
 
 ${kleur.bold("Examples:")}
-  npx rahman-resources add personal-brand-os my-app    ${kleur.dim("# layout — pulls folders + installs deps")}
-  npx rahman-resources add ai-sdk-openrouter my-app    ${kleur.dim("# feature — runs npm install")}
-  npx rahman-resources add block-editor                ${kleur.dim("# recipe — prints code + source URL")}
-  npx rahman-resources list features
+  npx rahman-resources init my-app
+  npx rahman-resources init my-app --template personal-brand-os --skills frontend-design,mcp-builder
+  npx rahman-resources init my-app --no-install
+  npx rahman-resources add personal-brand-os .
+  npx rahman-resources add-skill webapp-testing
+  npx rahman-resources list skills
 `);
 }
 
+// ─── flag parsing ─────────────────────────────────────────────────────────
+
+function parseFlags(rest) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (next && !next.startsWith("--")) { flags[key] = next; i++; }
+      else flags[key] = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function csv(s) {
+  if (!s || s === true) return [];
+  return String(s).split(",").map((x) => x.trim()).filter(Boolean);
+}
+
+// ─── catalog lookups ──────────────────────────────────────────────────────
+
 function findEntry(slug) {
   for (const kind of KINDS) {
     const list = manifest[kind + "s"];
@@ -86,24 +151,49 @@ function findEntry(slug) {
   return null;
 }
 
+function findSkill(slug) {
+  return skillsInventory.skills.find((s) => s.slug === slug) ?? null;
+}
+
+// ─── list / info ──────────────────────────────────────────────────────────
+
 function runList([filter]) {
-  const groups = filter ? [filter] : ["layouts", "recipes", "features"];
+  const groups = filter
+    ? [filter]
+    : ["layouts", "recipes", "features", "skills"];
   for (const g of groups) {
+    if (g === "skills") {
+      console.log(`\n${kleur.bold("SKILLS")} ${kleur.dim(`(${skillsInventory.skills.length})`)}\n`);
+      for (const s of skillsInventory.skills) {
+        console.log(`  ${kleur.cyan(s.slug.padEnd(28))} ${kleur.dim((s.category ?? "").padEnd(12))} ${s.title}`);
+      }
+      continue;
+    }
     const list = manifest[g];
     if (!list || list.length === 0) continue;
     console.log(`\n${kleur.bold(g.toUpperCase())} ${kleur.dim(`(${list.length})`)}\n`);
     for (const t of list) {
       const cat = (t.category ?? t.source ?? "").padEnd(20).slice(0, 20);
-      console.log(
-        `  ${kleur.cyan(t.slug.padEnd(30))} ${kleur.dim(cat)} ${t.title}`,
-      );
+      console.log(`  ${kleur.cyan(t.slug.padEnd(30))} ${kleur.dim(cat)} ${t.title}`);
     }
   }
-  console.log(`\nRun ${kleur.cyan("info <slug>")} for detail, ${kleur.cyan("add <slug> [target]")} to install.\n`);
+  console.log(`\nRun ${kleur.cyan("info <slug>")} for detail, ${kleur.cyan("add <slug>")} or ${kleur.cyan("add-skill <slug>")} to install.\n`);
 }
 
 function runInfo([slug]) {
   if (!slug) throw new Error("Usage: rahman-resources info <slug>");
+  const skill = findSkill(slug);
+  if (skill) {
+    console.log(`
+${kleur.bold(skill.title)}  ${kleur.dim("[skill]")}  ${kleur.dim(skill.category)}
+
+${skill.description}
+
+${kleur.bold("Source:")}  ${skill.source}/${skill.path}
+${kleur.bold("Install:")} ${kleur.cyan(`npx rahman-resources add-skill ${skill.slug}`)}
+`);
+    return;
+  }
   const found = findEntry(slug);
   if (!found) throw new Error(`Slug not found: ${slug}. Run 'list' to see all.`);
   const { kind, entry: t } = found;
@@ -113,7 +203,6 @@ ${kleur.bold(t.title)}  ${kleur.dim(`[${kind}]`)}  ${kleur.dim(t.category ?? "")
 
 ${t.description}
 `);
-
   if (kind === "layout") {
     console.log(`${kleur.bold("Pulls:")}`);
     console.log(t.pullPaths.map((p) => `  · ${p}`).join("\n") || "  (none)");
@@ -131,11 +220,152 @@ ${t.description}
     console.log(`${kleur.bold("Files:")}`);
     console.log(t.files.map((f) => `  · ${f}`).join("\n"));
   }
-
   if (t.docsUrl) console.log(`\n${kleur.dim(`Docs: ${t.docsUrl}`)}`);
   console.log(`${kleur.dim(`Source: ${t.source ?? "—"}`)}\n`);
 }
 
+// ─── starter copy ─────────────────────────────────────────────────────────
+
+const STARTER_RENAME_PAIRS = [
+  ["_package", "package"],
+  ["_gitignore", ".gitignore"],
+  ["_env", ".env"],
+  ["_README", "README"],
+];
+
+function renameStarterFile(name) {
+  for (const pair of STARTER_RENAME_PAIRS) {
+    const f = pair[0];
+    const t = pair[1];
+    if (name === f || name.startsWith(f + ".")) return t + name.slice(f.length);
+  }
+  return name;
+}
+
+function copyStarterTree(src, dest, appName, slug) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const sFull = path.join(src, entry);
+    const dEntry = renameStarterFile(entry);
+    const dFull = path.join(dest, dEntry);
+    const stat = statSync(sFull);
+    if (stat.isDirectory()) {
+      copyStarterTree(sFull, dFull, appName, slug);
+    } else {
+      let body = readFileSync(sFull, "utf8");
+      body = body.replaceAll("__APP_NAME__", appName).replaceAll("__APP_SLUG__", slug);
+      writeFileSync(dFull, body);
+    }
+  }
+}
+
+// ─── init ─────────────────────────────────────────────────────────────────
+
+async function runInit(rest) {
+  const { positional, flags } = parseFlags(rest);
+  const [appName] = positional;
+  if (!appName || appName.startsWith("-")) {
+    throw new Error("Usage: rahman-resources init <app-name> [--template slug] [--features a,b] [--skills x,y]");
+  }
+  const slug = appName.replace(/[^a-z0-9-_]/gi, "-").toLowerCase();
+  const target = path.resolve(process.cwd(), appName);
+  if (existsSync(target)) {
+    throw new Error(`Directory already exists: ${target}`);
+  }
+
+  const features = csv(flags.features);
+  const skills = csv(flags.skills);
+  const template = typeof flags.template === "string" ? flags.template : null;
+
+  if (template && !findEntry(template)) {
+    throw new Error(`Unknown template: ${template}. Run 'list layouts' to see available.`);
+  }
+  for (const s of skills) {
+    if (!findSkill(s)) throw new Error(`Unknown skill: ${s}. Run 'list skills' to see available.`);
+  }
+  for (const f of features) {
+    if (!findEntry(f)) throw new Error(`Unknown feature: ${f}. Run 'list features' to see available.`);
+  }
+
+  console.log(kleur.bold(`\n→ Scaffolding ${kleur.cyan(slug)} (Next 16 + Convex + shadcn)\n`));
+
+  const starter = path.join(__dirname, "../lib/starter");
+  if (!existsSync(starter)) throw new Error(`Starter not found at ${starter}`);
+
+  process.stdout.write(`  copying starter ... `);
+  copyStarterTree(starter, target, appName, slug);
+  console.log(kleur.green("ok"));
+
+  const skipInstall = !!flags["no-install"];
+  const reinitShadcn = !!flags["with-shadcn-reinit"];
+
+  if (!skipInstall) {
+    console.log(kleur.bold(`\n→ Installing dependencies (npm install --legacy-peer-deps)\n`));
+    try {
+      await runShell("npm", ["install", "--legacy-peer-deps"], target);
+    } catch (err) {
+      console.log(kleur.yellow(`  ⚠ npm install failed (${err.message}). You can rerun manually.`));
+    }
+  } else {
+    console.log(kleur.dim(`\n  (skipping npm install — --no-install)`));
+  }
+
+  if (reinitShadcn && !skipInstall) {
+    console.log(kleur.bold(`\n→ Re-running shadcn init (--with-shadcn-reinit)\n`));
+    try {
+      // Remove pre-baked components.json so shadcn writes a fresh one — post-init re-applies our aliases.
+      const cjPath = path.join(target, "components.json");
+      if (existsSync(cjPath)) writeFileSync(cjPath + ".bak", readFileSync(cjPath, "utf8"));
+      await runShell("npx", ["shadcn@latest", "init", "--yes", "--defaults"], target);
+    } catch (err) {
+      console.log(kleur.yellow(`  ⚠ shadcn init failed (${err.message}). Continuing.`));
+    }
+  } else if (!skipInstall) {
+    console.log(kleur.dim(`\n  (skipping shadcn init — starter already pre-configured. Pass --with-shadcn-reinit to force re-init.)`));
+  }
+
+  process.stdout.write(`\n  post-init restructure ... `);
+  const post = runPostInit(target, { template, features, skills });
+  console.log(kleur.green("ok"));
+  for (const c of post.changed) console.log(`    ${kleur.green("+")} ${c}`);
+  for (const s of post.skipped) console.log(`    ${kleur.dim("-")} ${kleur.dim(s)}`);
+
+  if (template) {
+    console.log(kleur.bold(`\n→ Pulling template ${kleur.cyan(template)}\n`));
+    const t = findEntry(template).entry;
+    for (const p of t.pullPaths ?? []) {
+      const dest = path.join(target, p);
+      process.stdout.write(`  ${kleur.dim(p)} ... `);
+      await pull(p, dest);
+      console.log(kleur.green("ok"));
+    }
+  }
+
+  if (skills.length) {
+    console.log(kleur.bold(`\n→ Pulling ${skills.length} Claude skill(s)\n`));
+    for (const s of skills) await installSkill(s, target);
+  }
+
+  console.log(`\n${kleur.green("✓")} Done. ${kleur.bold(slug)} scaffolded.\n`);
+  console.log(`${kleur.bold("Next:")}`);
+  console.log(`  cd ${appName}`);
+  console.log(`  cp .env.example .env.local   ${kleur.dim("# fill NEXT_PUBLIC_CONVEX_URL")}`);
+  if (skipInstall) console.log(`  npm install --legacy-peer-deps`);
+  console.log(`  npx convex dev --once         ${kleur.dim("# generates convex/_generated")}`);
+  console.log(`  npm run dev\n`);
+}
+
+// Spawn a child process inheriting stdio, resolves on exit 0.
+function runShell(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const ps = spawn(cmd, args, { cwd, stdio: "inherit", shell: true });
+    ps.on("error", reject);
+    ps.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`))));
+  });
+}
+
+// ─── add (template / feature / recipe) ────────────────────────────────────
+
 async function runAdd([slug, targetArg = "."]) {
   if (!slug) {
     console.error(kleur.red("Missing slug."));
@@ -143,11 +373,7 @@ async function runAdd([slug, targetArg = "."]) {
     process.exit(1);
   }
   const found = findEntry(slug);
-  if (!found) {
-    throw new Error(
-      `"${slug}" not found. Run ${kleur.cyan("npx rahman-resources list")}.`,
-    );
-  }
+  if (!found) throw new Error(`"${slug}" not found. Run ${kleur.cyan("npx rahman-resources list")}.`);
   const { kind, entry } = found;
   const target = path.resolve(process.cwd(), targetArg);
 
@@ -179,6 +405,12 @@ async function addLayout(t, target, targetArg) {
     }
   }
 
+  if (rrExists(target)) {
+    const rr = readRr(target);
+    rr.template = { slug: t.slug, version: "main" };
+    writeRr(rr, target);
+  }
+
   console.log(`\n${kleur.green("✓")} Done. ${kleur.bold(t.title)} installed.`);
   if (t.agentRecipe) console.log(`\n${kleur.bold("Next:")}\n${indent(t.agentRecipe, 2)}\n`);
 }
@@ -198,11 +430,15 @@ async function addFeature(t, target, targetArg) {
     }
   }
 
-  console.log(`\n${kleur.green("✓")} Feature added: ${kleur.bold(t.title)}`);
-  if (t.exampleCode) {
-    console.log(`\n${kleur.bold("Example:")}`);
-    console.log(indent(t.exampleCode, 2));
+  if (rrExists(target)) {
+    const rr = readRr(target);
+    rrAddFeature(rr, t.slug);
+    writeRr(rr, target);
+    console.log(kleur.dim(`  rr.json: features += ${t.slug}`));
   }
+
+  console.log(`\n${kleur.green("✓")} Feature added: ${kleur.bold(t.title)}`);
+  if (t.exampleCode) console.log(`\n${kleur.bold("Example:")}\n${indent(t.exampleCode, 2)}`);
   if (t.agentRecipe) console.log(`\n${kleur.bold("Wire-up:")}\n${indent(t.agentRecipe, 2)}\n`);
   if (t.docsUrl) console.log(`\n${kleur.dim(`Docs: ${t.docsUrl}`)}\n`);
 }
@@ -213,20 +449,97 @@ function addRecipe(t) {
   console.log(`\n${kleur.bold("Source:")} ${t.source}`);
   console.log(`\n${kleur.bold("Files to port:")}`);
   console.log(t.files.map((f) => `  · ${f}`).join("\n"));
-  if (t.exampleCode) {
-    console.log(`\n${kleur.bold("Example:")}`);
-    console.log(indent(t.exampleCode, 2));
-  }
+  if (t.exampleCode) console.log(`\n${kleur.bold("Example:")}\n${indent(t.exampleCode, 2)}`);
   if (t.agentRecipe) console.log(`\n${kleur.bold("Wire-up:")}\n${indent(t.agentRecipe, 2)}\n`);
   console.log(kleur.dim(`\n(Recipes are educational patterns — copy from source repo into your project manually.)\n`));
 }
 
+// ─── add-skill ────────────────────────────────────────────────────────────
+
+async function runAddSkill([slug, targetArg = "."]) {
+  if (!slug) throw new Error("Usage: rahman-resources add-skill <slug>");
+  const skill = findSkill(slug);
+  if (!skill) throw new Error(`Unknown skill: ${slug}. Run 'list skills' to see available.`);
+  const target = path.resolve(process.cwd(), targetArg);
+  await installSkill(slug, target);
+
+  if (rrExists(target)) {
+    const rr = readRr(target);
+    rrAddSkill(rr, slug, skill.source);
+    writeRr(rr, target);
+    console.log(kleur.dim(`  rr.json: skills += ${slug}`));
+  }
+
+  console.log(`\n${kleur.green("✓")} Skill installed: ${kleur.bold(skill.title)}`);
+  console.log(kleur.dim(`  Location: .claude/skills/${slug}/`));
+}
+
+async function installSkill(slug, target) {
+  const skill = findSkill(slug);
+  if (!skill) throw new Error(`Unknown skill: ${slug}`);
+  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);
+  } else if (skill.source === "rahman") {
+    // Future: ship rahman-authored skills inside this repo. For now, scaffold a stub.
+    mkdirSync(dest, { recursive: true });
+    writeFileSync(
+      path.join(dest, "SKILL.md"),
+      `---\nname: ${skill.slug}\ndescription: ${skill.description}\n---\n\n# ${skill.title}\n\nStub — to be filled by rahman-resources kitab.\n`,
+    );
+  } else {
+    throw new Error(`Unsupported skill source: ${skill.source}`);
+  }
+  console.log(kleur.green("ok"));
+}
+
+// ─── doctor ───────────────────────────────────────────────────────────────
+
+function runDoctor() {
+  const target = process.cwd();
+  if (!rrExists(target)) {
+    console.log(kleur.yellow("⚠ No rr.json found in cwd. Run 'rahman-resources init <app>' first."));
+    process.exit(1);
+  }
+  const rr = readRr(target);
+  const issues = validateRr(rr);
+  if (issues.length === 0) {
+    console.log(kleur.green("✓ rr.json is valid."));
+    console.log(`  template:  ${kleur.cyan(rr.template?.slug ?? "(none)")}`);
+    console.log(`  features:  ${kleur.cyan(rr.features?.length ?? 0)}`);
+    console.log(`  skills:    ${kleur.cyan(rr.skills?.length ?? 0)}`);
+    return;
+  }
+  console.log(kleur.red(`✖ rr.json has ${issues.length} issue(s):`));
+  for (const i of issues) console.log(`  · ${i}`);
+  process.exit(1);
+}
+
+function runMcpHint() {
+  console.log(`
+${kleur.bold("Rahman Resources MCP server")}
+
+Install + wire it into your Claude Code / Cursor config:
+
+${kleur.cyan(`{
+  "mcpServers": {
+    "rahman-resources": {
+      "command": "npx",
+      "args": ["-y", "@rahman-resources/mcp"]
+    }
+  }
+}`)}
+
+Then in Claude Code: ${kleur.cyan("/mcp")} to see available rr_* tools.
+`);
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
 async function pull(repoPath, dest) {
-  const emitter = tiged(`${REPO}/${repoPath}#${BRANCH}`, {
-    cache: false,
-    force: true,
-    verbose: false,
-  });
+  const emitter = tiged(`${REPO}/${repoPath}#${BRANCH}`, { cache: false, force: true, verbose: false });
   await emitter.clone(dest);
 }
 
@@ -246,9 +559,7 @@ function runPM(pm, deps, cwd) {
   return new Promise((resolve, reject) => {
     const ps = spawn(pm, args, { cwd, stdio: "inherit", shell: true });
     ps.on("error", reject);
-    ps.on("exit", (code) =>
-      code === 0 ? resolve() : reject(new Error(`${pm} ${args[0]} exited ${code}`)),
-    );
+    ps.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${pm} ${args[0]} exited ${code}`))));
   });
 }