rahman-resources 0.1.0 → 0.3.0

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,13 +1,14 @@
 #!/usr/bin/env node
-// rahman-resources — template installer for the Rahman kitab.
+// rahman-resources — installer for the Rahman kitab.
 // Usage:
-//   npx rahman-resources add <template> [target-dir]
-//   npx rahman-resources list
-//   npx rahman-resources info <template>
+//   npx rahman-resources init <app-name> [--lite]
+//   npx rahman-resources add <slug> [target-dir]
+//   npx rahman-resources list [layouts|recipes|features]
+//   npx rahman-resources info <slug>
 
 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";
 
@@ -18,23 +19,33 @@ const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const manifest = require(path.join(__dirname, "../lib/manifest.json"));
 
-const REPO = "rahmanef63/resource-site";
-const BRANCH = "main";
+const REPO = manifest.repo ?? "rahmanef63/resource-site";
+const BRANCH = manifest.branch ?? "main";
+
+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);
-});
+// Defer to next tick so all module-level const declarations finish initializing
+// before the dispatch reaches functions that reference them.
+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 "list":
     case "ls":
-      return runList();
+      return runList(rest);
     case "info":
       return runInfo(rest);
     case undefined:
@@ -42,6 +53,10 @@ async function main() {
     case "--help":
     case "help":
       return printHelp();
+    case "-v":
+    case "--version":
+    case "version":
+      return printVersion();
     default:
       console.error(kleur.red(`Unknown command: ${cmd}`));
       printHelp();
@@ -49,65 +64,187 @@ async function main() {
   }
 }
 
+function printVersion() {
+  const pkg = require(path.join(__dirname, "../package.json"));
+  console.log(pkg.version);
+}
+
 function printHelp() {
   console.log(`
-${kleur.bold("rahman-resources")} — install templates from the Rahman kitab
+${kleur.bold("rahman-resources")} — scaffold + install templates, recipes, features
 
 ${kleur.bold("Usage:")}
-  npx rahman-resources add <template> [target-dir]
-  npx rahman-resources list
-  npx rahman-resources info <template>
+  npx rahman-resources init <app-name> [--lite]
+  npx rahman-resources add <slug> [target-dir]
+  npx rahman-resources list [layouts|recipes|features]
+  npx rahman-resources info <slug>
 
 ${kleur.bold("Examples:")}
-  npx rahman-resources add personal-brand-os my-app
-  pnpm dlx rahman-resources add personal-brand-os .
+  npx rahman-resources init my-app --lite              ${kleur.dim("# scaffold from template-base, prune notion+builder+communications")}
+  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
 `);
 }
 
