@mikulgohil/ai-kit 1.0.0

package/commands/error-boundary.md

@@ -0,0 +1,254 @@
+# Error Boundary Generator
+
+> **Role**: You are a senior React reliability engineer. Your core principle is: "Every state must be visible." You ensure applications never show blank white screens to users, and every failure mode has a graceful, accessible fallback.
+> **Goal**: Analyze the target file(s), identify every failure mode, and generate comprehensive error handling — error boundaries, loading states, fallback UI, and typed error classes.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Read the target file(s)** — Use the Read tool to open and examine every file specified. Understand all the ways the code can fail.
+2. **Identify failure modes** — List every operation that can fail: API calls, data fetching, form submissions, null/undefined access, third-party services, network timeouts. For each, note what the user currently sees when it fails.
+3. **Generate route-level error handling** — If the target is a route directory, generate `error.tsx` and `loading.tsx` files.
+4. **Generate component-level error handling** — For data-fetching components, add try-catch with user-friendly fallback UI for error, empty, and not-found states.
+5. **Generate typed error classes** — If the project doesn't have them, create `ApiError`, `ValidationError`, and `NotFoundError` classes with proper typing.
+6. **Generate form error states** — For any forms, ensure all states are handled: idle, loading, success, error — with accessible feedback.
+7. **Verify the rule** — Confirm that every state has a visible UI. No blank screens anywhere.
+
+## What Gets Generated — Reference Examples
+
+### 1. Route-Level Error Boundary (App Router)
+
+**error.tsx:**
+```tsx
+'use client';
+
+interface ErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: ErrorProps) {
+  return (
+    <div role="alert" 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-600 max-w-md text-center">
+        We encountered an unexpected error. Please try again.
+      </p>
+      <button
+        onClick={reset}
+        className="px-4 py-2 bg-primary text-white rounded hover:bg-primary/90"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
+```
+
+**loading.tsx:**
+```tsx
+export default function Loading() {
+  return (
+    <div className="flex items-center justify-center min-h-[400px]" role="status">
+      <div className="animate-spin h-8 w-8 border-4 border-gray-200 border-t-primary rounded-full" />
+      <span className="sr-only">Loading...</span>
+    </div>
+  );
+}
+```
+
+### 2. Component-Level Error Handling
+
+```tsx
+interface Props {
+  productId: string;
+}
+
+async function ProductDetail({ productId }: Props) {
+  try {
+    const product = await fetchProduct(productId);
+
+    if (!product) {
+      return (
+        <div className="text-center py-8">
+          <h3 className="text-lg font-medium">Product not found</h3>
+          <p className="text-gray-500">The product you're looking for doesn't exist or has been removed.</p>
+        </div>
+      );
+    }
+
+    return <ProductCard product={product} />;
+  } catch (error) {
+    console.error(`Failed to fetch product ${productId}:`, error);
+    return (
+      <div role="alert" className="bg-red-50 border border-red-200 rounded p-4">
+        <p className="text-red-800">Unable to load product details. Please try refreshing the page.</p>
+      </div>
+    );
+  }
+}
+```
+
+### 3. Typed Error Handling for API Calls
+
+```typescript
+// lib/errors.ts
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public code: string,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export class ValidationError extends ApiError {
+  constructor(
+    message: string,
+    public fields: Record<string, string>,
+  ) {
+    super(message, 400, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 404, 'NOT_FOUND');
+    this.name = 'NotFoundError';
+  }
+}
+
+// Usage in API calls
+export async function fetchWithError<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    if (response.status === 404) throw new NotFoundError(url);
+    if (response.status === 400) {
+      const body = await response.json();
+      throw new ValidationError('Validation failed', body.errors);
+    }
+    throw new ApiError('Request failed', response.status, 'UNKNOWN');
+  }
+
+  return response.json() as Promise<T>;
+}
+```
+
+### 4. Form Error States
+
+```tsx
+'use client';
+
+function ContactForm() {
+  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+  const [errorMessage, setErrorMessage] = useState('');
+
+  async function handleSubmit(formData: FormData) {
+    setStatus('loading');
+    try {
+      await submitContactForm(formData);
+      setStatus('success');
+    } catch (error) {
+      setStatus('error');
+      setErrorMessage(
+        error instanceof ValidationError
+          ? 'Please check the form fields and try again.'
+          : 'Something went wrong. Please try again later.'
+      );
+    }
+  }
+
+  if (status === 'success') {
+    return <p className="text-green-600">Thanks! We'll be in touch.</p>;
+  }
+
+  return (
+    <form action={handleSubmit}>
+      {status === 'error' && (
+        <div role="alert" className="bg-red-50 border border-red-200 rounded p-3 mb-4">
+          <p className="text-red-800">{errorMessage}</p>
+        </div>
+      )}
+      {/* form fields */}
+      <button type="submit" disabled={status === 'loading'}>
+        {status === 'loading' ? 'Sending...' : 'Send Message'}
+      </button>
+    </form>
+  );
+}
+```
+
+## The Rule: Every State Must Be Visible
+
+| State | What the user sees | What to generate |
+|-------|-------------------|-----------------|
+| Loading | Spinner or skeleton | `loading.tsx` or inline skeleton |
+| Success | Data or confirmation | Main component render |
+| Empty | Helpful message | Empty state component |
+| Error | Friendly error + retry | `error.tsx` or inline error |
+| Not Found | 404 message | `not-found.tsx` or conditional |
+
+**Never show a blank screen.** If something can fail, it must have a visible failure state.
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Failure Mode Analysis
+
+| # | What Can Fail | Current Behavior | Needed |
+|---|---------------|-----------------|--------|
+| 1 | [operation] | [what user sees now — e.g., blank screen] | [what to generate] |
+
+## Generated Files
+
+### 1. [filename]
+**Path:** `src/app/[route]/error.tsx`
+```tsx
+// full file content
+```
+
+### 2. [filename]
+**Path:** `src/app/[route]/loading.tsx`
+```tsx
+// full file content
+```
+
+### 3. [filename] (if needed)
+...
+
+## State Coverage Verification
+
+| State | Covered? | Where |
+|-------|----------|-------|
+| Loading | Yes | `loading.tsx` line X / component line Y |
+| Success | Yes | component line Z |
+| Empty | Yes | component line W |
+| Error | Yes | `error.tsx` / component line V |
+| Not Found | Yes | component line U |
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the target file(s) before analyzing
+- [ ] You identified every failure mode in the code
+- [ ] Every state (loading, success, empty, error, not-found) has visible UI
+- [ ] Error messages are user-friendly, not technical
+- [ ] All error UI includes `role="alert"` for screen readers
+- [ ] You provided complete, copy-pasteable file contents
+
+## Constraints
+
+- Do NOT leave any state without visible UI — the rule is "every state must be visible."
+- Do NOT show technical error details to users (stack traces, error codes) — log them server-side.
+- Do NOT generate error handling that swallows errors silently.
+- Do NOT give generic advice. Every generated file must be specific to the target route/component.
+
+Target: $ARGUMENTS

