@girardmedia/bootspring 1.1.0

package/agents/performance-expert/context.md

@@ -0,0 +1,377 @@
+# Performance Expert Agent
+
+## Role
+Specialized in web performance optimization, Core Web Vitals, caching strategies, bundle optimization, and ensuring fast user experiences.
+
+## Core Expertise
+
+### Core Web Vitals
+
+```
+LCP (Largest Contentful Paint): < 2.5s
+  - Optimize images (WebP, proper sizing)
+  - Preload critical resources
+  - Server-side rendering
+
+FID (First Input Delay): < 100ms
+  - Minimize JavaScript execution
+  - Break up long tasks
+  - Use Web Workers for heavy computation
+
+CLS (Cumulative Layout Shift): < 0.1
+  - Set explicit dimensions on images/videos
+  - Reserve space for dynamic content
+  - Avoid inserting content above existing content
+```
+
+### Image Optimization
+
+```tsx
+// Use Next.js Image component
+import Image from 'next/image';
+
+// Good: Optimized images
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority // For above-the-fold images
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,..."
+/>
+
+// Responsive images
+<Image
+  src="/product.jpg"
+  alt="Product"
+  fill
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  className="object-cover"
+/>
+
+// Remote images - configure in next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'cdn.example.com',
+      },
+    ],
+    formats: ['image/avif', 'image/webp'],
+  },
+};
+```
+
+### Code Splitting & Lazy Loading
+
+```tsx
+// Dynamic imports for code splitting
+import dynamic from 'next/dynamic';
+
+// Heavy component loaded only when needed
+const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false, // Client-only component
+});
+
+// Route-based code splitting (automatic in App Router)
+// Each page.tsx is automatically code-split
+
+// Lazy load below-the-fold content
+'use client';
+import { useInView } from 'react-intersection-observer';
+
+function LazySection() {
+  const { ref, inView } = useInView({
+    triggerOnce: true,
+    rootMargin: '200px',
+  });
+
+  return (
+    <div ref={ref}>
+      {inView ? <HeavyContent /> : <Placeholder />}
+    </div>
+  );
+}
+```
+
+### Bundle Analysis & Optimization
+
+```bash
+# Analyze bundle
+npm install @next/bundle-analyzer
+
+# next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+module.exports = withBundleAnalyzer({
+  // config
+});
+
+# Run analysis
+ANALYZE=true npm run build
+```
+
+```typescript
+// Tree-shaking friendly imports
+// Bad: Imports entire library
+import _ from 'lodash';
+
+// Good: Import only what's needed
+import debounce from 'lodash/debounce';
+
+// Or use lodash-es for better tree-shaking
+import { debounce } from 'lodash-es';
+```
+
+### Caching Strategies
+
+```typescript
+// app/api/posts/route.ts
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const posts = await getPosts();
+
+  return NextResponse.json(posts, {
+    headers: {
+      // Cache for 1 hour, revalidate in background
+      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
+    },
+  });
+}
+
+// Page-level caching with revalidation
+// app/posts/page.tsx
+export const revalidate = 3600; // Revalidate every hour
+
+// On-demand revalidation
+// app/api/revalidate/route.ts
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+export async function POST(request: Request) {
+  const { path, tag } = await request.json();
+
+  if (path) revalidatePath(path);
+  if (tag) revalidateTag(tag);
+
+  return Response.json({ revalidated: true });
+}
+
+// Using tags for granular cache control
+async function getPosts() {
+  return fetch('https://api.example.com/posts', {
+    next: { tags: ['posts'] },
+  });
+}
+```
+
+### Database Query Optimization
+
+```typescript
+// Avoid N+1 queries
+// Bad: N+1 problem
+const users = await prisma.user.findMany();
+for (const user of users) {
+  user.posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// Good: Include related data
+const users = await prisma.user.findMany({
+  include: {
+    posts: {
+      take: 5,
+      orderBy: { createdAt: 'desc' },
+    },
+  },
+});
+
+// Use select for partial data
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    // Only fields you need
+  },
+});
+
+// Pagination with cursor (more efficient than offset)
+const posts = await prisma.post.findMany({
+  take: 20,
+  cursor: lastPostId ? { id: lastPostId } : undefined,
+  skip: lastPostId ? 1 : 0,
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+### React Performance
+
+```tsx
+// Memo for expensive computations
+'use client';
+import { useMemo, useCallback, memo } from 'react';
+
+function ExpensiveList({ items, filter }) {
+  // Memoize expensive computation
+  const filteredItems = useMemo(() => {
+    return items.filter(item =>
+      item.name.toLowerCase().includes(filter.toLowerCase())
+    );
+  }, [items, filter]);
+
+  // Memoize callback
+  const handleItemClick = useCallback((id: string) => {
+    console.log('Clicked:', id);
+  }, []);
+
+  return (
+    <ul>
+      {filteredItems.map(item => (
+        <MemoizedItem
+          key={item.id}
+          item={item}
+          onClick={handleItemClick}
+        />
+      ))}
+    </ul>
+  );
+}
+
+// Memoize component
+const MemoizedItem = memo(function Item({ item, onClick }) {
+  return (
+    <li onClick={() => onClick(item.id)}>
+      {item.name}
+    </li>
+  );
+});
+
+// Virtualization for long lists
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} className="h-[400px] overflow-auto">
+      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+        {virtualizer.getVirtualItems().map(virtualRow => (
+          <div
+            key={virtualRow.key}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              height: `${virtualRow.size}px`,
+              transform: `translateY(${virtualRow.start}px)`,
+            }}
+          >
+            {items[virtualRow.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Preloading & Prefetching
+
+```tsx
+// Prefetch on hover
+import Link from 'next/link';
+
+<Link href="/dashboard" prefetch={true}>
+  Dashboard
+</Link>
+
+// Preload critical resources
+// app/layout.tsx
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossOrigin="" />
+        <link rel="preconnect" href="https://api.example.com" />
+        <link rel="dns-prefetch" href="https://analytics.example.com" />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Streaming with Suspense
+import { Suspense } from 'react';
+
+export default async function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Stream this content as it becomes available */}
+      <Suspense fallback={<StatsSkeleton />}>
+        <Stats />
+      </Suspense>
+      <Suspense fallback={<ChartSkeleton />}>
+        <RevenueChart />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### Monitoring & Metrics
+
+```typescript
+// Using Web Vitals API
+// app/components/WebVitals.tsx
+'use client';
+
+import { useReportWebVitals } from 'next/web-vitals';
+
+export function WebVitals() {
+  useReportWebVitals((metric) => {
+    // Send to analytics
+    console.log(metric);
+
+    // Example: Send to custom endpoint
+    fetch('/api/analytics', {
+      method: 'POST',
+      body: JSON.stringify({
+        name: metric.name,
+        value: metric.value,
+        rating: metric.rating, // 'good', 'needs-improvement', 'poor'
+      }),
+    });
+  });
+
+  return null;
+}
+```
+
+## Performance Checklist
+
+- [ ] Images optimized with next/image
+- [ ] Lazy loading for below-fold content
+- [ ] Bundle analyzed and optimized
+- [ ] Database queries include/select optimized
+- [ ] Caching strategy implemented
+- [ ] No layout shift (CLS)
+- [ ] Critical CSS inlined
+- [ ] Fonts optimized
+- [ ] Third-party scripts deferred
+- [ ] Web Vitals monitoring in place
+
+## Trigger Keywords
+performance, optimize, slow, fast, cache, bundle, lazy load, code split, web vitals, lcp, fid, cls, image, font, preload, prefetch, streaming, virtualize

package/agents/security-expert/context.md

@@ -0,0 +1,343 @@
+# Security Expert Agent
+
+## Role
+Specialized in application security, authentication, authorization, and protecting against common vulnerabilities. Expert in OWASP guidelines and secure coding practices.
+
+## Core Expertise
+
+### Authentication Patterns
+
+#### Clerk Integration
+```typescript
+// Middleware setup
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher([
+  '/',
+  '/sign-in(.*)',
+  '/sign-up(.*)',
+  '/api/webhooks(.*)',
+]);
+
+export default clerkMiddleware((auth, req) => {
+  if (!isPublicRoute(req)) {
+    auth().protect();
+  }
+});
+
+// Server Component auth check
+import { auth } from '@clerk/nextjs/server';
+
+export default async function ProtectedPage() {
+  const { userId } = await auth();
+  if (!userId) redirect('/sign-in');
+
+  return <Dashboard />;
+}
+
+// Client Component hook
+'use client';
+import { useAuth, useUser } from '@clerk/nextjs';
+
+export function UserProfile() {
+  const { isLoaded, userId } = useAuth();
+  const { user } = useUser();
+
+  if (!isLoaded) return <Skeleton />;
+  if (!userId) return <SignInButton />;
+
+  return <div>Hello, {user?.firstName}</div>;
+}
+```
+
+#### NextAuth.js
+```typescript
+// app/api/auth/[...nextauth]/route.ts
+import NextAuth from 'next-auth';
+import GitHub from 'next-auth/providers/github';
+import Google from 'next-auth/providers/google';
+import Credentials from 'next-auth/providers/credentials';
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  providers: [
+    GitHub,
+    Google,
+    Credentials({
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' }
+      },
+      async authorize(credentials) {
+        // Validate credentials against database
+        const user = await validateUser(credentials);
+        return user;
+      }
+    })
+  ],
+  callbacks: {
+    async jwt({ token, user }) {
+      if (user) {
+        token.role = user.role;
+      }
+      return token;
+    },
+    async session({ session, token }) {
+      session.user.role = token.role;
+      return session;
+    }
+  }
+});
+
+export const { GET, POST } = handlers;
+```
+
+### Authorization & RBAC
+
+```typescript
+// Role-based access control
+type Role = 'user' | 'admin' | 'superadmin';
+
+const PERMISSIONS = {
+  user: ['read:own', 'write:own'],
+  admin: ['read:all', 'write:all', 'delete:own'],
+  superadmin: ['read:all', 'write:all', 'delete:all', 'admin:users']
+} as const;
+
+function hasPermission(role: Role, permission: string): boolean {
+  return PERMISSIONS[role]?.includes(permission) ?? false;
+}
+
+// Server Action with authorization
+async function deleteUser(userId: string) {
+  const session = await auth();
+  if (!session?.user) throw new Error('Unauthorized');
+
+  const canDelete = hasPermission(session.user.role, 'delete:all') ||
+    (hasPermission(session.user.role, 'delete:own') && session.user.id === userId);
+
+  if (!canDelete) throw new Error('Forbidden');
+
+  await prisma.user.delete({ where: { id: userId } });
+}
+```
+
+### Input Validation & Sanitization
+
+```typescript
+import { z } from 'zod';
+import DOMPurify from 'isomorphic-dompurify';
+
+// Zod schema for validation
+const UserInputSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100).transform(s => s.trim()),
+  bio: z.string().max(1000).optional().transform(s =>
+    s ? DOMPurify.sanitize(s) : s
+  ),
+  website: z.string().url().optional().or(z.literal('')),
+});
+
+// Usage in Server Action
+export async function updateProfile(formData: FormData) {
+  const result = UserInputSchema.safeParse({
+    email: formData.get('email'),
+    name: formData.get('name'),
+    bio: formData.get('bio'),
+    website: formData.get('website'),
+  });
+
+  if (!result.success) {
+    return { error: result.error.flatten() };
+  }
+
+  // Safe to use result.data
+  await prisma.user.update({
+    where: { id: userId },
+    data: result.data
+  });
+}
+```
+
+### OWASP Top 10 Protection
+
+#### 1. Injection Prevention
+```typescript
+// ALWAYS use parameterized queries
+// Bad: SQL injection vulnerable
+const result = await db.query(`SELECT * FROM users WHERE id = '${userId}'`);
+
+// Good: Parameterized
+const result = await prisma.user.findUnique({ where: { id: userId } });
+
+// For raw queries, use parameters
+const result = await prisma.$queryRaw`SELECT * FROM users WHERE id = ${userId}`;
+```
+
+#### 2. XSS Prevention
+```typescript
+// React escapes by default, but be careful with:
+// Bad: dangerouslySetInnerHTML without sanitization
+<div dangerouslySetInnerHTML={{ __html: userContent }} />
+
+// Good: Sanitize first
+import DOMPurify from 'isomorphic-dompurify';
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />
+
+// Better: Use markdown library with sanitization
+import { marked } from 'marked';
+const html = DOMPurify.sanitize(marked.parse(userContent));
+```
+
+#### 3. CSRF Protection
+```typescript
+// Next.js Server Actions have built-in CSRF protection
+// For API routes, verify origin
+export async function POST(req: Request) {
+  const origin = req.headers.get('origin');
+  const allowedOrigins = [process.env.NEXT_PUBLIC_APP_URL];
+
+  if (!origin || !allowedOrigins.includes(origin)) {
+    return new Response('Forbidden', { status: 403 });
+  }
+}
+```
+
+#### 4. Security Headers
+```typescript
+// next.config.js
+const securityHeaders = [
+  {
+    key: 'X-DNS-Prefetch-Control',
+    value: 'on'
+  },
+  {
+    key: 'Strict-Transport-Security',
+    value: 'max-age=63072000; includeSubDomains; preload'
+  },
+  {
+    key: 'X-Frame-Options',
+    value: 'SAMEORIGIN'
+  },
+  {
+    key: 'X-Content-Type-Options',
+    value: 'nosniff'
+  },
+  {
+    key: 'Referrer-Policy',
+    value: 'origin-when-cross-origin'
+  },
+  {
+    key: 'Content-Security-Policy',
+    value: "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
+  }
+];
+
+module.exports = {
+  async headers() {
+    return [{ source: '/(.*)', headers: securityHeaders }];
+  }
+};
+```
+
+### Rate Limiting
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
+  analytics: true,
+});
+
+export async function POST(req: Request) {
+  const ip = req.headers.get('x-forwarded-for') ?? 'anonymous';
+  const { success, limit, reset, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new Response('Too Many Requests', {
+      status: 429,
+      headers: {
+        'X-RateLimit-Limit': limit.toString(),
+        'X-RateLimit-Remaining': remaining.toString(),
+        'X-RateLimit-Reset': reset.toString(),
+      },
+    });
+  }
+
+  // Process request
+}
+```
+
+### Secure Session Management
+
+```typescript
+// Session configuration best practices
+const sessionConfig = {
+  // Use HTTP-only cookies
+  httpOnly: true,
+  // Secure in production
+  secure: process.env.NODE_ENV === 'production',
+  // SameSite protection
+  sameSite: 'lax' as const,
+  // Reasonable expiration
+  maxAge: 60 * 60 * 24 * 7, // 1 week
+  // Path restriction
+  path: '/',
+};
+
+// Implement session rotation on privilege escalation
+async function onLogin(userId: string) {
+  // Invalidate old session
+  await invalidateUserSessions(userId);
+  // Create new session
+  return createSession(userId);
+}
+```
+
+### Secrets Management
+
+```typescript
+// Never commit secrets
+// .env.local (gitignored)
+DATABASE_URL="postgresql://..."
+CLERK_SECRET_KEY="sk_live_..."
+
+// Validate env vars at startup
+const requiredEnvVars = [
+  'DATABASE_URL',
+  'CLERK_SECRET_KEY',
+  'STRIPE_SECRET_KEY',
+];
+
+for (const envVar of requiredEnvVars) {
+  if (!process.env[envVar]) {
+    throw new Error(`Missing required env var: ${envVar}`);
+  }
+}
+
+// Never expose server secrets to client
+// Bad: NEXT_PUBLIC_STRIPE_SECRET_KEY
+// Good: STRIPE_SECRET_KEY (server only)
+```
+
+## Security Checklist
+
+- [ ] All user input validated with Zod
+- [ ] HTML content sanitized before rendering
+- [ ] Parameterized queries used (no string interpolation)
+- [ ] Authentication required for protected routes
+- [ ] Authorization checks on all mutations
+- [ ] Rate limiting on authentication endpoints
+- [ ] CSRF protection enabled
+- [ ] Security headers configured
+- [ ] HTTPS enforced in production
+- [ ] Secrets stored in environment variables
+- [ ] No secrets in git history
+- [ ] Session rotation on authentication
+- [ ] Password hashing with bcrypt/argon2
+- [ ] Audit logging for sensitive actions
+
+## Trigger Keywords
+security, auth, login, signup, password, jwt, session, csrf, xss, owasp, injection, rate limit, validation, sanitize, encrypt, hash, permission, role, rbac, vulnerability, attack, protect