@girardmedia/bootspring 1.1.0

package/agents/frontend-expert/context.md

@@ -0,0 +1,364 @@
+# Frontend Expert Agent
+
+## Role
+Specialized in React, Next.js App Router, modern component patterns, state management, and UI development with Tailwind CSS.
+
+## Core Expertise
+
+### React Server Components (Default)
+
+```tsx
+// Server Components are the default in Next.js App Router
+// They run on the server and can directly access data
+
+// app/users/page.tsx - Server Component
+import { prisma } from '@/lib/prisma';
+
+export default async function UsersPage() {
+  // Direct database access - no API needed!
+  const users = await prisma.user.findMany({
+    take: 10,
+    orderBy: { createdAt: 'desc' }
+  });
+
+  return (
+    <main className="container mx-auto py-8">
+      <h1 className="text-2xl font-bold mb-4">Users</h1>
+      <ul className="space-y-2">
+        {users.map(user => (
+          <UserCard key={user.id} user={user} />
+        ))}
+      </ul>
+    </main>
+  );
+}
+
+// This is also a Server Component
+function UserCard({ user }: { user: User }) {
+  return (
+    <div className="p-4 border rounded-lg">
+      <h2 className="font-medium">{user.name}</h2>
+      <p className="text-gray-500">{user.email}</p>
+    </div>
+  );
+}
+```
+
+### Client Components (When Needed)
+
+```tsx
+'use client';
+
+// Use 'use client' ONLY when you need:
+// - useState, useEffect, useRef
+// - Event handlers (onClick, onChange, etc.)
+// - Browser APIs (window, document)
+// - Third-party libraries that use hooks
+
+import { useState, useTransition } from 'react';
+import { updateUser } from '@/app/actions';
+
+export function EditUserForm({ user }: { user: User }) {
+  const [name, setName] = useState(user.name);
+  const [isPending, startTransition] = useTransition();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    startTransition(async () => {
+      await updateUser(user.id, { name });
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <input
+        type="text"
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        className="border rounded px-3 py-2 w-full"
+        disabled={isPending}
+      />
+      <button
+        type="submit"
+        disabled={isPending}
+        className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
+      >
+        {isPending ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Component Composition Pattern
+
+```tsx
+// Compose Server and Client Components effectively
+
+// ServerWrapper.tsx (Server Component)
+import { prisma } from '@/lib/prisma';
+import { InteractiveList } from './InteractiveList';
+
+export async function ServerWrapper() {
+  const items = await prisma.item.findMany();
+
+  // Pass data to client component
+  return <InteractiveList initialItems={items} />;
+}
+
+// InteractiveList.tsx (Client Component)
+'use client';
+
+import { useState } from 'react';
+
+export function InteractiveList({ initialItems }: { initialItems: Item[] }) {
+  const [items, setItems] = useState(initialItems);
+  const [filter, setFilter] = useState('');
+
+  const filteredItems = items.filter(item =>
+    item.name.toLowerCase().includes(filter.toLowerCase())
+  );
+
+  return (
+    <div>
+      <input
+        type="search"
+        placeholder="Filter..."
+        value={filter}
+        onChange={(e) => setFilter(e.target.value)}
+        className="border rounded px-3 py-2 mb-4 w-full"
+      />
+      <ul className="space-y-2">
+        {filteredItems.map(item => (
+          <li key={item.id} className="p-2 border rounded">
+            {item.name}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### State Management
+
+#### Local State (useState)
+```tsx
+// For component-specific state
+const [isOpen, setIsOpen] = useState(false);
+```
+
+#### URL State (useSearchParams)
+```tsx
+'use client';
+
+import { useSearchParams, useRouter, usePathname } from 'next/navigation';
+
+export function Filters() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const updateFilter = (key: string, value: string) => {
+    const params = new URLSearchParams(searchParams);
+    if (value) {
+      params.set(key, value);
+    } else {
+      params.delete(key);
+    }
+    router.push(`${pathname}?${params.toString()}`);
+  };
+
+  return (
+    <select
+      value={searchParams.get('status') ?? ''}
+      onChange={(e) => updateFilter('status', e.target.value)}
+    >
+      <option value="">All</option>
+      <option value="active">Active</option>
+      <option value="archived">Archived</option>
+    </select>
+  );
+}
+```
+
+#### Global State (Zustand)
+```tsx
+// store/user-store.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface UserStore {
+  user: User | null;
+  setUser: (user: User | null) => void;
+  preferences: { theme: 'light' | 'dark' };
+  setTheme: (theme: 'light' | 'dark') => void;
+}
+
+export const useUserStore = create<UserStore>()(
+  persist(
+    (set) => ({
+      user: null,
+      setUser: (user) => set({ user }),
+      preferences: { theme: 'light' },
+      setTheme: (theme) => set((state) => ({
+        preferences: { ...state.preferences, theme }
+      })),
+    }),
+    { name: 'user-storage' }
+  )
+);
+
+// Usage in component
+'use client';
+
+export function ThemeToggle() {
+  const { preferences, setTheme } = useUserStore();
+
+  return (
+    <button onClick={() => setTheme(preferences.theme === 'light' ? 'dark' : 'light')}>
+      Toggle Theme
+    </button>
+  );
+}
+```
+
+### Tailwind CSS Patterns
+
+#### Responsive Design
+```tsx
+<div className="
+  grid
+  grid-cols-1      /* Mobile: 1 column */
+  sm:grid-cols-2   /* Small: 2 columns */
+  lg:grid-cols-3   /* Large: 3 columns */
+  xl:grid-cols-4   /* XL: 4 columns */
+  gap-4
+">
+  {items.map(item => <Card key={item.id} {...item} />)}
+</div>
+```
+
+#### Component Variants with cva
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+```
+
+### Loading & Error States
+
+```tsx
+// loading.tsx - Automatic loading UI
+export default function Loading() {
+  return (
+    <div className="flex items-center justify-center min-h-[400px]">
+      <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
+    </div>
+  );
+}
+
+// error.tsx - Automatic error UI
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[400px] gap-4">
+      <h2 className="text-xl font-semibold">Something went wrong!</h2>
+      <p className="text-gray-500">{error.message}</p>
+      <button
+        onClick={reset}
+        className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
+```
+
+### Suspense Boundaries
+
+```tsx
+import { Suspense } from 'react';
+
+export default function DashboardPage() {
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      <Suspense fallback={<CardSkeleton />}>
+        <RevenueCard />
+      </Suspense>
+      <Suspense fallback={<CardSkeleton />}>
+        <UsersCard />
+      </Suspense>
+      <Suspense fallback={<TableSkeleton />}>
+        <RecentOrders />
+      </Suspense>
+    </div>
+  );
+}
+
+function CardSkeleton() {
+  return (
+    <div className="h-32 bg-gray-100 rounded-lg animate-pulse" />
+  );
+}
+```
+
+## Component Checklist
+
+- [ ] Server Component by default
+- [ ] 'use client' only when necessary
+- [ ] Props typed with TypeScript
+- [ ] Loading state handled
+- [ ] Error boundary in place
+- [ ] Accessible (keyboard nav, ARIA labels)
+- [ ] Responsive (mobile-first)
+- [ ] No inline styles (use Tailwind)
+- [ ] Component is focused and small
+- [ ] Reusable where appropriate
+
+## Trigger Keywords
+component, react, ui, tailwind, state, client, server component, hook, useState, useEffect, form, button, input, modal, dropdown, responsive, mobile, layout, grid, flex, styling, css

package/agents/index.js

@@ -0,0 +1,140 @@
+/**
+ * Bootspring Agents Module
+ * Programmatic access to agent data and invocation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Agent registry from cli/agent.js
+const AGENTS = {
+  'database-expert': {
+    name: 'Database Expert',
+    expertise: ['SQL', 'Prisma', 'PostgreSQL', 'migrations', 'query optimization'],
+    description: 'Expert in database design, queries, and optimization'
+  },
+  'security-expert': {
+    name: 'Security Expert',
+    expertise: ['OWASP', 'authentication', 'authorization', 'encryption', 'vulnerabilities'],
+    description: 'Expert in application security and best practices'
+  },
+  'frontend-expert': {
+    name: 'Frontend Expert',
+    expertise: ['React', 'Next.js', 'Tailwind', 'components', 'state management'],
+    description: 'Expert in frontend development and UI'
+  },
+  'backend-expert': {
+    name: 'Backend Expert',
+    expertise: ['Node.js', 'APIs', 'server actions', 'middleware', 'serverless'],
+    description: 'Expert in backend development and server-side logic'
+  },
+  'api-expert': {
+    name: 'API Expert',
+    expertise: ['REST', 'GraphQL', 'tRPC', 'webhooks', 'API design'],
+    description: 'Expert in API design and integration'
+  },
+  'testing-expert': {
+    name: 'Testing Expert',
+    expertise: ['Vitest', 'Jest', 'Playwright', 'coverage', 'TDD'],
+    description: 'Expert in testing strategies and implementation'
+  },
+  'performance-expert': {
+    name: 'Performance Expert',
+    expertise: ['optimization', 'caching', 'profiling', 'Core Web Vitals', 'lazy loading'],
+    description: 'Expert in application performance optimization'
+  },
+  'devops-expert': {
+    name: 'DevOps Expert',
+    expertise: ['CI/CD', 'Docker', 'deployment', 'monitoring', 'infrastructure'],
+    description: 'Expert in DevOps practices and deployment'
+  },
+  'ui-ux-expert': {
+    name: 'UI/UX Expert',
+    expertise: ['design systems', 'accessibility', 'user experience', 'responsive design'],
+    description: 'Expert in UI/UX design and implementation'
+  },
+  'architecture-expert': {
+    name: 'Architecture Expert',
+    expertise: ['system design', 'patterns', 'scalability', 'microservices'],
+    description: 'Expert in software architecture and system design'
+  },
+  'code-review-expert': {
+    name: 'Code Review Expert',
+    expertise: ['code quality', 'best practices', 'refactoring', 'maintainability'],
+    description: 'Expert in code review and quality assessment'
+  },
+  'vercel-expert': {
+    name: 'Vercel Expert',
+    expertise: ['Vercel', 'serverless', 'edge functions', 'deployment', 'analytics'],
+    description: 'Expert in Vercel platform and deployment'
+  }
+};
+
+/**
+ * Get all available agents
+ */
+function getAgents() {
+  return AGENTS;
+}
+
+/**
+ * Get a specific agent by name
+ */
+function getAgent(name) {
+  return AGENTS[name] || null;
+}
+
+/**
+ * List agent names
+ */
+function listAgents() {
+  return Object.keys(AGENTS);
+}
+
+/**
+ * Get agent context file path
+ */
+function getAgentContextPath(name) {
+  const agentsDir = path.dirname(__dirname);
+  return path.join(agentsDir, 'agents', name, 'context.md');
+}
+
+/**
+ * Load agent context file
+ */
+function loadAgentContext(name) {
+  const contextPath = getAgentContextPath(name);
+  if (fs.existsSync(contextPath)) {
+    return fs.readFileSync(contextPath, 'utf-8');
+  }
+  return null;
+}
+
+/**
+ * Find agents by expertise keyword
+ */
+function findAgentsByExpertise(keyword) {
+  const matches = [];
+  const lowerKeyword = keyword.toLowerCase();
+
+  for (const [id, agent] of Object.entries(AGENTS)) {
+    const hasMatch = agent.expertise.some(exp =>
+      exp.toLowerCase().includes(lowerKeyword)
+    );
+    if (hasMatch) {
+      matches.push({ id, ...agent });
+    }
+  }
+
+  return matches;
+}
+
+module.exports = {
+  AGENTS,
+  getAgents,
+  getAgent,
+  listAgents,
+  getAgentContextPath,
+  loadAgentContext,
+  findAgentsByExpertise
+};