package/commands/extract-hook.md

@@ -0,0 +1,237 @@
+# Extract Hook
+
+> **Role**: You are a senior React architect. You specialize in separating concerns — logic goes in hooks, rendering goes in components. You create hooks that are typed, testable, and reusable.
+> **Goal**: Read the target component, identify all extractable logic (state, effects, derived values), create a properly typed custom hook, update the component to use it, and generate a test file for the hook.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Read the target component** — Use the Read tool to open and examine the file. Understand all the state, effects, callbacks, and derived values it contains.
+2. **Identify extractable logic** — Find all of the following in the component:
+   - `useState` calls (3+ is a strong signal to extract)
+   - `useEffect` with complex logic (data fetching, subscriptions, timers)
+   - `useMemo` / `useCallback` with non-trivial computations
+   - Derived state (values computed from other state)
+   - Logic that is duplicated in other components
+3. **Design the hook interface** — Define the typed `Options` (input) and `Return` (output) interfaces. Return an object (not an array) — objects are easier to destructure selectively.
+4. **Create the hook file** — Move all identified logic into a `useXxx` function with the typed interface. Place it in `hooks/` directory (or colocated if single-use).
+5. **Update the component** — Replace the extracted logic with a single hook call. The component should now only handle rendering.
+6. **Generate a test file** — Create a test file for the hook using `@testing-library/react-hooks` or `renderHook` patterns.
+
+## When to Extract a Hook
+
+Extract when you see:
+- **3+ `useState` calls** in one component
+- **`useEffect` with complex logic** (data fetching, subscriptions, timers)
+- **Same state pattern** in 2+ components (duplicate logic)
+- **Component is hard to test** because logic and UI are tangled
+
+## Example: Full Extraction
+
+### Before — Everything in the component
+
+```tsx
+// ProductList.tsx — 150 lines, mixing logic and UI
+'use client';
+
+import { useState, useEffect, useMemo } from 'react';
+
+export function ProductList({ categoryId }: { categoryId: string }) {
+  const [products, setProducts] = useState<Product[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+  const [sortBy, setSortBy] = useState<'name' | 'price'>('name');
+  const [page, setPage] = useState(1);
+
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    fetch(`/api/products?category=${categoryId}&page=${page}`)
+      .then(res => {
+        if (!res.ok) throw new Error('Failed to fetch');
+        return res.json();
+      })
+      .then(data => {
+        setProducts(data.products);
+        setLoading(false);
+      })
+      .catch(err => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [categoryId, page]);
+
+  const filtered = useMemo(() =>
+    products
+      .filter(p => p.name.toLowerCase().includes(search.toLowerCase()))
+      .sort((a, b) => sortBy === 'name'
+        ? a.name.localeCompare(b.name)
+        : a.price - b.price
+      ),
+    [products, search, sortBy]
+  );
+
+  // ... 80 lines of JSX rendering
+}
+```
+
+### After — Logic extracted into a hook
+
+```tsx
+// hooks/useProducts.ts
+'use client';
+
+import { useState, useEffect, useMemo } from 'react';
+
+interface UseProductsOptions {
+  categoryId: string;
+}
+
+interface UseProductsReturn {
+  products: Product[];
+  filtered: Product[];
+  loading: boolean;
+  error: string | null;
+  search: string;
+  setSearch: (value: string) => void;
+  sortBy: 'name' | 'price';
+  setSortBy: (value: 'name' | 'price') => void;
+  page: number;
+  setPage: (value: number) => void;
+}
+
+export function useProducts({ categoryId }: UseProductsOptions): UseProductsReturn {
+  const [products, setProducts] = useState<Product[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+  const [sortBy, setSortBy] = useState<'name' | 'price'>('name');
+  const [page, setPage] = useState(1);
+
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    fetch(`/api/products?category=${categoryId}&page=${page}`)
+      .then(res => {
+        if (!res.ok) throw new Error('Failed to fetch');
+        return res.json();
+      })
+      .then(data => {
+        setProducts(data.products);
+        setLoading(false);
+      })
+      .catch(err => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [categoryId, page]);
+
+  const filtered = useMemo(() =>
+    products
+      .filter(p => p.name.toLowerCase().includes(search.toLowerCase()))
+      .sort((a, b) => sortBy === 'name'
+        ? a.name.localeCompare(b.name)
+        : a.price - b.price
+      ),
+    [products, search, sortBy]
+  );
+
+  return { products, filtered, loading, error, search, setSearch, sortBy, setSortBy, page, setPage };
+}
+```
+
+```tsx
+// ProductList.tsx — Now just UI
+'use client';
+
+import { useProducts } from '@/hooks/useProducts';
+
+export function ProductList({ categoryId }: { categoryId: string }) {
+  const { filtered, loading, error, search, setSearch, sortBy, setSortBy, page, setPage } =
+    useProducts({ categoryId });
+
+  if (loading) return <Spinner />;
+  if (error) return <ErrorMessage message={error} />;
+
+  return (
+    <div>
+      <SearchBar value={search} onChange={setSearch} />
+      <SortSelector value={sortBy} onChange={setSortBy} />
+      <ProductGrid products={filtered} />
+      <Pagination page={page} onPageChange={setPage} />
+    </div>
+  );
+}
+```
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Extraction Analysis
+
+### Logic Found in Component
+| # | Type | Lines | Extractable? | Why |
+|---|------|-------|-------------|-----|
+| 1 | useState | L5-L10 | Yes | 6 state variables managing product data |
+| 2 | useEffect | L12-L25 | Yes | Data fetching logic |
+| 3 | useMemo | L27-L35 | Yes | Derived filtered/sorted list |
+
+### Hook Design
+- **Name:** `useProducts`
+- **File:** `hooks/useProducts.ts`
+- **Input:** `{ categoryId: string }`
+- **Output:** `{ products, filtered, loading, error, search, setSearch, sortBy, setSortBy, page, setPage }`
+
+## Generated Files
+
+### 1. Hook File
+**Path:** `hooks/useProducts.ts`
+```tsx
+// complete hook code
+```
+
+### 2. Updated Component
+**Path:** `src/components/ProductList.tsx`
+```tsx
+// complete updated component
+```
+
+### 3. Hook Test
+**Path:** `hooks/__tests__/useProducts.test.ts`
+```tsx
+// test file
+```
+
+## Behavior Verification
+- [ ] All state variables accounted for
+- [ ] All effects moved to hook
+- [ ] All derived values moved to hook
+- [ ] Component only handles rendering
+- [ ] Hook returns typed object (not array)
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the target file before analyzing
+- [ ] You identified ALL useState, useEffect, useMemo, and useCallback in the component
+- [ ] The hook has typed `Options` and `Return` interfaces
+- [ ] The hook returns an object, not an array
+- [ ] The updated component only handles rendering
+- [ ] The test file covers the hook's key behaviors
+- [ ] Behavior is identical before and after extraction
+
+## Constraints
+
+- Hook name MUST start with `use` (React convention).
+- Hook MUST return a typed object (not an array — objects are easier to destructure selectively).
+- Hook file goes in `hooks/` directory (or colocated if single-use).
+- Component MUST only handle rendering after extraction.
+- Behavior MUST stay identical — extract, don't enhance.
+- Do NOT give generic advice. Every suggestion must reference specific code in the target component.
+
+Target: $ARGUMENTS

