@girardmedia/bootspring 1.1.2 → 1.1.5

package/README.md

@@ -30,6 +30,37 @@ npm install -g @girardmedia/bootspring
 bootspring init
 ```
 
+## Authentication
+
+Bootspring uses account-based authentication with device fingerprinting for security.
+
+```bash
+# Register a new account
+bootspring auth register
+
+# Login to your account
+bootspring auth login
+
+# View account status
+bootspring auth status
+
+# Logout
+bootspring auth logout
+```
+
+### Device Management
+
+Each account has a device limit based on your subscription tier:
+
+| Tier | Max Devices |
+|------|-------------|
+| Free | 2 |
+| Pro | 5 |
+| Team | 10 |
+| Enterprise | 50 |
+
+Your devices are automatically tracked when you login. If you hit your device limit, logout from another device or upgrade your plan.
+
 ## Commands
 
 ### Getting Started
@@ -55,13 +86,16 @@ bootspring context validate  # Validate project setup
 ```bash
 bootspring agent list        # List available agents
 bootspring agent show <name> # Show agent details
-bootspring agent invoke <n>  # Get specialized help
+bootspring agent invoke <n>  # Get specialized help (MCP required)
 bootspring skill search <q>  # Find code patterns
+bootspring skill show <name> # View skill content (MCP required)
 bootspring skill list --external  # Include curated external catalog
 bootspring orchestrator workflows  # List workflows and premium packs
 bootspring telemetry status  # Inspect local telemetry pipeline
 ```
 
+> **Note:** Commands marked "MCP required" only work when invoked through an MCP-compatible AI assistant (Claude Code, etc). This protects proprietary prompts and agent configurations from being exposed in standalone CLI mode.
+
 Premium workflow packs:
 
 - `launch-pack` (pro)

package/agents/README.md

@@ -0,0 +1,93 @@
+# Bootspring Agents
+
+Specialized AI agents for different development domains. Each agent provides focused expertise, context, and patterns for its area.
+
+## Available Agents
+
+| Agent | Domain | Use When |
+|-------|--------|----------|
+| [database-expert](./database-expert/) | Database & ORM | Schema design, queries, migrations |
+| [security-expert](./security-expert/) | Security & Auth | Auth flows, vulnerabilities, OWASP |
+| [frontend-expert](./frontend-expert/) | UI & React | Components, state, styling |
+| [backend-expert](./backend-expert/) | Server Logic | API routes, server actions, business logic |
+| [api-expert](./api-expert/) | API Design | REST, GraphQL, route handlers |
+| [testing-expert](./testing-expert/) | Testing | Unit, integration, E2E tests |
+| [performance-expert](./performance-expert/) | Performance | Optimization, caching, profiling |
+| [devops-expert](./devops-expert/) | DevOps & CI/CD | Deployment, pipelines, infrastructure |
+| [ui-ux-expert](./ui-ux-expert/) | Design & UX | User experience, accessibility, design |
+| [architecture-expert](./architecture-expert/) | Architecture | System design, patterns, scaling |
+| [code-review-expert](./code-review-expert/) | Code Quality | Reviews, best practices, refactoring |
+| [vercel-expert](./vercel-expert/) | Vercel Platform | Deployment, edge, serverless |
+
+## Using Agents
+
+### Via CLI
+```bash
+# List all agents
+bootspring agent list
+
+# Show agent details
+bootspring agent show database-expert
+
+# Invoke agent for current context
+bootspring agent invoke security-expert
+```
+
+### Via MCP
+When using Claude Code, agents are automatically suggested based on your task context. You can also explicitly request an agent:
+
+```
+@bootspring agent database-expert
+```
+
+### Agent Selection
+
+Bootspring automatically detects which agents are relevant based on keywords in your request:
+
+- **database-expert**: database, schema, prisma, drizzle, migration, query, model
+- **security-expert**: auth, login, security, password, jwt, csrf, xss, owasp
+- **frontend-expert**: component, react, ui, tailwind, state, client, hook
+- **backend-expert**: api, server, action, business, logic, service
+- **testing-expert**: test, spec, jest, vitest, playwright, coverage
+- **performance-expert**: performance, optimize, cache, slow, fast, bundle
+- **devops-expert**: deploy, ci, cd, docker, kubernetes, pipeline
+- **architecture-expert**: architecture, design, pattern, scale, structure
+
+## Agent Context Files
+
+Each agent directory contains:
+
+```
+agents/{name}/
+├── context.md       # Full agent context and expertise
+├── patterns.md      # Common patterns this agent uses
+└── checklist.md     # Review checklist for this domain
+```
+
+## Creating Custom Agents
+
+Add a new directory under `agents/` with at minimum a `context.md` file:
+
+```markdown
+# Custom Agent Name
+
+## Role
+Brief description of what this agent does.
+
+## Expertise
+- Area 1
+- Area 2
+
+## Context
+Detailed knowledge and patterns...
+```
+
+Then register it in your `bootspring.config.js`:
+
+```javascript
+module.exports = {
+  agents: {
+    custom: ['my-custom-agent']
+  }
+};
+```

package/agents/api-expert/context.md

@@ -0,0 +1,416 @@
+# API Expert Agent
+
+## Role
+Specialized in API design, RESTful patterns, GraphQL, route handler implementation, and API documentation for modern web applications.
+
+## Core Expertise
+
+### RESTful API Design
+
+#### Resource Naming
+```
+# Good: Plural nouns, hierarchical
+GET    /api/users
+GET    /api/users/{id}
+GET    /api/users/{id}/posts
+POST   /api/users
+PATCH  /api/users/{id}
+DELETE /api/users/{id}
+
+# Avoid: Verbs in URLs
+GET    /api/getUsers        ❌
+POST   /api/createUser      ❌
+POST   /api/users/delete/1  ❌
+```
+
+#### HTTP Methods & Status Codes
+```typescript
+// GET: Retrieve resource(s)
+// 200 OK - Success
+// 404 Not Found - Resource doesn't exist
+
+// POST: Create resource
+// 201 Created - Resource created
+// 400 Bad Request - Validation failed
+// 409 Conflict - Duplicate (unique constraint)
+
+// PATCH: Partial update
+// 200 OK - Updated
+// 404 Not Found - Resource doesn't exist
+
+// PUT: Full replacement
+// 200 OK - Replaced
+// 201 Created - Created if didn't exist
+
+// DELETE: Remove resource
+// 204 No Content - Deleted
+// 404 Not Found - Resource doesn't exist
+```
+
+### Route Handler Patterns
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { auth } from '@clerk/nextjs/server';
+import { prisma } from '@/lib/prisma';
+import { z } from 'zod';
+
+// Pagination helper
+function parsePagination(searchParams: URLSearchParams) {
+  return {
+    page: Math.max(1, parseInt(searchParams.get('page') ?? '1')),
+    limit: Math.min(100, Math.max(1, parseInt(searchParams.get('limit') ?? '20'))),
+    sort: searchParams.get('sort') ?? 'createdAt',
+    order: (searchParams.get('order') ?? 'desc') as 'asc' | 'desc',
+  };
+}
+
+// GET with filtering, sorting, pagination
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const { page, limit, sort, order } = parsePagination(searchParams);
+
+  // Filters
+  const status = searchParams.get('status');
+  const authorId = searchParams.get('authorId');
+  const search = searchParams.get('q');
+
+  const where = {
+    ...(status && { status }),
+    ...(authorId && { authorId }),
+    ...(search && {
+      OR: [
+        { title: { contains: search, mode: 'insensitive' } },
+        { content: { contains: search, mode: 'insensitive' } },
+      ],
+    }),
+  };
+
+  const [posts, total] = await Promise.all([
+    prisma.post.findMany({
+      where,
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { [sort]: order },
+      include: {
+        author: { select: { id: true, name: true, avatar: true } },
+        _count: { select: { comments: true, likes: true } },
+      },
+    }),
+    prisma.post.count({ where }),
+  ]);
+
+  return NextResponse.json({
+    data: posts,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+      hasNext: page * limit < total,
+      hasPrev: page > 1,
+    },
+  });
+}
+
+// POST with validation
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+  status: z.enum(['draft', 'published']).default('draft'),
+  tags: z.array(z.string()).optional(),
+});
+
+export async function POST(request: NextRequest) {
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
+  }
+
+  const result = CreatePostSchema.safeParse(body);
+  if (!result.success) {
+    return NextResponse.json(
+      { error: 'Validation failed', details: result.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  const post = await prisma.post.create({
+    data: {
+      ...result.data,
+      authorId: userId,
+    },
+    include: {
+      author: { select: { id: true, name: true } },
+    },
+  });
+
+  return NextResponse.json(post, { status: 201 });
+}
+```
+
+### API Response Formats
+
+```typescript
+// Consistent response envelope
+interface ApiResponse<T> {
+  data: T;
+  meta?: {
+    pagination?: Pagination;
+    [key: string]: unknown;
+  };
+}
+
+interface ApiError {
+  error: string;
+  code?: string;
+  details?: Record<string, string[]>;
+}
+
+// Helper function
+function apiResponse<T>(data: T, meta?: Record<string, unknown>): NextResponse {
+  return NextResponse.json({ data, ...(meta && { meta }) });
+}
+
+function apiError(
+  message: string,
+  status: number,
+  details?: Record<string, unknown>
+): NextResponse {
+  return NextResponse.json(
+    { error: message, ...details },
+    { status }
+  );
+}
+
+// Usage
+return apiResponse(posts, { pagination });
+return apiError('Validation failed', 400, { details: errors });
+```
+
+### API Versioning
+
+```typescript
+// app/api/v1/users/route.ts
+// app/api/v2/users/route.ts
+
+// Or via headers
+export async function GET(request: NextRequest) {
+  const version = request.headers.get('api-version') ?? 'v1';
+
+  if (version === 'v2') {
+    // V2 response format
+    return NextResponse.json({ users: data, meta: {} });
+  }
+
+  // V1 response format (default)
+  return NextResponse.json(data);
+}
+```
+
+### Rate Limiting
+
+```typescript
+// lib/rate-limit.ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(100, '1 m'),
+});
+
+export async function rateLimit(identifier: string) {
+  const { success, limit, remaining, reset } = await ratelimit.limit(identifier);
+
+  return {
+    success,
+    headers: {
+      'X-RateLimit-Limit': limit.toString(),
+      'X-RateLimit-Remaining': remaining.toString(),
+      'X-RateLimit-Reset': reset.toString(),
+    },
+  };
+}
+
+// Usage in route
+export async function POST(request: NextRequest) {
+  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous';
+  const { success, headers } = await rateLimit(`api:${ip}`);
+
+  if (!success) {
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      { status: 429, headers }
+    );
+  }
+
+  // Process request...
+  const response = NextResponse.json(data);
+  Object.entries(headers).forEach(([key, value]) => {
+    response.headers.set(key, value);
+  });
+  return response;
+}
+```
+
+### CORS Configuration
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+const allowedOrigins = [
+  'https://yourapp.com',
+  'https://admin.yourapp.com',
+];
+
+export function middleware(request: NextRequest) {
+  const origin = request.headers.get('origin');
+  const isApiRoute = request.nextUrl.pathname.startsWith('/api');
+
+  if (isApiRoute) {
+    // Handle preflight
+    if (request.method === 'OPTIONS') {
+      return new NextResponse(null, {
+        status: 204,
+        headers: {
+          'Access-Control-Allow-Origin': allowedOrigins.includes(origin ?? '') ? origin! : '',
+          'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+          'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+          'Access-Control-Max-Age': '86400',
+        },
+      });
+    }
+
+    // Add CORS headers to response
+    const response = NextResponse.next();
+    if (origin && allowedOrigins.includes(origin)) {
+      response.headers.set('Access-Control-Allow-Origin', origin);
+    }
+    return response;
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: '/api/:path*',
+};
+```
+
+### OpenAPI Documentation
+
+```typescript
+// Using next-swagger-doc
+// lib/swagger.ts
+import { createSwaggerSpec } from 'next-swagger-doc';
+
+export const getApiDocs = () => {
+  const spec = createSwaggerSpec({
+    apiFolder: 'app/api',
+    definition: {
+      openapi: '3.0.0',
+      info: {
+        title: 'Your API',
+        version: '1.0.0',
+      },
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+          },
+        },
+      },
+      security: [{ bearerAuth: [] }],
+    },
+  });
+  return spec;
+};
+
+// JSDoc comments in route handlers
+/**
+ * @swagger
+ * /api/posts:
+ *   get:
+ *     summary: List posts
+ *     tags: [Posts]
+ *     parameters:
+ *       - in: query
+ *         name: page
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: List of posts
+ */
+export async function GET(request: NextRequest) {
+  // ...
+}
+```
+
+### File Upload API
+
+```typescript
+// app/api/upload/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { put } from '@vercel/blob';
+
+export async function POST(request: NextRequest) {
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const formData = await request.formData();
+  const file = formData.get('file') as File;
+
+  if (!file) {
+    return NextResponse.json({ error: 'No file provided' }, { status: 400 });
+  }
+
+  // Validate file
+  const maxSize = 5 * 1024 * 1024; // 5MB
+  if (file.size > maxSize) {
+    return NextResponse.json({ error: 'File too large' }, { status: 400 });
+  }
+
+  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
+  if (!allowedTypes.includes(file.type)) {
+    return NextResponse.json({ error: 'Invalid file type' }, { status: 400 });
+  }
+
+  // Upload to Vercel Blob
+  const blob = await put(file.name, file, {
+    access: 'public',
+  });
+
+  return NextResponse.json({ url: blob.url }, { status: 201 });
+}
+```
+
+## API Checklist
+
+- [ ] RESTful naming conventions
+- [ ] Proper HTTP methods used
+- [ ] Consistent response format
+- [ ] Input validation with Zod
+- [ ] Authentication required
+- [ ] Rate limiting configured
+- [ ] CORS headers set
+- [ ] Error responses standardized
+- [ ] Pagination implemented
+- [ ] API documentation added
+
+## Trigger Keywords
+api, rest, endpoint, route, handler, get, post, patch, delete, request, response, json, cors, rate limit, pagination, filter, sort, openapi, swagger, webhook