@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/edge-computing.md

@@ -0,0 +1,268 @@
+---
+name: edge-computing
+description: Edge computing patterns for Cloudflare Workers, edge middleware, geolocation routing, KV storage, and Durable Objects.
+---
+
+# Edge Computing Patterns
+
+## When to Use
+Deploy logic to the edge when you need sub-50ms response times globally, geolocation-based routing, request transformation before reaching origin servers, or lightweight compute that does not require a full server. Edge functions are ideal for A/B testing, auth token validation, redirects, rate limiting, and personalization. Avoid edge for CPU-heavy workloads or anything requiring persistent connections to a single database.
+
+## How It Works
+
+### Cloudflare Worker Basics
+
+```typescript
+// src/worker.ts
+export interface Env {
+  MY_KV: KVNamespace;
+  MY_R2: R2Bucket;
+  API_KEY: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Route to handlers
+    if (url.pathname.startsWith('/api/')) return handleAPI(request, env, ctx);
+    if (url.pathname === '/health') return new Response('ok', { status: 200 });
+
+    return new Response('Not found', { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;
+
+async function handleAPI(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+  // Verify API key
+  const apiKey = request.headers.get('X-API-Key');
+  if (apiKey !== env.API_KEY) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const data = await env.MY_KV.get('cache:data', 'json');
+  return Response.json(data ?? { items: [] });
+}
+```
+
+### Edge Middleware (Next.js / Vercel)
+
+```typescript
+// middleware.ts (project root)
+import { NextRequest, NextResponse } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const { pathname, searchParams } = request.nextUrl;
+  const country = request.geo?.country ?? 'US';
+  const city = request.geo?.city ?? 'Unknown';
+
+  // Geolocation-based redirect
+  if (pathname === '/' && country === 'DE') {
+    return NextResponse.redirect(new URL('/de', request.url));
+  }
+
+  // A/B testing via cookie
+  const bucket = request.cookies.get('ab-bucket')?.value;
+  if (!bucket && pathname === '/pricing') {
+    const assigned = Math.random() < 0.5 ? 'control' : 'variant';
+    const response = NextResponse.rewrite(
+      new URL(`/pricing/${assigned}`, request.url)
+    );
+    response.cookies.set('ab-bucket', assigned, { maxAge: 60 * 60 * 24 * 30 });
+    return response;
+  }
+
+  // Add custom headers
+  const response = NextResponse.next();
+  response.headers.set('X-Country', country);
+  response.headers.set('X-City', city);
+  return response;
+}
+
+export const config = {
+  matcher: ['/', '/pricing/:path*', '/api/:path*'],
+};
+```
+
+### KV Storage Patterns
+
+```typescript
+// src/kv-cache.ts
+export async function cachedFetch(
+  kv: KVNamespace,
+  cacheKey: string,
+  fetcher: () => Promise<unknown>,
+  ttlSeconds: number = 300
+): Promise<unknown> {
+  // Try KV cache first
+  const cached = await kv.get(cacheKey, 'json');
+  if (cached !== null) return cached;
+
+  // Fetch from origin
+  const data = await fetcher();
+
+  // Store in KV with TTL (non-blocking)
+  await kv.put(cacheKey, JSON.stringify(data), {
+    expirationTtl: ttlSeconds,
+  });
+
+  return data;
+}
+
+// KV with metadata for cache management
+export async function putWithMetadata(
+  kv: KVNamespace,
+  key: string,
+  value: unknown,
+  metadata: { version: number; source: string }
+) {
+  await kv.put(key, JSON.stringify(value), {
+    expirationTtl: 3600,
+    metadata,
+  });
+}
+
+export async function getWithMetadata(kv: KVNamespace, key: string) {
+  const { value, metadata } = await kv.getWithMetadata<{ version: number; source: string }>(
+    key, 'json'
+  );
+  return { data: value, metadata };
+}
+```
+
+### Durable Objects (Stateful Edge)
+
+```typescript
+// src/rate-limiter.ts
+export class RateLimiter implements DurableObject {
+  private requests: number[] = [];
+  private readonly limit = 100;
+  private readonly windowMs = 60_000;
+
+  constructor(private state: DurableObjectState, private env: Env) {}
+
+  async fetch(request: Request): Promise<Response> {
+    const now = Date.now();
+
+    // Load state
+    this.requests = (await this.state.storage.get<number[]>('requests')) ?? [];
+
+    // Prune old entries
+    this.requests = this.requests.filter((t) => now - t < this.windowMs);
+
+    if (this.requests.length >= this.limit) {
+      const retryAfter = Math.ceil((this.requests[0] + this.windowMs - now) / 1000);
+      return new Response('Rate limit exceeded', {
+        status: 429,
+        headers: {
+          'Retry-After': String(retryAfter),
+          'X-RateLimit-Limit': String(this.limit),
+          'X-RateLimit-Remaining': '0',
+        },
+      });
+    }
+
+    this.requests.push(now);
+    await this.state.storage.put('requests', this.requests);
+
+    return Response.json({
+      remaining: this.limit - this.requests.length,
+      limit: this.limit,
+    });
+  }
+}
+
+// Worker entry — route to Durable Object
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const ip = request.headers.get('CF-Connecting-IP') ?? 'unknown';
+    const id = env.RATE_LIMITER.idFromName(ip);
+    const stub = env.RATE_LIMITER.get(id);
+    return stub.fetch(request);
+  },
+};
+```
+
+### R2 Object Storage at the Edge
+
+```typescript
+// src/r2-handler.ts
+export async function handleR2(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  const key = url.pathname.slice(1); // remove leading /
+
+  if (request.method === 'GET') {
+    const object = await env.MY_R2.get(key);
+    if (!object) return new Response('Not found', { status: 404 });
+
+    return new Response(object.body, {
+      headers: {
+        'Content-Type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+        'ETag': object.etag,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      },
+    });
+  }
+
+  if (request.method === 'PUT') {
+    const contentType = request.headers.get('Content-Type') ?? 'application/octet-stream';
+    await env.MY_R2.put(key, request.body, {
+      httpMetadata: { contentType },
+    });
+    return new Response('Created', { status: 201 });
+  }
+
+  return new Response('Method not allowed', { status: 405 });
+}
+```
+
+### Geolocation-Based Content
+
+```typescript
+// src/geo-router.ts
+interface GeoConfig {
+  country: string;
+  redirects: Record<string, string>;
+  blockedCountries: string[];
+}
+
+export function geoRoute(request: Request, cf: IncomingRequestCfProperties): Response | null {
+  const country = cf.country ?? 'US';
+  const continent = cf.continent ?? 'NA';
+
+  // Block sanctioned regions
+  const blocked = ['KP', 'IR', 'SY'];
+  if (blocked.includes(country)) {
+    return new Response('Service unavailable in your region', { status: 451 });
+  }
+
+  // Inject geolocation headers for downstream
+  const headers = new Headers();
+  headers.set('X-Geo-Country', country);
+  headers.set('X-Geo-Continent', continent);
+  headers.set('X-Geo-City', cf.city ?? 'Unknown');
+  headers.set('X-Geo-Latitude', String(cf.latitude ?? 0));
+  headers.set('X-Geo-Longitude', String(cf.longitude ?? 0));
+
+  return null; // continue to origin with headers
+}
+```
+
+## Examples
+
+| Pattern | Latency | State | Use Case |
+|---------|---------|-------|----------|
+| KV cache | ~10ms global | Eventually consistent | Config, feature flags, cached API |
+| Durable Object | ~20ms | Strongly consistent | Rate limiting, counters, sessions |
+| R2 storage | ~50ms | Strongly consistent | File uploads, static assets |
+| Edge middleware | ~1ms overhead | Stateless | Auth, redirects, headers |
+| Worker fetch | ~5ms cold start | Stateless | API proxy, transformation |
+
+## Checklist
+- [ ] Workers handle errors gracefully and return proper HTTP status codes
+- [ ] KV keys include version or TTL metadata for cache invalidation
+- [ ] Durable Objects used only when strong consistency is required
+- [ ] Geolocation checks use `request.cf` (Cloudflare) or `request.geo` (Vercel)
+- [ ] R2 responses include Cache-Control and ETag headers
+- [ ] Sensitive logic (API keys, auth) runs at the edge, not in client
+- [ ] Worker bundle size stays under 1MB (compressed) for fast cold starts
+- [ ] `waitUntil()` used for non-blocking background work

