@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/background-jobs.md

@@ -0,0 +1,162 @@
+---
+name: background-jobs
+description: Background job patterns with BullMQ, Celery, Sidekiq, retry strategies, priority queues, and rate limiting.
+---
+
+# Background Job Patterns
+
+## When to Use
+Move work to background jobs when it is slow (API calls, email, PDF generation), not needed for the user's immediate response, or must be retried on failure. This skill covers job queue design across BullMQ (Node.js), Celery (Python), and Sidekiq (Ruby), plus universal patterns for retries, priorities, rate limiting, and monitoring.
+
+## How It Works
+
+### BullMQ (Node.js) -- Queue + Worker
+
+```typescript
+import { Queue, Worker, Job } from "bullmq";
+import IORedis from "ioredis";
+
+const connection = new IORedis({ host: "localhost", port: 6379, maxRetriesPerRequest: null });
+const emailQueue = new Queue("emails", { connection });
+
+// Enqueue a job
+await emailQueue.add("welcome", {
+  to: "alice@example.com",
+  template: "welcome",
+  variables: { name: "Alice" },
+}, {
+  priority: 1,
+  attempts: 5,
+  backoff: { type: "exponential", delay: 5000 },
+  removeOnComplete: { count: 1000 },
+  removeOnFail: { age: 7 * 86400 },
+});
+
+// Worker -- process jobs
+const worker = new Worker("emails", async (job: Job) => {
+  switch (job.name) {
+    case "welcome":
+      await sendEmail(job.data.to, job.data.template, job.data.variables);
+      break;
+    default:
+      throw new Error(`Unknown job: ${job.name}`);
+  }
+}, {
+  connection,
+  concurrency: 5,
+  limiter: { max: 50, duration: 60_000 },
+});
+
+worker.on("failed", (job, err) => {
+  console.error(`Job ${job?.id} failed: ${err.message}`);
+});
+```
+
+### Celery (Python) -- Distributed Tasks
+
+```python
+from celery import Celery
+
+app = Celery("tasks", broker="redis://localhost:6379/0")
+
+app.conf.update(
+    task_serializer="json",
+    task_acks_late=True,
+    worker_prefetch_multiplier=1,
+    task_reject_on_worker_lost=True,
+)
+
+@app.task(bind=True, max_retries=5, autoretry_for=(ConnectionError, TimeoutError),
+          retry_backoff=True, retry_backoff_max=3600)
+def process_payment(self, order_id: str):
+    order = Order.objects.get(id=order_id)
+    try:
+        charge = gateway.charge(order.total, order.payment_method)
+        order.mark_paid(charge.id)
+    except PaymentDeclined:
+        order.mark_declined()
+        raise  # don't retry business failures
+
+process_payment.apply_async(args=["order-123"], queue="payments", priority=0)
+```
+
+### Sidekiq (Ruby) -- Threaded Workers
+
+```ruby
+class WelcomeEmailJob
+  include Sidekiq::Job
+
+  sidekiq_options queue: :mailers, retry: 5, backtrace: true
+
+  sidekiq_retry_in do |count, _exception|
+    (count ** 4) + 15 + (rand(10) * (count + 1))
+  end
+
+  def perform(user_id)
+    user = User.find(user_id)
+    UserMailer.welcome(user).deliver_now
+  end
+end
+
+WelcomeEmailJob.perform_async(user.id)
+WelcomeEmailJob.perform_in(5.minutes, user.id)
+```
+
+### Retry Strategies
+
+| Strategy | Formula | Use Case |
+|----------|---------|----------|
+| Fixed delay | 30s every time | Simple rate-limited APIs |
+| Exponential backoff | `delay * 2^attempt` | Transient failures |
+| Exponential + jitter | `delay * 2^attempt + random(0, delay)` | Prevent thundering herd |
+| Custom schedule | `[10s, 30s, 2m, 10m, 1h]` | Known recovery patterns |
+
+Do not retry: 400 Bad Request, 401/403, 404, or business logic failures (declined payment, validation error).
+
+### Job Design Rules
+
+```typescript
+// GOOD: Pass IDs, not objects -- jobs are serialized to JSON
+await queue.add("process-order", { orderId: "abc-123" });
+
+// BAD: Passing the full object -- stale data, large payloads
+await queue.add("process-order", { order: fullOrderObject });
+
+// GOOD: Idempotent -- safe to run twice
+async function processOrder(job: Job) {
+  const order = await db.orders.findUnique({ where: { id: job.data.orderId } });
+  if (order.status === "processed") return;
+  await chargeAndFulfill(order);
+}
+```
+
+### Rate Limiting
+
+```typescript
+// BullMQ: 100 API calls per minute per tenant
+const apiQueue = new Queue("external-api", { connection });
+
+await apiQueue.add("sync-crm", { tenantId, data }, {
+  group: { id: tenantId },
+  limiter: { max: 100, duration: 60_000 },
+});
+```
+
+## Examples
+
+| Framework | Language | Backend | Unique Feature |
+|-----------|----------|---------|----------------|
+| BullMQ | TypeScript | Redis | Flow (parent-child jobs) |
+| Celery | Python | Redis/RabbitMQ | Canvas (chord, chain, group) |
+| Sidekiq | Ruby | Redis | Batches (pro), threading |
+| Temporal | Any (via SDK) | Temporal Server | Durable execution, sagas |
+
+## Checklist
+- [ ] Jobs are idempotent -- safe to process the same job twice
+- [ ] Jobs pass IDs, not serialized objects (re-fetch fresh data)
+- [ ] Retry strategy uses exponential backoff with jitter
+- [ ] Non-retryable errors (4xx, business failures) are not retried
+- [ ] Dead letter queue captures permanently failed jobs
+- [ ] Rate limiting configured per external API or tenant
+- [ ] Priority levels defined and documented
+- [ ] Job queue dashboard deployed (Bull Board, Flower, Sidekiq Web)

