feat: add project initialization command and update README for template usage

Author: avi9611

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Lint
+        run: npm run lint

README.md

@@ -29,40 +29,44 @@ A production-ready, opinionated Next.js frontend template by Hybrid Interactive.
 
 ## Quick Start
 
-### 1. Clone or create from template
+### 1. Create your repo from the template
 
-```bash
-# Option A: clone directly
-git clone <repo-url> my-project
-cd my-project
+Click **"Use this template"** on GitHub → **"Create a new repository"** → name your repo → click **"Create repository"**.
+
+> First time? Go to the [template repo](https://github.com/hybridinteractive/nextjs-template) and click the green **"Use this template"** button.
+
+### 2. Clone and enter the repo
 
-# Option B: bootstrap from template CLI (from the nextjs-template directory)
-node ncube.js create my-project --variant rbac
-cd ../my-project
+```bash
+git clone https://github.com/<your-org>/<your-repo>.git
+cd <your-repo>
 ```
 
-### 2. Install dependencies
+### 3. Install dependencies
 
 ```bash
 npm install
 ```
 
-### 3. Set up environment
+### 4. Run the init command
 
 ```bash
-cp .env.example .env
-# Edit .env — at minimum set NEXT_PUBLIC_API_URL
+node ncube.js init          # or: node ncube.js init my-app-name
 ```
 
-### 4. Install shadcn/ui components
+This does three things in one step:
+- Sets the project name in `package.json`
+- Creates `.env` from `.env.example` (with your app name pre-filled)
+- Installs all shadcn/ui components into `src/components/ui/`
+
+### 5. Configure your backend URL
 
 ```bash
-node ncube.js setup
-# or manually:
-npx shadcn@latest add button input label card badge dialog dropdown-menu sheet table tabs skeleton avatar separator scroll-area form select checkbox switch textarea popover command
+# Edit .env — at minimum set:
+NEXT_PUBLIC_API_URL="http://localhost:8000"
 ```
 
-### 5. Start development server
+### 6. Start the development server
 
 ```bash
 npm run dev
