@nimbuslab/cli 1.1.0 → 1.2.0

package/README.md

@@ -1,136 +1,228 @@
 # @nimbuslab/cli
 
-CLI para criar projetos com a stack moderna da nimbuslab.
+> Modern Next.js project generator with AI-friendly documentation and best practices built-in.
 
-## Instalacao
+Create production-ready Next.js projects in seconds with intelligent setup, optimized documentation for AI coding assistants, and interactive service configuration.
 
-```bash
-npm install -g @nimbuslab/cli
-```
+## Features
 
-## Comandos
+✨ **Modern Stack** - Next.js 16, React 19, TypeScript, Tailwind CSS 4, shadcn/ui
+🤖 **AI-Friendly Documentation** - Auto-generated context files for Claude Code, Cursor, GitHub Copilot
+⚡ **Interactive Setup** - Configure services (email, analytics) during project creation
+📦 **Zero Config** - Smart defaults, production-ready from day one
+🎨 **Beautiful UI** - shadcn/ui components with dark mode support
+
+## Quick Start
 
 ```bash
-nimbus create       # Criar novo projeto (interativo)
-nimbus analyze      # Analisar stack do projeto atual
-nimbus upgrade      # Planejar upgrades de dependencias
-nimbus update       # Atualizar o CLI
-nimbus setup node   # Configurar ambiente Node.js (Volta)
-nimbus help         # Ajuda
+npm install -g @nimbuslab/cli
+nimbus create my-project
 ```
 
 ## Templates
 
 ### Landing Page
 
+Perfect for marketing sites, product launches, and portfolios.
+
 ```bash
-nimbus create meu-site --landing
+nimbus create my-site --landing
 ```
 
-Stack: Next.js 16 + React 19 + Tailwind CSS 4 + shadcn/ui
+**Includes:**
+- Next.js 16 (App Router, Turbopack)
+- React 19 (Server Components)
+- Tailwind CSS 4 (CSS-first)
+- shadcn/ui (default style)
+- TypeScript (strict mode)
+- Responsive design
+- Dark mode support
+- SEO optimized
+
+### Web Application
 
-### Web App
+Full-stack app with authentication and database.
 
 ```bash
-nimbus create meu-app --app
+nimbus create my-app --app
 ```
 
-Stack: Landing + Better Auth + Drizzle ORM + Docker
+**Everything in Landing, plus:**
+- Better Auth (authentication)
+- Drizzle ORM (database)
+- Protected routes
+- User management
+- Dashboard layout
+- Docker support
 
 ### Monorepo
 
+Turborepo setup for multi-app projects.
+
 ```bash
-nimbus create meu-projeto --turborepo
+nimbus create my-workspace --turborepo
 ```
 
-Stack: Turborepo + apps/packages compartilhados
+**Includes:**
+- Turborepo (build system)
+- Shared packages (ui, config, utils)
+- Multiple apps support
+- Optimized caching
+- Parallel execution
+
+## AI-Friendly Documentation
+
+Every project includes automatically generated documentation optimized for LLMs:
 
-## Features AI-Friendly
+### Generated Files
 
-Todos os templates públicos incluem automaticamente:
+- **AGENTS.md** - Universal context for Claude Code, Cursor, GitHub Copilot
+- **llms.txt** - 2026 standard for LLM indexing (ChatGPT, Perplexity)
+- **ARCHITECTURE.md** - Architectural decisions with rationale
+- **EXAMPLES.md** - Common tasks with complete code examples
+- **Compatibility symlinks** - `.cursorrules`, `.github/copilot-instructions.md`
 
-### Documentação Otimizada para LLMs
+### Interactive Service Setup
 
-- **AGENTS.md** - Contexto universal para Claude Code, Cursor, GitHub Copilot
-- **llms.txt** - Padrão 2026 para indexação por LLMs (ChatGPT, Perplexity)
-- **ARCHITECTURE.md** - Decisões arquiteturais explicadas
-- **EXAMPLES.md** - Casos de uso com código completo
-- **Symlinks** - `.cursorrules` e `.github/copilot-instructions.md` apontam para AGENTS.md
+Configure integrations during project creation:
 
