@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/swift-patterns.md

@@ -0,0 +1,227 @@
+---
+name: swift-patterns
+description: Swift patterns for protocols, async/await, Combine, SwiftUI state, property wrappers, and Codable.
+---
+
+# Swift Patterns
+
+## When to Use
+
+Apply these patterns when writing Swift 5.9+ code for iOS, macOS, or server-side
+Swift. Use this skill for protocol-oriented design, structured concurrency with
+async/await, managing SwiftUI state, creating property wrappers, and encoding/
+decoding data with Codable.
+
+## How It Works
+
+### Protocol-Oriented Design
+
+Define protocols for behavior contracts. Use protocol extensions for default
+implementations. Prefer protocols over class inheritance.
+
+```swift
+protocol Repository {
+    associatedtype Entity: Identifiable
+    func fetch(id: Entity.ID) async throws -> Entity
+    func save(_ entity: Entity) async throws
+}
+
+extension Repository {
+    func fetchOrCreate(id: Entity.ID, default: Entity) async throws -> Entity {
+        do {
+            return try await fetch(id: id)
+        } catch {
+            try await save(default)
+            return default
+        }
+    }
+}
+
+struct UserRepository: Repository {
+    func fetch(id: UUID) async throws -> User { ... }
+    func save(_ entity: User) async throws { ... }
+}
+```
+
+### Async/Await and Structured Concurrency
+
+Use `async let` for parallel work. Use `TaskGroup` for dynamic fan-out. Use
+`Task` for fire-and-forget from synchronous contexts.
+
+```swift
+func loadDashboard() async throws -> Dashboard {
+    async let profile = fetchProfile()
+    async let notifications = fetchNotifications()
+    async let analytics = fetchAnalytics()
+
+    return try await Dashboard(
+        profile: profile,
+        notifications: notifications,
+        analytics: analytics
+    )
+}
+
+func fetchAll(urls: [URL]) async throws -> [Data] {
+    try await withThrowingTaskGroup(of: (Int, Data).self) { group in
+        for (index, url) in urls.enumerated() {
+            group.addTask {
+                let (data, _) = try await URLSession.shared.data(from: url)
+                return (index, data)
+            }
+        }
+        var results = [Data](repeating: Data(), count: urls.count)
+        for try await (index, data) in group {
+            results[index] = data
+        }
+        return results
+    }
+}
+```
+
+### Combine for Reactive Pipelines
+
+Use Combine for event streams, timers, and publisher chains. Prefer async/await
+for one-shot async work; use Combine when you need ongoing observation.
+
+```swift
+class SearchModel: ObservableObject {
+    @Published var query = ""
+    @Published private(set) var results: [SearchResult] = []
+
+    private var cancellables = Set<AnyCancellable>()
+
+    init(service: SearchService) {
+        $query
+            .debounce(for: .milliseconds(300), scheduler: RunLoop.main)
+            .removeDuplicates()
+            .filter { $0.count >= 2 }
+            .flatMap { query in
+                service.search(query: query)
+                    .catch { _ in Just([]) }
+            }
+            .assign(to: &$results)
+    }
+}
+```
+
+### SwiftUI State Management
+
+Use `@State` for local view state, `@Binding` for child views, `@StateObject`
+for owned observable objects, `@EnvironmentObject` for shared dependencies.
+
+```swift
+struct ItemListView: View {
+    @StateObject private var viewModel = ItemListViewModel()
+    @State private var showingAddSheet = false
+
+    var body: some View {
+        List(viewModel.items) { item in
+            ItemRow(item: item, onToggle: { viewModel.toggle(item) })
+        }
+        .searchable(text: $viewModel.searchText)
+        .sheet(isPresented: $showingAddSheet) {
+            AddItemView(onSave: { item in
+                viewModel.add(item)
+                showingAddSheet = false
+            })
+        }
+    }
+}
+
+@Observable
+class ItemListViewModel {
+    var items: [Item] = []
+    var searchText = ""
+
+    var filteredItems: [Item] {
+        guard !searchText.isEmpty else { return items }
+        return items.filter { $0.title.localizedCaseInsensitiveContains(searchText) }
+    }
+}
+```
+
+### Property Wrappers
+
+Create property wrappers for cross-cutting concerns: clamping values, UserDefaults
+persistence, or validation.
+
+```swift
+@propertyWrapper
+struct Clamped<Value: Comparable> {
+    private var value: Value
+    let range: ClosedRange<Value>
+
+    var wrappedValue: Value {
+        get { value }
+        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
+    }
+
+    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
+        self.range = range
+        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
+    }
+}
+
+struct AudioSettings {
+    @Clamped(0...100) var volume: Int = 50
+    @Clamped(0.5...2.0) var playbackSpeed: Double = 1.0
+}
+```
+
+### Codable
+
+Use `CodingKeys` for key mapping. Implement custom `init(from:)` for complex
+decoding. Use `@propertyWrapper` for date formats.
+
+```swift
+struct APIResponse: Codable {
+    let id: Int
+    let displayName: String
+    let createdAt: Date
+    let tags: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case displayName = "display_name"
+        case createdAt = "created_at"
+        case tags
+    }
+}
+
+// Decoder configuration
+let decoder = JSONDecoder()
+decoder.dateDecodingStrategy = .iso8601
+decoder.keyDecodingStrategy = .convertFromSnakeCase
+```
+
+## Examples
+
+**Pattern: Result type with typed errors**
+```swift
+enum NetworkError: Error, LocalizedError {
+    case notFound
+    case unauthorized
+    case serverError(statusCode: Int)
+
+    var errorDescription: String? {
+        switch self {
+        case .notFound: "Resource not found"
+        case .unauthorized: "Authentication required"
+        case .serverError(let code): "Server error (\(code))"
+        }
+    }
+}
+```
+
+## Checklist
+
+- [ ] Protocols over class inheritance; protocol extensions for defaults
+- [ ] `async let` for parallel work, `TaskGroup` for dynamic concurrency
+- [ ] `@State` for local, `@StateObject` for owned objects, `@EnvironmentObject` for shared
+- [ ] `@Observable` macro (iOS 17+) over `ObservableObject` where possible
+- [ ] Property wrappers for cross-cutting validation and persistence
+- [ ] `CodingKeys` for JSON key mapping; snake_case strategy on decoder
+- [ ] Errors conform to `LocalizedError` with `errorDescription`
+- [ ] `guard let` / `guard else` for early returns, not nested `if let`
+- [ ] `Task` cancellation handled (check `Task.isCancelled` in loops)
+- [ ] SwiftUI previews for every view with representative data

