@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/caching-patterns.md

@@ -0,0 +1,253 @@
+---
+name: caching-patterns
+description: Apply caching at every layer — HTTP headers, Redis, stale-while-revalidate, CDN, and in-memory memoization.
+---
+
+# Caching Patterns
+
+## When to Use
+
+Apply caching when you need to reduce latency, lower database load, or decrease
+API costs. Cache at the layer closest to the consumer: browser cache for static
+assets, CDN for public pages, Redis for shared application state, in-memory for
+hot function results. Every cache decision requires answering: how stale is
+acceptable, and how do you invalidate?
+
+## How It Works
+
+### 1. HTTP Cache Headers
+
+Control browser and CDN caching with response headers.
+
+```typescript
+// Static assets (CSS, JS, images) — cache forever, bust with filename hash
+app.use('/assets', express.static('public', {
+  maxAge: '1y',
+  immutable: true,
+}));
+// Cache-Control: public, max-age=31536000, immutable
+
+// API responses — short cache, revalidate
+app.get('/api/products', (req, res) => {
+  res.set('Cache-Control', 'public, max-age=60, s-maxage=300');
+  res.set('ETag', computeETag(products));
+  res.json(products);
+});
+
+// Private user data — never cache in shared caches
+app.get('/api/me', authenticate, (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
+  res.json(req.user);
+});
+```
+
+Key headers:
+| Header | Purpose |
+|--------|---------|
+| `max-age=N` | Browser caches for N seconds |
+| `s-maxage=N` | CDN/proxy caches for N seconds |
+| `no-store` | Never cache (auth responses, sensitive data) |
+| `stale-while-revalidate=N` | Serve stale while fetching fresh in background |
+| `ETag` + `If-None-Match` | Conditional requests — 304 if unchanged |
+
+### 2. Redis Caching
+
+Shared cache across multiple server instances.
+
+```typescript
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+async function cachedQuery<T>(
+  key: string,
+  ttlSeconds: number,
+  fetcher: () => Promise<T>,
+): Promise<T> {
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached) as T;
+
+  const fresh = await fetcher();
+  await redis.set(key, JSON.stringify(fresh), 'EX', ttlSeconds);
+  return fresh;
+}
+
+// Usage
+const products = await cachedQuery(
+  'products:featured',
+  300, // 5 minutes
+  () => db.product.findMany({ where: { featured: true } }),
+);
+```
+
+### 3. Stale-While-Revalidate
+
+Serve cached data immediately, refresh in the background.
+
+```typescript
+async function swr<T>(
+  key: string,
+  ttlSeconds: number,
+  staleSeconds: number,
+  fetcher: () => Promise<T>,
+): Promise<T> {
+  const raw = await redis.get(key);
+
+  if (raw) {
+    const { data, timestamp } = JSON.parse(raw);
+    const age = (Date.now() - timestamp) / 1000;
+
+    if (age < ttlSeconds) {
+      return data as T; // fresh
+    }
+
+    if (age < ttlSeconds + staleSeconds) {
+      // Stale — return immediately but refresh in background
+      fetcher().then(async (fresh) => {
+        await redis.set(key, JSON.stringify({ data: fresh, timestamp: Date.now() }));
+      });
+      return data as T;
+    }
+  }
+
+  // Expired or miss — fetch synchronously
+  const fresh = await fetcher();
+  await redis.set(key, JSON.stringify({ data: fresh, timestamp: Date.now() }));
+  return fresh;
+}
+```
+
+### 4. Cache Invalidation
+
+The hardest problem. Three strategies:
+
+**Time-based (TTL):** simplest, eventual consistency.
+
+```typescript
+await redis.set('user:123', JSON.stringify(user), 'EX', 60);
+```
+
+**Event-based:** invalidate on mutation.
+
+```typescript
+async function updateUser(id: string, data: UpdateInput) {
+  const user = await db.user.update({ where: { id }, data });
+  await redis.del(`user:${id}`);           // exact key
+  await redis.del('users:list');            // invalidate list
+  return user;
+}
+```
+
+**Tag-based:** group related keys for bulk invalidation.
+
+```typescript
+async function setWithTags(key: string, value: string, tags: string[], ttl: number) {
+  await redis.set(key, value, 'EX', ttl);
+  for (const tag of tags) {
+    await redis.sadd(`tag:${tag}`, key);
+  }
+}
+
+async function invalidateTag(tag: string) {
+  const keys = await redis.smembers(`tag:${tag}`);
+  if (keys.length > 0) {
+    await redis.del(...keys);
+  }
+  await redis.del(`tag:${tag}`);
+}
+
+// Usage
+await setWithTags('product:42', data, ['products', 'featured'], 300);
+await invalidateTag('featured'); // clears all featured product caches
+```
+
+### 5. CDN Caching
+
+Use `s-maxage` and `Surrogate-Key` headers for CDN-level control.
+
+```typescript
+app.get('/blog/:slug', async (req, res) => {
+  const post = await getPost(req.params.slug);
+  res.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=86400');
+  res.set('Surrogate-Key', `post-${post.id} blog`);
+  res.json(post);
+});
+
+// Purge on update (Fastly/Cloudflare API)
+async function purgePost(postId: string) {
+  await cdnClient.purgeTag(`post-${postId}`);
+}
+```
+
+### 6. In-Memory Memoization
+
+For expensive pure computations within a single process.
+
+```typescript
+function memoize<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+  keyFn: (...args: Args) => string = (...args) => JSON.stringify(args),
+  maxSize: number = 1000,
+): (...args: Args) => Result {
+  const cache = new Map<string, Result>();
+
+  return (...args: Args): Result => {
+    const key = keyFn(...args);
+    if (cache.has(key)) return cache.get(key)!;
+
+    const result = fn(...args);
+
+    if (cache.size >= maxSize) {
+      const firstKey = cache.keys().next().value!;
+      cache.delete(firstKey); // evict oldest
+    }
+
+    cache.set(key, result);
+    return result;
+  };
+}
+
+const computeScore = memoize(
+  (userId: string, period: string) => expensiveCalculation(userId, period),
+);
+```
+
+### 7. Cache Stampede Prevention
+
+When cache expires and 100 requests hit the database simultaneously.
+
+```typescript
+const locks = new Map<string, Promise<unknown>>();
+
+async function singleFlight<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
+  const existing = locks.get(key);
+  if (existing) return existing as Promise<T>;
+
+  const promise = fetcher().finally(() => locks.delete(key));
+  locks.set(key, promise);
+  return promise;
+}
+
+// All concurrent callers share one fetch
+const data = await singleFlight('expensive-query', () => db.query(...));
+```
+
+## Examples
+
+| Layer | TTL | Invalidation | Use case |
+|-------|-----|-------------|----------|
+| Browser | 1 year | Filename hash | Static assets |
+| CDN | 1 hour | Surrogate key purge | Blog posts, marketing pages |
+| Redis | 5 min | Event-based `DEL` | API list endpoints |
+| In-memory | Process lifetime | LRU eviction | Parsed configs, computed scores |
+
+## Checklist
+
+- [ ] Static assets use long `max-age` with content hashes in filenames
+- [ ] Private data responses include `Cache-Control: private, no-store`
+- [ ] Redis cache uses consistent key naming (`entity:id:subresource`)
+- [ ] Every cache write has an explicit TTL — no indefinite caching
+- [ ] Mutations invalidate related cache keys
+- [ ] SWR pattern is used for data where slight staleness is acceptable
+- [ ] Cache stampede is prevented with single-flight or mutex
+- [ ] In-memory caches have a max size to prevent unbounded growth

