@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/search-patterns.md

@@ -0,0 +1,227 @@
+---
+name: search-patterns
+description: Search implementation patterns with full-text search, Elasticsearch, Meilisearch, faceted search, and autocomplete.
+---
+
+# Search Patterns
+
+## When to Use
+Apply when users need to find content in your application -- products, articles, users, or documents. Good search is the difference between "I cannot find anything" and "it reads my mind." Start with Postgres full-text search, graduate to Elasticsearch or Meilisearch when you need fuzzy matching, facets, or scale beyond 1M documents.
+
+## How It Works
+
+### Postgres Full-Text Search -- Start Here
+
+Built into Postgres, no extra infrastructure:
+
+```sql
+-- Add a tsvector column for search
+ALTER TABLE products ADD COLUMN search_vector tsvector;
+
+-- Populate from name and description with weighted fields
+UPDATE products SET search_vector =
+  setweight(to_tsvector('english', coalesce(name, '')), 'A') ||
+  setweight(to_tsvector('english', coalesce(description, '')), 'B') ||
+  setweight(to_tsvector('english', coalesce(category, '')), 'C');
+
+-- GIN index for fast lookups
+CREATE INDEX idx_products_search ON products USING GIN (search_vector);
+
+-- Auto-update with trigger
+CREATE FUNCTION products_search_trigger() RETURNS trigger AS $$
+BEGIN
+  NEW.search_vector :=
+    setweight(to_tsvector('english', coalesce(NEW.name, '')), 'A') ||
+    setweight(to_tsvector('english', coalesce(NEW.description, '')), 'B') ||
+    setweight(to_tsvector('english', coalesce(NEW.category, '')), 'C');
+  RETURN NEW;
+END $$ LANGUAGE plpgsql;
+
+CREATE TRIGGER products_search_update
+  BEFORE INSERT OR UPDATE ON products
+  FOR EACH ROW EXECUTE FUNCTION products_search_trigger();
+```
+
+```typescript
+async function searchProducts(query: string, limit = 20) {
+  const result = await db.query(`
+    SELECT id, name, description,
+           ts_rank(search_vector, websearch_to_tsquery('english', $1)) AS rank
+    FROM products
+    WHERE search_vector @@ websearch_to_tsquery('english', $1)
+    ORDER BY rank DESC
+    LIMIT $2
+  `, [query, limit]);
+  return result.rows;
+}
+```
+
+### Meilisearch -- Fast and Simple
+
+Easier to run than Elasticsearch, great for most use cases:
+
+```typescript
+import { MeiliSearch } from "meilisearch";
+
+const client = new MeiliSearch({ host: "http://localhost:7700", apiKey: "masterKey" });
+const index = client.index("products");
+
+// Index documents
+await index.addDocuments(products);
+
+// Configure searchable and filterable attributes
+await index.updateSettings({
+  searchableAttributes: ["name", "description", "category"],
+  filterableAttributes: ["category", "price", "inStock"],
+  sortableAttributes: ["price", "createdAt"],
+  typoTolerance: { enabled: true, minWordSizeForTypos: { oneTypo: 4, twoTypos: 8 } },
+});
+
+// Search with filters and facets
+const results = await index.search("wireless keyboard", {
+  filter: ["category = electronics", "price < 100", "inStock = true"],
+  facets: ["category"],
+  sort: ["price:asc"],
+  limit: 20,
+});
+// results.hits, results.facetDistribution, results.estimatedTotalHits
+```
+
+### Elasticsearch -- Full-Featured
+
+Use when you need complex aggregations or operate at > 10M documents:
+
+```typescript
+import { Client } from "@elastic/elasticsearch";
+
+const elastic = new Client({ node: "http://localhost:9200" });
+
+// Search with boosting, fuzzy matching, and highlighting
+async function search(query: string, filters: SearchFilters) {
+  const result = await elastic.search({
+    index: "products",
+    body: {
+      query: {
+        bool: {
+          must: {
+            multi_match: {
+              query,
+              fields: ["name^3", "description", "tags^2"],
+              fuzziness: "AUTO",
+              type: "best_fields",
+            },
+          },
+          filter: [
+            ...(filters.category ? [{ term: { category: filters.category } }] : []),
+            ...(filters.maxPrice ? [{ range: { price: { lte: filters.maxPrice } } }] : []),
+          ],
+        },
+      },
+      highlight: { fields: { name: {}, description: {} } },
+      aggs: {
+        categories: { terms: { field: "category.keyword", size: 20 } },
+        price_ranges: {
+          range: {
+            field: "price",
+            ranges: [
+              { key: "under-25", to: 25 },
+              { key: "25-50", from: 25, to: 50 },
+              { key: "50-100", from: 50, to: 100 },
+              { key: "over-100", from: 100 },
+            ],
+          },
+        },
+      },
+    },
+  });
+  return result;
+}
+```
+
+### Autocomplete / Typeahead
+
+Show suggestions as the user types. Must respond in under 100ms:
+
+```typescript
+// Simple prefix matching in Postgres (good for < 100K items)
+async function autocomplete(prefix: string, limit = 8) {
+  return db.query(
+    "SELECT DISTINCT name FROM products WHERE name ILIKE $1 ORDER BY popularity DESC LIMIT $2",
+    [`${prefix}%`, limit]
+  );
+}
+
+// Frontend -- debounce input, abort previous request
+function useAutocomplete(query: string) {
+  const [suggestions, setSuggestions] = useState<string[]>([]);
+
+  useEffect(() => {
+    if (query.length < 2) { setSuggestions([]); return; }
+    const controller = new AbortController();
+    const timer = setTimeout(async () => {
+      const res = await fetch(`/api/autocomplete?q=${encodeURIComponent(query)}`, {
+        signal: controller.signal,
+      });
+      setSuggestions(await res.json());
+    }, 150);
+    return () => { clearTimeout(timer); controller.abort(); };
+  }, [query]);
+
+  return suggestions;
+}
+```
+
+### Fuzzy Matching
+
+Handle typos and misspellings:
+
+```sql
+-- Postgres pg_trgm extension for trigram similarity
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX idx_products_name_trgm ON products USING GIN (name gin_trgm_ops);
+
+-- Find "laptop" even if user types "laptpo"
+SELECT name, similarity(name, 'laptpo') AS sim
+FROM products
+WHERE name % 'laptpo'
+ORDER BY sim DESC
+LIMIT 10;
+```
+
+### Faceted Search
+
+Let users filter results by categories, price ranges, and attributes:
+
+```typescript
+// Response shape for faceted search
+interface SearchResponse {
+  hits: Product[];
+  total: number;
+  facets: {
+    categories: { value: string; count: number }[];
+    priceRanges: { label: string; min: number; max: number; count: number }[];
+  };
+  query: string;
+  took: number;
+}
+```
+
+## Examples
+
+| Scale | Tool | When |
+|-------|------|------|
+| < 100K docs | Postgres `tsvector` + GIN | Already have Postgres |
+| 100K-10M, easy ops | Meilisearch | Need fuzzy + facets, simple setup |
+| 10M+, complex queries | Elasticsearch | Need aggregations, custom scoring |
+| Semantic search | pgvector, Pinecone | Meaning-based retrieval |
+| Code search | `pg_trgm` | Substring and regex matching |
+
+## Checklist
+- [ ] Search query debounced on frontend (150-300ms)
+- [ ] Autocomplete returns results in under 100ms
+- [ ] Fuzzy matching handles common typos
+- [ ] Search fields weighted by importance (name > description)
+- [ ] Results include highlighted matching snippets
+- [ ] Faceted filters show counts and update dynamically
+- [ ] Empty and no-results states show helpful suggestions
+- [ ] Search index kept in sync with source database