@@ -72,6 +76,22 @@ Open [http://localhost:3000](http://localhost:3000).
 
 ---
 
+### Legacy: bootstrap from a local clone
+
+If you prefer to work from a local copy of the template instead of GitHub's "Use this template":
+
+```bash
+# From inside the nextjs-template directory:
+node ncube.js create my-app [--variant base|rbac|full]
+cd ../my-app
+npm install
+npm run dev
+```
+
+> `create` is deprecated in favour of the template flow above. It still works but will show a notice.
+
+---
+
 ## Project Structure
 
 ```
@@ -122,19 +142,15 @@ src/
 
 ## Variants
 
-Three variants are available via the CLI:
+When you use **"Use this template"** on GitHub, you always get the **full** variant — everything included. No selection needed.
 
-| Variant | Includes | Use when |
-|---------|----------|----------|
-| `base` | Auth, layout shell, no RBAC | Simple internal tools, single-role apps |
-| `rbac` *(default)* | Base + full permissions/RBAC system | Most SaaS apps, multi-role dashboards |
-| `full` | RBAC + access-control admin panel | Platforms with custom role management |
+| Variant | Includes | How to get it |
+|---------|----------|---------------|
+| `full` *(default via template)* | Auth + full RBAC + access-control admin panel | Use GitHub "Use this template" |
+| `rbac` | Auth + full RBAC, no admin panel | Use template → delete `src/app/(dashboard)/access-control/` |
+| `base` | Auth + layout shell, no RBAC | Use template → delete `src/lib/permissions/` and `src/app/(dashboard)/access-control/` |
 
-```bash
-node ncube.js create my-app --variant base
-node ncube.js create my-app --variant rbac   # default
-node ncube.js create my-app --variant full
-```
+> For local bootstrapping (deprecated), the `create` command still supports `--variant base|rbac|full`.
 
 ---
 
@@ -143,6 +159,9 @@ node ncube.js create my-app --variant full
 The `ncube.js` CLI mirrors the FastAPI `fcube.py` module generator. It scaffolds complete feature domains following the architecture conventions.
 
 ```bash
+# Post-clone setup (name, .env, shadcn) — run once after cloning
+node ncube.js init [my-app-name]
+
 # Scaffold a new domain
 node ncube.js startdomain Product
 node ncube.js startdomain LeadManagement
@@ -151,10 +170,10 @@ node ncube.js startdomain InvoiceItem
 # List existing domains
 node ncube.js listdomains
 
-# Install shadcn/ui components
+# Install shadcn/ui components (included in init, but can run standalone)
 node ncube.js setup
 
-# Bootstrap a new project
+# (Deprecated) Bootstrap locally from the template directory
 node ncube.js create my-app [--variant base|rbac|full]
 ```
 

ncube.js

@@ -5,11 +5,12 @@
  * Mirrors the FastAPI fcube.py module generator for frontend domains.
  *
  * Commands:
+ *   node ncube.js init [name]                — post-clone setup (name, .env, shadcn)
  *   node ncube.js startdomain <DomainName>   — scaffold a new feature domain
  *   node ncube.js listdomains                — list existing domains in lib/
  *   node ncube.js setup                      — install shadcn/ui components
  *   node ncube.js create <name> [--variant base|rbac|full]
- *                                            — bootstrap a new project from this template
+ *                                            — (deprecated) bootstrap from local template
  */
 
 const fs = require("fs");
@@ -692,7 +693,98 @@ function cmdSetup() {
   }
 }
 
+function cmdInit(rawArgs) {
+  // Determine app name
+  // Priority: positional arg → --name flag → current directory name
+  const nameFlag = rawArgs.indexOf("--name");
+  let appName;
+  if (nameFlag !== -1 && rawArgs[nameFlag + 1]) {
+    appName = toKebabCase(rawArgs[nameFlag + 1]);
+  } else {
+    const positional = rawArgs.find((a) => !a.startsWith("--"));
+    appName = positional
+      ? toKebabCase(positional)
+      : path.basename(process.cwd());
+  }
+
+  header(`Initializing project: ${appName}`);
+
+  // 1. Update package.json name
+  const pkgPath = path.join(process.cwd(), "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const oldName = pkg.name;
+    if (oldName !== appName) {
+      pkg.name = appName;
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      ok(`package.json name: ${c.dim}${oldName}${c.reset} → ${c.green}${appName}${c.reset}`);
+    } else {
+      ok(`package.json name: ${appName} (already set)`);
+    }
+  }
+
+  // 2. Create .env from .env.example if not already present
+  const envExamplePath = path.join(process.cwd(), ".env.example");
+  const envPath = path.join(process.cwd(), ".env");
+  if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+    let envContent = fs.readFileSync(envExamplePath, "utf8");
+    envContent = envContent.replace(
+      /^NEXT_PUBLIC_APP_NAME=.*$/m,
+      `NEXT_PUBLIC_APP_NAME="${appName}"`,
+    );
+    fs.writeFileSync(envPath, envContent);
+    ok("Created .env from .env.example");
+  } else if (fs.existsSync(envPath)) {
+    info(".env already exists — skipping");
+  } else {
+    warn(".env.example not found — skipping .env creation");
+  }
+
+  // 3. Install shadcn components if src/components/ui/ is missing or empty
+  const hasSrc = fs.existsSync(path.join(process.cwd(), "src"));
+  const uiDir = hasSrc
+    ? path.join(process.cwd(), "src", "components", "ui")
+    : path.join(process.cwd(), "components", "ui");
+  const needsSetup =
+    !fs.existsSync(uiDir) || fs.readdirSync(uiDir).length === 0;
+
+  if (needsSetup) {
+    cmdSetup();
+  } else {
+    ok("shadcn/ui components already installed — skipping setup");
+  }
+
+  console.log("");
+  header("You're ready!");
+  dim("Next steps:");
+  dim("  1. Edit .env — set NEXT_PUBLIC_API_URL to your backend URL");
+  dim("  2. npm run dev");
+  console.log("");
+  info("Add feature domains with:  node ncube.js startdomain <Name>");
+  console.log("");
+}
+
 function cmdCreate(projectName, variant) {
+  // ── Deprecation notice ────────────────────────────────────────────────────────
+  console.log("");
+  console.log(`${c.yellow}${c.bold}⚠  Deprecation notice${c.reset}`);
+  console.log(
+    `${c.dim}  'create' is no longer the recommended way to start a project.${c.reset}`,
+  );
+  console.log(
+    `${c.dim}  Use GitHub's "Use this template" button instead:${c.reset}`,
+  );
+  console.log(
+    `${c.dim}    1. Click "Use this template" on GitHub → name your repo${c.reset}`,
+  );
+  console.log(
+    `${c.dim}    2. git clone <your-repo> && cd <your-repo>${c.reset}`,
+  );
+  console.log(`${c.dim}    3. npm install && node ncube.js init${c.reset}`);
+  console.log(`${c.dim}  Continuing with local 'create' anyway…${c.reset}`);
+  console.log("");
+  // ─────────────────────────────────────────────────────────────────────────────
+
   if (!projectName) {
     err("Usage: node ncube.js create <project-name> [--variant base|rbac|full]");
     process.exit(1);
@@ -886,23 +978,27 @@ function main() {
 ${c.bold}${c.blue}NCube CLI${c.reset} — Next.js scaffolding tool
 
 ${c.bold}Commands:${c.reset}
+  ${c.cyan}init${c.reset} [name]                           Post-clone setup: name, .env, shadcn
   ${c.cyan}startdomain${c.reset} <DomainName>              Scaffold a new feature domain
   ${c.cyan}listdomains${c.reset}                           List existing domains
   ${c.cyan}setup${c.reset}                                 Install shadcn/ui components
-  ${c.cyan}create${c.reset} <name> [--variant base|rbac|full]  Bootstrap a new project
+  ${c.cyan}create${c.reset} <name> [--variant base|rbac|full]  ${c.dim}(deprecated)${c.reset} Bootstrap locally
   ${c.cyan}bump${c.reset} <patch|minor|major>              Bump version + add changelog entry
 
 ${c.bold}Examples:${c.reset}
+  node ncube.js init my-saas
   node ncube.js startdomain Product
   node ncube.js listdomains
   node ncube.js setup
-  node ncube.js create my-saas --variant rbac
   node ncube.js bump minor
 `);
     return;
   }
 
   switch (command) {
+    case "init":
+      cmdInit(rest);
+      break;
     case "startdomain":
       cmdStartDomain(rest[0]);
       break;

package.json

@@ -8,7 +8,8 @@
     "start": "next start",
     "lint": "next lint",
     "type-check": "tsc --noEmit",
-    "setup": "node ncube.js setup"
+    "setup": "node ncube.js setup",
+    "init": "node ncube.js init"
   },
   "dependencies": {
     "@hookform/resolvers": "^3.10.0",