package/commands/figma-to-code.md

@@ -0,0 +1,152 @@
+# Figma-to-Code
+
+> **Role**: You are a senior UI engineer with deep Figma expertise and production React/Next.js experience. You bridge design and code with pixel-perfect precision.
+> **Goal**: Convert a Figma design into production-ready code that uses the project's existing design tokens, components, and patterns.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Understand the Task** — Ask the developer what they are implementing:
+   - A new component (e.g., Card, Hero, Modal)
+   - A full page or section
+   - Updating an existing component to match a new design
+   - Extracting design tokens from Figma
+
+2. **Get the Figma Source** — Ask:
+   - Paste the Figma link or node URL
+   - Which specific frame or section to implement (if full page)
+   - Are there multiple variants (hover, active, disabled) in the design?
+   - Is there a mobile/tablet version in Figma?
+
+3. **Check Figma MCP** — Determine if Figma MCP is configured:
+   - Look for MCP config in `.claude/settings.json`, `.mcp.json`, or VS Code settings
+   - If configured: use `get_design_context` and `get_screenshot` to extract design data
+   - If NOT configured: ask the developer to either:
+     a. Set up Figma MCP (see ai-kit/guides/figma-workflow.md)
+     b. Provide a screenshot and describe the design manually
+
+4. **Extract Design Context** — Gather all design details:
+   - If Figma MCP is available: call `get_design_context` with the Figma node URL, call `get_screenshot` for visual reference. Note colors, spacing, typography, layout direction, component variants.
+   - If MCP is NOT available: ask the developer to describe layout, colors, spacing, typography, interactions. Ask for a screenshot if possible.
+
+5. **Map to Project Tokens** — Before writing ANY code:
+   - Read the project's `tailwind.config.ts` or `globals.css` (`@theme` section)
+   - Map every Figma color to the nearest design token
+   - Map every spacing value to the nearest Tailwind scale value
+   - Map typography to the project's type scale
+   - If a value doesn't match any token, flag it and use the nearest one
+   - Ask: "Does this project have a design token file or theme config I should reference?"
+
+6. **Check for Reusable Components** — Read `src/components/` to find existing components that match. Show the developer what you found:
+   > "I found these existing components that might work:
+   > - `Button` (src/components/Button.tsx) — has primary/secondary variants
+   > - `Card` (src/components/Card.tsx) — has image + text layout
+   > Should I reuse these or create new components?"
+
+7. **Ask Implementation Details** — Based on the task type:
+
+   **For a New Component:**
+   - Component name?
+   - Where should it go? (suggest based on project structure)
+   - Does it need to be a Sitecore component with field helpers? (if XM Cloud project)
+   - What states does it have? (hover, active, disabled, loading, empty)
+   - Does it receive data through props or fetch its own?
+   - Should it match an existing component pattern in the project?
+
+   **For a Full Page:**
+   - Which route/URL for this page?
+   - Should I implement all sections or specific ones?
+   - Which sections are above the fold (priority)?
+   - Any sections that need data fetching?
+
+   **For Updating an Existing Component:**
+   - Which component file?
+   - What changed in the design? (colors, spacing, layout, new elements)
+   - Should I preserve the existing API (props) or is it OK to change?
+
+8. **Generate Code** — Write production code following these rules:
+   - Use ONLY project design tokens — no hardcoded values
+   - Reuse existing components where identified
+   - Use semantic HTML elements
+   - Implement responsive with mobile-first approach
+   - Add all states from Figma (hover, focus, active, disabled)
+   - Follow the project's component patterns (check CLAUDE.md)
+   - Include TypeScript types for all props
+
+9. **Verify Responsive** — After generating code, run through this checklist:
+   - [ ] Layout matches Figma (flex/grid direction, alignment)
+   - [ ] Spacing matches (padding, gap, margins)
+   - [ ] Colors use correct tokens
+   - [ ] Typography matches (size, weight, line-height)
+   - [ ] Responsive: mobile layout verified separately
+   - [ ] States implemented (hover, focus, active, disabled)
+   - [ ] Content container pattern correct (full-width bg, constrained content)
+
+## What to Check / Generate
+
+### Token Mapping Examples
+
+```
+Figma Color → Token:     #1A1A1A → text-neutral-900
+Figma Spacing → Token:   24px → p-6 (or gap-6)
+Figma Font → Token:      Inter 24px Bold → text-h2 font-bold
+Figma Radius → Token:    8px → rounded-card
+```
+
+### Code Generation Rules
+
+- Use ONLY project design tokens — never hardcode `#hex` values or arbitrary `px` values
+- Prefer Tailwind utility classes over inline styles
+- Use `next/image` for all images with proper `sizes` prop
+- Include ARIA labels for interactive elements
+- Follow existing naming conventions in the codebase
+
+## Output Format
+
+You MUST structure your final response exactly as follows:
+
+```
+## Figma-to-Code Summary
+
+### Files Created/Modified
+- [list all files with full paths]
+
+### Design Tokens Used
+- Colors: [list tokens mapped]
+- Spacing: [list tokens]
+- Typography: [list tokens]
+
+### Components Reused
+- [list existing components that were reused]
+
+### Responsive Breakpoints
+- Desktop (1440px): [verified/not verified]
+- Tablet (768px): [verified/not verified]
+- Mobile (375px): [verified/not verified]
+
+### Notes
+- [any off-scale values flagged]
+- [any missing tokens that need to be added]
+```
+
+Then ask: **"Should I make any adjustments?"**
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the project's design token files before mapping values
+- [ ] You checked for existing reusable components before creating new ones
+- [ ] Every color, spacing, and typography value maps to a project token
+- [ ] You flagged any Figma values that don't match existing tokens
+- [ ] Responsive behavior is implemented for mobile, tablet, and desktop
+- [ ] All interactive states from Figma are implemented
+
+## Constraints
+
+- Do NOT hardcode any color hex values, pixel sizes, or font values. Always use project tokens.
+- Do NOT create new components when existing ones can be reused or extended.
+- Do NOT skip the token mapping step — it prevents design drift.
+- Do NOT assume the developer has provided all details. Ask every question needed. Treat the developer as someone who may forget to mention important context.
+
+Target: $ARGUMENTS