@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/serverless-patterns.md

@@ -0,0 +1,223 @@
+---
+name: serverless-patterns
+description: Serverless patterns for cold starts, function composition, event triggers, DynamoDB, and step functions.
+---
+
+# Serverless Patterns
+
+## When to Use
+
+Apply these patterns when building on AWS Lambda, Azure Functions, or Google Cloud
+Functions. Use this skill for minimizing cold starts, composing functions into
+workflows, handling event triggers from queues and streams, designing DynamoDB
+tables, and orchestrating multi-step processes with Step Functions.
+
+## How It Works
+
+### Cold Start Mitigation
+
+Cold starts add latency on first invocation. Minimize them by keeping bundles
+small, initializing outside the handler, and using provisioned concurrency for
+latency-sensitive paths.
+
+```typescript
+// Initialize OUTSIDE the handler — runs once per container
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
+
+const client = new DynamoDBClient({})
+const ddb = DynamoDBDocumentClient.from(client)
+
+// Lazy initialization for rarely-used resources
+let s3Client: S3Client | null = null
+function getS3() {
+  if (!s3Client) s3Client = new S3Client({})
+  return s3Client
+}
+
+// The handler itself should be fast
+export async function handler(event: APIGatewayProxyEvent) {
+  const body = JSON.parse(event.body ?? '{}')
+  const result = await processRequest(ddb, body)
+  return {
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(result),
+  }
+}
+```
+
+**Bundle size tips:**
+- Use `esbuild` or `tsup` to tree-shake and bundle
+- Import only needed clients: `@aws-sdk/client-dynamodb` not `aws-sdk`
+- Keep the deployment package under 5MB zipped
+- Exclude dev dependencies and test files
+
+### Event Triggers
+
+Lambda functions respond to events from SQS, SNS, S3, EventBridge, DynamoDB
+Streams, and API Gateway. Handle each event type with its own handler pattern.
+
+```typescript
+// SQS batch handler with partial failure reporting
+import type { SQSEvent, SQSBatchResponse } from 'aws-lambda'
+
+export async function handler(event: SQSEvent): Promise<SQSBatchResponse> {
+  const failures: string[] = []
+
+  await Promise.allSettled(
+    event.Records.map(async (record) => {
+      try {
+        const body = JSON.parse(record.body)
+        await processMessage(body)
+      } catch (error) {
+        console.error(`Failed to process ${record.messageId}:`, error)
+        failures.push(record.messageId)
+      }
+    }),
+  )
+
+  return {
+    batchItemFailures: failures.map(id => ({ itemIdentifier: id })),
+  }
+}
+
+// S3 trigger
+export async function handleUpload(event: S3Event) {
+  for (const record of event.Records) {
+    const bucket = record.s3.bucket.name
+    const key = decodeURIComponent(record.s3.object.key)
+    await processFile(bucket, key)
+  }
+}
+```
+
+### DynamoDB Single-Table Design
+
+Model multiple entity types in one table using composite keys. Use GSIs for
+access patterns. Avoid scans; every query should hit an index.
+
+```typescript
+// Single table: PK and SK encode entity type and ID
+// Entity       | PK              | SK                | GSI1PK         | GSI1SK
+// User         | USER#123        | PROFILE           | EMAIL#a@b.com  | USER#123
+// Order        | USER#123        | ORDER#456         | ORDER#456      | STATUS#active
+// OrderItem    | ORDER#456       | ITEM#789          | —              | —
+
+interface TableItem {
+  PK: string
+  SK: string
+  GSI1PK?: string
+  GSI1SK?: string
+  type: string // discriminator
+  [key: string]: unknown
+}
+
+// Get user by ID
+const user = await ddb.get({ TableName: TABLE, Key: { PK: `USER#${id}`, SK: 'PROFILE' } })
+
+// Get all orders for user
+const orders = await ddb.query({
+  TableName: TABLE,
+  KeyConditionExpression: 'PK = :pk AND begins_with(SK, :sk)',
+  ExpressionAttributeValues: { ':pk': `USER#${userId}`, ':sk': 'ORDER#' },
+})
+
+// Get order by order ID (via GSI)
+const order = await ddb.query({
+  TableName: TABLE,
+  IndexName: 'GSI1',
+  KeyConditionExpression: 'GSI1PK = :pk',
+  ExpressionAttributeValues: { ':pk': `ORDER#${orderId}` },
+})
+```
+
+### Step Functions for Orchestration
+
+Use AWS Step Functions to orchestrate multi-step workflows. Define states as a
+state machine. Handle retries, parallelism, and error handling declaratively.
+
+```json
+{
+  "StartAt": "ValidateInput",
+  "States": {
+    "ValidateInput": {
+      "Type": "Task",
+      "Resource": "arn:aws:lambda:us-east-1:123:function:validate",
+      "Next": "ProcessParallel",
+      "Catch": [{ "ErrorEquals": ["ValidationError"], "Next": "HandleError" }]
+    },
+    "ProcessParallel": {
+      "Type": "Parallel",
+      "Branches": [
+        { "StartAt": "GenerateReport", "States": { "GenerateReport": { "Type": "Task", "Resource": "arn:aws:lambda:...:report", "End": true } } },
+        { "StartAt": "SendNotification", "States": { "SendNotification": { "Type": "Task", "Resource": "arn:aws:lambda:...:notify", "End": true } } }
+      ],
+      "Next": "Complete"
+    },
+    "Complete": { "Type": "Succeed" },
+    "HandleError": { "Type": "Fail", "Error": "ProcessingFailed" }
+  }
+}
+```
+
+### Function Composition Patterns
+
+Use SNS/SQS for fan-out, EventBridge for event routing, and Step Functions for
+orchestration. Avoid direct Lambda-to-Lambda invocation.
+
+```
+API Gateway -> Lambda (validate) -> SQS -> Lambda (process) -> DynamoDB
+                                       \-> Lambda (audit) -> CloudWatch
+
+EventBridge Rule: source=orders, detail-type=OrderCreated
+  -> Target 1: Lambda (send-confirmation)
+  -> Target 2: Lambda (update-analytics)
+  -> Target 3: SQS (inventory-queue)
+```
+
+### Environment and Configuration
+
+Use SSM Parameter Store or Secrets Manager for configuration. Cache values
+in the Lambda container to avoid repeated API calls.
+
+```typescript
+import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm'
+
+const ssm = new SSMClient({})
+const paramCache = new Map<string, { value: string; expiry: number }>()
+
+async function getParam(name: string, ttl = 300_000): Promise<string> {
+  const cached = paramCache.get(name)
+  if (cached && cached.expiry > Date.now()) return cached.value
+
+  const result = await ssm.send(new GetParameterCommand({ Name: name, WithDecryption: true }))
+  const value = result.Parameter!.Value!
+  paramCache.set(name, { value, expiry: Date.now() + ttl })
+  return value
+}
+```
+
+## Examples
+
+**Pattern: Idempotent handler with DynamoDB conditional write**
+```typescript
+await ddb.put({
+  TableName: TABLE,
+  Item: { PK: `IDEM#${idempotencyKey}`, result, TTL: Math.floor(Date.now() / 1000) + 86400 },
+  ConditionExpression: 'attribute_not_exists(PK)',
+})
+```
+
+## Checklist
+
+- [ ] SDK clients initialized outside handler (reused across invocations)
+- [ ] Bundle size under 5MB zipped; tree-shaken with esbuild
+- [ ] Provisioned concurrency on latency-sensitive functions
+- [ ] SQS handlers return `batchItemFailures` for partial failure
+- [ ] DynamoDB single-table design with composite keys and GSIs
+- [ ] No table scans; every access pattern uses a key or index
+- [ ] Step Functions for multi-step orchestration (not Lambda-to-Lambda calls)
+- [ ] SSM/Secrets Manager for config, cached in-container with TTL
+- [ ] Idempotency keys on all mutating operations
+- [ ] Dead letter queues on all SQS queues and async Lambda invocations

package/assets/skills/sql-optimization.md

@@ -0,0 +1,154 @@
+---
+name: sql-optimization
+description: SQL optimization patterns with EXPLAIN ANALYZE, index strategies, query rewriting, CTEs, and window functions.
+---
+
+# SQL Optimization
+
+## When to Use
+Apply when queries are slow, tables are growing, or you are designing a new schema. SQL optimization starts with measuring (EXPLAIN ANALYZE), then choosing the right index, then restructuring the query. Fix the query first before adding application-level caching.
+
+## How It Works
+
+### EXPLAIN ANALYZE -- Always Measure First
+
+Never guess. Run EXPLAIN ANALYZE to see actual execution time and row counts:
+
+```sql
+EXPLAIN ANALYZE
+SELECT o.id, o.total, u.email
+FROM orders o
+JOIN users u ON u.id = o.user_id
+WHERE o.status = 'pending'
+  AND o.created_at > NOW() - INTERVAL '7 days'
+ORDER BY o.created_at DESC
+LIMIT 20;
+```
+
+Key things to look for:
+- **Seq Scan** on large tables -- needs an index
+- **Rows** actual vs estimated -- stale statistics need `ANALYZE`
+- **Sort** with high cost -- add an index matching the ORDER BY
+- **Nested Loop** with high row count -- consider hash or merge join
+
+### Index Strategies
+
+```sql
+-- Composite index: leftmost columns must match WHERE clause
+CREATE INDEX idx_orders_status_created ON orders (status, created_at DESC);
+
+-- Partial index: only index rows you actually query
+CREATE INDEX idx_orders_pending ON orders (created_at DESC)
+WHERE status = 'pending';
+
+-- Covering index: includes all selected columns, avoids table lookup
+CREATE INDEX idx_orders_cover ON orders (status, created_at DESC)
+INCLUDE (total, user_id);
+
+-- Expression index: index computed values
+CREATE INDEX idx_users_lower_email ON users (LOWER(email));
+
+-- Always use CONCURRENTLY in production
+CREATE INDEX CONCURRENTLY idx_orders_user ON orders (user_id);
+```
+
+Index rules of thumb:
+- Columns in WHERE, JOIN ON, ORDER BY are index candidates
+- High-cardinality columns first in composite indexes
+- Partial indexes when you filter on a constant value
+- Do not index columns that change frequently
+
+### CTEs -- Readable Subquery Composition
+
+```sql
+WITH monthly_revenue AS (
+    SELECT DATE_TRUNC('month', created_at) AS month,
+           SUM(total) AS revenue
+    FROM orders
+    WHERE status = 'paid'
+    GROUP BY 1
+),
+growth AS (
+    SELECT month,
+           revenue,
+           LAG(revenue) OVER (ORDER BY month) AS prev_revenue
+    FROM monthly_revenue
+)
+SELECT month,
+       revenue,
+       ROUND((revenue - prev_revenue) / NULLIF(prev_revenue, 0) * 100, 1) AS growth_pct
+FROM growth
+WHERE prev_revenue IS NOT NULL
+ORDER BY month;
+```
+
+In PostgreSQL 12+, CTEs are inlined by default. Use `MATERIALIZED` only when you need to force a single evaluation.
+
+### Window Functions -- Avoid Self-Joins
+
+```sql
+-- Rank users by order count
+SELECT user_id,
+       COUNT(*) AS order_count,
+       RANK() OVER (ORDER BY COUNT(*) DESC) AS rank
+FROM orders
+GROUP BY user_id;
+
+-- Running total
+SELECT id, amount,
+       SUM(amount) OVER (ORDER BY created_at ROWS UNBOUNDED PRECEDING) AS running_total
+FROM transactions;
+
+-- Get previous and next values without self-join
+SELECT id, amount,
+       LAG(amount) OVER (ORDER BY created_at) AS prev_amount,
+       LEAD(amount) OVER (ORDER BY created_at) AS next_amount
+FROM transactions;
+```
+
+### Partitioning -- Scale Large Tables
+
+```sql
+CREATE TABLE events (
+    id BIGSERIAL,
+    event_type TEXT NOT NULL,
+    payload JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE events_2026_01 PARTITION OF events
+    FOR VALUES FROM ('2026-01-01') TO ('2026-02-01');
+CREATE TABLE events_2026_02 PARTITION OF events
+    FOR VALUES FROM ('2026-02-01') TO ('2026-03-01');
+```
+
+Always include the partition key in WHERE clauses for partition pruning.
+
+### Common Anti-Patterns
+
+| Anti-Pattern | Fix |
+|-------------|-----|
+| `SELECT *` | List only needed columns |
+| `WHERE function(col) = value` | Use expression index or rewrite |
+| `LIKE '%term%'` | Use `pg_trgm` GIN index or full-text search |
+| `NOT IN (subquery)` with NULLs | Use `NOT EXISTS` instead |
+| Missing `LIMIT` on dashboards | Always paginate (keyset preferred) |
+| `ORDER BY RANDOM()` | Use `TABLESAMPLE` or precomputed column |
+
+## Examples
+
+| Scenario | Before | After |
+|----------|--------|-------|
+| Filter + sort | Seq Scan + Sort (2.3s) | Index Scan (4ms) |
+| Aggregate + rank | Self-join (800ms) | Window function (50ms) |
+| Time-range on 500M rows | Full scan (45s) | Partition pruning (200ms) |
+
+## Checklist
+- [ ] `EXPLAIN ANALYZE` run on every query touching > 10K rows
+- [ ] All foreign keys have indexes
+- [ ] Composite indexes match common WHERE + ORDER BY patterns
+- [ ] Partial indexes exist for status-filtered queries
+- [ ] No `SELECT *` in application code
+- [ ] Window functions replace self-joins and correlated subqueries
+- [ ] Tables over 100M rows are partitioned
+- [ ] `CREATE INDEX` always uses `CONCURRENTLY` in production

package/assets/skills/state-management.md

@@ -0,0 +1,254 @@
+---
+name: state-management
+description: Manage React state effectively — Zustand for client, TanStack Query for server, URL state, and optimistic updates.
+---
+
+# State Management
+
+## When to Use
+
+Choose the right state tool for the job. Most React apps misuse global state
+stores for data that belongs in the URL, the server, or a local component.
+The rule: keep state as close as possible to where it's used, and use the
+simplest tool that works.
+
+## How It Works
+
+### 1. Decision Framework
+
+| State type | Where it lives | Tool |
+|-----------|----------------|------|
+| Component UI (open/closed, hover) | Component `useState` | React |
+| Form input | Component `useState` or form library | React / react-hook-form |
+| URL state (filters, pagination, tabs) | URL search params | `useSearchParams` |
+| Client-only global (theme, sidebar) | Global store | Zustand |
+| Server data (users, orders) | Server cache | TanStack Query |
+| Auth session | Context + server | Context + cookies |
+
+### 2. Zustand for Client State
+
+Minimal, no boilerplate, works outside React components.
+
+```typescript
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface UIStore {
+  sidebarOpen: boolean;
+  toggleSidebar: () => void;
+  theme: 'light' | 'dark';
+  setTheme: (theme: 'light' | 'dark') => void;
+}
+
+export const useUIStore = create<UIStore>()(
+  persist(
+    (set) => ({
+      sidebarOpen: true,
+      toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
+      theme: 'light',
+      setTheme: (theme) => set({ theme }),
+    }),
+    { name: 'ui-store' }, // persists to localStorage
+  ),
+);
+```
+
+Usage in components:
+
+```tsx
+function Sidebar() {
+  const open = useUIStore((s) => s.sidebarOpen); // only re-renders on this slice
+  if (!open) return null;
+  return <nav>...</nav>;
+}
+
+function ThemeToggle() {
+  const [theme, setTheme] = useUIStore((s) => [s.theme, s.setTheme]);
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      {theme === 'light' ? 'Dark mode' : 'Light mode'}
+    </button>
+  );
+}
+```
+
+Select individual fields to avoid unnecessary re-renders.
+
+### 3. React Context — When Zustand is Overkill
+
+For state scoped to a subtree, not the whole app.
+
+```tsx
+interface ModalContextValue {
+  isOpen: boolean;
+  open: (content: ReactNode) => void;
+  close: () => void;
+  content: ReactNode | null;
+}
+
+const ModalContext = createContext<ModalContextValue | null>(null);
+
+export function ModalProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<{ isOpen: boolean; content: ReactNode | null }>({
+    isOpen: false,
+    content: null,
+  });
+
+  const value = useMemo(() => ({
+    ...state,
+    open: (content: ReactNode) => setState({ isOpen: true, content }),
+    close: () => setState({ isOpen: false, content: null }),
+  }), [state]);
+
+  return (
+    <ModalContext.Provider value={value}>
+      {children}
+      {state.isOpen && <ModalOverlay>{state.content}</ModalOverlay>}
+    </ModalContext.Provider>
+  );
+}
+
+export function useModal() {
+  const ctx = useContext(ModalContext);
+  if (!ctx) throw new Error('useModal must be used within ModalProvider');
+  return ctx;
+}
+```
+
+### 4. URL State for Shareable UI
+
+Filters, pagination, search, and tabs should live in the URL so users can
+bookmark and share.
+
+```tsx
+import { useSearchParams } from 'react-router-dom';
+
+function OrderList() {
+  const [params, setParams] = useSearchParams();
+  const status = params.get('status') ?? 'all';
+  const page = Number(params.get('page') ?? '1');
+  const search = params.get('q') ?? '';
+
+  function setFilter(key: string, value: string) {
+    setParams((prev) => {
+      const next = new URLSearchParams(prev);
+      if (value) next.set(key, value);
+      else next.delete(key);
+      next.set('page', '1'); // reset to page 1 on filter change
+      return next;
+    });
+  }
+
+  return (
+    <>
+      <FilterBar
+        status={status}
+        onStatusChange={(v) => setFilter('status', v)}
+        search={search}
+        onSearchChange={(v) => setFilter('q', v)}
+      />
+      <OrderTable status={status} page={page} search={search} />
+      <Pagination page={page} onChange={(p) => setFilter('page', String(p))} />
+    </>
+  );
+}
+```
+
+### 5. TanStack Query for Server State
+
+Server data is not client state. It has its own lifecycle: loading, fresh,
+stale, error, background refresh.
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+// Fetch
+function useOrders(filters: OrderFilters) {
+  return useQuery({
+    queryKey: ['orders', filters],
+    queryFn: () => api.orders.list(filters),
+    staleTime: 30_000,       // fresh for 30s
+    gcTime: 5 * 60_000,      // keep in cache 5min
+    placeholderData: (prev) => prev, // show old data while refetching
+  });
+}
+
+// Mutate with cache invalidation
+function useDeleteOrder() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => api.orders.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['orders'] });
+    },
+  });
+}
+```
+
+### 6. Optimistic Updates
+
+Update the UI immediately, roll back if the server rejects.
+
+```typescript
+function useToggleFavorite() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => api.favorites.toggle(id),
+    onMutate: async (id) => {
+      await queryClient.cancelQueries({ queryKey: ['favorites'] });
+
+      const previous = queryClient.getQueryData<string[]>(['favorites']);
+
+      queryClient.setQueryData<string[]>(['favorites'], (old = []) =>
+        old.includes(id) ? old.filter((x) => x !== id) : [...old, id],
+      );
+
+      return { previous };
+    },
+    onError: (_err, _id, context) => {
+      // Roll back on failure
+      queryClient.setQueryData(['favorites'], context?.previous);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['favorites'] });
+    },
+  });
+}
+```
+
+### 7. Derived State — Compute, Don't Store
+
+```tsx
+// Bad — derived state stored separately
+const [items, setItems] = useState<Item[]>([]);
+const [total, setTotal] = useState(0);
+// total drifts if you forget to update it
+
+// Good — compute from source
+const [items, setItems] = useState<Item[]>([]);
+const total = useMemo(() => items.reduce((sum, i) => sum + i.price, 0), [items]);
+```
+
+## Examples
+
+| Scenario | Approach |
+|----------|----------|
+| Dark mode toggle | Zustand with `persist` middleware |
+| Data table with filters | URL search params + TanStack Query |
+| Shopping cart | Zustand (client state with persistence) |
+| User profile data | TanStack Query (`useQuery`) |
+| Like button | Optimistic mutation (`useMutation` + `onMutate`) |
+| Modal open/close | Local `useState` or Context |
+
+## Checklist
+
+- [ ] Server data uses TanStack Query, not `useState` + `useEffect`
+- [ ] Filters, pagination, and search live in URL params
+- [ ] Zustand selectors pick individual fields to minimize re-renders
+- [ ] No derived state is stored — it's computed with `useMemo`
+- [ ] Optimistic updates include rollback logic in `onError`
+- [ ] Context is used for subtree state (modals, forms), Zustand for app-wide
+- [ ] `staleTime` is configured per query to avoid unnecessary refetches
+- [ ] Loading, error, and empty states are handled for every server query