package/assets/skills/security-hardening.md

@@ -0,0 +1,237 @@
+---
+name: security-hardening
+description: Harden web applications — CSP, CORS, rate limiting, input validation, injection prevention, and secrets management.
+---
+
+# Security Hardening
+
+## When to Use
+
+Apply these patterns to every web application and API from the start. Security
+is not a feature you add later — it's a set of constraints that prevent
+catastrophic failures. Each pattern here blocks a specific, common attack vector.
+
+## How It Works
+
+### 1. Content Security Policy (CSP)
+
+Prevent XSS by controlling which resources the browser can load.
+
+```typescript
+import helmet from 'helmet';
+
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'nonce-{{NONCE}}'"],  // no 'unsafe-inline'
+      styleSrc: ["'self'", "'unsafe-inline'"],      // inline styles often needed
+      imgSrc: ["'self'", "data:", "https://cdn.example.com"],
+      connectSrc: ["'self'", "https://api.example.com"],
+      fontSrc: ["'self'", "https://fonts.gstatic.com"],
+      objectSrc: ["'none'"],
+      frameAncestors: ["'none'"],
+    },
+  },
+}));
+```
+
+Generate a unique nonce per request for inline scripts:
+
+```typescript
+app.use((req, res, next) => {
+  res.locals.nonce = crypto.randomBytes(16).toString('base64');
+  next();
+});
+```
+
+### 2. CORS Configuration
+
+Only allow origins you explicitly trust.
+
+```typescript
+import cors from 'cors';
+
+app.use(cors({
+  origin: (origin, callback) => {
+    const allowed = ['https://app.example.com', 'https://admin.example.com'];
+    if (!origin || allowed.includes(origin)) {
+      callback(null, true);
+    } else {
+      callback(new Error('Not allowed by CORS'));
+    }
+  },
+  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  credentials: true,
+  maxAge: 86400,  // preflight cache: 24 hours
+}));
+```
+
+Never use `origin: '*'` with `credentials: true` — browsers block it anyway,
+and trying to work around it opens you to credential theft.
+
+### 3. Rate Limiting
+
+Prevent brute force, DDoS, and abuse.
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// Global: 100 requests per minute per IP
+app.use(rateLimit({
+  windowMs: 60 * 1000,
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: { code: 'RATE_LIMITED', message: 'Too many requests' } },
+}));
+
+// Strict: 5 login attempts per 15 minutes
+app.use('/api/auth/login', rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5,
+  skipSuccessfulRequests: true,
+}));
+
+// API keys: higher limits
+app.use('/api/v1', rateLimit({
+  windowMs: 60 * 1000,
+  max: 1000,
+  keyGenerator: (req) => req.headers['x-api-key'] as string || req.ip,
+}));
+```
+
+For production, use a Redis-backed store so limits work across server instances.
+
+### 4. Input Validation
+
+Validate and sanitize every input at the boundary. Use Zod for schema
+validation.
+
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100).trim(),
+  email: z.string().email().max(255).toLowerCase(),
+  age: z.number().int().min(13).max(150),
+  bio: z.string().max(2000).optional(),
+});
+
+function validateBody<T>(schema: z.ZodSchema<T>) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      return res.status(400).json({
+        error: {
+          code: 'VALIDATION_ERROR',
+          details: result.error.flatten().fieldErrors,
+        },
+      });
+    }
+    req.body = result.data; // replace with validated data
+    next();
+  };
+}
+
+router.post('/users', validateBody(CreateUserSchema), createUser);
+```
+
+### 5. SQL Injection Prevention
+
+Use parameterized queries. Never concatenate user input into SQL.
+
+```typescript
+// DANGEROUS — SQL injection
+const result = await db.query(`SELECT * FROM users WHERE id = '${userId}'`);
+
+// SAFE — parameterized query
+const result = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+
+// SAFE — Prisma (parameterized by default)
+const user = await prisma.user.findUnique({ where: { id: userId } });
+
+// SAFE — tagged template (Prisma raw)
+const result = await prisma.$queryRaw`SELECT * FROM users WHERE id = ${userId}`;
+```
+
+### 6. Security Headers
+
+```typescript
+app.use(helmet({
+  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+  referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+  noSniff: true,                    // X-Content-Type-Options: nosniff
+  frameguard: { action: 'deny' },   // X-Frame-Options: DENY
+}));
+
+// Permissions Policy — disable unused browser features
+app.use((req, res, next) => {
+  res.setHeader('Permissions-Policy',
+    'camera=(), microphone=(), geolocation=(), payment=()');
+  next();
+});
+```
+
+### 7. Secrets Management
+
+```typescript
+// Load from environment, never from code
+const config = {
+  dbUrl: requireEnv('DATABASE_URL'),
+  jwtSecret: requireEnv('JWT_SECRET'),
+  apiKey: requireEnv('STRIPE_API_KEY'),
+};
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env var: ${name}`);
+  return value;
+}
+```
+
+Rules:
+- `.env` is in `.gitignore` — always
+- Use `.env.example` with placeholder values for documentation
+- Production secrets come from the deployment platform (Vercel, AWS SSM, Vault)
+- Rotate secrets quarterly; immediately after any exposure
+- Never log secrets — redact in structured logging
+
+### 8. Request Body Limits
+
+Prevent denial of service via large payloads.
+
+```typescript
+app.use(express.json({ limit: '1mb' }));
+app.use(express.urlencoded({ extended: true, limit: '1mb' }));
+
+// Stricter limits on specific routes
+app.post('/api/auth/login', express.json({ limit: '10kb' }), loginHandler);
+
+// File upload routes get larger limits
+app.post('/api/uploads', express.raw({ limit: '50mb' }), uploadHandler);
+```
+
+## Examples
+
+| Attack | Defense | Implementation |
+|--------|---------|---------------|
+| XSS | CSP + input sanitization | helmet CSP + Zod validation |
+| CSRF | SameSite cookies + CORS | `sameSite: 'lax'` + origin whitelist |
+| Brute force | Rate limiting | express-rate-limit + Redis store |
+| SQL injection | Parameterized queries | Prisma / `$1` placeholders |
+| Credential theft | HTTPS + secure headers | HSTS + httpOnly cookies |
+| Secret exposure | Environment variables | `.env` in `.gitignore` + requireEnv |
+
+## Checklist
+
+- [ ] CSP is configured with no `unsafe-inline` for scripts
+- [ ] CORS whitelist contains only known origins — no wildcards with credentials
+- [ ] Rate limiting is enabled globally and stricter on auth endpoints
+- [ ] All user input is validated with Zod at the route boundary
+- [ ] All SQL uses parameterized queries or an ORM — zero string concatenation
+- [ ] Helmet sets HSTS, noSniff, frameguard, and referrer policy
+- [ ] `.env` is in `.gitignore` and secrets never appear in logs or responses
+- [ ] Request body size limits are set per route
+- [ ] Dependencies are audited (`npm audit`) and updated monthly

package/assets/skills/seo-patterns.md

@@ -0,0 +1,179 @@
+---
+name: seo-patterns
+description: SEO patterns for meta tags, JSON-LD structured data, sitemaps, Core Web Vitals, and SSR/SSG rendering strategies.
+---
+
+# SEO Patterns
+
+## When to Use
+Apply these patterns to any public-facing web application. SEO is not an afterthought -- it is a core requirement for content sites, e-commerce, SaaS landing pages, and documentation. This skill covers technical SEO: meta tags, structured data (JSON-LD), sitemaps, Core Web Vitals optimization, and rendering strategy selection (SSR vs. SSG vs. ISR).
+
+## How It Works
+
+### Meta Tags -- The Foundation
+
+```tsx
+// Next.js App Router metadata API
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const product = await getProduct(params.slug);
+  return {
+    title: `${product.name} | MyStore`,
+    description: product.summary.slice(0, 155),
+    alternates: { canonical: `https://mystore.com/products/${params.slug}` },
+    openGraph: {
+      title: product.name,
+      description: product.summary,
+      images: [{ url: product.image, width: 1200, height: 630, alt: product.name }],
+      type: "website",
+    },
+    twitter: { card: "summary_large_image", title: product.name, images: [product.image] },
+    robots: { index: product.isPublished, follow: true },
+  };
+}
+```
+
+Every page needs a unique `<title>` (50-60 chars) and `<meta description>` (120-155 chars). Set canonical URL to prevent duplicate content. Use `noindex` for admin pages and search results.
+
+### Structured Data (JSON-LD)
+
+```tsx
+function ProductJsonLd({ product }: { product: Product }) {
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.name,
+    image: product.images,
+    description: product.description,
+    sku: product.sku,
+    brand: { "@type": "Brand", name: product.brand },
+    offers: {
+      "@type": "Offer",
+      priceCurrency: "USD",
+      price: product.price,
+      availability: product.inStock
+        ? "https://schema.org/InStock"
+        : "https://schema.org/OutOfStock",
+    },
+    aggregateRating: product.rating ? {
+      "@type": "AggregateRating",
+      ratingValue: product.rating.average,
+      reviewCount: product.rating.count,
+    } : undefined,
+  };
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+    />
+  );
+}
+```
+
+Common schema types: `Article`, `Product`, `FAQPage`, `BreadcrumbList`, `Organization`, `LocalBusiness`.
+
+### Sitemap Generation
+
+```typescript
+// Next.js App Router sitemap.ts
+import { MetadataRoute } from "next";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const products = await db.products.findMany({
+    where: { isPublished: true },
+    select: { slug: true, updatedAt: true },
+  });
+
+  return [
+    { url: "https://mystore.com", lastModified: new Date(), changeFrequency: "daily", priority: 1 },
+    { url: "https://mystore.com/about", lastModified: new Date(), changeFrequency: "monthly", priority: 0.5 },
+    ...products.map((p) => ({
+      url: `https://mystore.com/products/${p.slug}`,
+      lastModified: p.updatedAt,
+      changeFrequency: "weekly" as const,
+      priority: 0.8,
+    })),
+  ];
+}
+```
+
+For large sites (>50K URLs), split into sitemap index files.
+
+### Core Web Vitals
+
+| Metric | Target | Optimization |
+|--------|--------|-------------|
+| LCP | < 2.5s | Preload hero image, use `<Image priority>`, optimize server response |
+| INP | < 200ms | Avoid long tasks, use `startTransition`, debounce inputs |
+| CLS | < 0.1 | Set explicit width/height on images, avoid injecting content above fold |
+
+```tsx
+// Preload critical hero image
+<link rel="preload" as="image" href="/hero.webp" fetchPriority="high" />
+
+// Next.js Image with priority
+<Image src={product.image} alt={product.name} width={800} height={600}
+  priority sizes="(max-width: 768px) 100vw, 50vw" />
+
+// Font preloading to prevent CLS
+<link rel="preload" href="/fonts/inter-var.woff2" as="font"
+  type="font/woff2" crossOrigin="anonymous" />
+```
+
+### Rendering Strategy Selection
+
+| Strategy | When to Use | SEO Impact |
+|----------|-------------|------------|
+| SSG | Content changes rarely (blog, docs) | Best -- instant, fully crawlable |
+| ISR | Content changes periodically | Great -- static + fresh |
+| SSR | Content changes per request | Good -- crawlable but slower |
+| CSR | Behind auth, dashboards | Poor -- use SSR for public pages |
+
+```typescript
+// Next.js ISR -- revalidate every 60 seconds
+export const revalidate = 60;
+
+export default async function ProductPage({ params }: Props) {
+  const product = await getProduct(params.slug);
+  return <ProductView product={product} />;
+}
+```
+
+### Heading Hierarchy and Internal Linking
+
+```html
+<!-- One H1 per page, logical heading hierarchy -->
+<h1>Running Shoes</h1>
+  <h2>Men's Running Shoes</h2>
+    <h3>Trail Running</h3>
+    <h3>Road Running</h3>
+  <h2>Women's Running Shoes</h2>
+
+<!-- Breadcrumbs with semantic markup -->
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/shoes">Shoes</a></li>
+    <li aria-current="page">Running Shoes</li>
+  </ol>
+</nav>
+```
+
+## Examples
+
+| Pattern | Impact | Effort |
+|---------|--------|--------|
+| Unique title + description | High -- click-through rate | Low |
+| JSON-LD structured data | High -- rich snippets | Medium |
+| Sitemap | Medium -- crawl discovery | Low |
+| Core Web Vitals | High -- ranking signal | Medium-High |
+| SSG/ISR | High -- speed + crawlability | Medium |
+
+## Checklist
+- [ ] Every public page has a unique title (50-60 chars) and description (120-155 chars)
+- [ ] Canonical URLs set on all pages to prevent duplicate content
+- [ ] JSON-LD structured data on product, article, FAQ, and organization pages
+- [ ] Sitemap generated dynamically and submitted to Google Search Console
+- [ ] robots.txt blocks admin, API, and auth routes
+- [ ] Images have explicit width/height, alt text, and use WebP/AVIF formats
+- [ ] LCP < 2.5s, INP < 200ms, CLS < 0.1 (measured with Lighthouse)
+- [ ] Public content uses SSG or ISR, not client-side rendering