rahman-resources 0.2.1 → 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 — installer for the Rahman kitab.
 // Usage:
+//   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";
 
@@ -25,13 +26,21 @@ 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":
@@ -62,14 +71,16 @@ function printVersion() {
 
 function printHelp() {
   console.log(`
-${kleur.bold("rahman-resources")} — install templates, recipes, and features
+${kleur.bold("rahman-resources")} — scaffold + install templates, recipes, features
 
 ${kleur.bold("Usage:")}
+  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 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")}
@@ -136,6 +147,79 @@ ${t.description}
   console.log(`${kleur.dim(`Source: ${t.source ?? "—"}`)}\n`);
 }
 
+// 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 slug."));

package/lib/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 2,
-  "generatedAt": "2026-05-05T11:50:32.844Z",
+  "generatedAt": "2026-05-05T12:19:53.839Z",
   "repo": "rahmanef63/resource-site",
   "branch": "main",
   "layouts": [

package/lib/starter/_README.md

@@ -0,0 +1,37 @@
+# __APP_NAME__
+
+Scaffolded with [`rahman-resources`](https://www.npmjs.com/package/rahman-resources) — Next 16 + React 19 + Convex (self-hosted) + Tailwind 4 + shadcn/ui.
+
+## Setup
+
+```bash
+npm install --legacy-peer-deps
+cp .env.example .env.local           # fill NEXT_PUBLIC_CONVEX_URL etc.
+npx convex dev --once                 # generates convex/_generated
+npm run dev
+```
+
+## Add a layout / recipe / feature
+
+```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)
+```
+
+## 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
+
+| | |
+|---|---|
+| Framework | Next.js 16 (App Router + cacheComponents) |
+| UI | React 19 + Tailwind 4 + shadcn |
+| Backend | Convex (self-hosted compatible) |
+| Auth | `@convex-dev/auth` (Password provider by default) |

package/lib/starter/_env.example

@@ -0,0 +1,16 @@
+# Convex (self-hosted or cloud)
+NEXT_PUBLIC_CONVEX_URL=
+
+# @convex-dev/auth — required for auth signing
+JWKS=
+JWT_PRIVATE_KEY=
+SITE_URL=http://localhost:3000
+
+# Server actions encryption (multi-instance — pin once, share across instances)
+NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=
+
+# Optional OAuth providers
+AUTH_GITHUB_ID=
+AUTH_GITHUB_SECRET=
+AUTH_GOOGLE_ID=
+AUTH_GOOGLE_SECRET=

package/lib/starter/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+.next
+.turbo
+out
+dist
+.env*.local
+.env
+*.tsbuildinfo
+next-env.d.ts
+convex/_generated
+.vercel
+.DS_Store

package/lib/starter/_package.json

@@ -0,0 +1,39 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --turbo --port 3000",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit",
+    "convex:dev": "convex dev",
+    "convex:codegen": "convex dev --once"
+  },
+  "dependencies": {
+    "@convex-dev/auth": "^0.0.84",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "convex": "^1.18.0",
+    "lucide-react": "^0.460.0",
+    "next": "^16.0.0",
+    "next-themes": "^0.4.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sonner": "^1.7.1",
+    "tailwind-merge": "^2.5.5"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.0.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "postcss": "^8.5.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/lib/starter/app/globals.css

@@ -0,0 +1,85 @@
+@import "tailwindcss";
+
+@theme {
+  --font-sans: var(--font-sans), ui-sans-serif, system-ui, sans-serif;
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.625rem;
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(1 0 0 / 0.1);
+  --input: oklch(1 0 0 / 0.15);
+  --ring: oklch(0.556 0 0);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+* {
+  border-color: var(--color-border);
+}
+
+body {
+  background: var(--color-background);
+  color: var(--color-foreground);
+}

package/lib/starter/app/layout.tsx

@@ -0,0 +1,23 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import { ConvexClientProvider } from "@/components/convex-provider";
+import { Toaster } from "sonner";
+import "./globals.css";
+
+const inter = Inter({ subsets: ["latin"], variable: "--font-sans" });
+
+export const metadata: Metadata = {
+  title: { default: "__APP_NAME__", template: "%s — __APP_NAME__" },
+  description: "Built with rahman-resources kitab.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${inter.variable} font-sans antialiased`}>
+        <ConvexClientProvider>{children}</ConvexClientProvider>
+        <Toaster position="bottom-right" />
+      </body>
+    </html>
+  );
+}

