red64-cli 0.1.0 → 0.3.0

package/framework/stacks/nextjs/api.md

@@ -0,0 +1,431 @@
+# API Design Standards
+
+Next.js App Router API conventions for route handlers, server actions, request validation, and consistent response patterns.
+
+---
+
+## Philosophy
+
+- **Server Actions first**: Use server actions for mutations; reserve route handlers for external/webhook APIs
+- **Type-safe end-to-end**: Zod validates input, TypeScript types flow from server to client
+- **Consistent responses**: Every route handler follows the same response envelope
+- **Thin handlers**: Validation and response formatting in the handler, business logic in services
+
+---
+
+## Route Handler Conventions
+
+### File Structure
+
+```
+app/
+  api/
+    health/
+      route.ts              # GET /api/health
+    users/
+      route.ts              # GET, POST /api/users
+      [id]/
+        route.ts            # GET, PATCH, DELETE /api/users/:id
+    webhooks/
+      stripe/
+        route.ts            # POST /api/webhooks/stripe
+```
+
+### Basic Route Handler
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { prisma } from "@/lib/prisma";
+import { auth } from "@/lib/auth";
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(255),
+});
+
+export async function GET(request: NextRequest) {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json(
+      { error: { code: "UNAUTHORIZED", message: "Authentication required" } },
+      { status: 401 }
+    );
+  }
+
+  const { searchParams } = request.nextUrl;
+  const page = Number(searchParams.get("page") ?? "1");
+  const limit = Math.min(Number(searchParams.get("limit") ?? "20"), 100);
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { createdAt: "desc" },
+      select: { id: true, email: true, name: true, createdAt: true },
+    }),
+    prisma.user.count(),
+  ]);
+
+  return NextResponse.json({
+    items: users,
+    total,
+    page,
+    limit,
+    totalPages: Math.ceil(total / limit),
+  });
+}
+
+export async function POST(request: NextRequest) {
+  const session = await auth();
+  if (!session) {
+    return NextResponse.json(
+      { error: { code: "UNAUTHORIZED", message: "Authentication required" } },
+      { status: 401 }
+    );
+  }
+
+  const body = await request.json();
+  const parsed = createUserSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: { code: "VALIDATION_ERROR", message: "Invalid input", details: parsed.error.flatten() } },
+      { status: 422 }
+    );
+  }
+
+  const user = await prisma.user.create({ data: parsed.data });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+---
+
+## HTTP Methods and Status Codes
+
+### RESTful Conventions
+
+| Method | URL Pattern | Action | Status |
+|---|---|---|---|
+| `GET` | `/api/users` | List users | 200 |
+| `GET` | `/api/users/42` | Get single user | 200 |
+| `POST` | `/api/users` | Create user | 201 |
+| `PATCH` | `/api/users/42` | Partial update | 200 |
+| `DELETE` | `/api/users/42` | Delete user | 204 |
+
+### URL Naming Rules
+
+```
+# GOOD
+GET  /api/users
+POST /api/users
+GET  /api/users/42/posts
+
+# BAD
+GET  /api/getUsers
+POST /api/createUser
+GET  /api/user/42/getAllPosts
+```
+
+- Plural nouns for resources: `/users`, `/posts`
+- Lowercase with hyphens for multi-word: `/api-keys`, `/user-profiles`
+- No verbs in URLs (HTTP methods convey action)
+- No trailing slashes
+- Maximum two levels of nesting
+
+---
+
+## Response Envelope
+
+### Success: Single Resource
+
+```json
+{
+  "id": 42,
+  "email": "user@example.com",
+  "name": "Jane Doe",
+  "createdAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Success: Collection
+
+```json
+{
+  "items": [...],
+  "total": 142,
+  "page": 1,
+  "limit": 20,
+  "totalPages": 8
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found",
+    "details": { "resource": "User", "id": "42" }
+  }
+}
+```
+
+### Standard Error Codes
+
+| Code | HTTP Status | Meaning |
+|---|---|---|
+| `VALIDATION_ERROR` | 422 | Invalid request body or params |
+| `UNAUTHORIZED` | 401 | Missing or invalid authentication |
+| `FORBIDDEN` | 403 | Authenticated but insufficient permissions |
+| `NOT_FOUND` | 404 | Resource does not exist |
+| `CONFLICT` | 409 | Duplicate resource or state conflict |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Unhandled server error |
+
+---
+
+## Server Actions vs Route Handlers
+
+### When to Use Each
+
+| Use Case | Approach |
+|---|---|
+| Form submissions | Server Action |
+| Data mutations from UI | Server Action |
+| External API consumers | Route Handler |
+| Webhooks | Route Handler |
+| File uploads with progress | Route Handler |
+| CORS-enabled endpoints | Route Handler |
+| Streaming responses | Route Handler |
+
+### Server Action Pattern
+
+```typescript
+// app/actions/users.ts
+"use server";
+
+import { z } from "zod";
+import { auth } from "@/lib/auth";
+import { prisma } from "@/lib/prisma";
+import { revalidatePath } from "next/cache";
+
+const updateProfileSchema = z.object({
+  name: z.string().min(1).max(255),
+  bio: z.string().max(500).optional(),
+});
+
+export async function updateProfile(formData: FormData) {
+  const session = await auth();
+  if (!session?.user?.id) {
+    return { error: "Unauthorized" };
+  }
+
+  const parsed = updateProfileSchema.safeParse({
+    name: formData.get("name"),
+    bio: formData.get("bio"),
+  });
+
+  if (!parsed.success) {
+    return { error: "Invalid input", fieldErrors: parsed.error.flatten().fieldErrors };
+  }
+
+  await prisma.user.update({
+    where: { id: session.user.id },
+    data: parsed.data,
+  });
+
+  revalidatePath("/profile");
+  return { success: true };
+}
+```
+
+---
+
+## Middleware
+
+### Authentication Middleware
+
+```typescript
+// middleware.ts
+import { auth } from "@/lib/auth";
+import { NextResponse } from "next/server";
+
+export default auth((req) => {
+  const isApiRoute = req.nextUrl.pathname.startsWith("/api");
+  const isPublicApi = req.nextUrl.pathname.startsWith("/api/health") ||
+                      req.nextUrl.pathname.startsWith("/api/webhooks");
+
+  if (isApiRoute && !isPublicApi && !req.auth) {
+    return NextResponse.json(
+      { error: { code: "UNAUTHORIZED", message: "Authentication required" } },
+      { status: 401 }
+    );
+  }
+
+  return NextResponse.next();
+});
+
+export const config = {
+  matcher: ["/api/:path*", "/dashboard/:path*"],
+};
+```
+
+### CORS for Route Handlers
+
+```typescript
+// app/api/public/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+const ALLOWED_ORIGINS = [
+  "https://example.com",
+  process.env.NODE_ENV === "development" && "http://localhost:3001",
+].filter(Boolean) as string[];
+
+function corsHeaders(origin: string | null) {
+  const headers = new Headers();
+  if (origin && ALLOWED_ORIGINS.includes(origin)) {
+    headers.set("Access-Control-Allow-Origin", origin);
+    headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    headers.set("Access-Control-Max-Age", "86400");
+  }
+  return headers;
+}
+
+export async function OPTIONS(request: NextRequest) {
+  return new NextResponse(null, {
+    status: 204,
+    headers: corsHeaders(request.headers.get("origin")),
+  });
+}
+
+export async function GET(request: NextRequest) {
+  const data = { message: "Hello" };
+  return NextResponse.json(data, {
+    headers: corsHeaders(request.headers.get("origin")),
+  });
+}
+```
+
+---
+
+## Rate Limiting
+
+### Token Bucket with Headers
+
+```typescript
+// lib/rate-limit.ts
+const rateLimitMap = new Map<string, { tokens: number; lastRefill: number }>();
+
+export function rateLimit(
+  key: string,
+  options: { limit: number; windowMs: number }
+): { success: boolean; remaining: number; reset: number } {
+  const now = Date.now();
+  const record = rateLimitMap.get(key) ?? { tokens: options.limit, lastRefill: now };
+
+  const elapsed = now - record.lastRefill;
+  const refillRate = options.limit / options.windowMs;
+  record.tokens = Math.min(options.limit, record.tokens + elapsed * refillRate);
+  record.lastRefill = now;
+
+  if (record.tokens < 1) {
+    rateLimitMap.set(key, record);
+    return { success: false, remaining: 0, reset: Math.ceil(options.windowMs / 1000) };
+  }
+
+  record.tokens -= 1;
+  rateLimitMap.set(key, record);
+  return { success: true, remaining: Math.floor(record.tokens), reset: Math.ceil(options.windowMs / 1000) };
+}
+
+// Usage in route handler
+export async function POST(request: NextRequest) {
+  const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+  const { success, remaining, reset } = rateLimit(ip, { limit: 10, windowMs: 60_000 });
+
+  if (!success) {
+    return NextResponse.json(
+      { error: { code: "RATE_LIMITED", message: "Too many requests" } },
+      {
+        status: 429,
+        headers: {
+          "X-RateLimit-Limit": "10",
+          "X-RateLimit-Remaining": String(remaining),
+          "X-RateLimit-Reset": String(reset),
+          "Retry-After": String(reset),
+        },
+      }
+    );
+  }
+
+  // ... handle request
+}
+```
+
+---
+
+## Streaming Responses
+
+```typescript
+// app/api/stream/route.ts
+export async function GET() {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (const chunk of ["Hello", " ", "World"]) {
+        controller.enqueue(encoder.encode(chunk));
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}
+```
+
+---
+
+## Health Check
+
+```typescript
+// app/api/health/route.ts
+import { prisma } from "@/lib/prisma";
+
+export async function GET() {
+  try {
+    await prisma.$queryRaw`SELECT 1`;
+    return Response.json({ status: "ok", database: "connected" });
+  } catch {
+    return Response.json(
+      { status: "error", database: "disconnected" },
+      { status: 503 }
+    );
+  }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Verbs in URLs | Not RESTful | Use HTTP methods to convey action |
+| Using route handlers for form submissions | Unnecessary complexity | Use server actions for UI mutations |
+| No input validation | Security risk, bad data | Validate with zod in every handler |
+| Business logic in route handlers | Hard to test, duplicated | Extract to service functions |
+| Returning raw Prisma errors | Leaks schema details | Map to error envelope with safe messages |
+| No rate limiting on auth endpoints | Brute force vulnerability | Rate limit login and signup endpoints |
+
+---
+
+_APIs are contracts. Validate every input, standardize every output, and keep business logic out of handlers._

package/framework/stacks/nextjs/coding-style.md

@@ -0,0 +1,282 @@
+# Coding Style
+
+TypeScript and React conventions for Next.js 15 App Router projects with strict type safety and consistent patterns.
+
+---
+
+## Philosophy
+
+- **Strict TypeScript**: Enable all strict checks; `any` is a code smell, not a solution
+- **Explicit over implicit**: Named exports, explicit return types on public functions, no magic
+- **Consistency**: One way to do things, enforced by tooling, not willpower
+- **Functional React**: Function components, hooks, composition over inheritance
+
+---
+
+## TypeScript Configuration
+
+### Strict Mode (Non-Negotiable)
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### Type vs Interface
+
+| Use | When |
+|---|---|
+| `type` | Unions, intersections, mapped types, utility types |
+| `interface` | Object shapes that may be extended, component props |
+
+```typescript
+// Interface for props (extendable)
+interface ButtonProps {
+  variant: "primary" | "secondary";
+  size?: "sm" | "md" | "lg";
+  children: React.ReactNode;
+}
+
+// Type for unions and utility types
+type ApiResponse<T> = { data: T; error: null } | { data: null; error: string };
+type UserRole = "admin" | "member" | "viewer";
+```
+
+**Rule**: Be consistent within a file. When in doubt, use `interface` for props and `type` for everything else.
+
+---
+
+## Naming Conventions
+
+| Entity | Convention | Example |
+|---|---|---|
+| Components | PascalCase | `UserProfile`, `DataTable` |
+| Component files | PascalCase or kebab-case | `UserProfile.tsx` or `user-profile.tsx` |
+| Hooks | camelCase with `use` prefix | `useAuth`, `useDebounce` |
+| Utilities | camelCase | `formatDate`, `cn` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES`, `API_BASE_URL` |
+| Types/Interfaces | PascalCase | `UserProfile`, `ApiResponse` |
+| Enums | PascalCase (members too) | `UserRole.Admin` |
+| Route files | lowercase (Next.js convention) | `page.tsx`, `layout.tsx`, `route.ts` |
+| Server actions | camelCase verb phrases | `createUser`, `updateProfile` |
+| Zod schemas | camelCase + Schema suffix | `createUserSchema`, `loginSchema` |
+| Environment variables | UPPER_SNAKE_CASE | `DATABASE_URL`, `NEXT_PUBLIC_APP_NAME` |
+
+### Boolean Naming
+
+```typescript
+// Prefix with is, has, can, should
+const isLoading = true;
+const hasPermission = user.role === "admin";
+const canEdit = hasPermission && !isArchived;
+const shouldRefetch = Date.now() - lastFetch > STALE_TIME;
+```
+
+---
+
+## Function Components
+
+### Component Structure
+
+```typescript
+// 1. Imports
+import { type ComponentProps } from "react";
+import { cn } from "@/lib/utils";
+
+// 2. Types
+interface CardProps {
+  title: string;
+  description?: string;
+  children: React.ReactNode;
+  className?: string;
+}
+
+// 3. Component (named export)
+export function Card({ title, description, children, className }: CardProps) {
+  return (
+    <div className={cn("rounded-lg border p-6", className)}>
+      <h3 className="text-lg font-semibold">{title}</h3>
+      {description && <p className="text-muted-foreground mt-1">{description}</p>}
+      <div className="mt-4">{children}</div>
+    </div>
+  );
+}
+```
+
+### Rules
+
+- Named exports only (no `export default` except for `page.tsx`, `layout.tsx`, and other Next.js conventions)
+- Props interface defined above the component
+- Destructure props in the function signature
+- No `React.FC` -- use plain function with typed props
+
+---
+
+## Import Organization
+
+### Order (Enforced by ESLint)
+
+```typescript
+// 1. React / Next.js
+import { useState, useCallback } from "react";
+import { useRouter } from "next/navigation";
+import Image from "next/image";
+
+// 2. External libraries
+import { z } from "zod";
+import { useForm } from "react-hook-form";
+
+// 3. Internal aliases (@/)
+import { prisma } from "@/lib/prisma";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+
+// 4. Relative imports
+import { UserAvatar } from "./user-avatar";
+
+// 5. Types (type-only imports)
+import type { User } from "@prisma/client";
+```
+
+### Barrel Exports
+
+```typescript
+// components/ui/index.ts -- use sparingly
+export { Button } from "./button";
+export { Input } from "./input";
+export { Card } from "./card";
+```
+
+**Warning**: Barrel exports can hurt tree-shaking and dev server performance. Use them for UI component libraries only, not for feature modules.
+
+---
+
+## Hooks Patterns
+
+### Custom Hook Structure
+
+```typescript
+// hooks/use-debounce.ts
+import { useState, useEffect } from "react";
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+```
+
+### Hook Rules
+
+- One hook per file, named after the hook
+- Always return a stable API (avoid returning new object references)
+- Prefer returning tuples for simple state: `[value, setValue]`
+- Prefer returning objects for complex state: `{ data, error, isLoading }`
+
+---
+
+## ESLint and Prettier
+
+### ESLint Flat Config
+
+```javascript
+// eslint.config.mjs
+import { FlatCompat } from "@eslint/eslintrc";
+
+const compat = new FlatCompat({ baseDirectory: import.meta.dirname });
+
+export default [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/no-explicit-any": "error",
+      "prefer-const": "error",
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+    },
+  },
+];
+```
+
+### Prettier Config
+
+```json
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "plugins": ["prettier-plugin-tailwindcss"]
+}
+```
+
+---
+
+## Module Organization
+
+### Feature Modules
+
+```
+src/
+  app/                     # Next.js routes
+  components/
+    ui/                    # Reusable UI primitives (Button, Input, Card)
+    forms/                 # Form-specific components
+    layouts/               # Layout components (Sidebar, Header)
+  lib/
+    prisma.ts              # Prisma client singleton
+    auth.ts                # NextAuth configuration
+    utils.ts               # General utilities (cn, formatDate)
+  hooks/                   # Custom React hooks
+  actions/                 # Server actions
+  types/                   # Shared type definitions
+```
+
+### Avoid Deep Nesting
+
+```typescript
+// GOOD: Flat imports with aliases
+import { Button } from "@/components/ui/button";
+import { prisma } from "@/lib/prisma";
+
+// BAD: Deep relative paths
+import { Button } from "../../../components/ui/button";
+import { prisma } from "../../../lib/prisma";
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| `any` type | Bypasses type checking entirely | Use `unknown` and narrow, or define proper types |
+| `export default` everywhere | Inconsistent naming on import | Named exports except Next.js conventions |
+| `React.FC` | Legacy, issues with generics | Plain function with typed props |
+| Barrel exports for features | Breaks tree-shaking, slow HMR | Direct imports for feature modules |
+| `as` type assertions | Unsafe, hides errors | Type guards and narrowing |
+| Inline types in function signatures | Unreadable, not reusable | Define named types and interfaces |
+| `// @ts-ignore` | Silences real errors | Fix the type, or use `// @ts-expect-error` with explanation |
+
+---
+
+_TypeScript exists to catch bugs before they ship. Configure it strictly, trust the compiler, and never silence it without a comment explaining why._