start-vibing-stacks 2.3.0 → 2.4.1

package/stacks/nodejs/stack.json

@@ -1,29 +1,13 @@
 {
   "id": "nodejs",
   "name": "Node.js / TypeScript",
-  "icon": "\ud83d\udce6",
+  "icon": "📦",
   "runtime": "Bun / Node.js 20+",
   "minVersion": "20.0.0",
   "packageManager": "bun|npm|pnpm",
-  "extensions": [
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs"
-  ],
-  "testExtensions": [
-    "*.test.ts",
-    "*.spec.ts",
-    "*.test.tsx"
-  ],
-  "detectFiles": [
-    "package.json",
-    "tsconfig.json",
-    "bun.lockb",
-    "next.config.js"
-  ],
+  "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+  "testExtensions": ["*.test.ts", "*.spec.ts", "*.test.tsx"],
+  "detectFiles": ["package.json", "tsconfig.json", "bun.lockb", "bun.lock", "next.config.js"],
   "commands": {
     "test": "bun run test",
     "lint": "bun run lint",
@@ -33,146 +17,95 @@
     "typecheck": "bun run typecheck"
   },
   "qualityGates": [
-    {
-      "name": "TypeCheck",
-      "command": "bun run typecheck",
-      "required": true,
-      "order": 1
-    },
-    {
-      "name": "Lint",
-      "command": "bun run lint",
-      "required": true,
-      "order": 2
-    },
-    {
-      "name": "Tests",
-      "command": "bun run test",
-      "required": true,
-      "order": 3
-    },
-    {
-      "name": "Build",
-      "command": "bun run build",
-      "required": true,
-      "order": 4
-    }
+    { "name": "TypeCheck", "command": "bun run typecheck", "required": true, "order": 1 },
+    { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
+    { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 4 }
   ],
   "frameworks": [
     {
       "id": "nextjs",
       "name": "Next.js (App Router)",
-      "icon": "\u25b2",
-      "detectFiles": [
-        "next.config.js",
-        "next.config.ts",
-        "next.config.mjs"
-      ]
+      "icon": "▲",
+      "detectFiles": ["next.config.js", "next.config.ts", "next.config.mjs"],
+      "default": true,
+      "skills": ["nextjs-app-router"]
     },
     {
       "id": "nuxt",
       "name": "Nuxt",
-      "icon": "\ud83d\udc9a",
-      "detectFiles": [
-        "nuxt.config.ts"
-      ]
+      "icon": "💚",
+      "detectFiles": ["nuxt.config.ts"],
+      "skills": []
     },
     {
       "id": "astro",
       "name": "Astro",
-      "icon": "\ud83d\ude80",
-      "detectFiles": [
-        "astro.config.mjs"
-      ]
+      "icon": "🚀",
+      "detectFiles": ["astro.config.mjs"],
+      "skills": []
     },
     {
       "id": "express",
       "name": "Express",
-      "icon": "\u26a1"
+      "icon": "⚡",
+      "skills": ["trpc-api"]
     },
     {
       "id": "fastify",
       "name": "Fastify",
-      "icon": "\ud83c\udfce\ufe0f"
+      "icon": "🏎️",
+      "skills": ["trpc-api"]
     },
     {
       "id": "vanilla",
       "name": "Vanilla Node.js",
-      "icon": "\ud83d\udcc4"
+      "icon": "📄",
+      "skills": []
     }
   ],
   "databases": [
-    {
-      "id": "mongodb",
-      "name": "MongoDB",
-      "icon": "\ud83c\udf43"
-    },
-    {
-      "id": "postgresql",
-      "name": "PostgreSQL",
-      "icon": "\ud83d\udc18"
-    },
-    {
-      "id": "mysql",
-      "name": "MySQL / MariaDB",
-      "icon": "\ud83d\udc2c"
-    },
-    {
-      "id": "sqlite",
-      "name": "SQLite (Turso / libSQL)",
-      "icon": "\ud83d\udcc1"
-    },
-    {
-      "id": "redis",
-      "name": "Redis (Upstash)",
-      "icon": "\ud83d\udd34"
-    },
-    {
-      "id": "none",
-      "name": "None",
-      "icon": "\u274c"
-    }
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "sqlite", "name": "SQLite (Turso / libSQL)", "icon": "📁" },
+    { "id": "redis", "name": "Redis (Upstash)", "icon": "🔴" },
+    { "id": "none", "name": "None", "icon": "❌" }
   ],
   "frontendOptions": [
     {
       "id": "react-tailwind",
       "name": "React 19+ / TailwindCSS 4+",
-      "icon": "\u269b\ufe0f"
+      "icon": "⚛️",
+      "skillsDir": "react",
+      "default": true,
+      "frameworks": ["nextjs", "express", "fastify", "vanilla"]
     },
     {
       "id": "vue",
       "name": "Vue.js / Nuxt",
-      "icon": "\ud83d\udc9a"
+      "icon": "💚",
+      "frameworks": ["nuxt"]
     },
     {
       "id": "svelte",
       "name": "Svelte / SvelteKit",
-      "icon": "\ud83d\udd25"
-    },
-    {
-      "id": "shadcn",
-      "name": "shadcn/ui + Tailwind",
-      "icon": "\ud83c\udfa8"
+      "icon": "🔥",
+      "frameworks": ["astro", "vanilla"]
     },
     {
       "id": "none",
-      "name": "API only \u2014 no frontend",
-      "icon": "\u274c"
+      "name": "API only — no frontend",
+      "icon": "❌"
     }
   ],
   "deployTargets": [
-    {
-      "id": "github",
-      "name": "GitHub (git push)",
-      "icon": "\ud83d\udc19"
-    }
+    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
   ],
   "skills": [
     "typescript-strict",
-    "react-patterns",
-    "nextjs-app-router",
-    "zod-validation",
-    "vitest-testing"
+    "bun-runtime",
+    "zod-validation"
   ],
   "requirements": [
     {
@@ -185,17 +118,6 @@
         "linux": "curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs"
       },
       "versionRegex": "v?(\\d+\\.\\d+\\.\\d+)"
-    },
-    {
-      "name": "Bun",
-      "command": "bun",
-      "versionFlag": "--version",
-      "minVersion": "1.0.0",
-      "installCommand": {
-        "macos": "brew install oven-sh/bun/bun",
-        "linux": "curl -fsSL https://bun.sh/install | bash"
-      },
-      "versionRegex": "(\\d+\\.\\d+\\.\\d+)"
     }
   ]
 }

