start-vibing-stacks 1.6.0 → 1.7.1

package/dist/index.js

@@ -5,7 +5,8 @@
  * Multi-stack AI-powered development workflow for Claude Code.
  * Detects project stack, validates requirements, and configures agents.
  */
-import { basename } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import * as ui from './ui.js';
@@ -66,6 +67,54 @@ async function main() {
     console.log(ui.LOGO);
     const projectDir = process.cwd();
     const projectName = basename(projectDir);
+    // ─── Quick Resume: Skip setup if already configured ─────────────────────
+    const activeProjectPath = join(projectDir, '.claude', 'config', 'active-project.json');
+    if (existsSync(activeProjectPath) && !FLAGS.force) {
+        try {
+            const existing = JSON.parse(readFileSync(activeProjectPath, 'utf8'));
+            ui.success(`Project already configured: ${existing.name || projectName}`);
+            ui.info(`Stack: ${existing.stack} | Framework: ${existing.framework} | DB: ${existing.database}`);
+            console.log('');
+            const { action } = await inquirer.prompt([
+                {
+                    type: 'list',
+                    name: 'action',
+                    message: 'What do you want to do?',
+                    choices: [
+                        { name: '🚀  Launch Claude Code', value: 'launch' },
+                        { name: '🔄  Reconfigure project (fresh setup)', value: 'reconfig' },
+                        { name: '❌  Exit', value: 'exit' },
+                    ],
+                },
+            ]);
+            if (action === 'launch') {
+                if (!FLAGS.noClaude) {
+                    console.log(chalk.dim('\n  Launching Claude Code...\n'));
+                    const { execSync: run } = await import('child_process');
+                    try {
+                        run('claude --dangerously-skip-permissions', {
+                            cwd: projectDir,
+                            stdio: 'inherit',
+                            env: { ...process.env },
+                        });
+                    }
+                    catch {
+                        ui.info('Claude Code session ended.');
+                    }
+                }
+                process.exit(0);
+            }
+            if (action === 'exit') {
+                process.exit(0);
+            }
+            // action === 'reconfig' → continue with full setup below
+            ui.info('Reconfiguring project...');
+            console.log('');
+        }
+        catch {
+            // Corrupted config, continue with fresh setup
+        }
+    }
     // ─── Step 1: Detect Project ─────────────────────────────────────────────
     ui.header('🔍 Scanning project directory...');
     const detection = detectProject(projectDir);

package/dist/setup.js

@@ -176,7 +176,7 @@ export async function setupProject(projectDir, config, options = {}) {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'npx tsx .claude/hooks/run-hook.ts user-prompt-submit',
+                                command: 'bash .claude/hooks/run-hook.sh user-prompt-submit',
                                 timeout: 10,
                             },
                         ],
@@ -187,7 +187,7 @@ export async function setupProject(projectDir, config, options = {}) {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'npx tsx .claude/hooks/run-hook.ts stop-validator',
+                                command: 'bash .claude/hooks/run-hook.sh stop-validator',
                                 timeout: 30,
                             },
                         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -0,0 +1,88 @@