package/assets/skills/ci-cd.md

@@ -0,0 +1,251 @@
+---
+name: ci-cd
+description: Build reliable CI/CD pipelines with GitHub Actions — caching, matrix builds, deploy gates, and rollbacks.
+---
+
+# CI/CD Patterns
+
+## When to Use
+
+Set up CI/CD from the first commit. Every merged PR should be automatically
+tested, and every release should flow through a pipeline that catches problems
+before users do. These patterns focus on GitHub Actions but the principles
+apply to any CI system.
+
+## How It Works
+
+### 1. Basic Workflow Structure
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true   # cancel stale PR runs
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npm test -- --coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage/lcov.info
+```
+
+### 2. Matrix Builds
+
+Test across multiple Node versions and operating systems.
+
+```yaml
+test:
+  strategy:
+    fail-fast: false   # don't cancel others when one fails
+    matrix:
+      node-version: [18, 20, 22]
+      os: [ubuntu-latest, macos-latest]
+  runs-on: ${{ matrix.os }}
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: npm
+    - run: npm ci
+    - run: npm test
+```
+
+### 3. Dependency Caching
+
+Cache `node_modules` and build artifacts to cut install time from minutes to
+seconds.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: npm          # built-in npm cache
+
+# For monorepos with turbo
+- uses: actions/cache@v4
+  with:
+    path: node_modules/.cache/turbo
+    key: turbo-${{ runner.os }}-${{ hashFiles('**/turbo.json') }}
+    restore-keys: turbo-${{ runner.os }}-
+
+# For Docker layer caching
+- uses: docker/build-push-action@v5
+  with:
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+### 4. Deploy Gates
+
+Require all checks to pass before deploy. Use environments for approval flows.
+
+```yaml
+deploy-staging:
+  needs: [lint, typecheck, test]
+  runs-on: ubuntu-latest
+  environment: staging                # auto-deploys
+  steps:
+    - uses: actions/checkout@v4
+    - run: ./scripts/deploy.sh staging
+
+deploy-production:
+  needs: [deploy-staging]
+  runs-on: ubuntu-latest
+  environment: production             # requires manual approval
+  if: github.ref == 'refs/heads/main'
+  steps:
+    - uses: actions/checkout@v4
+    - run: ./scripts/deploy.sh production
+```
+
+Configure environment protection rules in GitHub:
+- Required reviewers (1-2 people)
+- Wait timer (e.g., 15 minutes after staging deploy)
+- Branch restrictions (only `main`)
+
+### 5. Environment Secrets
+
+```yaml
+env:
+  NODE_ENV: production
+
+steps:
+  - run: npm run deploy
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      API_KEY: ${{ secrets.API_KEY }}
+```
+
+Rules:
+- Never echo secrets in logs. GitHub auto-redacts known secrets but custom
+  values can leak.
+- Use environment-scoped secrets (`staging` vs `production`)
+- Rotate secrets quarterly. Use OIDC for cloud providers when possible.
+
+### 6. Rollback Strategy
+
+```yaml
+deploy-production:
+  steps:
+    - name: Deploy
+      id: deploy
+      run: ./scripts/deploy.sh production
+      continue-on-error: true
+
+    - name: Smoke test
+      id: smoke
+      run: ./scripts/smoke-test.sh ${{ vars.PRODUCTION_URL }}
+
+    - name: Rollback on failure
+      if: steps.deploy.outcome == 'failure' || steps.smoke.outcome == 'failure'
+      run: ./scripts/rollback.sh production
+```
+
+Alternative: blue-green deploys where the old version stays running until the
+new one passes health checks.
+
+### 7. Reusable Workflows
+
+Extract common jobs into shared workflows.
+
+```yaml
+# .github/workflows/reusable-test.yml
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        type: string
+        default: '20'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+```
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      node-version: '20'
+```
+
+### 8. PR Annotations
+
+Post test results and coverage directly on PRs.
+
+```yaml
+- name: Report coverage
+  uses: davelosert/vitest-coverage-report-action@v2
+  if: github.event_name == 'pull_request'
+  with:
+    vite-config-path: vitest.config.ts
+```
+
+## Examples
+
+| Scenario | Pattern |
+|----------|---------|
+| Flaky tests blocking PRs | `fail-fast: false` + retry step |
+| Slow installs | `actions/setup-node` with `cache: npm` |
+| Multi-platform support | Matrix with `os` and `node-version` |
+| Production safety | Environment protection + smoke tests + rollback |
+| DRY pipeline config | Reusable workflows with `workflow_call` |
+
+## Checklist
+
+- [ ] CI runs on every push and PR — lint, typecheck, and test in parallel
+- [ ] `concurrency` cancels stale PR runs to save compute
+- [ ] Dependency caching is configured (npm cache at minimum)
+- [ ] Production deploys require staging success + manual approval
+- [ ] Secrets are scoped to environments, not repository-wide
+- [ ] Deploy step includes smoke test with automatic rollback on failure
+- [ ] Matrix builds cover minimum and latest supported Node versions
+- [ ] Reusable workflows extract duplicated job definitions
+- [ ] No secrets are printed in logs (audit with `ACTIONS_STEP_DEBUG`)