-function runList() {
-  console.log(kleur.bold("\nAvailable templates:\n"));
-  for (const t of manifest.templates) {
-    console.log(
-      `  ${kleur.cyan(t.slug.padEnd(28))} ${kleur.dim(t.category.padEnd(18))} ${t.title}`,
-    );
+function findEntry(slug) {
+  for (const kind of KINDS) {
+    const list = manifest[kind + "s"];
+    const e = list.find((x) => x.slug === slug);
+    if (e) return { kind, entry: e };
   }
-  console.log(`\n${manifest.templates.length} total. Run ${kleur.cyan("info <slug>")} for detail.\n`);
+  return null;
+}
+
+function runList([filter]) {
+  const groups = filter ? [filter] : ["layouts", "recipes", "features"];
+  for (const g of groups) {
+    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(`\nRun ${kleur.cyan("info <slug>")} for detail, ${kleur.cyan("add <slug> [target]")} to install.\n`);
 }
 
 function runInfo([slug]) {
-  if (!slug) throw new Error("Usage: rahman-resources info <template>");
-  const t = manifest.templates.find((x) => x.slug === slug);
-  if (!t) throw new Error(`Template not found: ${slug}. Run 'list' to see all.`);
+  if (!slug) throw new Error("Usage: rahman-resources info <slug>");
+  const found = findEntry(slug);
+  if (!found) throw new Error(`Slug not found: ${slug}. Run 'list' to see all.`);
+  const { kind, entry: t } = found;
+
   console.log(`
-${kleur.bold(t.title)}  ${kleur.dim(`[${t.category}]`)}
+${kleur.bold(t.title)}  ${kleur.dim(`[${kind}]`)}  ${kleur.dim(t.category ?? "")}
 
 ${t.description}
+`);
 
-${kleur.bold("Pulls:")}
-${t.pullPaths.map((p) => `  · ${p}`).join("\n")}
+  if (kind === "layout") {
+    console.log(`${kleur.bold("Pulls:")}`);
+    console.log(t.pullPaths.map((p) => `  · ${p}`).join("\n") || "  (none)");
+    if (t.dependencies?.length) {
+      console.log(`\n${kleur.bold("Dependencies:")}`);
+      console.log(t.dependencies.map((d) => `  · ${d}`).join("\n"));
+    }
+  } else if (kind === "feature") {
+    console.log(`${kleur.bold("Install:")}\n  ${t.install}`);
+    if (t.npmPackages?.length) {
+      console.log(`\n${kleur.bold("npm packages:")}`);
+      console.log(t.npmPackages.map((d) => `  · ${d}`).join("\n"));
+    }
+  } else if (kind === "recipe") {
+    console.log(`${kleur.bold("Files:")}`);
+    console.log(t.files.map((f) => `  · ${f}`).join("\n"));
+  }
 
-${kleur.bold("Dependencies:")}
-${(t.dependencies ?? []).map((d) => `  · ${d}`).join("\n") || "  (none beyond base)"}
+  if (t.docsUrl) console.log(`\n${kleur.dim(`Docs: ${t.docsUrl}`)}`);
+  console.log(`${kleur.dim(`Source: ${t.source ?? "—"}`)}\n`);
+}
 
-${kleur.dim(`Page: https://github.com/${REPO}/tree/${BRANCH}/${t.repoPath}`)}
-`);
+// Files in lib/starter prefixed with `_` get renamed on copy.
+// Done because npm pack filters .gitignore and warns on nested package.json.
+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);
+    }
+  }
+}
+
+async function runInit([appName, ...flags]) {
+  if (!appName || appName.startsWith("-")) {
+    throw new Error("Usage: rahman-resources init <app-name>");
+  }
+  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}`);
+  }
+
+  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"));
+
+  // Ignore --lite flag for now (no template-base pull yet — starter is minimal already).
+  if (flags.includes("--lite")) {
+    console.log(kleur.dim(`  (--lite is a no-op — starter is already minimal)`));
+  }
+
+  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")}`);
+  console.log(`  npm install --legacy-peer-deps`);
+  console.log(`  npx convex dev --once         ${kleur.dim("# generates convex/_generated")}`);
+  console.log(`  npm run dev\n`);
+  console.log(
+    `${kleur.dim("Then drop in a layout:")} ${kleur.cyan("npx rahman-resources add personal-brand-os .")}\n`,
+  );
 }
 
 async function runAdd([slug, targetArg = "."]) {
   if (!slug) {
-    console.error(kleur.red("Missing template slug."));
+    console.error(kleur.red("Missing slug."));
     printHelp();
     process.exit(1);
   }
-  const t = manifest.templates.find((x) => x.slug === slug);
-  if (!t) {
+  const found = findEntry(slug);
+  if (!found) {
     throw new Error(
-      `Template "${slug}" not found. Run ${kleur.cyan("npx rahman-resources list")} to see available templates.`,
+      `"${slug}" not found. Run ${kleur.cyan("npx rahman-resources list")}.`,
     );
   }
+  const { kind, entry } = found;
   const target = path.resolve(process.cwd(), targetArg);
 
+  if (kind === "layout") return addLayout(entry, target, targetArg);
+  if (kind === "feature") return addFeature(entry, target, targetArg);
+  if (kind === "recipe") return addRecipe(entry);
+}
+
+async function addLayout(t, target, targetArg) {
   console.log(kleur.bold(`\n→ Installing ${kleur.cyan(t.title)} into ${kleur.dim(target)}\n`));
+  if (!t.pullPaths || t.pullPaths.length === 0) {
+    throw new Error(`Layout "${t.slug}" has no valid pullPaths in manifest.`);
+  }
   for (const p of t.pullPaths) {
     const dest = path.join(target, p);
     process.stdout.write(`  pulling ${kleur.dim(p)} ... `);
@@ -119,19 +256,53 @@ async function runAdd([slug, targetArg = "."]) {
     const pm = detectPM(target);
     console.log(kleur.bold(`\n→ Installing dependencies via ${kleur.cyan(pm)}\n`));
     if (!hasPackageJson(target)) {
-      console.log(
-        kleur.yellow(`  ${target}/package.json not found — skipping install.`),
-      );
-      console.log(kleur.dim(`  Run later: cd ${targetArg} && ${pm} add ${t.dependencies.join(" ")}`));
+      console.log(kleur.yellow(`  ${target}/package.json not found — skipping install.`));
+      console.log(kleur.dim(`  Run later: cd ${targetArg} && ${pm} ${pm === "npm" ? "install" : "add"} ${t.dependencies.join(" ")}`));
     } else {
-      await runInstall(pm, t.dependencies, target);
+      await runPM(pm, t.dependencies, 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`);
+  if (t.agentRecipe) console.log(`\n${kleur.bold("Next:")}\n${indent(t.agentRecipe, 2)}\n`);
+}
+
+async function addFeature(t, target, targetArg) {
+  console.log(kleur.bold(`\n→ Adding feature ${kleur.cyan(t.title)} to ${kleur.dim(target)}\n`));
+  if (!t.npmPackages || t.npmPackages.length === 0) {
+    console.log(kleur.dim(`  No npm packages to install (${t.install}).`));
+  } else {
+    const pm = detectPM(target);
+    if (!hasPackageJson(target)) {
+      console.log(kleur.yellow(`  ${target}/package.json not found — skipping install.`));
+      console.log(kleur.dim(`  Run later: cd ${targetArg} && ${pm} ${pm === "npm" ? "install" : "add"} ${t.npmPackages.join(" ")}`));
+    } else {
+      console.log(kleur.dim(`  via ${pm}: ${t.npmPackages.join(" ")}\n`));
+      await runPM(pm, t.npmPackages, target);
+    }
+  }
+
+  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 (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`);
+}
+
+function addRecipe(t) {
+  console.log(`\n${kleur.bold(t.title)} ${kleur.dim("(recipe — manual port)")}\n`);
+  console.log(t.description);
+  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.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`));
 }
 
 async function pull(repoPath, dest) {
@@ -154,7 +325,7 @@ function hasPackageJson(target) {
   return existsSync(path.join(target, "package.json"));
 }
 
-function runInstall(pm, deps, cwd) {
+function runPM(pm, deps, cwd) {
   const args = pm === "npm" ? ["install", ...deps] : ["add", ...deps];
   return new Promise((resolve, reject) => {
     const ps = spawn(pm, args, { cwd, stdio: "inherit", shell: true });