@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/refactoring.md

@@ -0,0 +1,218 @@
+---
+name: refactoring
+description: Refactoring patterns including extract function, introduce parameter object, replace conditional with polymorphism, and strangler fig.
+---
+
+# Refactoring Patterns
+
+## When to Use
+Apply when code is correct but hard to understand, extend, or test. Refactor before adding new features to the area, after getting a feature working in TDD, or when code review reveals structural problems. Never refactor and change behavior in the same commit.
+
+## How It Works
+
+### Extract Function
+
+Pull a block of code into a named function when it does one identifiable thing. The signal: you write a comment explaining what the next block does. The comment is the function name.
+
+```typescript
+// Before -- one function doing three things
+async function processOrder(order: Order) {
+  if (!order.items.length) throw new Error("Empty order");
+  if (order.items.some((i) => i.qty <= 0)) throw new Error("Invalid quantity");
+
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.qty;
+    if (item.taxable) total += item.price * item.qty * 0.08;
+  }
+
+  await db.orders.insert({ ...order, total, status: "pending" });
+  await emailService.send(order.email, "Order confirmed", `Total: $${total}`);
+}
+
+// After -- each concern is a named, testable function
+const TAX_RATE = 0.08;
+
+function validateOrder(order: Order): void {
+  if (!order.items.length) throw new Error("Empty order");
+  if (order.items.some((i) => i.qty <= 0)) throw new Error("Invalid quantity");
+}
+
+function calculateTotal(items: OrderItem[]): number {
+  return items.reduce((sum, item) => {
+    const subtotal = item.price * item.qty;
+    return sum + subtotal + (item.taxable ? subtotal * TAX_RATE : 0);
+  }, 0);
+}
+
+async function processOrder(order: Order) {
+  validateOrder(order);
+  const total = calculateTotal(order.items);
+  await db.orders.insert({ ...order, total, status: "pending" });
+  await emailService.send(order.email, "Order confirmed", `Total: $${total}`);
+}
+```
+
+### Introduce Parameter Object
+
+When three or more parameters travel together, group them:
+
+```typescript
+// Before -- long parameter list
+function searchProducts(
+  query: string, minPrice: number, maxPrice: number,
+  category: string, sortBy: string, page: number, pageSize: number
+) { /* ... */ }
+
+// After -- cohesive parameter object
+interface ProductSearchParams {
+  query: string;
+  priceRange: { min: number; max: number };
+  category: string;
+  sort: { field: string; direction: "asc" | "desc" };
+  pagination: { page: number; pageSize: number };
+}
+
+function searchProducts(params: ProductSearchParams) { /* ... */ }
+
+// Call site is self-documenting
+const results = searchProducts({
+  query: "widget",
+  priceRange: { min: 10, max: 100 },
+  category: "hardware",
+  sort: { field: "price", direction: "asc" },
+  pagination: { page: 1, pageSize: 20 },
+});
+```
+
+### Replace Conditional with Polymorphism
+
+When a switch/if-else chain selects behavior based on a type field, use a strategy map:
+
+```typescript
+// Before -- switch grows with every new notification type
+function sendNotification(notification: Notification) {
+  switch (notification.type) {
+    case "email": return sendEmail(notification.to, notification.body);
+    case "sms": return sendSms(notification.phone, notification.body);
+    case "push": return sendPush(notification.token, notification.body);
+    case "slack": return postSlack(notification.channel, notification.body);
+  }
+}
+
+// After -- each type handles itself
+interface NotificationSender {
+  send(notification: Notification): Promise<void>;
+}
+
+const senders: Record<string, NotificationSender> = {
+  email: new EmailSender(),
+  sms: new SmsSender(),
+  push: new PushSender(),
+  slack: new SlackSender(),
+};
+
+function sendNotification(notification: Notification) {
+  const sender = senders[notification.type];
+  if (!sender) throw new Error(`Unknown type: ${notification.type}`);
+  return sender.send(notification);
+}
+```
+
+### Strangler Fig Pattern
+
+Migrate a legacy system incrementally by routing traffic through a facade:
+
+```typescript
+// Phase 1: Facade routes to old system
+class OrderFacade {
+  async createOrder(data: OrderData): Promise<Order> {
+    return this.legacyOrderService.create(data);
+  }
+}
+
+// Phase 2: Route some traffic to new system
+class OrderFacade {
+  async createOrder(data: OrderData): Promise<Order> {
+    if (await this.featureFlags.isEnabled("new-order-service", data.userId)) {
+      return this.newOrderService.create(data);
+    }
+    return this.legacyOrderService.create(data);
+  }
+}
+
+// Phase 3: All traffic to new system, legacy removed
+class OrderFacade {
+  async createOrder(data: OrderData): Promise<Order> {
+    return this.newOrderService.create(data);
+  }
+}
+```
+
+### Simplify Boolean Logic with Guard Clauses
+
+```typescript
+// Before -- nested conditions
+function canUserPurchase(user: User, product: Product): boolean {
+  if (user.isActive) {
+    if (!user.isBanned) {
+      if (product.inStock) {
+        if (user.balance >= product.price) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+// After -- guard clauses with early returns
+function canUserPurchase(user: User, product: Product): boolean {
+  if (!user.isActive) return false;
+  if (user.isBanned) return false;
+  if (!product.inStock) return false;
+  if (user.balance < product.price) return false;
+  return true;
+}
+```
+
+### Replace Temp with Query
+
+Eliminate intermediate variables that exist only to hold a computed value:
+
+```typescript
+// Before -- temps obscure the logic
+const basePrice = order.quantity * order.itemPrice;
+const discount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05;
+const shipping = Math.min(basePrice * 0.1, 100);
+const total = basePrice - discount + shipping;
+
+// After -- named, testable computed properties
+class Order {
+  get basePrice(): number { return this.quantity * this.itemPrice; }
+  get discount(): number { return Math.max(0, this.quantity - 500) * this.itemPrice * 0.05; }
+  get shipping(): number { return Math.min(this.basePrice * 0.1, 100); }
+  get total(): number { return this.basePrice - this.discount + this.shipping; }
+}
+```
+
+## Examples
+
+| Code Smell | Refactoring | Benefit |
+|-----------|-------------|---------|
+| Function > 30 lines | Extract Function | Each piece testable and named |
+| 5+ positional parameters | Introduce Parameter Object | Self-documenting call sites |
+| switch on type field | Replace Conditional with Polymorphism | Open for extension |
+| Nested if/else 4 levels deep | Guard clauses | Linear, readable flow |
+| Legacy system rewrite | Strangler Fig | Incremental, zero-downtime migration |
+| Same 3 lines copy-pasted | Extract Function + call from each site | Single source of truth |
+
+## Checklist
+- [ ] Tests pass before and after every refactoring step
+- [ ] Each commit is either a refactoring OR a behavior change, never both
+- [ ] No function exceeds 30 lines (extract when it does)
+- [ ] No parameter list exceeds 3 positional arguments
+- [ ] Switch/if-else chains on type fields replaced with polymorphism
+- [ ] Duplicated code extracted to a shared function or module
+- [ ] Boolean conditions use guard clauses or named predicates
+- [ ] Strangler fig pattern used for incremental legacy migration