package/assets/skills/tailwind-patterns.md

@@ -0,0 +1,272 @@
+---
+name: tailwind-patterns
+description: Write effective Tailwind CSS — responsive design, dark mode, animations, component extraction, and custom utilities.
+---
+
+# Tailwind CSS Patterns
+
+## When to Use
+
+Use these patterns when building UIs with Tailwind CSS. Tailwind's utility-first
+approach is fast but can produce unreadable class strings and duplicated styles
+without discipline. These patterns keep your Tailwind code maintainable as the
+project grows.
+
+## How It Works
+
+### 1. Responsive Design
+
+Mobile-first breakpoints. Unprefixed utilities apply to all screens, prefixed
+utilities apply at that breakpoint and above.
+
+```tsx
+<div className="
+  grid grid-cols-1 gap-4 p-4
+  md:grid-cols-2 md:gap-6 md:p-6
+  lg:grid-cols-3 lg:gap-8
+  xl:grid-cols-4
+">
+  {items.map(item => <Card key={item.id} item={item} />)}
+</div>
+```
+
+Common breakpoints: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px).
+
+Container pattern for consistent page width:
+
+```tsx
+<main className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+  {children}
+</main>
+```
+
+### 2. Dark Mode
+
+Use the `dark:` variant. Configure with `class` strategy for user-controlled
+toggling.
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  darkMode: 'class', // toggled via class on <html>
+};
+```
+
+```tsx
+<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">
+  <h1 className="text-2xl font-bold text-gray-800 dark:text-gray-200">
+    Dashboard
+  </h1>
+  <p className="text-gray-600 dark:text-gray-400">
+    Welcome back
+  </p>
+</div>
+```
+
+Toggle implementation:
+
+```typescript
+function toggleDarkMode() {
+  document.documentElement.classList.toggle('dark');
+  const isDark = document.documentElement.classList.contains('dark');
+  localStorage.setItem('theme', isDark ? 'dark' : 'light');
+}
+
+// Initialize on page load
+const theme = localStorage.getItem('theme') ??
+  (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+document.documentElement.classList.toggle('dark', theme === 'dark');
+```
+
+### 3. Animations and Transitions
+
+```tsx
+// Hover transition
+<button className="
+  rounded-lg bg-blue-600 px-4 py-2 text-white
+  transition-colors duration-200
+  hover:bg-blue-700
+  active:bg-blue-800
+">
+  Save
+</button>
+
+// Smooth expand/collapse
+<div className={`
+  overflow-hidden transition-all duration-300 ease-in-out
+  ${isOpen ? 'max-h-96 opacity-100' : 'max-h-0 opacity-0'}
+`}>
+  {content}
+</div>
+
+// Keyframe animation (built-in)
+<div className="animate-pulse rounded-lg bg-gray-200 h-48" />  {/* skeleton */}
+<div className="animate-spin h-5 w-5 border-2 border-white border-t-transparent rounded-full" />  {/* spinner */}
+```
+
+Custom animations in config:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      keyframes: {
+        'slide-in': {
+          '0%': { transform: 'translateX(100%)' },
+          '100%': { transform: 'translateX(0)' },
+        },
+        'fade-in': {
+          '0%': { opacity: '0' },
+          '100%': { opacity: '1' },
+        },
+      },
+      animation: {
+        'slide-in': 'slide-in 0.3s ease-out',
+        'fade-in': 'fade-in 0.2s ease-in',
+      },
+    },
+  },
+};
+```
+
+### 4. Component Extraction with CVA
+
+Use `class-variance-authority` to build variant-driven components.
+
+```typescript
+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 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-blue-600 text-white hover:bg-blue-700',
+        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-100',
+        danger: 'bg-red-600 text-white hover:bg-red-700',
+        ghost: 'hover:bg-gray-100 dark:hover:bg-gray-800',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-sm',
+        lg: 'h-12 px-6 text-base',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  },
+);
+
+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} />
+  );
+}
+```
+
+The `cn` utility merges Tailwind classes without conflicts:
+
+```typescript
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### 5. Custom Utilities
+
+Extend Tailwind for project-specific needs.
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: '#f0f4ff',
+          500: '#3b6cf5',
+          600: '#2a5ce0',
+          700: '#1a4cc0',
+        },
+      },
+      spacing: {
+        '18': '4.5rem',
+        '88': '22rem',
+      },
+      fontSize: {
+        'display': ['3.5rem', { lineHeight: '1.1', letterSpacing: '-0.02em' }],
+      },
+    },
+  },
+};
+```
+
+### 6. Prose for Long-Form Content
+
+```tsx
+<article className="prose prose-lg dark:prose-invert max-w-none">
+  <h1>Getting Started</h1>
+  <p>This content is styled automatically by the typography plugin.</p>
+  <pre><code>npm install @bootspring/cli</code></pre>
+</article>
+```
+
+Install: `@tailwindcss/typography` plugin.
+
+### 7. Layout Patterns
+
+```tsx
+// Sticky header
+<header className="sticky top-0 z-50 border-b bg-white/80 backdrop-blur dark:bg-gray-900/80">
+  <nav className="mx-auto flex h-16 max-w-7xl items-center justify-between px-4">
+    ...
+  </nav>
+</header>
+
+// Sidebar layout
+<div className="flex h-screen">
+  <aside className="hidden w-64 shrink-0 border-r md:block">...</aside>
+  <main className="flex-1 overflow-y-auto p-6">...</main>
+</div>
+
+// Card grid with consistent height
+<div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+  <div className="flex flex-col rounded-lg border p-6">
+    <h3 className="text-lg font-semibold">Title</h3>
+    <p className="mt-2 flex-1 text-gray-600">Description fills space</p>
+    <button className="mt-4">Action</button>
+  </div>
+</div>
+```
+
+## Examples
+
+| Pattern | Classes | Purpose |
+|---------|---------|---------|
+| Responsive grid | `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` | Adapts to screen size |
+| Dark mode text | `text-gray-900 dark:text-gray-100` | Theme-aware content |
+| Smooth hover | `transition-colors duration-200 hover:bg-blue-700` | Polished interactions |
+| Loading skeleton | `animate-pulse bg-gray-200 rounded h-4` | Content placeholder |
+| Truncated text | `truncate` or `line-clamp-2` | Overflow prevention |
+
+## Checklist
+
+- [ ] All responsive styles are mobile-first (unprefixed = mobile, `md:` = tablet, `lg:` = desktop)
+- [ ] Dark mode uses `dark:` variants with `darkMode: 'class'` strategy
+- [ ] Repeated class patterns are extracted into components with CVA
+- [ ] `cn()` utility (clsx + tailwind-merge) is used for conditional and merged classes
+- [ ] Custom colors use the brand scale defined in `tailwind.config.js`
+- [ ] Transitions use `duration-200` or `duration-300` for polished feel
+- [ ] Long class strings are broken across multiple lines for readability
+- [ ] The `@tailwindcss/typography` plugin is used for prose content

package/assets/skills/tdd-workflow.md

@@ -0,0 +1,199 @@
+---
+name: tdd-workflow
+description: Test-driven development workflow with red-green-refactor, test doubles, outside-in TDD, and property-based testing.
+---
+
+# Test-Driven Development
+
+## When to Use
+Apply when building new features, fixing bugs, or refactoring existing code. TDD catches design problems early, produces naturally testable code, and creates a safety net for future changes. Skip TDD only for throwaway spikes or exploratory prototypes that will be rewritten.
+
+## How It Works
+
+### Red-Green-Refactor Cycle
+
+The core loop. Never skip a step.
+
+```
+RED    -> Write a failing test for the next behavior you need
+GREEN  -> Write the minimum code to make it pass
+REFACTOR -> Clean up without changing behavior (tests stay green)
+```
+
+```typescript
+// RED -- test for a function that doesn't exist yet
+import { describe, it, expect } from "vitest";
+import { calculateDiscount } from "./pricing";
+
+describe("calculateDiscount", () => {
+  it("applies 10% discount for orders over $100", () => {
+    expect(calculateDiscount(150)).toBe(15);
+  });
+
+  it("returns 0 for orders at or below $100", () => {
+    expect(calculateDiscount(100)).toBe(0);
+    expect(calculateDiscount(50)).toBe(0);
+  });
+});
+
+// GREEN -- simplest implementation
+export function calculateDiscount(orderTotal: number): number {
+  if (orderTotal > 100) return orderTotal * 0.1;
+  return 0;
+}
+
+// REFACTOR -- extract magic numbers
+const DISCOUNT_THRESHOLD = 100;
+const DISCOUNT_RATE = 0.1;
+
+export function calculateDiscount(orderTotal: number): number {
+  return orderTotal > DISCOUNT_THRESHOLD ? orderTotal * DISCOUNT_RATE : 0;
+}
+```
+
+Each cycle should take 1-5 minutes. If you spend longer, the step is too big.
+
+### Test Doubles
+
+Use the right kind of double for the job:
+
+```typescript
+import { vi, describe, it, expect } from "vitest";
+
+// STUB -- returns canned data, no assertions on calls
+const userRepo = {
+  findById: vi.fn().mockResolvedValue({ id: "1", name: "Alice" }),
+};
+
+// MOCK -- asserts specific interactions happened
+const emailService = { send: vi.fn() };
+await resetPassword(userRepo, emailService, "alice@test.com");
+expect(emailService.send).toHaveBeenCalledWith(
+  expect.objectContaining({
+    to: "alice@test.com",
+    subject: expect.stringContaining("Reset"),
+  })
+);
+
+// SPY -- wraps real implementation, records calls
+const logSpy = vi.spyOn(console, "warn");
+processInput(invalidData);
+expect(logSpy).toHaveBeenCalledOnce();
+logSpy.mockRestore();
+
+// FAKE -- working in-memory implementation
+class InMemoryUserRepo implements UserRepository {
+  private users = new Map<string, User>();
+  async save(user: User) { this.users.set(user.id, user); }
+  async findById(id: string) { return this.users.get(id) ?? null; }
+}
+```
+
+Prefer fakes for repositories and stubs for external services. Only use mocks when verifying that a side effect actually happened.
+
+### Outside-In TDD (London School)
+
+Start from the outermost boundary and work inward:
+
+```typescript
+// Step 1: API test (outermost layer)
+describe("POST /api/orders", () => {
+  it("creates an order and returns 201", async () => {
+    const res = await request(app)
+      .post("/api/orders")
+      .send({ items: [{ sku: "WIDGET-1", qty: 2 }] });
+    expect(res.status).toBe(201);
+    expect(res.body.order.total).toBe(49.98);
+  });
+});
+
+// Step 2: Discover the service interface from the route handler
+// -> orderService.create(items) => Order
+
+// Step 3: Discover the repository interface from the service
+// -> productRepo.findBySku(sku) => Product
+
+// Step 4: Implement the repository (innermost layer)
+// -> Use a fake for unit tests, real DB for integration tests
+```
+
+Each layer defines the interface it needs from the next layer down.
+
+### Property-Based Testing
+
+Instead of testing individual examples, declare properties that must always hold:
+
+```typescript
+import { fc } from "@fast-check/vitest";
+import { describe, it, expect } from "vitest";
+
+describe("sort", () => {
+  it.prop([fc.array(fc.integer())])("output length equals input length", (arr) => {
+    expect(sort(arr)).toHaveLength(arr.length);
+  });
+
+  it.prop([fc.array(fc.integer())])("output is ordered", (arr) => {
+    const sorted = sort(arr);
+    for (let i = 1; i < sorted.length; i++) {
+      expect(sorted[i]).toBeGreaterThanOrEqual(sorted[i - 1]);
+    }
+  });
+
+  it.prop([fc.array(fc.integer())])("output contains same elements", (arr) => {
+    expect(sort(arr).sort()).toEqual([...arr].sort());
+  });
+});
+```
+
+Property-based testing excels at finding edge cases: empty arrays, negative numbers, duplicates, and boundary values that hand-written examples miss.
+
+### Mutation Testing
+
+Tests pass, but are they actually checking the right things?
+
+```bash
+npx stryker run
+```
+
+```javascript
+// stryker.config.mjs
+export default {
+  mutator: "typescript",
+  testRunner: "vitest",
+  reporters: ["html", "clear-text"],
+  coverageAnalysis: "perTest",
+  thresholds: { high: 80, low: 60, break: 50 },
+};
+```
+
+Common mutations Stryker introduces: replace `>` with `>=`, remove function calls, swap `true`/`false`, replace `+` with `-`. A mutation score below 70% means tests are passing but not actually verifying behavior.
+
+### When to Write Tests After
+
+TDD is the default, but some situations call for test-after:
+
+- **Exploratory spikes** -- learning how an API works, throw away the code
+- **UI layout** -- visual correctness verified by eye or screenshot tests
+- **Generated code** -- test the generator, not every generated file
+
+Even in test-after mode, write tests before considering the work done.
+
+## Examples
+
+| Situation | TDD Approach | Outcome |
+|-----------|-------------|---------|
+| New pricing engine | Red-green-refactor, one rule at a time | Each rule tested in isolation |
+| Integrating Stripe webhooks | Outside-in from route handler | Clean service boundary |
+| Bug: discount applied twice | Write failing test reproducing the bug | Regression test prevents reoccurrence |
+| Refactoring a 500-line function | Characterization tests, then extract | Safe refactoring with full coverage |
+| Serializer edge cases | Property-based testing | Finds empty/null/unicode edge cases |
+
+## Checklist
+- [ ] Every new feature starts with a failing test
+- [ ] Each red-green-refactor cycle takes under 5 minutes
+- [ ] Test doubles chosen intentionally (fake > stub > mock)
+- [ ] Tests verify behavior, not implementation details
+- [ ] Outside-in tests define interfaces from the caller's perspective
+- [ ] Property-based tests cover invariants for pure functions
+- [ ] Mutation testing runs on critical business logic (score > 70%)
+- [ ] Bug fixes include a regression test written before the fix