-### Setup Interativo de Serviços
+- **Resend** - Transactional email (3,000 emails/month free)
+- **Google Analytics** - Site metrics (free)
 
-Durante a criação do projeto, você pode configurar:
+The CLI provides:
+- Pricing information and signup links
+- API key validation
+- Automatic `.env` and `.env.example` generation
+- Direct links to documentation
 
-- **Resend** - Email transacional (3.000 emails/mês grátis)
-- **Google Analytics** - Métricas do site (grátis)
+Based on [GEO (Generative Engine Optimization)](https://gitbook.com/docs/guides/seo-and-llm-optimization/geo-guide) best practices.
 
-O CLI:
-- Mostra informações de pricing e signup
-- Valida formato das API keys
-- Gera `.env` e `.env.example` automaticamente
-- Inclui links diretos para obter chaves
+## Commands
 
-Baseado em [GEO (Generative Engine Optimization)](https://gitbook.com/docs/guides/seo-and-llm-optimization/geo-guide) e padrões 2026.
+```bash
+nimbus create [name]    # Create new project (interactive)
+nimbus analyze [dir]    # Analyze existing project stack
+nimbus upgrade [target] # Plan dependency upgrades
+nimbus update           # Update CLI itself
+nimbus setup node       # Configure Node.js environment (Volta)
+nimbus help             # Show help
+```
+
+## Options
 
-## Setup Node (Volta)
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Accept defaults (skip prompts) |
+| `--no-git` | Skip Git initialization |
+| `--no-install` | Skip dependency installation |
+| `--landing` | Use landing page template |
+| `--app` | Use web app template |
+| `--turborepo` | Use monorepo template |
 
-O comando `nimbus setup node` configura o ambiente Node.js usando [Volta](https://volta.sh).
+## Examples
 
-**Por que Volta?**
-- fnm e nvm causam problemas de cache do shell
-- Volta nao tem esse problema (binarios nativos)
-- Funciona igual no Linux e Windows
-- Gerencia Node, npm e pacotes globais automaticamente
+### Landing Page (Auto Mode)
 
 ```bash
-# Verificar ambiente atual
-nimbus setup node --check
+nimbus create portfolio --landing -y
+cd portfolio
+bun dev
+```
 
-# Migrar para Volta (interativo)
-nimbus setup node
+### Web App (Interactive)
+
+```bash
+nimbus create dashboard --app
+# Follow prompts for service configuration
+cd dashboard
+bun setup  # Database setup
+bun dev
 ```
 
-O comando:
-1. Detecta fnm/nvm instalados
-2. Remove automaticamente
-3. Instala Volta
-4. Reinstala pacotes globais
+### Analyze Existing Project
+
+```bash
+nimbus analyze ./my-project
+nimbus analyze --json  # JSON output
+```
 
-## Analyze e Upgrade
+### Plan Upgrades
 
 ```bash
-# Analisar projeto existente
-nimbus analyze ./meu-projeto
-nimbus analyze --json
-
-# Planejar upgrades
-nimbus upgrade --plan
-nimbus upgrade tailwind
-nimbus upgrade next
+nimbus upgrade --plan        # Show available upgrades
+nimbus upgrade tailwind      # Upgrade specific package
+nimbus upgrade next          # Upgrade Next.js
 ```
 
-## Opcoes
+## Node.js Setup (Volta)
+
+Configure Node.js environment using [Volta](https://volta.sh).
+
+**Why Volta?**
+- No shell cache issues (unlike fnm/nvm)
+- Native binaries for better performance
+- Cross-platform (Linux, macOS, Windows)
+- Automatic version management per project
+
+```bash
+# Check current environment
+nimbus setup node --check
+
+# Migrate to Volta (interactive)
+nimbus setup node
+```
 
-| Flag | Descricao |
-|------|-----------|
-| `-y, --yes` | Aceitar padroes |
-| `--no-git` | Nao inicializar Git |
-| `--no-install` | Nao instalar dependencias |
+The command will:
+1. Detect existing fnm/nvm installations
+2. Remove them automatically
+3. Install Volta
+4. Reinstall global packages
 
-## Requisitos
+## Requirements
 
 - [Bun](https://bun.sh) >= 1.0
 
 ```bash
+# Linux/macOS
 curl -fsSL https://bun.sh/install | bash
+
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
-## Templates Open Source
+## Open Source Templates
+
+- [create-next-landing](https://github.com/nimbuslab/create-next-landing) - Landing page template
+- [create-next-app](https://github.com/nimbuslab/create-next-app) - Web app template
+- [create-turborepo](https://github.com/nimbuslab/create-turborepo) - Monorepo template
+
+## Why nimbuslab CLI?
+
+**Modern Stack**
+Built with the latest technologies: Next.js 16, React 19, Tailwind CSS 4. Always up-to-date.
+
+**AI-First**
+Documentation designed for AI coding assistants. Get better suggestions, faster onboarding.
+
+**Zero Config**
+Smart defaults based on industry best practices. Production-ready from day one.
+
+**Interactive**
+Guided setup for services and integrations. No more reading docs to get started.
+
+**Open Source**
+All templates are open source. Fork, customize, contribute back.
+
+## Support
+
+- 📖 [Documentation](https://github.com/nimbuslab/nimbus-cli)
+- 🐛 [Issues](https://github.com/nimbuslab/nimbus-cli/issues)
+- 💬 [Discussions](https://github.com/nimbuslab/nimbus-cli/discussions)
+
+## License
 
-- [create-next-landing](https://github.com/nimbuslab/create-next-landing)
-- [create-next-app](https://github.com/nimbuslab/create-next-app)
-- [create-turborepo](https://github.com/nimbuslab/create-turborepo)
+MIT © [nimbuslab](https://nimbuslab.com.br)
 
-## Licenca
+---
 
-UNLICENSED - [nimbuslab](https://nimbuslab.com.br) 2026
+**Created by nimbuslab** - Building digital products with design and technology.

package/dist/index.js

@@ -877,6 +877,7 @@ async function generateAIFriendlyDocs(projectPath, config) {
   await generateLLMsFile(projectPath, config);
   await generateArchitectureDoc(projectPath, config);
   await generateExamplesDoc(projectPath, config);
+  await generateModificationsDoc(projectPath, config);
   await createCompatibilitySymlinks(projectPath);
 }
 async function generateAgentsFile(projectPath, config) {
@@ -982,6 +983,14 @@ import type { User } from '@/types'
 - Use arrow functions for components
 - Explicit return types for exported functions
 
+## Project Inventory
+
+${generateProjectInventory(config)}
+
+## Feature Dependencies
+
+${generateFeatureDependencies(config)}
+
 ## Common Tasks
 
 ### Add a new section
@@ -1094,6 +1103,7 @@ async function generateLLMsFile(projectPath, config) {
 - [Project Overview](./AGENTS.md)
 - [Architecture](./ARCHITECTURE.md)
 - [Examples](./EXAMPLES.md)
+- [How to Modify](./MODIFICATIONS.md)
 - [Contributing](./CONTRIBUTING.md)
 
 ## Quick Context
@@ -1160,7 +1170,20 @@ async function generateArchitectureDoc(projectPath, config) {
 - Smaller bundle size
 - Familiar DX
 
-${config.type === "landing" ? `### 3. Landing Page Structure
+### 3. ${config.stack.components}
+
+**Why:**
+- Copy-paste workflow (no lock-in)
+- Full control over components
+- Customizable without ejecting
+- Built on Radix UI (accessibility)
+
+**Trade-offs:**
+- Manual updates (not auto-updated via npm)
+- More files in your repo
+- Worth it for flexibility
+
+${config.type === "landing" ? `### 4. Landing Page Structure
 
 \`\`\`
 Hero
@@ -1178,7 +1201,17 @@ CTA
 Footer
 \`\`\`
 
-` : ""}## Data Flow
+**Why this order:**
+- Hero grabs attention first
+- Features build interest
+- FAQ reduces friction
+- CTA when ready to convert
+
+` : ""}## This Project's Specific Decisions
+
+${generateProjectDecisions(config)}
+
+## Data Flow
 
 \`\`\`
 User Action
@@ -1327,6 +1360,348 @@ export const env = envSchema.parse(process.env)
 `;
   await Bun.write(join(projectPath, "EXAMPLES.md"), content);
 }
+function generateProjectDecisions(config) {
+  let decisions = "";
+  if (config.stack.email) {
+    decisions += `### Email Provider: ${config.stack.email}
+
+**Why chosen:**
+- 3,000 emails/month free tier
+- React Email support (type-safe templates)
+- Simple API, great DX
+
+**Alternatives considered:**
+- SendGrid: More complex, steeper pricing
+- Postmark: Great but no free tier
+- AWS SES: Requires more setup
+
+**If you need to change:**
+1. Update \`lib/email.ts\` client
+2. Update env vars (\`.env\`)
+3. Update API route implementation
+
+`;
+  }
+  if (config.stack.forms) {
+    decisions += `### Form Library: ${config.stack.forms}
+
+**Why chosen:**
+- Better performance than Formik
+- Smaller bundle size
+- Native TypeScript support
+- Works great with Zod
+
+**Trade-off:**
+- More verbose than simple useState
+- Worth it for complex forms with validation
+
+**If you need simpler forms:**
+- Use plain \`<form>\` + \`useState\`
+- Good for 1-2 field forms
+
+`;
+  }
+  if (config.features.contactForm) {
+    decisions += `### Contact Form Implementation
+
+**Current setup:**
+- Client-side validation (instant feedback)
+- Server-side validation (security)
+- Rate limiting (spam prevention)
+
+**Why both validations:**
+- Client: Better UX (immediate feedback)
+- Server: Security (never trust client)
+
+`;
+  }
+  if (!decisions) {
+    decisions = `No specific architectural decisions documented yet. As you make choices, document them here.
+`;
+  }
+  return decisions;
+}
+function generateProjectInventory(config) {
+  let inventory = `**Implemented Components:**
+`;
+  if (config.type === "landing") {
+    inventory += `- Hero (\`components/sections/hero.tsx\`) - Main value proposition and CTA
+- Features (\`components/sections/features.tsx\`) - Product features grid
+- FAQ (\`components/sections/faq.tsx\`) - Frequently asked questions
+`;
+    if (config.features.contactForm) {
+      inventory += `- Contact Form (\`components/forms/contact-form.tsx\`) - Email contact with validation
+`;
+    }
+  }
+  if (config.type === "app") {
+    inventory += `- Dashboard Layout (\`components/dashboard/layout.tsx\`) - Main app layout
+- Auth Forms (\`components/auth/\`) - Login/signup components
+`;
+  }
+  inventory += `
+**API Routes:**
+`;
+  if (config.features.contactForm) {
+    inventory += `- \`/api/contact\` - Form submission handler (rate-limited, ${config.stack.email || "email"} integration)
+`;
+  }
+  if (config.features.auth) {
+    inventory += `- \`/api/auth/[...nextauth]\` - Authentication endpoints
+`;
+  }
+  if (!config.features.contactForm && !config.features.auth) {
+    inventory += `- None yet (add API routes in \`app/api/\`)
+`;
+  }
+  inventory += `
+**Utilities:**
+`;
+  if (config.stack.email) {
+    inventory += `- \`lib/email.ts\` - ${config.stack.email} client configuration
+`;
+  }
+  if (config.features.contactForm) {
+    inventory += `- \`lib/validations.ts\` - Zod schemas (contactSchema: name, email, message)
+`;
+  }
+  inventory += `- \`lib/utils.ts\` - Helper functions (cn, formatters)
+`;
+  return inventory;
+}
+function generateFeatureDependencies(config) {
+  let deps = "";
+  if (config.features.contactForm) {
+    deps += `**Contact Form** depends on:
+\`\`\`
+\u251C\u2500 React Hook Form (form state management)
+\u251C\u2500 Zod (validation schemas)
+${config.stack.email ? `\u251C\u2500 ${config.stack.email} (email sending)
+` : ""}\u2514\u2500 /api/contact (server endpoint)
+\`\`\`
+
+**To modify contact form:**
+1. Update validation: \`lib/validations.ts\` (contactSchema)
+2. Update UI: \`components/forms/contact-form.tsx\`
+3. Update API: \`app/api/contact/route.ts\`
+4. Update email template: \`emails/contact-email.tsx\` (if exists)
+
+`;
+  }
+  if (config.features.auth) {
+    deps += `**Authentication** depends on:
+\`\`\`
+\u251C\u2500 ${config.stack.auth} (auth provider)
+\u251C\u2500 Database (user storage)
+\u2514\u2500 /api/auth/[...nextauth] (auth endpoints)
+\`\`\`
+
+**To modify auth:**
+1. Update config: \`lib/auth.ts\`
+2. Update providers: Add/remove in auth config
+3. Update callbacks: Customize JWT/session
+
+`;
+  }
+  if (!deps) {
+    deps = `No complex feature dependencies yet. Add features and their dependency maps will appear here.
+`;
+  }
+  return deps;
+}
+async function generateModificationsDoc(projectPath, config) {
+  let content = `# Modification Guide
+
+This file shows you exactly how to modify existing features in this project.
+
+> **Context-aware:** These are the actual files in YOUR project, not generic examples.
+
+`;
+  if (config.type === "landing") {
+    content += `## Landing Page Sections
+
+### Change Hero Text
+
+**File:** \`components/sections/hero.tsx\`
+**What to edit:** Lines with \`<h1>\` and \`<p>\` tags
+**Current pattern:** Value proposition + subheading + CTA
+**Example change:**
+\`\`\`tsx
+<h1 className="text-4xl font-bold">
+  Your New Headline Here
+</h1>
+<p className="text-xl text-muted-foreground">
+  Your new subheading
+</p>
+\`\`\`
+
+### Add/Remove Feature Cards
+
+**File:** \`components/sections/features.tsx\`
+**What to edit:** \`features\` array (usually lines 10-25)
+**Current:** 3 feature cards
+**To add:** Push new object to array: \`{ icon: Icon, title: "", description: "" }\`
+**To remove:** Delete object from array or filter it out
+
+### Modify FAQ Questions
+
+**File:** \`components/sections/faq.tsx\`
+**What to edit:** \`questions\` array
+**Current:** Pre-populated with common questions
+**Pattern:** Keep answers concise (< 100 chars) for better UX
+**To add:** \`{ question: "...", answer: "..." }\`
+
+`;
+  }
+  if (config.features.contactForm) {
+    content += `## Contact Form
+
+### Change Form Fields
+
+**Files to modify:**
+1. \`lib/validations.ts\` - Add field to schema
+2. \`components/forms/contact-form.tsx\` - Add UI input
+3. \`app/api/contact/route.ts\` - Handle new field
+
+**Example: Add phone field**
+\`\`\`typescript
+// 1. lib/validations.ts
+export const contactSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  phone: z.string().min(10), // NEW
+  message: z.string().min(10),
+})
+
+// 2. components/forms/contact-form.tsx
+<FormField
+  name="phone"
+  control={form.control}
+  render={({ field }) => (
+    <Input placeholder="Phone" {...field} />
+  )}
+/>
+
+// 3. app/api/contact/route.ts
+// Phone is now available in validated data
+const { name, email, phone, message } = validated.data
+\`\`\`
+
+### Change Email Template
+
+**File:** \`emails/contact-email.tsx\` (if using React Email)
+**Alternative:** Inline in \`app/api/contact/route.ts\`
+**What to edit:** Subject, body content, styling
+**Test locally:** \`bun run email:dev\` (if available)
+
+### Change Email Recipient
+
+**File:** \`app/api/contact/route.ts\`
+**What to edit:** The \`to:\` field in email send
+\`\`\`typescript
+await resend.emails.send({
+  to: 'your-new-email@example.com', // CHANGE THIS
+  // ...
+})
+\`\`\`
+
+`;
+  }
+  content += `## Styling Changes
+
+### Update Colors
+
+**File:** \`app/globals.css\`
+**What to edit:** CSS variables in \`:root\` and \`.dark\`
+\`\`\`css
+:root {
+  --primary: 220 90% 56%; /* Change this */
+}
+\`\`\`
+**Tip:** Use [shadcn theme editor](https://ui.shadcn.com/themes) to generate new colors
+
+### Change Fonts
+
+**File:** \`app/layout.tsx\`
+**What to edit:** Font imports and \`className\` on \`<body>\`
+\`\`\`tsx
+import { Inter } from 'next/font/google'
+
+const font = Inter({ subsets: ['latin'] })
+
+<body className={font.className}>
+\`\`\`
+
+## Adding New Features
+
+### Add a New Page
+
+\`\`\`bash
+# 1. Create route
+touch app/about/page.tsx
+
+# 2. Add navigation link
+# Edit: components/layout/header.tsx or footer.tsx
+\`\`\`
+
+### Add shadcn/ui Component
+
+\`\`\`bash
+bunx --bun shadcn@latest add [component-name]
+# Example: bunx --bun shadcn@latest add dialog
+\`\`\`
+
+## Environment Variables
+
+**File:** \`.env\` (create from \`.env.example\`)
+
+${config.stack.email ? `### ${config.stack.email} API Key
+\`\`\`env
+RESEND_API_KEY=re_xxxxxxxxxxxx
+\`\`\`
+**Get key:** [${config.stack.email} Dashboard](https://resend.com/api-keys)
+
+` : ""}${config.features.analytics ? `### Google Analytics
+\`\`\`env
+NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
+\`\`\`
+**Get ID:** [Google Analytics](https://analytics.google.com)
+
+` : ""}## Common Modifications
+
+### Change Site Metadata (SEO)
+
+**File:** \`app/layout.tsx\`
+**What to edit:** \`metadata\` export
+\`\`\`tsx
+export const metadata = {
+  title: 'Your New Title',
+  description: 'Your new description',
+  // ...
+}
+\`\`\`
+
+### Add Custom Font from File
+
+\`\`\`tsx
+// app/layout.tsx
+import localFont from 'next/font/local'
+
+const customFont = localFont({
+  src: './fonts/CustomFont.woff2',
+  variable: '--font-custom',
+})
+\`\`\`
+
+---
+
+**Pro tip:** Before modifying, search the codebase for the text/component you want to change:
+\`\`\`bash
+grep -r "text to find" .
+\`\`\`
+`;
+  await Bun.write(join(projectPath, "MODIFICATIONS.md"), content);
+}
 async function createCompatibilitySymlinks(projectPath) {
   const agentsContent = await Bun.file(join(projectPath, "AGENTS.md")).text();
   await Bun.write(join(projectPath, ".cursorrules"), agentsContent);
@@ -3965,7 +4340,7 @@ async function setupNode(args) {
 
 // src/index.ts
 var PACKAGE_NAME2 = "@nimbuslab/cli";
-var CURRENT_VERSION = "1.1.0";
+var CURRENT_VERSION = "1.2.0";
 var LOGO = `
  \u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
  \u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbuslab/cli",
-  "version": "1.1.0",
-  "description": "CLI para criar projetos nimbuslab",
+  "version": "1.2.0",
+  "description": "Modern Next.js project generator with AI-friendly documentation and best practices built-in",
   "type": "module",
   "bin": {
     "nimbus": "./dist/index.js"