+# Hook Development — Claude Code Hooks
+
+**ALWAYS invoke when creating or modifying Claude Code hooks.**
+
+## Hook Types
+
+| Event | When | Use Case |
+|-------|------|----------|
+| `UserPromptSubmit` | Before prompt is sent | Inject workflow, validate input |
+| `Stop` | Before task completion | Validate state, block if dirty |
+| `PreToolUse` | Before tool execution | Approve/block dangerous tools |
+| `PostToolUse` | After tool execution | Log, validate output |
+
+## File Structure
+
+```
+.claude/hooks/
+├── run-hook.sh              # Entry point (bash → bun/tsx fallback)
+├── user-prompt-submit.ts    # Prompt injection
+└── stop-validator.ts        # Task completion gate
+```
+
+## Hook Input (stdin JSON)
+
+```typescript
+// UserPromptSubmit
+interface PromptInput {
+  user_prompt: string;
+  session_id: string;
+}
+
+// Stop
+interface StopInput {
+  stop_hook_active?: boolean;  // Cycle detection
+  transcript?: string;
+}
+```
+
+## Hook Output (stdout JSON)
+
+```typescript
+// UserPromptSubmit — inject system message
+{ "continue": true, "systemMessage": "WORKFLOW: ..." }
+
+// Stop — approve or block
+{ "continue": false, "decision": "approve", "reason": "All checks passed" }
+{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+```
+
+## Template: Stop Validator
+
+```typescript
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+
+function cmd(c: string): string {
+  try { return execSync(c, { encoding: 'utf8' }).trim(); } catch { return ''; }
+}
+
+const branch = cmd('git rev-parse --abbrev-ref HEAD');
+const dirty = cmd('git status --porcelain');
+
+const result = (!dirty && (branch === 'main' || branch === 'master'))
+  ? { continue: false, decision: 'approve', reason: 'Clean main branch' }
+  : { continue: true, decision: 'block', reason: `Branch: ${branch}, dirty: ${!!dirty}` };
+
+console.log(JSON.stringify(result));
+```
+
+## settings.json Registration
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh stop-validator", "timeout": 30 }] }],
+    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh user-prompt-submit", "timeout": 10 }] }]
+  }
+}
+```
+
+## Rules
+
+1. **Always use `run-hook.sh` as entry** — handles bun/tsx fallback
+2. **Read stdin with timeout** — hooks must not hang
+3. **Exit 0 always** — non-zero kills the session
+4. **Output valid JSON to stdout** — Claude Code parses it
+5. **Cycle detection** — check `stop_hook_active` flag in Stop hooks
+6. **Keep hooks fast** — timeout applies (10s for prompt, 30s for stop)

package/stacks/frontend/react/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,92 @@
+# shadcn/ui — Component Library Patterns
+
+**ALWAYS invoke when adding or modifying shadcn/ui components.**
+
+## Installation
+
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button card dialog input
+```
+
+## Theming
+
+```css
+/* globals.css — CSS variables for theming */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --border: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;
+  }
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+  }
+}
+```
+
+## Component Customization
+
+```tsx
+// CORRECT — extend via className + variants
+import { Button } from '@/components/ui/button';
+<Button variant="outline" size="lg" className="rounded-full">Custom</Button>
+
+// WRONG — modify component source for one-off styles
+```
+
+## Composition Pattern
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+
+// Compose primitives, don't create monolithic components
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    <Card><CardContent>...</CardContent></Card>
+  </DialogContent>
+</Dialog>
+```
+
+## Form Pattern (with Zod)
+
+```tsx
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const form = useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema) });
+
+<Form {...form}>
+  <FormField control={form.control} name="email" render={({ field }) => (
+    <FormItem>
+      <FormLabel>Email</FormLabel>
+      <FormControl><Input {...field} /></FormControl>
+      <FormMessage />
+    </FormItem>
+  )} />
+</Form>
+```
+
+## FORBIDDEN
+
+1. **Modifying component source for one-off needs** — use className/variants
+2. **Installing without init** — always `npx shadcn@latest init` first
+3. **Ignoring dark mode** — all components must work in both themes
+4. **Skipping accessibility** — shadcn components have built-in a11y, don't break it

package/stacks/nodejs/skills/bun-runtime/SKILL.md

@@ -0,0 +1,86 @@
+# Bun Runtime — Fast JavaScript Runtime
+
+**ALWAYS invoke when using Bun for scripts, packages, bundling, or testing.**
+
+## Package Management
+
+```bash
+bun install               # Install deps (replaces npm install)
+bun add zod               # Add dependency
+bun add -D vitest         # Add dev dependency
+bun remove lodash         # Remove
+bun update                # Update all
+```
+
+## Scripts
+
+```bash
+bun run dev               # Run script from package.json
+bun run build
+bun --watch src/index.ts  # Watch mode
+```
+
+## TypeScript (native, no config needed)
+
+```typescript
+// Bun runs .ts files directly — no tsc/tsx needed
+// bun src/index.ts
+
+import { serve } from 'bun';
+
+serve({
+  port: 3000,
+  fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === '/api/health') {
+      return Response.json({ status: 'ok' });
+    }
+    return new Response('Not Found', { status: 404 });
+  },
+});
+```
+
+## File I/O (Bun APIs)
+
+```typescript
+// Fast file operations
+const content = await Bun.file('data.json').text();
+const parsed = await Bun.file('data.json').json();
+await Bun.write('output.txt', 'Hello');
+
+// Glob
+const glob = new Bun.Glob('**/*.ts');
+for await (const file of glob.scan('.')) { console.log(file); }
+```
+
+## Testing (built-in)
+
+```typescript
+// *.test.ts — bun test
+import { describe, it, expect } from 'bun:test';
+
+describe('math', () => {
+  it('adds', () => expect(1 + 1).toBe(2));
+});
+```
+
+```bash
+bun test                  # Run all tests
+bun test --coverage       # With coverage
+bun test --watch          # Watch mode
+```
+
+## Environment Variables
+
+```typescript
+// .env loaded automatically
+const apiKey = Bun.env['API_KEY'];      // Bun.env (recommended)
+const dbUrl = process.env['DATABASE_URL']; // Also works
+```
+
+## FORBIDDEN
+
+1. **`node` command when `bun` works** — prefer bun for speed
+2. **`npx` when `bunx` works** — `bunx` is faster
+3. **Manual .env loading** — Bun loads `.env` automatically
+4. **CommonJS `require()`** — use ESM `import`

package/stacks/nodejs/skills/mongoose-patterns/SKILL.md

@@ -0,0 +1,77 @@
+# Mongoose Patterns — MongoDB ODM
+
+**ALWAYS invoke when writing Mongoose schemas, queries, or aggregations.**
+
+## Schema Pattern
+
+```typescript
+import { Schema, model, type InferSchemaType } from 'mongoose';
+
+const userSchema = new Schema({
+  name: { type: String, required: true, trim: true, minlength: 2 },
+  email: { type: String, required: true, unique: true, lowercase: true, index: true },
+  role: { type: String, enum: ['admin', 'user', 'moderator'] as const, default: 'user' },
+  profile: {
+    avatar: String,
+    bio: { type: String, maxlength: 500 },
+  },
+  tags: [{ type: String, index: true }],
+  isActive: { type: Boolean, default: true, index: true },
+}, {
+  timestamps: true,         // createdAt, updatedAt
+  toJSON: { virtuals: true, transform: (_, ret) => { delete ret.__v; return ret; } },
+});
+
+// Compound index
+userSchema.index({ email: 1, isActive: 1 });
+// Text index for search
+userSchema.index({ name: 'text', 'profile.bio': 'text' });
+
+type IUser = InferSchemaType<typeof userSchema>;
+export const User = model('User', userSchema);
+```
+
+## Query Patterns
+
+```typescript
+// Pagination
+async function paginate(page: number, limit: number) {
+  const [items, total] = await Promise.all([
+    User.find({ isActive: true }).skip((page - 1) * limit).limit(limit).lean(),
+    User.countDocuments({ isActive: true }),
+  ]);
+  return { items, total, pages: Math.ceil(total / limit) };
+}
+
+// Aggregation
+const stats = await User.aggregate([
+  { $match: { isActive: true } },
+  { $group: { _id: '$role', count: { $sum: 1 }, avgAge: { $avg: '$age' } } },
+  { $sort: { count: -1 } },
+]);
+```
+
+## Middleware
+
+```typescript
+// Pre-save: hash password
+userSchema.pre('save', async function (next) {
+  if (!this.isModified('password')) return next();
+  this.password = await bcrypt.hash(this.password, 12);
+  next();
+});
+
+// Pre-find: exclude inactive by default
+userSchema.pre(/^find/, function (next) {
+  this.where({ isActive: { $ne: false } });
+  next();
+});
+```
+
+## FORBIDDEN
+
+1. **No indexes on queried fields** — always index filter/sort fields
+2. **`find()` without `.lean()`** for read-only — wastes memory
+3. **Unbounded queries** — always `.limit()`
+4. **N+1 queries** — use `.populate()` or aggregation `$lookup`
+5. **String IDs without casting** — use `new Types.ObjectId(id)`

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,123 @@
+# Next.js App Router — Modern Patterns
+
+**ALWAYS invoke when writing Next.js pages, layouts, or server components.**
+
+## File Conventions
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page
+├── loading.tsx         # Loading UI (Suspense boundary)
+├── error.tsx           # Error boundary ('use client')
+├── not-found.tsx       # 404 page
+├── (auth)/             # Route group (no URL segment)
+│   ├── login/page.tsx
+│   └── register/page.tsx
+├── dashboard/
+│   ├── layout.tsx      # Nested layout
+│   ├── page.tsx
+│   └── [id]/page.tsx   # Dynamic route
+└── api/
+    └── route.ts        # API route handler
+```
+
+## Server vs Client Components
+
+```tsx
+// DEFAULT: Server Component (no directive needed)
+async function UserList() {
+  const users = await db.user.findMany(); // Direct DB access
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// CLIENT: Only when needed (interactivity, hooks, browser APIs)
+'use client';
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c + 1)}>{count}</button>;
+}
+```
+
+## Data Fetching
+
+```tsx
+// Server Component — fetch with caching
+async function Page() {
+  const data = await fetch('https://api.example.com/data', {
+    next: { revalidate: 3600 }, // ISR: revalidate every hour
+  });
+  return <div>{data}</div>;
+}
+
+// Dynamic data (no cache)
+async function Page() {
+  const data = await fetch('https://api.example.com/data', {
+    cache: 'no-store',
+  });
+}
+```
+
+## Server Actions
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  await db.user.create({ data: { name } });
+  revalidatePath('/users');
+}
+
+// In component
+<form action={createUser}>
+  <input name="name" />
+  <button type="submit">Create</button>
+</form>
+```
+
+## Route Handlers (API)
+
+```tsx
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const page = Number(searchParams.get('page') ?? '1');
+  const users = await db.user.findMany({ skip: (page - 1) * 20, take: 20 });
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const result = schema.safeParse(body);
+  if (!result.success) return NextResponse.json(result.error, { status: 400 });
+  const user = await db.user.create({ data: result.data });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## Metadata
+
+```tsx
+// Static
+export const metadata = { title: 'Dashboard', description: 'User dashboard' };
+
+// Dynamic
+export async function generateMetadata({ params }: { params: { id: string } }) {
+  const user = await getUser(params.id);
+  return { title: user.name };
+}
+```
+
+## FORBIDDEN
+
+1. **`'use client'` on server-capable components** — default to server
+2. **Fetching in client when server fetch works** — use server components
+3. **`getServerSideProps` / `getStaticProps`** — App Router uses async components
+4. **API routes for server-only data** — use server components directly
+5. **Prop drilling through layouts** — use parallel routes or context