package/assets/skills/electron-patterns.md

@@ -0,0 +1,266 @@
+---
+name: electron-patterns
+description: Build Electron apps — IPC communication, preload scripts, auto-update, window management, security, and packaging.
+---
+
+# Electron Patterns
+
+## When to Use
+
+Use Electron when building cross-platform desktop applications with web
+technologies. Covers the critical security boundary between main and renderer
+processes, IPC communication, preload scripts for safe API exposure,
+auto-updates, window management, and packaging for distribution. Apply these
+patterns from the start — Electron security mistakes are hard to retrofit.
+
+## How It Works
+
+### 1. Process Architecture
+
+Electron has two process types. Never bypass this boundary.
+
+```
+Main Process (Node.js)          Renderer Process (Chromium)
+|- File system access           |- UI rendering
+|- Native APIs                  |- DOM manipulation
+|- Window management            |- Web APIs only
+|- System tray                  +- No Node.js (when secure)
++- IPC handler
+        <-> IPC bridge (preload.ts)
+```
+
+### 2. Preload Script — Safe API Surface
+
+```typescript
+// preload.ts — runs in renderer context with Node.js access
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('electronAPI', {
+  // File operations — exposed as async functions
+  readFile: (path: string) => ipcRenderer.invoke('file:read', path),
+  writeFile: (path: string, data: string) => ipcRenderer.invoke('file:write', path, data),
+  selectFile: () => ipcRenderer.invoke('dialog:openFile'),
+
+  // App info
+  getVersion: () => ipcRenderer.invoke('app:version'),
+
+  // One-way events (renderer -> main)
+  minimize: () => ipcRenderer.send('window:minimize'),
+  maximize: () => ipcRenderer.send('window:maximize'),
+
+  // Subscriptions (main -> renderer)
+  onUpdateAvailable: (callback: (info: UpdateInfo) => void) => {
+    const handler = (_event: Event, info: UpdateInfo) => callback(info);
+    ipcRenderer.on('update:available', handler);
+    return () => ipcRenderer.removeListener('update:available', handler);
+  },
+});
+```
+
+```typescript
+// Type declaration for renderer
+declare global {
+  interface Window {
+    electronAPI: {
+      readFile: (path: string) => Promise<string>;
+      writeFile: (path: string, data: string) => Promise<void>;
+      selectFile: () => Promise<string | null>;
+      getVersion: () => Promise<string>;
+      minimize: () => void;
+      maximize: () => void;
+      onUpdateAvailable: (callback: (info: UpdateInfo) => void) => () => void;
+    };
+  }
+}
+```
+
+### 3. IPC Handlers — Main Process
+
+```typescript
+// main.ts
+import { app, BrowserWindow, ipcMain, dialog } from 'electron';
+import fs from 'fs/promises';
+import path from 'path';
+
+// Invoke handlers (bidirectional — returns a value)
+ipcMain.handle('file:read', async (_event, filePath: string) => {
+  // Validate path to prevent directory traversal
+  const resolved = path.resolve(filePath);
+  if (!resolved.startsWith(app.getPath('userData'))) {
+    throw new Error('Access denied: path outside user data directory');
+  }
+  return fs.readFile(resolved, 'utf-8');
+});
+
+ipcMain.handle('dialog:openFile', async () => {
+  const result = await dialog.showOpenDialog({
+    properties: ['openFile'],
+    filters: [{ name: 'Text', extensions: ['txt', 'md', 'json'] }],
+  });
+  return result.canceled ? null : result.filePaths[0];
+});
+
+ipcMain.handle('app:version', () => app.getVersion());
+
+// One-way handlers
+ipcMain.on('window:minimize', (event) => {
+  BrowserWindow.fromWebContents(event.sender)?.minimize();
+});
+```
+
+### 4. Window Management
+
+```typescript
+function createMainWindow(): BrowserWindow {
+  const win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    minWidth: 800,
+    minHeight: 600,
+    titleBarStyle: 'hiddenInset',  // macOS frameless with traffic lights
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,       // REQUIRED — never disable
+      nodeIntegration: false,       // REQUIRED — never enable
+      sandbox: true,                // extra isolation
+    },
+  });
+
+  // Save/restore window position
+  const bounds = store.get('windowBounds');
+  if (bounds) win.setBounds(bounds);
+
+  win.on('close', () => {
+    store.set('windowBounds', win.getBounds());
+  });
+
+  if (isDev) {
+    win.loadURL('http://localhost:3000');
+    win.webContents.openDevTools();
+  } else {
+    win.loadFile(path.join(__dirname, '../renderer/index.html'));
+  }
+
+  return win;
+}
+```
+
+### 5. Auto-Update
+
+```typescript
+import { autoUpdater } from 'electron-updater';
+import log from 'electron-log';
+
+autoUpdater.logger = log;
+autoUpdater.autoDownload = false; // let user decide
+
+export function setupAutoUpdater(mainWindow: BrowserWindow) {
+  autoUpdater.on('update-available', (info) => {
+    mainWindow.webContents.send('update:available', {
+      version: info.version,
+      releaseNotes: info.releaseNotes,
+    });
+  });
+
+  autoUpdater.on('download-progress', (progress) => {
+    mainWindow.webContents.send('update:progress', {
+      percent: progress.percent,
+    });
+  });
+
+  autoUpdater.on('update-downloaded', () => {
+    mainWindow.webContents.send('update:ready');
+  });
+
+  // Check every 4 hours
+  setInterval(() => autoUpdater.checkForUpdates(), 4 * 60 * 60 * 1000);
+  autoUpdater.checkForUpdates();
+}
+
+// IPC handler for user-initiated download/install
+ipcMain.handle('update:download', () => autoUpdater.downloadUpdate());
+ipcMain.handle('update:install', () => autoUpdater.quitAndInstall());
+```
+
+### 6. Security Hardening
+
+```typescript
+// main.ts — security headers
+app.on('web-contents-created', (_event, contents) => {
+  // Prevent navigation away from the app
+  contents.on('will-navigate', (event, url) => {
+    const parsed = new URL(url);
+    if (parsed.origin !== 'http://localhost:3000' && parsed.protocol !== 'file:') {
+      event.preventDefault();
+    }
+  });
+
+  // Prevent new windows (open links in default browser)
+  contents.setWindowOpenHandler(({ url }) => {
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+});
+
+// Content Security Policy
+session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
+  callback({
+    responseHeaders: {
+      ...details.responseHeaders,
+      'Content-Security-Policy': [
+        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"
+      ],
+    },
+  });
+});
+```
+
+### 7. Packaging — electron-builder
+
+```json
+{
+  "build": {
+    "appId": "com.myapp.desktop",
+    "productName": "MyApp",
+    "mac": {
+      "target": ["dmg", "zip"],
+      "category": "public.app-category.developer-tools",
+      "hardenedRuntime": true,
+      "notarize": true
+    },
+    "win": {
+      "target": ["nsis"],
+      "certificateSubjectName": "My Company"
+    },
+    "linux": {
+      "target": ["AppImage", "deb"],
+      "category": "Development"
+    },
+    "publish": {
+      "provider": "github"
+    }
+  }
+}
+```
+
+## Examples
+
+| Pattern | Process | Purpose |
+|---------|---------|---------|
+| `contextBridge.exposeInMainWorld` | Preload | Safe API for renderer |
+| `ipcMain.handle` / `ipcRenderer.invoke` | Main/Renderer | Bidirectional async IPC |
+| `autoUpdater` | Main | Seamless updates |
+| `BrowserWindow` options | Main | Security + UX config |
+
+## Checklist
+
+- [ ] `contextIsolation: true` and `nodeIntegration: false` on all windows
+- [ ] `sandbox: true` enabled for extra process isolation
+- [ ] All renderer-to-main communication goes through preload + IPC
+- [ ] IPC handlers validate and sanitize all arguments
+- [ ] File paths validated against allowed directories (no traversal)
+- [ ] Navigation and new-window events restricted
+- [ ] CSP headers set to prevent XSS
+- [ ] Auto-updater configured with code signing
+- [ ] macOS builds notarized, Windows builds code-signed
+- [ ] Dev tools disabled in production builds