@dinakars777/create-nexus 1.0.0 → 1.1.0

package/README.md

@@ -1,40 +1,55 @@
-# 🧠 create-nexus
+# create-nexus 🧠
 
-> **The Ultimate Agent-Native Boilerplate Generator.**
+[![npm version](https://img.shields.io/npm/v/@dinakars777/create-nexus.svg?style=flat-square)](https://www.npmjs.com/package/@dinakars777/create-nexus)
+[![npm downloads](https://img.shields.io/npm/dm/@dinakars777/create-nexus.svg?style=flat-square)](https://www.npmjs.com/package/@dinakars777/create-nexus)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-Most Next.js boilerplates are optimized for human readability.
-**Project Nexus** is optimized to be perfectly indexed, mutated, and scaled by AI Coding Agents (Cursor, Claude, Devin) with *zero hallucinations*.
+> The Ultimate Agent-Native Boilerplate Generator.
+
+Most Next.js boilerplates are optimized for human readability. **create-nexus** is optimized to be perfectly indexed, mutated, and scaled by AI coding agents (Cursor, Claude, Devin) with zero hallucinations.
 
 ## The Problem
-When you ask an AI Agent to "build a feature" in a standard Next.js codebase, it hallucinates. It mixes Pages Router with App Router, it writes raw SQL instead of using your ORM, or it bypasses your API layer entirely to write Server Actions in the UI. 
 
-## The Solution
-`create-nexus` generates a fortress. It scaffolds a high-density, strictly-typed environment (Next.js, Hono, Drizzle, Zod) that includes a built-in **Context Control Plane** explicitly designed to govern AI behavior.
+When you ask an AI agent to "build a feature" in a standard Next.js codebase, it hallucinates. It mixes Pages Router with App Router, writes raw SQL instead of using your ORM, or bypasses your API layer entirely. **create-nexus** generates a fortress that governs AI behavior by design.
 
-### 📦 The Tech Stack
-*   **Frontend:** Next.js (App Router) + Tailwind CSS
-*   **API:** Hono RPC (End-to-End Type Safety)
-*   **Database:** Drizzle ORM + Postgres
-*   **Validation:** Strict Zod Boundaries
+## Quick Start
 
-### 🤖 The Agent-Native Architecture
-When you run the generator, you aren't just getting React components. You get:
+```bash
+npx @dinakars777/create-nexus
+```
 
-1.  **The `.agent/` Control Directory**: Contains global `rules.md`, an architectural `project-map.json`, and a `scratchpad.md` for the agent to "think" out loud.
-2.  **The Twin-File System**: Every major directory (`src/app`, `src/db`) contains a `CONCEPTS.md`. This defines the Business Logic vs. Implementation boundaries so the agent understands the "why" and doesn't guess context.
-3.  **Strict Type-Safety Walls**: Absolute zero `any` types. Every API route uses `zValidator`. If an agent hallucinates an API shape, the Typescript compiler crashes, forcing the agent to read the error and fix itself.
-4.  **Verification Hooks**: Pre-configured Husky pre-commit hooks run `tsc --noEmit`. If the agent breaks the build, the Git commit natively fails, forcing it to loop until structurally sound.
-5.  **MCP Stub**: An integrated Model Context Protocol server stub (`server/mcp`) allowing local agents to securely query database schemas without reading thousands of lines of code.
+Follow the interactive prompts. The CLI handles directory scaffolding, Git initialization, and dependency installation.
 
-## Quickstart
+## What You Get
 
-Instantly generate your Agent-Native workspace:
+| Feature | Description |
+|---|---|
+| `.agent/` Control Directory | `rules.md`, `project-map.json`, and `scratchpad.md` for agent context |
+| Twin-File System | `CONCEPTS.md` in every major directory defining business logic boundaries |
+| Strict Type-Safety | Zero `any` types, Zod-validated API routes — compiler crashes on hallucinations |
+| Verification Hooks | Husky pre-commit hooks run `tsc --noEmit` — broken builds can't be committed |
+| MCP Stub | Integrated Model Context Protocol server for secure local DB schema queries |
 
-```bash
-npx @dinakars777/create-nexus
-```
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend | Next.js (App Router) + Tailwind CSS |
+| API | Hono RPC (end-to-end type safety) |
+| Database | Drizzle ORM + Postgres |
+| Validation | Zod |
+
+## Templates
 
-Follow the interactive prompts to name your project. The CLI will handle directory scaffolding, Git initialization, and NPM dependency installations.
+The generator supports multiple project types:
+
+| Template | Description |
+|---|---|
+| `stack` | Full-stack Next.js + Hono + Drizzle |
+| `agent` | AI agent scaffold with `.agent/` control plane |
+| `mcp` | Model Context Protocol server stub |
+| `twin` | Twin-file system with `CONCEPTS.md` structure |
 
 ## License
+
 MIT

package/dist/index.js

@@ -252,6 +252,7 @@ async function generateBoilerplate(projectName) {
       "lint": "next lint",
       "check": "tsc --noEmit",
       "db:push": "drizzle-kit push",
+      "db:studio": "drizzle-kit studio",
       "prepare": "husky install"
     },
     dependencies: {
@@ -317,6 +318,140 @@ npx lint-staged
 npm run check
 `;
   await fs.writeFile(path.join(targetDir, ".husky/pre-commit"), huskyPreCommit);
+  const envExample = `# Database
+DATABASE_URL="postgres://localhost:5432/nexus"
+
+# Next.js
+NEXT_PUBLIC_API_URL="http://localhost:3000"
+`;
+  await fs.writeFile(path.join(targetDir, ".env.example"), envExample);
+  const cursorrules = `# Agent Rules for ${projectName}
+
+## Architecture
+- **Frontend**: Next.js App Router (React Server Components)
+- **API**: Hono RPC with end-to-end type safety
+- **Database**: Drizzle ORM + PostgreSQL
+- **Validation**: Zod schemas for all inputs
+
+## Critical Rules
+1. **Verify Before Commit**: Always run \`npm run check\` before committing. Never commit failing code.
+2. **Strict Typing**: Never use \`any\`. Use Zod for all validations.
+3. **Twin-Files**: If you create a new directory, create a \`CONCEPTS.md\` explaining its business logic and boundaries.
+4. **Architecture Limits**: 
+   - Do not import UI components into the API layer
+   - Do not import Drizzle directly into Next.js React UI layer
+   - Use the Hono RPC client (\`hc\`) for all frontend-to-backend communication
+5. **Think First**: Before making massive destructive changes, write your plan in \`.agent/scratchpad.md\`
+
+## Directory Structure
+- \`src/app/\` - Next.js routing and React UI pages (read \`src/app/CONCEPTS.md\`)
+- \`src/server/\` - Hono API backend and RPC routes (read \`src/server/CONCEPTS.md\`)
+- \`src/db/\` - Drizzle schema operations (read \`src/db/CONCEPTS.md\`)
+- \`server/mcp/\` - Model Context Protocol stubs for agent querying
+- \`.agent/\` - Agent control plane (rules, project map, scratchpad)
+
+## Workflow
+1. Read the relevant \`CONCEPTS.md\` file before modifying a directory
+2. Use \`npm run db:studio\` to visualize the database schema
+3. Run \`npm run check\` to verify TypeScript compilation
+4. Check \`.agent/scratchpad.md\` for any ongoing work or notes
+`;
+  await fs.writeFile(path.join(targetDir, ".cursorrules"), cursorrules);
+  const readme = `# ${projectName}
+
+> Agent-Native Next.js boilerplate generated with [create-nexus](https://github.com/dinakars777/create-nexus)
+
+## Stack
+
+- **Frontend**: Next.js 14 (App Router)
+- **API**: Hono RPC (end-to-end type safety)
+- **Database**: Drizzle ORM + PostgreSQL
+- **Validation**: Zod
+- **AI Integration**: Built-in \`.agent/\` control plane + MCP server
+
+## Getting Started
+
+1. **Install dependencies**:
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+2. **Set up environment variables**:
+   \`\`\`bash
+   cp .env.example .env
+   # Edit .env with your DATABASE_URL
+   \`\`\`
+
+3. **Push database schema**:
+   \`\`\`bash
+   npm run db:push
+   \`\`\`
+
+4. **Start development server**:
+   \`\`\`bash
+   npm run dev
+   \`\`\`
+
+5. **Open Drizzle Studio** (optional):
+   \`\`\`bash
+   npm run db:studio
+   \`\`\`
+
+## Architecture
+
+This project follows the **Agent-Native Architecture** pattern:
+
+### The \`.agent/\` Control Plane
+- \`rules.md\` - Global rules for AI agents working on this codebase
+- \`project-map.json\` - High-level architecture overview
+- \`scratchpad.md\` - Temporary workspace for planning complex changes
+
+### The Twin-File System
+Each major directory contains a \`CONCEPTS.md\` file that defines:
+- Business logic boundaries
+- What the directory is responsible for
+- What it should NOT do
+
+This prevents AI agents from hallucinating incorrect architectures.
+
+### Directory Structure
+
+\`\`\`
+${projectName}/
+\u251C\u2500\u2500 .agent/              # Agent control plane
+\u251C\u2500\u2500 src/
+\u2502   \u251C\u2500\u2500 app/            # Next.js pages (read CONCEPTS.md)
+\u2502   \u251C\u2500\u2500 server/         # Hono API routes (read CONCEPTS.md)
+\u2502   \u2514\u2500\u2500 db/             # Drizzle schema (read CONCEPTS.md)
+\u251C\u2500\u2500 server/
+\u2502   \u2514\u2500\u2500 mcp/            # Model Context Protocol server
+\u251C\u2500\u2500 .cursorrules        # AI IDE integration (Cursor, Cline)
+\u2514\u2500\u2500 .husky/             # Git hooks (pre-commit type checking)
+\`\`\`
+
+## Available Scripts
+
+- \`npm run dev\` - Start Next.js development server
+- \`npm run build\` - Build for production
+- \`npm run start\` - Start production server
+- \`npm run check\` - Run TypeScript type checking
+- \`npm run db:push\` - Push schema changes to database
+- \`npm run db:studio\` - Open Drizzle Studio (database GUI)
+
+## Working with AI Agents
+
+This project is optimized for AI coding agents (Cursor, Cline, Claude, etc.):
+
+1. **Read \`.cursorrules\`** - Contains all architectural rules
+2. **Check \`CONCEPTS.md\`** - Before modifying any directory
+3. **Use \`.agent/scratchpad.md\`** - For planning complex changes
+4. **Run \`npm run check\`** - Before committing (enforced by Husky)
+
+## License
+
+MIT
+`;
+  await fs.writeFile(path.join(targetDir, "README.md"), readme);
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinakars777/create-nexus",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Scaffold the ultimate Agent-Native Boilerplate. Next.js, Hono, Drizzle, Zod, with built-in .agent control plane.",
   "main": "dist/index.js",
   "type": "module",

package/src/generator.ts

@@ -58,6 +58,7 @@ export async function generateBoilerplate(projectName: string) {
       "lint": "next lint",
       "check": "tsc --noEmit",
       "db:push": "drizzle-kit push",
+      "db:studio": "drizzle-kit studio",
       "prepare": "husky install"
     },
     dependencies: {
@@ -128,6 +129,145 @@ npx lint-staged
 npm run check
 `;
   await fs.writeFile(path.join(targetDir, '.husky/pre-commit'), huskyPreCommit);
-  // Ensure the hook is executable (not natively supported by fs.writeFile easily cross-platform, but good enough for a generated boilerplate before install)
+
+  // 7. Generate .env.example
+  const envExample = `# Database
+DATABASE_URL="postgres://localhost:5432/nexus"
+
+# Next.js
+NEXT_PUBLIC_API_URL="http://localhost:3000"
+`;
+  await fs.writeFile(path.join(targetDir, '.env.example'), envExample);
+
+  // 8. Generate .cursorrules for AI IDE integration
+  const cursorrules = `# Agent Rules for ${projectName}
+
+## Architecture
+- **Frontend**: Next.js App Router (React Server Components)
+- **API**: Hono RPC with end-to-end type safety
+- **Database**: Drizzle ORM + PostgreSQL
+- **Validation**: Zod schemas for all inputs
+
+## Critical Rules
+1. **Verify Before Commit**: Always run \`npm run check\` before committing. Never commit failing code.
+2. **Strict Typing**: Never use \`any\`. Use Zod for all validations.
+3. **Twin-Files**: If you create a new directory, create a \`CONCEPTS.md\` explaining its business logic and boundaries.
+4. **Architecture Limits**: 
+   - Do not import UI components into the API layer
+   - Do not import Drizzle directly into Next.js React UI layer
+   - Use the Hono RPC client (\`hc\`) for all frontend-to-backend communication
+5. **Think First**: Before making massive destructive changes, write your plan in \`.agent/scratchpad.md\`
+
+## Directory Structure
+- \`src/app/\` - Next.js routing and React UI pages (read \`src/app/CONCEPTS.md\`)
+- \`src/server/\` - Hono API backend and RPC routes (read \`src/server/CONCEPTS.md\`)
+- \`src/db/\` - Drizzle schema operations (read \`src/db/CONCEPTS.md\`)
+- \`server/mcp/\` - Model Context Protocol stubs for agent querying
+- \`.agent/\` - Agent control plane (rules, project map, scratchpad)
+
+## Workflow
+1. Read the relevant \`CONCEPTS.md\` file before modifying a directory
+2. Use \`npm run db:studio\` to visualize the database schema
+3. Run \`npm run check\` to verify TypeScript compilation
+4. Check \`.agent/scratchpad.md\` for any ongoing work or notes
+`;
+  await fs.writeFile(path.join(targetDir, '.cursorrules'), cursorrules);
+
+  // 9. Generate README.md
+  const readme = `# ${projectName}
+
+> Agent-Native Next.js boilerplate generated with [create-nexus](https://github.com/dinakars777/create-nexus)
+
+## Stack
+
+- **Frontend**: Next.js 14 (App Router)
+- **API**: Hono RPC (end-to-end type safety)
+- **Database**: Drizzle ORM + PostgreSQL
+- **Validation**: Zod
+- **AI Integration**: Built-in \`.agent/\` control plane + MCP server
+
+## Getting Started
+
+1. **Install dependencies**:
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+2. **Set up environment variables**:
+   \`\`\`bash
+   cp .env.example .env
+   # Edit .env with your DATABASE_URL
+   \`\`\`
+
+3. **Push database schema**:
+   \`\`\`bash
+   npm run db:push
+   \`\`\`
+
+4. **Start development server**:
+   \`\`\`bash
+   npm run dev
+   \`\`\`
+
+5. **Open Drizzle Studio** (optional):
+   \`\`\`bash
+   npm run db:studio
+   \`\`\`
+
+## Architecture
+
+This project follows the **Agent-Native Architecture** pattern:
+
+### The \`.agent/\` Control Plane
+- \`rules.md\` - Global rules for AI agents working on this codebase
+- \`project-map.json\` - High-level architecture overview
+- \`scratchpad.md\` - Temporary workspace for planning complex changes
+
+### The Twin-File System
+Each major directory contains a \`CONCEPTS.md\` file that defines:
+- Business logic boundaries
+- What the directory is responsible for
+- What it should NOT do
+
+This prevents AI agents from hallucinating incorrect architectures.
+
+### Directory Structure
+
+\`\`\`
+${projectName}/
+├── .agent/              # Agent control plane
+├── src/
+│   ├── app/            # Next.js pages (read CONCEPTS.md)
+│   ├── server/         # Hono API routes (read CONCEPTS.md)
+│   └── db/             # Drizzle schema (read CONCEPTS.md)
+├── server/
+│   └── mcp/            # Model Context Protocol server
+├── .cursorrules        # AI IDE integration (Cursor, Cline)
+└── .husky/             # Git hooks (pre-commit type checking)
+\`\`\`
+
+## Available Scripts
+
+- \`npm run dev\` - Start Next.js development server
+- \`npm run build\` - Build for production
+- \`npm run start\` - Start production server
+- \`npm run check\` - Run TypeScript type checking
+- \`npm run db:push\` - Push schema changes to database
+- \`npm run db:studio\` - Open Drizzle Studio (database GUI)
+
+## Working with AI Agents
+
+This project is optimized for AI coding agents (Cursor, Cline, Claude, etc.):
+
+1. **Read \`.cursorrules\`** - Contains all architectural rules
+2. **Check \`CONCEPTS.md\`** - Before modifying any directory
+3. **Use \`.agent/scratchpad.md\`** - For planning complex changes
+4. **Run \`npm run check\`** - Before committing (enforced by Husky)
+
+## License
+
+MIT
+`;
+  await fs.writeFile(path.join(targetDir, 'README.md'), readme);
 
 }