package/assets/skills/regex-patterns.md

@@ -0,0 +1,191 @@
+---
+name: regex-patterns
+description: Write effective regex — lookahead/behind, named groups, common validation patterns, and performance pitfalls.
+---
+
+# Regex Patterns
+
+## When to Use
+
+Use regex for input validation, text extraction, search-and-replace, and log
+parsing. This skill covers modern regex features (named groups, lookbehind,
+Unicode properties), common real-world patterns (emails, URLs, dates), and
+performance pitfalls that cause catastrophic backtracking. Apply when you need
+structured pattern matching — but prefer dedicated parsers for HTML, JSON, or
+complex grammars.
+
+## How It Works
+
+### 1. Named Groups — Readable Captures
+
+```typescript
+// Named groups make extracted data self-documenting
+const datePattern = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/;
+const match = '2026-05-26'.match(datePattern);
+if (match?.groups) {
+  const { year, month, day } = match.groups;
+  // year = "2026", month = "05", day = "26"
+}
+
+// Backreference by name
+const duplicateWord = /\b(?<word>\w+)\s+\k<word>\b/gi;
+'the the quick brown fox'.replace(duplicateWord, '$<word>');
+// "the quick brown fox"
+
+// Named groups in replace
+const isoDate = /(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})/g;
+'Date: 2026-05-26'.replace(isoDate, '$<m>/$<d>/$<y>');
+// "Date: 05/26/2026"
+```
+
+### 2. Lookahead and Lookbehind
+
+Zero-width assertions — match a position, not characters.
+
+```typescript
+// Positive lookahead: match "foo" only if followed by "bar"
+/foo(?=bar)/        // matches "foo" in "foobar", not in "foobaz"
+
+// Negative lookahead: match "foo" only if NOT followed by "bar"
+/foo(?!bar)/        // matches "foo" in "foobaz", not in "foobar"
+
+// Positive lookbehind: match "bar" only if preceded by "foo"
+/(?<=foo)bar/       // matches "bar" in "foobar", not in "bazbar"
+
+// Negative lookbehind: match digits NOT preceded by "$"
+/(?<!\$)\d+/        // matches "42" in "item 42", not "42" in "$42"
+
+// Practical: extract price values without the currency symbol
+const prices = 'Items: $29.99, EUR49.50, $100.00';
+const usdPrices = prices.matchAll(/(?<=\$)\d+\.\d{2}/g);
+// ["29.99", "100.00"]
+```
+
+### 3. Common Validation Patterns
+
+```typescript
+// Email (simplified — use a library for RFC 5322 compliance)
+const EMAIL = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+
+// URL (http/https)
+const URL_PATTERN = /^https?:\/\/[^\s/$.?#].[^\s]*$/i;
+
+// ISO 8601 date (YYYY-MM-DD)
+const ISO_DATE = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+
+// Semantic version
+const SEMVER = /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-(?<pre>[a-zA-Z0-9.]+))?(?:\+(?<build>[a-zA-Z0-9.]+))?$/;
+
+// UUID v4
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+// Password (min 8 chars, at least one upper, one lower, one digit)
+const STRONG_PASSWORD = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/;
+
+// IPv4 address
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|[01]?\d{1,2})\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d{1,2})$/;
+
+// Hex color (#RGB or #RRGGBB)
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}){1,2}$/;
+
+// Phone (international E.164)
+const PHONE_E164 = /^\+[1-9]\d{1,14}$/;
+```
+
+### 4. Text Extraction Patterns
+
+```typescript
+// Extract all hashtags
+const hashtags = text.matchAll(/#(\w+)/g);
+
+// Extract key-value pairs from logs
+const logLine = '2026-05-26T10:30:00Z level=error msg="Connection refused" host=db.prod retries=3';
+const kvPattern = /(?<key>\w+)=(?:"(?<quoted>[^"]*)"|(?<bare>\S+))/g;
+for (const m of logLine.matchAll(kvPattern)) {
+  const key = m.groups!.key;
+  const value = m.groups!.quoted ?? m.groups!.bare;
+  // { level: "error", msg: "Connection refused", host: "db.prod", retries: "3" }
+}
+
+// Extract markdown links
+const mdLinks = /\[(?<text>[^\]]+)\]\((?<url>[^)]+)\)/g;
+for (const m of content.matchAll(mdLinks)) {
+  console.log(m.groups!.text, m.groups!.url);
+}
+
+// Split on multiple delimiters
+'one, two;three  four'.split(/[,;\s]+/);
+// ["one", "two", "three", "four"]
+```
+
+### 5. Unicode-Aware Patterns
+
+```typescript
+// Match any letter (including accented, CJK, etc.)
+const anyLetter = /\p{Letter}+/gu;
+'cafe resume'.match(anyLetter);   // ["cafe", "resume"]
+
+// Match emoji
+const emojiPattern = /\p{Emoji_Presentation}/gu;
+
+// Match currency symbols
+const currencyPattern = /\p{Currency_Symbol}/gu;
+
+// Always use the 'u' flag for Unicode correctness
+const wordBoundary = /\b\w+\b/gu; // Unicode-safe word matching
+```
+
+### 6. Performance — Avoid Catastrophic Backtracking
+
+```typescript
+// BAD — exponential backtracking on non-matching input
+const bad = /^(a+)+$/;  // O(2^n) on "aaaaaaaaaaab"
+
+// GOOD — possessive-style (use atomic groups or rewrite)
+const good = /^a+$/;    // O(n)
+
+// BAD — nested quantifiers with overlap
+const bad2 = /^(\w+\s*)*$/;
+
+// GOOD — specific alternation
+const good2 = /^[\w\s]+$/;
+
+// Rule: Never nest quantifiers on overlapping character classes
+// Test with: "aaaaaaaaaaaaaaaaaab" — if it hangs, you have backtracking
+
+// Use RegExp timeout (Node.js 20+) or test with redos-detector
+```
+
+### 7. Flags Reference
+
+| Flag | Name | Effect |
+|------|------|--------|
+| `g` | global | Match all occurrences, not just first |
+| `i` | ignoreCase | Case-insensitive matching |
+| `m` | multiline | `^`/`$` match line starts/ends |
+| `s` | dotAll | `.` matches newlines too |
+| `u` | unicode | Enable Unicode property escapes |
+| `v` | unicodeSets | Extended Unicode sets (ES2024) |
+| `d` | hasIndices | Include start/end indices in match |
+
+## Examples
+
+| Pattern | Matches | Note |
+|---------|---------|------|
+| `(?<=@)\w+\.\w+` | Domain from email | Lookbehind extracts without `@` |
+| `\b\d{1,3}(,\d{3})*\b` | Formatted numbers | `1,000,000` but not `12,3` |
+| `(?:https?://)?\S+\.\w{2,}` | URLs with optional scheme | Non-capturing group |
+| `^(?!.*password).*$` | Lines without "password" | Negative lookahead filter |
+
+## Checklist
+
+- [ ] Named groups used instead of positional `$1`, `$2` captures
+- [ ] Unicode flag (`u` or `v`) enabled for international text
+- [ ] No nested quantifiers on overlapping character classes
+- [ ] Patterns tested against non-matching input for backtracking
+- [ ] `matchAll` used instead of `exec` loop for global matches
+- [ ] Complex validation uses a library, not a single mega-regex
+- [ ] Regex documented with comments (use `x` flag or string concatenation)
+- [ ] Lookaheads/lookbehinds used to avoid consuming matched text
+- [ ] Common patterns extracted to named constants, not inline literals
+- [ ] Regex tested with edge cases: empty string, Unicode, very long input