package/templates/CLAUDE-nodejs.md

@@ -0,0 +1,323 @@
+# {{PROJECT_NAME}}
+
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
+## Last Change
+
+**Branch:** main
+**Date:** {{DATE}}
+**Summary:** Initial project setup with start-vibing-stacks (Node.js)
+
+## 30 Seconds Overview
+
+{{PROJECT_NAME}} is a TypeScript project using {{FRAMEWORK}}.
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Bun / Node.js 20+ |
+| Language | TypeScript **strict mode** |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Validation | Zod |
+| Testing | Vitest + Playwright |
+| UI | React + Tailwind + shadcn |
+| Data | TanStack Query + Sonner |
+| Forms | react-hook-form + Zod |
+
+## Architecture
+
+```
+project/
+├── CLAUDE.md               # This file (40k char max)
+├── .claude/
+│   ├── agents/             # 6 active subagents
+│   ├── skills/             # Skill systems (auto-injected)
+│   ├── hooks/              # Validation hooks
+│   ├── config/             # Project configuration
+│   └── commands/           # Slash commands (/feature, /fix, /research, /validate)
+├── src/
+│   ├── app/                # Next.js App Router pages
+│   │   ├── (marketing)/    # Route group — public pages
+│   │   ├── (app)/          # Route group — authenticated
+│   │   │   └── dashboard/
+│   │   │       ├── page.tsx
+│   │   │       └── _components/  # Page-specific components
+│   │   ├── api/            # Route handlers (API endpoints)
+│   │   ├── layout.tsx      # Root layout with providers
+│   │   └── loading.tsx     # Global loading skeleton
+│   ├── components/
+│   │   ├── ui/             # shadcn primitives (Button, Input)
+│   │   ├── layout/         # Header, Sidebar, Footer
+│   │   ├── shared/         # Cross-feature components
+│   │   └── providers.tsx   # Context providers (client)
+│   ├── lib/
+│   │   ├── utils.ts        # cn utility (clsx + tailwind-merge)
+│   │   ├── api/            # API client instances
+│   │   └── validations/    # Zod schemas
+│   ├── hooks/              # Custom React hooks
+│   └── styles/             # Global styles, theme tokens
+├── types/                  # ALL TypeScript interfaces (MANDATORY)
+├── tests/
+│   ├── unit/               # Vitest unit tests
+│   └── e2e/                # Playwright E2E tests
+├── public/                 # Static assets
+├── tsconfig.json           # TypeScript config (strict: true)
+├── next.config.ts          # Framework config
+├── tailwind.config.ts      # TailwindCSS config
+├── vitest.config.ts        # Test config
+└── package.json            # Dependencies
+```
+
+## Workflow
+
+```
+0. TODO LIST      → Create detailed todo list from prompt
+1. BRANCH         → Create feature/ | fix/ | refactor/ | test/
+2. RESEARCH       → Run research-web agent for NEW features
+3. IMPLEMENT      → Follow project rules + strict types
+4. TEST           → Run tester agent (Vitest / Playwright)
+5. DOCUMENT       → Run documenter agent for modified files
+6. UPDATE         → Update THIS FILE (CLAUDE.md) with changes
+7. QUALITY        → bun run typecheck && lint && test
+8. COMMIT         → Conventional commits, merge to main
+```
+
+## CLAUDE.md Update Rules
+
+> After ANY implementation, update this file to reflect the current state.
+
+| Change Type | Sections to Update |
+|-------------|-------------------|
+| Any file change | Last Change (branch, date, summary) |
+| API/routes | Critical Rules, Architecture |
+| UI components | Architecture, Component Organization |
+| New feature | 30s Overview, Architecture |
+| New gotcha | FORBIDDEN or NRY |
+| New dependency | Stack |
+| Workflow change | Workflow section |
+
+1. **Last Change** documents WHAT was done
+2. **Other sections** document HOW things work NOW
+3. **Both must be current** — updating only Last Change is insufficient
+4. Keep only the LATEST Last Change entry (no stacking)
+
+## Agent System
+
+### Subagents (6)
+
+| Agent | Purpose |
+|-------|---------|
+| **research-web** | Researches best practices before new features |
+| **documenter** | Maps files to domains, creates/updates domain docs |
+| **domain-updater** | Records problems, solutions, learnings |
+| **commit-manager** | Manages git commits, conventional format |
+| **claude-md-compactor** | Compacts CLAUDE.md when > 40k chars |
+| **tester** | Creates tests with Vitest/Playwright |
+
+### Skills
+
+| Category | Skills |
+|----------|--------|
+| **Development** | typescript-strict, react-patterns, nextjs-app-router, zod-validation, shadcn-ui, tailwind-patterns |
+| **Quality** | quality-gate, security-scan, test-coverage, final-check |
+| **Infrastructure** | docker-patterns, git-workflow, performance-patterns, debugging-patterns |
+| **Documentation** | codebase-knowledge, docs-tracker, research-cache, ui-ux-audit |
+
+## Critical Rules
+
+- **TypeScript strict mode** — `strict: true` in tsconfig.json
+- **Bracket notation** for env vars: `process.env['VARIABLE']`
+- **Zod validation** for ALL external input (forms, API, env)
+- **Server Components by default** — push `'use client'` to leaf components
+- **Parallel data fetching** — `Promise.all()` over waterfall
+- **Type everything** — no `any`, use `unknown` for truly unknown data
+- **Loading states** — every data page must have `loading.tsx`
+- **Error boundaries** — every route should handle errors gracefully
+- **Conventional commits** — `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+
+### Environment Variables Security (MANDATORY)
+
+> **NEVER expose secrets to the browser.** `NEXT_PUBLIC_*` vars are embedded in the JS bundle and visible to anyone.
+
+| Prefix | Where it runs | Safe for |
+|--------|--------------|----------|
+| `NEXT_PUBLIC_*` | Browser + Server | Public URLs, analytics IDs, Stripe **publishable** key (`pk_`) |
+| No prefix | Server ONLY | API keys, secrets, tokens, database URLs, private keys |
+
+```typescript
+// .env.local
+OPENAI_KEY=sk-abc123                    // Server only — SAFE
+STRIPE_SECRET_KEY=sk_live_abc           // Server only — SAFE
+NEXT_PUBLIC_APP_URL=https://myapp.com   // Public — OK (no secret)
+NEXT_PUBLIC_STRIPE_KEY=pk_live_abc      // Public — OK (publishable key)
+
+// NEXT_PUBLIC_OPENAI_KEY=sk-abc123     // FORBIDDEN — exposed in browser bundle!
+```
+
+### API Proxy Pattern (MANDATORY for external APIs)
+
+> **ALL calls to external APIs with secrets MUST go through server-side Route Handlers or Server Actions. NEVER call external APIs directly from client components.**
+
+```typescript
+// app/api/chat/route.ts — Server-side proxy (token NEVER leaves server)
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { message } = await req.json();
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    headers: { Authorization: `Bearer ${process.env['OPENAI_KEY']}` },
+    method: 'POST',
+    body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: message }] }),
+  });
+  return NextResponse.json(await response.json());
+}
+
+// components/chat.tsx — Client calls YOUR API, not the external one
+'use client';
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  body: JSON.stringify({ message }),
+});
+```
+
+### Types Location
+
+- **ALL** interfaces/types MUST be in `types/` folder
+- **NEVER** define types in `src/` files
+- **EXCEPTION:** Zod inferred types (`z.infer<typeof Schema>`)
+
+### TypeScript Strict
+
+```typescript
+process.env['VARIABLE'];    // CORRECT (bracket notation)
+source: 'listed' as const;  // CORRECT (literal type)
+```
+
+### Component Organization
+
+| Question | Location |
+|----------|----------|
+| Used in ONE page only? | `app/[page]/_components/` |
+| Used across 2+ features? | `components/shared/` |
+| UI primitive (Button, Input)? | `components/ui/` |
+| Layout element (Header)? | `components/layout/` |
+
+| Lines | Action |
+|-------|--------|
+| < 200 | Keep in single file |
+| 200-400 | Consider splitting |
+| > 400 | **MUST split** into smaller components |
+
+## FORBIDDEN
+
+### Security (CRITICAL)
+
+| Action | Reason |
+|--------|--------|
+| `NEXT_PUBLIC_` with API keys/secrets/tokens | Exposes credentials in browser JS bundle — use server-side proxy |
+| Call external APIs from client components | Leaks tokens — route through `app/api/` Route Handlers |
+| `process.env['SECRET']` in `'use client'` files | Only `NEXT_PUBLIC_*` vars reach the browser — use Server Actions |
+| Hardcode API keys in source code | Use `.env.local` + server-side access only |
+| Commit `.env.local` / `.env` to git | Add to `.gitignore` — use `.env.example` with empty values |
+
+### Code Quality
+
+| Action | Reason |
+|--------|--------|
+| `any` type | Defeats strict mode — use `unknown` |
+| Skip typecheck | TypeScript errors become runtime bugs |
+| Relative imports (shared) | Breaks when files move — use `@/` alias |
+| Define types in `src/` | Must be in `types/` folder |
+| `'use client'` at top-level layouts | Breaks server rendering, push to leaves |
+| Waterfall data fetching | Use `Promise.all()` for parallel |
+| Skip `loading.tsx` on data pages | Flash of empty content |
+| Files > 400 lines | MUST split into smaller components |
+| Wildcard icon imports | Use named: `import { X } from 'lucide-react'` |
+| `var` keyword | Use `const` or `let` |
+| Raw `console.log` in production | Use structured logging |
+
+### Workflow
+
+| Action | Reason |
+|--------|--------|
+| Commit directly to main | Create feature/fix branches |
+| Skip research for new features | Leads to outdated patterns |
+| Skip todo list creation | Loses track of tasks |
+| Skip documenter agent | Documentation is mandatory |
+| Skip domain documentation | MUST update domains/*.md |
+| Stack Last Change entries | Keep only the LATEST |
+| Use MUI/Chakra | Use shadcn/ui + Radix |
+| Skip CLAUDE.md update | MUST update after implementations |
+
+## UI Architecture
+
+> Web apps MUST have **separate UIs** for each platform, NOT just "responsive design".
+
+| Platform | Layout |
+|----------|--------|
+| Mobile (375px) | Full-screen modals, bottom nav, touch-first |
+| Tablet (768px) | Condensed dropdowns, hybrid nav |
+| Desktop (1280px+) | Sidebar left, top navbar with search |
+
+## Quality Gates
+
+```bash
+bun run typecheck   # MUST pass
+bun run lint        # MUST pass
+bun run test        # MUST pass
+bun run build       # MUST pass
+```
+
+## Domain Documentation
+
+> Domain docs prevent Claude from re-exploring the codebase every session.
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── authentication.md
+├── api.md
+├── database.md
+├── ui-components.md
+└── [domain-name].md
+```
+
+Each domain file tracks: Files, Connections, Recent Commits, Attention Points, Problems & Solutions.
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`
+
+## NRY (Never Repeat Yourself)
+
+- Multi-line bash with `\` continuations (breaks permissions)
+- Relative paths in permission patterns
+- Using bash for file operations (use Read/Write/Edit tools)
+- Ignoring context size (use `/compact`)
+
+## Configuration
+
+Project settings in `.claude/config/`:
+
+- `active-project.json` — Stack, framework, database, skills
+- `domain-mapping.json` — File-to-domain mapping
+- `quality-gates.json` — Quality check commands
+- `testing-config.json` — Test framework config
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards
+
+## Setup by start-vibing-stacks
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`