npm - vibesuite - Versions diffs - 1.0.0 → 1.0.1 - Mend

vibesuite 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (83) hide show

package/.agent/skills/nextjs-standards/SKILL.md ADDED Viewed

@@ -0,0 +1,193 @@
+---
+name: nextjs-standards
+description: Comprehensive coding standards, verification protocols, and templates for Next.js App Router projects. Auto-loads on Next.js detection.
+---
+# Next.js Coding Standards Skill
+> **Auto-Load Trigger:** Presence of `next.config.*` or `"next"` in `package.json`
+## When to Use
+- Starting a new Next.js project
+- Before any TypeScript/React file edit
+- When context seems lost mid-session
+- After `/agent_reset` or `/prime_agent`
+---
+## 🛑 Verification Protocol (MANDATORY)
+### After Every TypeScript/TSX File Edit
+```bash
+npx tsc --noEmit
+```
+**If this fails:**
+1. DO NOT proceed to next file
+2. Fix the type error immediately
+3. Re-run until it passes
+4. Only then continue
+### Before Any Handoff
+```bash
+python scripts/vibe-verify.py
+```
+All checks must pass before claiming "done."
+---
+## The Blueprint & Build Protocol
+### Phase 1: Blueprint (Before Coding)
+1. Check `docs/features/` for existing patterns
+2. Create/update `docs/features/FeatureName.md`
+3. Wait for approval before coding
+### Phase 2: Build (Implementation)
+1. Announce which FR-XXX you're implementing
+2. Reference the corresponding issue in `docs/issues/`
+3. Implement one step at a time
+4. `tsc --noEmit` after every file
+5. Mark acceptance criteria as complete
+### Phase 3: Finalization
+1. Run full verification (`vibe-verify.py`)
+2. Update issue file with completion status
+3. Generate handoff summary
+---
+## Full-Stack Type Safety
+The AI reliability secret: **TypeScript tells you when you broke something.**
+### Core Principle
+If you change the backend, the frontend MUST type-check. If type-check fails:
+- The change broke something
+- Fix it before moving on
+- Never ignore type errors
+### Stack Alignment
+- Server Components fetch data → types flow to client
+- API routes return typed responses → frontend consumes them
+- Prisma schema changes → regenerate client → type-check
+---
+## Next.js App Router Rules
+1. **Server Components Default** — No `'use client'` unless required
+2. **Client Components Sparingly** — Only for interactivity, hooks, browser APIs
+3. **Data Fetching** — In async Server Components, not `useEffect`
+4. **Route Handlers** — All API in `app/api/.../route.ts`
+5. **Caching** — Be explicit: `{ cache: 'no-store' }` or `revalidate = N`
+---
+## File Structure (Feature-Sliced)
+```
+src/
+├── app/                    # Next.js App Router pages
+├── features/               # Business domains
+│   └── [FeatureName]/
+│       ├── components/     # Feature-specific components
+│       ├── hooks/          # Feature-specific hooks
+│       └── *.service.ts    # Business logic
+├── components/
+│   ├── ui/                 # Reusable UI (Button, Card)
+│   └── layout/             # Layout components
+├── lib/                    # Utilities, clients
+└── scripts/                # Automation (vibe-verify.py)
+```
+---
+## Component Rules
+1. **200-Line Limit** — Refactor if exceeded
+2. **Single Responsibility** — One thing per component
+3. **Props Interface** — Always use TypeScript interfaces
+4. **Custom Hooks** — Extract stateful logic into `use*` hooks
+---
+## Styling (Tailwind v4)
+> **Why Tailwind for AI Reliability:** Tailwind colocates styles with UI in a single file. Unlike separate `.css` files, AI agents see the complete context (logic + styles + structure) without jumping between files. This dramatically reduces hallucinations and context fragmentation.
+```css
+@import "tailwindcss";
+@theme {
+  --color-background: #ffffff;
+  --color-foreground: #0b1221;
+  --color-border: #e5e7eb;
+}
+@theme .dark {
+  --color-background: #0b1221;
+  --color-foreground: #e5e7eb;
+}
+```
+- Use `@theme` tokens, not `tailwind.config` extensions
+- Utility-first, no custom CSS files
+- Dark mode via `.dark` class on `<html>`
+---
+## Backend Rules
+### Service Layer Pattern
+- **Route Handlers** = Controllers (parse request, return response)
+- **Services** = Business logic (DB queries, calculations)
+### Validation
+```typescript
+import { z } from 'zod';
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+```
+All inputs validated with Zod. No exceptions.
+---
+## Templates Available
+This skill provides templates in `templates/`:
+1. **Coding_Guidelines.md** — Copy to `docs/Coding_Guidelines.md`
+2. **Issue_Template.md** — Format for FR issues
+---
+## Quick Reference
+| Command | When |
+|---------|------|
+| `npx tsc --noEmit` | After every TS/TSX edit |
+| `python scripts/vibe-verify.py` | Before handoff |
+| `npm run lint` | Check code style |
+| `npm run build` | Verify production build |
+---
+## Recovery Protocol
+If you break something:
+```bash
+git status                    # See changed files
+git diff                      # See what changed
+git checkout -- <file>        # Revert specific file
+git stash                     # Save and revert all
+```