package/assets/skills/remix-patterns.md

@@ -0,0 +1,262 @@
+---
+name: remix-patterns
+description: Remix patterns for loaders, actions, nested routes, error boundaries, and progressive enhancement.
+---
+
+# Remix Patterns
+
+## When to Use
+Use Remix for full-stack web applications where you want server-rendered pages with progressive enhancement. Remix excels at data loading, form handling, and nested layouts. It works without JavaScript on the client by default, making it ideal for apps that need accessibility, SEO, and resilient UX. Choose Remix when you want to lean into web platform standards rather than fight them.
+
+## How It Works
+
+### Loaders (Server-Side Data Fetching)
+
+```typescript
+// app/routes/posts._index.tsx
+import type { LoaderFunctionArgs } from '@remix-run/node';
+import { json } from '@remix-run/node';
+import { useLoaderData, Link } from '@remix-run/react';
+import { db } from '~/lib/db.server';
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const page = parseInt(url.searchParams.get('page') ?? '1');
+  const limit = 20;
+
+  const [posts, total] = await Promise.all([
+    db.post.findMany({
+      take: limit,
+      skip: (page - 1) * limit,
+      orderBy: { createdAt: 'desc' },
+      select: { id: true, title: true, slug: true, createdAt: true },
+    }),
+    db.post.count(),
+  ]);
+
+  return json(
+    { posts, page, totalPages: Math.ceil(total / limit) },
+    { headers: { 'Cache-Control': 'public, max-age=60, s-maxage=300' } }
+  );
+}
+
+export default function Posts() {
+  const { posts, page, totalPages } = useLoaderData<typeof loader>();
+
+  return (
+    <div>
+      <h1>Posts</h1>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Link to={`/posts/${post.slug}`} prefetch="intent">{post.title}</Link>
+          </li>
+        ))}
+      </ul>
+      <nav>
+        {page > 1 && <Link to={`?page=${page - 1}`}>Previous</Link>}
+        <span>Page {page} of {totalPages}</span>
+        {page < totalPages && <Link to={`?page=${page + 1}`}>Next</Link>}
+      </nav>
+    </div>
+  );
+}
+```
+
+### Actions (Form Handling)
+
+```typescript
+// app/routes/posts.new.tsx
+import type { ActionFunctionArgs } from '@remix-run/node';
+import { json, redirect } from '@remix-run/node';
+import { Form, useActionData, useNavigation } from '@remix-run/react';
+import { db } from '~/lib/db.server';
+import { requireAuth } from '~/lib/auth.server';
+
+export async function action({ request }: ActionFunctionArgs) {
+  const user = await requireAuth(request);
+  const formData = await request.formData();
+
+  const title = formData.get('title')?.toString().trim();
+  const body = formData.get('body')?.toString().trim();
+
+  const errors: Record<string, string> = {};
+  if (!title || title.length < 3) errors.title = 'Title must be at least 3 characters';
+  if (!body || body.length < 10) errors.body = 'Body must be at least 10 characters';
+
+  if (Object.keys(errors).length > 0) {
+    return json({ errors, values: { title, body } }, { status: 400 });
+  }
+
+  const slug = title!.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+  const post = await db.post.create({ data: { title: title!, body: body!, slug, authorId: user.id } });
+
+  return redirect(`/posts/${post.slug}`);
+}
+
+export default function NewPost() {
+  const actionData = useActionData<typeof action>();
+  const navigation = useNavigation();
+  const isSubmitting = navigation.state === 'submitting';
+
+  return (
+    <Form method="post">
+      <div>
+        <label htmlFor="title">Title</label>
+        <input
+          id="title"
+          name="title"
+          defaultValue={actionData?.values?.title ?? ''}
+          aria-invalid={!!actionData?.errors?.title}
+          aria-describedby={actionData?.errors?.title ? 'title-error' : undefined}
+        />
+        {actionData?.errors?.title && <p id="title-error">{actionData.errors.title}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="body">Body</label>
+        <textarea id="body" name="body" rows={10} defaultValue={actionData?.values?.body ?? ''} />
+        {actionData?.errors?.body && <p>{actionData.errors.body}</p>}
+      </div>
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Creating...' : 'Create Post'}
+      </button>
+    </Form>
+  );
+}
+```
+
+### Nested Routes and Layouts
+
+```typescript
+// app/routes/dashboard.tsx — layout route
+import { Outlet, NavLink } from '@remix-run/react';
+
+export default function DashboardLayout() {
+  return (
+    <div className="flex">
+      <aside className="w-64">
+        <nav>
+          <NavLink to="/dashboard" end className={({ isActive }) => isActive ? 'font-bold' : ''}>
+            Overview
+          </NavLink>
+          <NavLink to="/dashboard/analytics" className={({ isActive }) => isActive ? 'font-bold' : ''}>
+            Analytics
+          </NavLink>
+          <NavLink to="/dashboard/settings" className={({ isActive }) => isActive ? 'font-bold' : ''}>
+            Settings
+          </NavLink>
+        </nav>
+      </aside>
+      <main className="flex-1">
+        <Outlet />  {/* Child routes render here */}
+      </main>
+    </div>
+  );
+}
+
+// app/routes/dashboard._index.tsx — renders at /dashboard
+// app/routes/dashboard.analytics.tsx — renders at /dashboard/analytics
+// app/routes/dashboard.settings.tsx — renders at /dashboard/settings
+```
+
+### Error Boundaries
+
+```typescript
+// app/routes/posts.$slug.tsx
+import { isRouteErrorResponse, useRouteError } from '@remix-run/react';
+
+export function ErrorBoundary() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error)) {
+    return (
+      <div className="error-container">
+        <h1>{error.status} {error.statusText}</h1>
+        <p>{error.data?.message ?? 'Something went wrong'}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="error-container">
+      <h1>Unexpected Error</h1>
+      <p>{error instanceof Error ? error.message : 'Unknown error'}</p>
+    </div>
+  );
+}
+
+// In loaders, throw responses to trigger error boundaries:
+export async function loader({ params }: LoaderFunctionArgs) {
+  const post = await db.post.findUnique({ where: { slug: params.slug } });
+  if (!post) throw json({ message: 'Post not found' }, { status: 404 });
+  return json({ post });
+}
+```
+
+### Resource Routes (API Endpoints)
+
+```typescript
+// app/routes/api.posts.ts — no default export = resource route
+import type { LoaderFunctionArgs, ActionFunctionArgs } from '@remix-run/node';
+import { json } from '@remix-run/node';
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const posts = await db.post.findMany({ take: 50 });
+  return json(posts);
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method === 'DELETE') {
+    const { id } = await request.json();
+    await db.post.delete({ where: { id } });
+    return json({ success: true });
+  }
+  return json({ error: 'Method not allowed' }, { status: 405 });
+}
+```
+
+### Optimistic UI
+
+```typescript
+// app/routes/todos.tsx
+import { useFetcher } from '@remix-run/react';
+
+function TodoItem({ todo }: { todo: { id: string; title: string; done: boolean } }) {
+  const fetcher = useFetcher();
+  const optimisticDone = fetcher.formData
+    ? fetcher.formData.get('done') === 'true'
+    : todo.done;
+
+  return (
+    <fetcher.Form method="post" action="/todos/toggle">
+      <input type="hidden" name="id" value={todo.id} />
+      <input type="hidden" name="done" value={String(!todo.done)} />
+      <button type="submit" className={optimisticDone ? 'line-through' : ''}>
+        {todo.title}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+## Examples
+
+| Pattern | HTTP Method | URL | Purpose |
+|---------|-------------|-----|---------|
+| Loader | GET | `/posts` | Fetch list of posts |
+| Action | POST | `/posts/new` | Create a new post |
+| Resource route | GET/DELETE | `/api/posts` | JSON API endpoint |
+| Nested route | GET | `/dashboard/analytics` | Child layout rendering |
+| Fetcher | POST | `/todos/toggle` | In-place mutation without navigation |
+
+## Checklist
+- [ ] Loaders use `json()` with appropriate Cache-Control headers
+- [ ] Actions validate form data and return errors with `status: 400`
+- [ ] Forms use `<Form method="post">` for progressive enhancement
+- [ ] Error boundaries handle both route errors and unexpected errors
+- [ ] Links use `prefetch="intent"` for preloading on hover
+- [ ] `useNavigation().state` used to show loading states during transitions
+- [ ] Resource routes return proper status codes and Content-Type headers
+- [ ] Server-only imports use `.server.ts` suffix to prevent client bundling