package/stacks/nodejs/skills/trpc-api/SKILL.md

@@ -0,0 +1,87 @@
+# tRPC API — End-to-End Type Safety
+
+**ALWAYS invoke when building type-safe API routes with tRPC.**
+
+## Structure
+
+```
+server/
+├── trpc.ts              # tRPC init + context
+├── routers/
+│   ├── _app.ts          # Root router (merges all)
+│   ├── user.router.ts
+│   └── post.router.ts
+└── middleware/
+    └── auth.ts          # Auth middleware
+```
+
+## Setup
+
+```typescript
+// server/trpc.ts
+import { initTRPC, TRPCError } from '@trpc/server';
+import superjson from 'superjson';
+
+const t = initTRPC.context<Context>().create({ transformer: superjson });
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+
+export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
+  if (!ctx.session?.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
+  return next({ ctx: { ...ctx, user: ctx.session.user } });
+});
+```
+
+## Router Pattern
+
+```typescript
+// server/routers/user.router.ts
+import { z } from 'zod';
+import { router, protectedProcedure } from '../trpc';
+
+export const userRouter = router({
+  me: protectedProcedure.query(async ({ ctx }) => {
+    return ctx.db.user.findUnique({ where: { id: ctx.user.id } });
+  }),
+
+  update: protectedProcedure
+    .input(z.object({ name: z.string().min(2) }))
+    .mutation(async ({ ctx, input }) => {
+      return ctx.db.user.update({
+        where: { id: ctx.user.id },
+        data: input,
+      });
+    }),
+
+  list: protectedProcedure
+    .input(z.object({ page: z.number().min(1).default(1), limit: z.number().max(100).default(20) }))
+    .query(async ({ ctx, input }) => {
+      const { page, limit } = input;
+      return ctx.db.user.findMany({ skip: (page - 1) * limit, take: limit });
+    }),
+});
+```
+
+## Client Usage (React)
+
+```tsx
+import { trpc } from '@/utils/trpc';
+
+function Profile() {
+  const { data: user, isLoading } = trpc.user.me.useQuery();
+  const updateMutation = trpc.user.update.useMutation({
+    onSuccess: () => utils.user.me.invalidate(),
+  });
+
+  if (isLoading) return <Skeleton />;
+  return <div>{user?.name}</div>;
+}
+```
+
+## FORBIDDEN
+
+1. **REST endpoints when tRPC covers it** — use tRPC procedures
+2. **Unvalidated input** — always use Zod `.input()`
+3. **Public procedures for auth-required data** — use `protectedProcedure`
+4. **Direct DB access in client** — always through tRPC procedures