package/.agent/skills/nextjs-standards/scripts/vibe-verify.py ADDED Viewed

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+VibeCode Verification Script
+============================
+Cross-platform verification for Next.js/TypeScript projects.
+Runs TypeScript check, Lint, and Build to ensure code quality.
+Usage:
+    python scripts/vibe-verify.py
+    python scripts/vibe-verify.py --quick    # Skip build, just tsc + lint
+    python scripts/vibe-verify.py --strict   # Treat warnings as errors
+"""
+import subprocess
+import sys
+import os
+from pathlib import Path
+class Colors:
+    """ANSI color codes for terminal output."""
+    GREEN = '\033[92m'
+    RED = '\033[91m'
+    YELLOW = '\033[93m'
+    BLUE = '\033[94m'
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+def detect_package_manager() -> str:
+    """Detect which package manager is being used."""
+    if Path('pnpm-lock.yaml').exists():
+        return 'pnpm'
+    elif Path('yarn.lock').exists():
+        return 'yarn'
+    elif Path('bun.lockb').exists():
+        return 'bun'
+    else:
+        return 'npm'
+def run_command(cmd: list[str], description: str) -> tuple[bool, str]:
+    """Run a command and return success status and output."""
+    print(f"\n{Colors.BLUE}🔍 {description}...{Colors.RESET}")
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            shell=(os.name == 'nt')  # Use shell on Windows
+        )
+        if result.returncode == 0:
+            print(f"{Colors.GREEN}✅ {description}: PASS{Colors.RESET}")
+            return True, result.stdout
+        else:
+            print(f"{Colors.RED}❌ {description}: FAIL{Colors.RESET}")
+            # Show error output
+            error_output = result.stderr or result.stdout
+            if error_output:
+                # Limit output to first 20 lines
+                lines = error_output.strip().split('\n')[:20]
+                for line in lines:
+                    print(f"   {line}")
+                if len(error_output.strip().split('\n')) > 20:
+                    print(f"   ... (truncated, {len(error_output.strip().split(chr(10)))} total lines)")
+            return False, error_output
+    except FileNotFoundError:
+        print(f"{Colors.YELLOW}⚠️ {description}: SKIPPED (command not found){Colors.RESET}")
+        return True, ""  # Don't fail on missing commands
+    except Exception as e:
+        print(f"{Colors.RED}❌ {description}: ERROR - {str(e)}{Colors.RESET}")
+        return False, str(e)
+def main():
+    """Run all verification checks."""
+    quick_mode = '--quick' in sys.argv
+    strict_mode = '--strict' in sys.argv
+    print(f"\n{Colors.BOLD}{'='*50}")
+    print(f"🔍 VibeCode Verification Report")
+    print(f"{'='*50}{Colors.RESET}")
+    # Check we're in a Node.js project
+    if not Path('package.json').exists():
+        print(f"{Colors.RED}❌ No package.json found. Are you in the project root?{Colors.RESET}")
+        sys.exit(1)
+    pm = detect_package_manager()
+    print(f"\n📦 Package Manager: {Colors.BLUE}{pm}{Colors.RESET}")
+    results = []
+    # 1. TypeScript Check
+    tsc_passed, tsc_output = run_command(
+        ['npx', 'tsc', '--noEmit'],
+        "TypeScript Check"
+    )
+    results.append(('TypeScript', tsc_passed))
+    # 2. Lint Check
+    lint_cmd = [pm, 'run', 'lint']
+    if pm == 'npm':
+        lint_cmd = ['npm', 'run', 'lint', '--', '--quiet'] if not strict_mode else ['npm', 'run', 'lint']
+    lint_passed, lint_output = run_command(
+        lint_cmd,
+        "Lint Check"
+    )
+    results.append(('Lint', lint_passed))
+    # 3. Build Check (skip in quick mode)
+    if not quick_mode:
+        build_cmd = [pm, 'run', 'build']
+        if pm == 'npm':
+            build_cmd = ['npm', 'run', 'build']
+        build_passed, build_output = run_command(
+            build_cmd,
+            "Build Check"
+        )
+        results.append(('Build', build_passed))
+    # Summary
+    print(f"\n{Colors.BOLD}{'='*50}")
+    print(f"📊 Summary")
+    print(f"{'='*50}{Colors.RESET}")
+    all_passed = True
+    for name, passed in results:
+        status = f"{Colors.GREEN}PASS{Colors.RESET}" if passed else f"{Colors.RED}FAIL{Colors.RESET}"
+        print(f"   {name}: {status}")
+        if not passed:
+            all_passed = False
+    print(f"{'='*50}")
+    if all_passed:
+        print(f"\n{Colors.GREEN}{Colors.BOLD}✨ All checks passed! Ready for handoff.{Colors.RESET}\n")
+        sys.exit(0)
+    else:
+        print(f"\n{Colors.RED}{Colors.BOLD}🛑 Verification failed. Fix errors before proceeding.{Colors.RESET}\n")
+        sys.exit(1)
+if __name__ == '__main__':
+    main()

package/.agent/skills/nextjs-standards/templates/Coding_Guidelines.md ADDED Viewed

@@ -0,0 +1,337 @@
+# Coding Guidelines
+> **This document is the LAW.** Follow it without exception.
+---
+## 🛑 The Verification Protocol (MANDATORY)
+### After EVERY TypeScript/TSX File Edit
+```bash
+npx tsc --noEmit
+```
+**If this command fails:**
+1. **STOP.** Do not touch another file.
+2. Read the error message carefully.
+3. Fix the type error.
+4. Re-run the command.
+5. Only proceed when it passes.
+### Before Any Handoff or "Done" Claim
+```bash
+python scripts/vibe-verify.py
+```
+All checks must pass. No exceptions.
+---
+## The Blueprint & Build Protocol
+### Phase 1: Blueprint (Before Writing Code)
+Before implementing any non-trivial feature:
+1. **Context Analysis**
+   - Check `docs/features/` for existing implementations
+   - Check if existing components/hooks can be reused
+   - Identify potential impact on other features
+2. **Create the Plan**
+   - Create `docs/features/FeatureName.md` with:
+     - High-Level Goal
+     - Component Breakdown (label Server/Client)
+     - Logic & Data Breakdown
+     - Step-by-Step Implementation Plan
+3. **Get Approval**
+   - Present the plan to the user
+   - Wait for explicit approval before coding
+### Phase 2: Build (Implementation)
+1. **Announce**: "Implementing FR-XXX: [Title]"
+2. **Reference**: Open the corresponding issue in `docs/issues/`
+3. **Implement**: One file at a time
+4. **Verify**: `npx tsc --noEmit` after each file
+5. **Mark Complete**: Check off acceptance criteria as you complete them
+6. **Update Issue**: Edit the issue file to reflect progress
+### Phase 3: Finalization
+1. Run `python scripts/vibe-verify.py`
+2. Update all acceptance criteria checkboxes
+3. Generate handoff summary
+---
+## Full-Stack Type Safety
+### The Golden Rule
+> If you change the backend, the frontend MUST type-check.
+> If type-check fails, THE CHANGE BROKE SOMETHING.
+> Fix it before moving on.
+### How It Works
+1. **Prisma/DB Changes** → Regenerate client → Type-check
+2. **API Route Changes** → Frontend consumers must type-check
+3. **Server Component Changes** → Props must align with parent
+### Tools That Help
+- **tRPC**: Frontend imports backend types directly
+- **Server Components**: Backend code returns UI with type safety
+- **Zod**: Runtime validation that generates types
+---
+## Next.js App Router Architecture
+### Server vs Client Components
+| Use Server Components For | Use Client Components For |
+|---------------------------|---------------------------|
+| Data fetching | Event handlers (onClick) |
+| Database access | useState, useEffect |
+| Rendering static content | Browser APIs (localStorage) |
+| Accessing backend services | Interactivity |
+**Default**: Server Component (no directive)
+**Client**: Add `'use client'` at top of file
+### Data Fetching
+```tsx
+// ✅ GOOD: Fetch in Server Component
+async function ProductList() {
+  const products = await db.product.findMany();
+  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
+}
+// ❌ BAD: useEffect fetching
+function ProductList() {
+  const [products, setProducts] = useState([]);
+  useEffect(() => {
+    fetch('/api/products').then(...); // Avoid this
+  }, []);
+}
+```
+### Route Structure
+```
+app/
+├── page.tsx              # Home page
+├── layout.tsx            # Root layout
+├── api/
+│   └── [resource]/
+│       └── route.ts      # API endpoints
+├── (auth)/               # Route group
+│   ├── login/page.tsx
+│   └── register/page.tsx
+└── dashboard/
+    ├── page.tsx
+    └── settings/page.tsx
+```
+---
+## File Structure (Feature-Sliced)
+```
+src/
+├── app/                    # Next.js App Router
+├── features/               # Business domains
+│   └── [FeatureName]/
+│       ├── components/     # Feature UI
+│       ├── hooks/          # Feature hooks
+│       ├── [name].service.ts
+│       └── types.ts
+├── components/
+│   ├── ui/                 # Reusable: Button, Card, Input
+│   └── layout/             # Navbar, Sidebar, Footer
+├── lib/                    # Utilities
+│   ├── db.ts               # Prisma client
+│   └── utils.ts
+└── scripts/
+    └── vibe-verify.py
+```
+---
+## Component Rules
+### The 200-Line Rule
+A component file exceeding **200 lines** is a code smell.
+**When you hit the limit:**
+1. Extract logic into a custom hook
+2. Extract sub-components into separate files
+3. Move business logic to a service file
+### Props & Types
+```tsx
+// ✅ GOOD: Interface for props
+interface UserCardProps {
+  user: User;
+  onEdit?: (id: string) => void;
+}
+function UserCard({ user, onEdit }: UserCardProps) {
+  // ...
+}
+// ❌ BAD: No types
+function UserCard(props) {
+  const user = props.user; // No type safety
+}
+```
+### Custom Hooks
+Extract stateful logic into hooks:
+```tsx
+// hooks/useUser.ts
+export function useUser(userId: string) {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    fetchUser(userId).then(setUser).finally(() => setLoading(false));
+  }, [userId]);
+  return { user, loading };
+}
+```
+---
+## Styling (Tailwind CSS v4)
+### Setup
+```css
+/* globals.css */
+@import "tailwindcss";
+@theme {
+  --color-background: #ffffff;
+  --color-foreground: #0b1221;
+  --color-border: #e5e7eb;
+  --color-ring: #3b82f6;
+  /* Brand colors */
+  --color-primary: #2563eb;
+  --color-secondary: #7c3aed;
+}
+@theme .dark {
+  --color-background: #0b1221;
+  --color-foreground: #f3f4f6;
+  --color-border: #374151;
+}
+@layer base {
+  * { @apply border-border; }
+  body { @apply bg-background text-foreground; }
+}
+```
+### Rules
+1. **Utility-first**: Apply Tailwind classes in JSX
+2. **No custom CSS**: Unless absolutely necessary
+3. **Dark mode**: Use `dark:` prefix, controlled by `.dark` class
+4. **Tokens**: Define in `@theme`, not `tailwind.config`
+---
+## Backend / API Design
+### Service Layer Pattern
+```
+Route Handler (route.ts)     →  Controller (parse, respond)
+         ↓
+Service (*.service.ts)       →  Business logic
+         ↓
+Database (Prisma)            →  Data access
+```
+### Example
+```tsx
+// app/api/users/route.ts (Controller)
+export async function POST(request: Request) {
+  const body = await request.json();
+  const validated = createUserSchema.parse(body); // Zod validation
+  const user = await userService.createUser(validated);
+  return NextResponse.json({ data: user }, { status: 201 });
+}
+// features/users/user.service.ts (Service)
+export const userService = {
+  async createUser(data: CreateUserInput) {
+    return db.user.create({ data });
+  }
+};
+```
+### Validation with Zod
+```tsx
+import { z } from 'zod';
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+  role: z.enum(['USER', 'ADMIN']).default('USER'),
+});
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+**All inputs must be validated. No exceptions.**
+---
+## Recovery Protocol
+If you break something:
+```bash
+# See what changed
+git status
+git diff
+# Revert a specific file
+git checkout -- path/to/file.tsx
+# Save changes and revert
+git stash
+# Restore saved changes
+git stash pop
+```
+---
+## Quick Reference
+| Command | When to Run |
+|---------|-------------|
+| `npx tsc --noEmit` | After every TS/TSX edit |
+| `python scripts/vibe-verify.py` | Before handoff |
+| `python scripts/vibe-verify.py --quick` | Quick check (no build) |
+| `npm run lint` | Check code style |
+| `npm run build` | Full production build |
+| `npx prisma generate` | After schema changes |
+| `npx prisma migrate dev` | Apply DB migrations |