package/lib/starter/app/page.tsx

@@ -0,0 +1,26 @@
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+
+export default function HomePage() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-6 p-8 text-center">
+      <div className="max-w-xl space-y-3">
+        <h1 className="text-4xl font-bold tracking-tight">__APP_NAME__</h1>
+        <p className="text-muted-foreground">
+          Scaffolded with <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-sm">rahman-resources</code>.
+          Drop in a layout next:
+        </p>
+      </div>
+      <pre className="rounded-md bg-muted px-4 py-3 text-left text-sm">
+{`npx rahman-resources add personal-brand-os .
+npx rahman-resources add landing-bento .
+npx rahman-resources list`}
+      </pre>
+      <Button asChild>
+        <Link href="https://github.com/rahmanef63/resource-site" target="_blank" rel="noreferrer">
+          Browse the kitab
+        </Link>
+      </Button>
+    </main>
+  );
+}

package/lib/starter/components/convex-provider.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import { ConvexAuthNextjsProvider } from "@convex-dev/auth/nextjs";
+import { ConvexReactClient } from "convex/react";
+import type { ReactNode } from "react";
+
+const url = process.env.NEXT_PUBLIC_CONVEX_URL;
+const convex = url ? new ConvexReactClient(url) : null;
+
+export function ConvexClientProvider({ children }: { children: ReactNode }) {
+  if (!convex) return <>{children}</>;
+  return <ConvexAuthNextjsProvider client={convex}>{children}</ConvexAuthNextjsProvider>;
+}

package/lib/starter/components/ui/button.tsx

@@ -0,0 +1,43 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline: "border bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        secondary: "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return <Comp className={cn(buttonVariants({ variant, size, className }))} ref={ref} {...props} />;
+  },
+);
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

package/lib/starter/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/lib/starter/convex/auth.ts

@@ -0,0 +1,6 @@
+import { convexAuth } from "@convex-dev/auth/server";
+import { Password } from "@convex-dev/auth/providers/Password";
+
+export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
+  providers: [Password()],
+});

package/lib/starter/convex/http.ts

@@ -0,0 +1,7 @@
+import { httpRouter } from "convex/server";
+import { auth } from "./auth";
+
+const http = httpRouter();
+auth.addHttpRoutes(http);
+
+export default http;

package/lib/starter/convex/schema.ts

@@ -0,0 +1,14 @@
+import { authTables } from "@convex-dev/auth/server";
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  ...authTables,
+  // Add app tables here. Example:
+  // notes: defineTable({
+  //   userId: v.id("users"),
+  //   title: v.string(),
+  //   body: v.string(),
+  //   createdAt: v.number(),
+  // }).index("by_user", ["userId"]),
+});

package/lib/starter/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/lib/starter/next.config.mjs

@@ -0,0 +1,16 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  cacheComponents: true,
+  experimental: {
+    serverActions: {
+      bodySizeLimit: "5mb",
+    },
+  },
+  images: {
+    remotePatterns: [
+      { protocol: "https", hostname: "images.unsplash.com" },
+    ],
+  },
+};
+
+export default nextConfig;

package/lib/starter/postcss.config.mjs

@@ -0,0 +1,3 @@
+export default {
+  plugins: { "@tailwindcss/postcss": {} },
+};

package/lib/starter/proxy.ts

@@ -0,0 +1,12 @@
+// Next 16 proxy (renamed from middleware.ts).
+// Stub — extend with auth gate via convexAuthNextjsToken() when ready.
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function proxy(_req: NextRequest) {
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+};

package/lib/starter/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", "convex/_generated"]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rahman-resources",
-  "version": "0.2.1",
-  "description": "Template installer for Rahman Resources kitab — npx rahman-resources add <template> <target>",
+  "version": "0.3.0",
+  "description": "Scaffolder + installer for Rahman Resources kitab — npx rahman-resources init <app>; add <template>; list; info",
   "type": "module",
   "license": "MIT",
   "author": "Rahman <casadezian@gmail.com>",