package/assets/skills/browser-extensions.md

@@ -0,0 +1,309 @@
+---
+name: browser-extensions
+description: Browser extension patterns for Manifest V3, content scripts, background service workers, cross-script messaging, and storage.
+---
+
+# Browser Extension Patterns
+
+## When to Use
+Build a browser extension when you need to modify web page behavior, add UI overlays, intercept network requests, or provide cross-site functionality. These patterns cover Manifest V3 (required for Chrome), content scripts that run in page context, background service workers for event handling, popup and side panel UIs, secure messaging between contexts, and persistent storage.
+
+## How It Works
+
+### Manifest V3 Configuration
+
+```json
+{
+  "manifest_version": 3,
+  "name": "My Extension",
+  "version": "1.0.0",
+  "description": "A productivity extension",
+  "permissions": ["storage", "activeTab", "contextMenus", "alarms"],
+  "host_permissions": ["https://*.example.com/*"],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "content_scripts": [
+    {
+      "matches": ["https://*.example.com/*"],
+      "js": ["content.js"],
+      "css": ["content.css"],
+      "run_at": "document_idle"
+    }
+  ],
+  "action": {
+    "default_popup": "popup.html",
+    "default_icon": {
+      "16": "icons/16.png",
+      "48": "icons/48.png",
+      "128": "icons/128.png"
+    }
+  },
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  },
+  "options_page": "options.html",
+  "icons": {
+    "16": "icons/16.png",
+    "48": "icons/48.png",
+    "128": "icons/128.png"
+  }
+}
+```
+
+### Background Service Worker
+
+```typescript
+// background.ts
+chrome.runtime.onInstalled.addListener((details) => {
+  if (details.reason === 'install') {
+    chrome.storage.local.set({ settings: { enabled: true, theme: 'auto' } });
+
+    // Create context menu
+    chrome.contextMenus.create({
+      id: 'analyze-selection',
+      title: 'Analyze "%s"',
+      contexts: ['selection'],
+    });
+  }
+});
+
+// Context menu click handler
+chrome.contextMenus.onClicked.addListener(async (info, tab) => {
+  if (info.menuItemId === 'analyze-selection' && tab?.id) {
+    const result = await analyzeText(info.selectionText ?? '');
+    chrome.tabs.sendMessage(tab.id, { type: 'ANALYSIS_RESULT', data: result });
+  }
+});
+
+// Message handler for content script / popup communication
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === 'GET_DATA') {
+    fetchData(message.url)
+      .then((data) => sendResponse({ success: true, data }))
+      .catch((err) => sendResponse({ success: false, error: err.message }));
+    return true; // keep message channel open for async response
+  }
+
+  if (message.type === 'SAVE_SETTING') {
+    chrome.storage.sync.set({ [message.key]: message.value });
+    sendResponse({ success: true });
+  }
+});
+
+// Alarm for periodic tasks
+chrome.alarms.create('sync-data', { periodInMinutes: 30 });
+chrome.alarms.onAlarm.addListener(async (alarm) => {
+  if (alarm.name === 'sync-data') {
+    await syncDataToServer();
+  }
+});
+```
+
+### Content Script
+
+```typescript
+// content.ts
+class PageEnhancer {
+  private overlay: HTMLDivElement | null = null;
+
+  constructor() {
+    this.init();
+  }
+
+  private async init() {
+    const { settings } = await chrome.storage.local.get('settings');
+    if (!settings?.enabled) return;
+
+    this.injectUI();
+    this.observeDOM();
+  }
+
+  private injectUI() {
+    // Use Shadow DOM to isolate styles
+    const host = document.createElement('div');
+    host.id = 'my-extension-root';
+    const shadow = host.attachShadow({ mode: 'closed' });
+
+    const style = document.createElement('style');
+    style.textContent = `
+      .overlay { position: fixed; bottom: 16px; right: 16px; z-index: 999999;
+        background: white; border-radius: 8px; padding: 16px;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.15); font-family: system-ui; }
+      .overlay button { background: #2563eb; color: white; border: none;
+        padding: 8px 16px; border-radius: 4px; cursor: pointer; }
+    `;
+
+    this.overlay = document.createElement('div');
+    this.overlay.className = 'overlay';
+    this.overlay.innerHTML = `<p>Extension Active</p><button id="action-btn">Analyze</button>`;
+
+    shadow.appendChild(style);
+    shadow.appendChild(this.overlay);
+    document.body.appendChild(host);
+
+    shadow.getElementById('action-btn')?.addEventListener('click', () => this.analyze());
+  }
+
+  private observeDOM() {
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of mutation.addedNodes) {
+          if (node instanceof HTMLElement && node.matches('.target-element')) {
+            this.processElement(node);
+          }
+        }
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+
+  private async analyze() {
+    const response = await chrome.runtime.sendMessage({
+      type: 'GET_DATA',
+      url: window.location.href,
+    });
+    if (response.success) {
+      this.showResults(response.data);
+    }
+  }
+
+  private processElement(el: HTMLElement) { /* enhance element */ }
+  private showResults(data: unknown) { /* display in overlay */ }
+}
+
+// Listen for messages from background
+chrome.runtime.onMessage.addListener((message) => {
+  if (message.type === 'ANALYSIS_RESULT') {
+    new PageEnhancer().showResults(message.data);
+  }
+});
+
+new PageEnhancer();
+```
+
+### Popup UI
+
+```html
+<!-- popup.html -->
+<!DOCTYPE html>
+<html>
+<head><link rel="stylesheet" href="popup.css" /></head>
+<body>
+  <div id="app">
+    <h2>My Extension</h2>
+    <label><input type="checkbox" id="enabled" /> Enabled</label>
+    <div id="stats"></div>
+    <button id="analyze">Analyze Current Page</button>
+  </div>
+  <script src="popup.js" type="module"></script>
+</body>
+</html>
+```
+
+```typescript
+// popup.ts
+document.addEventListener('DOMContentLoaded', async () => {
+  const { settings } = await chrome.storage.local.get('settings');
+  const enabledCheckbox = document.getElementById('enabled') as HTMLInputElement;
+  enabledCheckbox.checked = settings?.enabled ?? true;
+
+  enabledCheckbox.addEventListener('change', () => {
+    chrome.storage.local.set({ settings: { ...settings, enabled: enabledCheckbox.checked } });
+  });
+
+  document.getElementById('analyze')?.addEventListener('click', async () => {
+    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+    if (tab?.id) {
+      chrome.tabs.sendMessage(tab.id, { type: 'TRIGGER_ANALYSIS' });
+      window.close();
+    }
+  });
+});
+```
+
+### Storage Patterns
+
+```typescript
+// storage.ts — typed wrapper around chrome.storage
+interface ExtensionStorage {
+  settings: { enabled: boolean; theme: 'light' | 'dark' | 'auto' };
+  cache: Record<string, { data: unknown; expires: number }>;
+  stats: { pagesAnalyzed: number; lastActive: string };
+}
+
+async function getStorage<K extends keyof ExtensionStorage>(
+  key: K
+): Promise<ExtensionStorage[K] | undefined> {
+  const result = await chrome.storage.local.get(key);
+  return result[key];
+}
+
+async function setStorage<K extends keyof ExtensionStorage>(
+  key: K,
+  value: ExtensionStorage[K]
+): Promise<void> {
+  await chrome.storage.local.set({ [key]: value });
+}
+
+// Listen for storage changes
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (area === 'local' && changes.settings) {
+    const newSettings = changes.settings.newValue;
+    applySettings(newSettings);
+  }
+});
+
+// Cached data with expiry
+async function getCachedData(key: string): Promise<unknown | null> {
+  const cache = await getStorage('cache') ?? {};
+  const entry = cache[key];
+  if (!entry || entry.expires < Date.now()) return null;
+  return entry.data;
+}
+
+async function setCachedData(key: string, data: unknown, ttlMs: number = 3600000) {
+  const cache = await getStorage('cache') ?? {};
+  cache[key] = { data, expires: Date.now() + ttlMs };
+  await setStorage('cache', cache);
+}
+```
+
+### Build Setup (Vite + CRXJS)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import crx from '@crxjs/vite-plugin';
+import manifest from './manifest.json';
+
+export default defineConfig({
+  plugins: [react(), crx({ manifest })],
+  build: {
+    rollupOptions: {
+      input: { popup: 'popup.html', sidepanel: 'sidepanel.html', options: 'options.html' },
+    },
+  },
+});
+```
+
+## Examples
+
+| Context | Access | Communication |
+|---------|--------|---------------|
+| Background (service worker) | Full Chrome APIs, no DOM | `chrome.runtime.onMessage` |
+| Content script | Page DOM, limited Chrome APIs | `chrome.runtime.sendMessage` |
+| Popup / Side panel | Full Chrome APIs, own DOM | `chrome.tabs.sendMessage` |
+| Injected script | Page JS context | `window.postMessage` |
+
+## Checklist
+- [ ] Manifest V3 used (V2 deprecated in Chrome)
+- [ ] Permissions are minimal — only request what is needed
+- [ ] Content script styles isolated with Shadow DOM
+- [ ] Background script handles async messages with `return true`
+- [ ] Storage uses typed wrapper with `chrome.storage.local` or `sync`
+- [ ] Context menus created in `onInstalled` handler, not on every load
+- [ ] Popup and options pages work without content script injection
+- [ ] Extension tested in Chrome, Firefox (WebExtensions API), and Edge