@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/prisma-patterns.md

@@ -0,0 +1,241 @@
+---
+name: prisma-patterns
+description: Use Prisma ORM effectively — relations, transactions, raw queries, migrations, and soft deletes.
+---
+
+# Prisma ORM Patterns
+
+## When to Use
+
+Apply these patterns when using Prisma as your database layer. Prisma's type
+safety is powerful but has sharp edges around performance, transactions, and
+advanced queries. These patterns keep you out of trouble as your schema grows.
+
+## How It Works
+
+### 1. Relations — Explicit Over Implicit
+
+Define both sides of every relation. Use `@relation` with named references when
+a model has multiple relations to the same table.
+
+```prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  posts     Post[]   @relation("author")
+  reviews   Post[]   @relation("reviewer")
+  profile   Profile?
+}
+
+model Post {
+  id          String @id @default(cuid())
+  authorId    String
+  author      User   @relation("author", fields: [authorId], references: [id])
+  reviewerId  String?
+  reviewer    User?  @relation("reviewer", fields: [reviewerId], references: [id])
+}
+
+model Profile {
+  id     String @id @default(cuid())
+  userId String @unique
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  bio    String @default("")
+}
+```
+
+Always set `onDelete` explicitly. The default is `SetNull` for optional relations
+and `Restrict` for required ones — both can surprise you.
+
+### 2. Select Only What You Need
+
+Avoid fetching entire objects when you need two fields.
+
+```typescript
+// Bad — fetches every column
+const users = await prisma.user.findMany({ include: { posts: true } });
+
+// Good — fetches only what the API response needs
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    posts: {
+      select: { id: true, title: true },
+      where: { published: true },
+      take: 5,
+      orderBy: { createdAt: 'desc' },
+    },
+  },
+});
+```
+
+### 3. Transactions
+
+Use interactive transactions for multi-step operations that must be atomic.
+
+```typescript
+const [order, payment] = await prisma.$transaction(async (tx) => {
+  const order = await tx.order.create({
+    data: { userId, items: { create: lineItems } },
+  });
+
+  const payment = await tx.payment.create({
+    data: {
+      orderId: order.id,
+      amount: calculateTotal(lineItems),
+      status: 'pending',
+    },
+  });
+
+  // If this throws, both order and payment are rolled back
+  await chargePaymentProvider(payment);
+
+  return [order, payment];
+}, {
+  maxWait: 5000,   // max time to acquire a connection
+  timeout: 10000,  // max transaction duration
+});
+```
+
+For simple batch writes, use the array form:
+
+```typescript
+await prisma.$transaction([
+  prisma.user.update({ where: { id }, data: { credits: { decrement: 10 } } }),
+  prisma.auditLog.create({ data: { action: 'credit_deduction', userId: id } }),
+]);
+```
+
+### 4. Raw Queries for Complex Operations
+
+When Prisma's query builder can't express what you need.
+
+```typescript
+// Upsert with conflict handling
+await prisma.$executeRaw`
+  INSERT INTO usage (user_id, month, api_calls)
+  VALUES (${userId}, ${month}, 1)
+  ON CONFLICT (user_id, month)
+  DO UPDATE SET api_calls = usage.api_calls + 1
+`;
+
+// Complex aggregate
+const stats = await prisma.$queryRaw<{ day: Date; count: bigint }[]>`
+  SELECT date_trunc('day', created_at) AS day, COUNT(*) AS count
+  FROM orders
+  WHERE created_at > ${startDate}
+  GROUP BY day
+  ORDER BY day
+`;
+
+// Note: $queryRaw returns bigint for COUNT — convert to Number if safe
+```
+
+Always use tagged template literals (not string concatenation) for SQL injection
+protection.
+
+### 5. Migrations Workflow
+
+```bash
+# Development: create and apply migration
+npx prisma migrate dev --name add_user_profile
+
+# Production: apply pending migrations (no interactive prompts)
+npx prisma migrate deploy
+
+# Reset dev database (drops all data)
+npx prisma migrate reset
+
+# Generate client after schema changes
+npx prisma generate
+```
+
+Name migrations descriptively: `add_user_profile`, `make_email_unique`,
+`add_order_status_index`.
+
+### 6. Seeding
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient();
+
+async function main() {
+  await prisma.user.upsert({
+    where: { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email: 'admin@example.com',
+      name: 'Admin',
+      role: 'ADMIN',
+    },
+  });
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect());
+```
+
+Use `upsert` in seeds so they're idempotent — safe to run multiple times.
+
+### 7. Soft Deletes with Middleware
+
+```typescript
+// Middleware approach
+prisma.$use(async (params, next) => {
+  if (params.model === 'Post') {
+    if (params.action === 'delete') {
+      params.action = 'update';
+      params.args.data = { deletedAt: new Date() };
+    }
+    if (params.action === 'findMany') {
+      params.args.where = { ...params.args.where, deletedAt: null };
+    }
+  }
+  return next(params);
+});
+```
+
+For new projects, prefer Prisma Client Extensions over middleware:
+
+```typescript
+const xprisma = prisma.$extends({
+  query: {
+    post: {
+      async delete({ args, query }) {
+        return prisma.post.update({
+          ...args,
+          data: { deletedAt: new Date() },
+        });
+      },
+    },
+  },
+});
+```
+
+### 8. Indexes for Performance
+
+```prisma
+model Order {
+  id        String   @id @default(cuid())
+  userId    String
+  status    String
+  createdAt DateTime @default(now())
+
+  @@index([userId, status])      // composite for filtered user queries
+  @@index([createdAt(sort: Desc)]) // sorted listing
+}
+```
+
+## Checklist
+
+- [ ] Every relation has explicit `onDelete` behavior
+- [ ] List queries use `select` instead of `include` when possible
+- [ ] Multi-step mutations use `$transaction` with appropriate timeouts
+- [ ] Raw queries use tagged template literals, never string concatenation
+- [ ] Migrations have descriptive names matching the change
+- [ ] Seed script is idempotent (uses `upsert`)
+- [ ] Composite indexes exist for common query patterns (check with `EXPLAIN`)
+- [ ] `prisma generate` runs in CI after schema changes
+- [ ] Soft deletes are implemented via client extension, not scattered `where` clauses

package/assets/skills/prompt-engineering.md

@@ -0,0 +1,193 @@
+---
+name: prompt-engineering
+description: Write effective LLM prompts with system instructions, few-shot examples, chain of thought, structured output, and guardrails.
+---
+
+# Prompt Engineering
+
+## When to Use
+
+Apply when building any LLM-powered feature — chatbots, code generation,
+classification, extraction, summarization, or tool-using agents. Good prompts
+are the difference between a demo and a product.
+
+## How It Works
+
+### 1. System Prompts
+
+Set identity, constraints, and output format upfront. Be explicit about what
+the model should and should not do.
+
+```typescript
+const systemPrompt = `You are a senior code reviewer for a TypeScript monorepo.
+
+Rules:
+- Focus on bugs, security issues, and performance problems
+- Ignore style preferences already handled by ESLint
+- Rate severity as critical/high/medium/low
+- If the code is correct, say "LGTM" with no further commentary
+- Never suggest adding comments to obvious code
+
+Output format: JSON array of { file, line, severity, issue, suggestion }`;
+```
+
+Key principles: put the most important instructions first, use imperative
+language, define the output schema explicitly, and state what to do when
+edge cases arise.
+
+### 2. Few-Shot Examples
+
+Show the model exactly what you want with 2-5 input/output pairs.
+
+```typescript
+const messages = [
+  { role: 'system', content: 'Extract structured data from invoice text.' },
+  { role: 'user', content: 'Invoice #1042 from Acme Corp, dated Jan 15 2025, total $3,450.00' },
+  { role: 'assistant', content: JSON.stringify({
+    number: '1042', vendor: 'Acme Corp',
+    date: '2025-01-15', total: 3450.00, currency: 'USD'
+  })},
+  { role: 'user', content: 'Inv 2087 - TechFlow Solutions, 2025-03-22, EUR 12,800' },
+  { role: 'assistant', content: JSON.stringify({
+    number: '2087', vendor: 'TechFlow Solutions',
+    date: '2025-03-22', total: 12800.00, currency: 'EUR'
+  })},
+  { role: 'user', content: actualInvoiceText },
+];
+```
+
+Choose diverse examples that cover edge cases. Order matters — put the most
+representative example last, closest to the actual input.
+
+### 3. Chain of Thought
+
+Force step-by-step reasoning for complex tasks. The model is more accurate
+when it shows its work.
+
+```typescript
+const prompt = `Analyze this error log and determine the root cause.
+
+Think step by step:
+1. Identify the first error in the chain (not symptoms)
+2. Check timestamps to establish the sequence
+3. Look for resource exhaustion or dependency failures
+4. State the root cause in one sentence
+5. Suggest a fix
+
+Error log:
+${errorLog}`;
+```
+
+For classification tasks, use "think step by step, then give your final answer
+on the last line as: ANSWER: <category>". This makes parsing reliable while
+keeping reasoning quality.
+
+### 4. Structured Output
+
+Use JSON mode or tool calls to guarantee parseable output.
+
+```typescript
+// OpenAI JSON mode
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  response_format: { type: 'json_object' },
+  messages: [{ role: 'system', content: 'Respond in JSON with keys: summary, sentiment, topics[]' }],
+});
+
+// Anthropic tool-use for structured output
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  tools: [{
+    name: 'extract_data',
+    description: 'Extract structured fields from text',
+    input_schema: {
+      type: 'object',
+      properties: {
+        sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+        topics: { type: 'array', items: { type: 'string' } },
+        confidence: { type: 'number', minimum: 0, maximum: 1 },
+      },
+      required: ['sentiment', 'topics', 'confidence'],
+    },
+  }],
+  tool_choice: { type: 'tool', name: 'extract_data' },
+  messages,
+});
+```
+
+### 5. Tool Use / Function Calling
+
+Give the model access to real capabilities instead of asking it to generate
+code or URLs.
+
+```typescript
+const tools = [
+  {
+    name: 'search_docs',
+    description: 'Search internal documentation. Use when the user asks about product features or policies.',
+    input_schema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search query, 3-10 words' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'create_ticket',
+    description: 'Create a support ticket. Only use after confirming the issue with the user.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+        priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
+      },
+      required: ['title', 'priority'],
+    },
+  },
+];
+```
+
+Write tool descriptions that say when to use (and when NOT to use) each tool.
+
+### 6. Guardrails
+
+Prevent harmful, off-topic, or low-quality outputs.
+
+```typescript
+// Input guardrail — reject prompt injection attempts
+const inputCheck = await classify(userInput, ['benign', 'injection', 'off_topic']);
+if (inputCheck !== 'benign') return { error: 'Request not supported' };
+
+// Output guardrail — validate before returning to user
+const output = await generateResponse(userInput);
+const validation = zodSchema.safeParse(JSON.parse(output));
+if (!validation.success) {
+  // Retry once with validation errors in the prompt
+  return await generateResponse(userInput + `\nFix these errors: ${validation.error}`);
+}
+
+// Topic guardrail in system prompt
+// "You are a cooking assistant. If the user asks about anything unrelated
+//  to cooking, respond: 'I can only help with cooking questions.'"
+```
+
+## Examples
+
+| Problem | Technique | Result |
+|---------|-----------|--------|
+| Model gives rambling answers | System prompt with strict output format | Consistent, parseable JSON |
+| Classification accuracy is 70% | Add 5 few-shot examples covering edge cases | Accuracy jumps to 92% |
+| Math reasoning fails | Chain-of-thought prompting | Step-by-step catches arithmetic errors |
+| Users ask off-topic questions | System prompt + input classifier guardrail | Graceful refusal, no hallucination |
+| Output format varies randomly | Tool use / function calling | Guaranteed schema compliance |
+
+## Checklist
+
+- [ ] System prompt defines role, constraints, output format, and edge case behavior
+- [ ] Few-shot examples cover the most important edge cases (not just happy path)
+- [ ] Complex reasoning tasks use chain-of-thought prompting
+- [ ] Output is structured via JSON mode, tool use, or explicit schema in prompt
+- [ ] Input validation catches injection attempts and off-topic queries
+- [ ] Output validation parses and checks the response before returning to users
+- [ ] Temperature is set intentionally (0 for deterministic, 0.7+ for creative)
+- [ ] Prompts are version-controlled alongside the code that uses them
+- [ ] Prompt changes are evaluated against a test set, not just eyeballed

package/assets/skills/pwa-patterns.md

@@ -0,0 +1,247 @@
+---
+name: pwa-patterns
+description: Build Progressive Web Apps — service workers, offline support, push notifications, install prompts, and caching strategies.
+---
+
+# Progressive Web App Patterns
+
+## When to Use
+
+Build a PWA when your web app needs to work offline, send push notifications,
+or provide an app-like experience without an app store. PWAs are especially
+valuable for mobile-first apps, field tools used in low-connectivity areas,
+and content apps that benefit from offline reading. This skill covers service
+workers, caching strategies, push notifications, and install prompts.
+
+## How It Works
+
+### 1. Web App Manifest
+
+```json
+{
+  "name": "MyApp",
+  "short_name": "MyApp",
+  "description": "Your productivity companion",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#0066ff",
+  "orientation": "portrait-primary",
+  "icons": [
+    { "src": "/icons/192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icons/512.png", "sizes": "512x512", "type": "image/png" },
+    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ],
+  "screenshots": [
+    { "src": "/screenshots/mobile.png", "sizes": "390x844", "type": "image/png", "form_factor": "narrow" },
+    { "src": "/screenshots/desktop.png", "sizes": "1280x720", "type": "image/png", "form_factor": "wide" }
+  ]
+}
+```
+
+### 2. Service Worker Registration
+
+```typescript
+// app.ts — register on load
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', async () => {
+    try {
+      const reg = await navigator.serviceWorker.register('/sw.js', { scope: '/' });
+      console.log('SW registered:', reg.scope);
+
+      // Check for updates every 30 minutes
+      setInterval(() => reg.update(), 30 * 60 * 1000);
+    } catch (err) {
+      console.error('SW registration failed:', err);
+    }
+  });
+}
+```
+
+### 3. Caching Strategies
+
+```typescript
+// sw.js — Workbox-style manual implementation
+const CACHE_NAME = 'v1';
+const STATIC_ASSETS = ['/', '/offline.html', '/styles.css', '/app.js'];
+
+// Cache-First — for static assets (fonts, images, CSS)
+async function cacheFirst(request: Request): Promise<Response> {
+  const cached = await caches.match(request);
+  if (cached) return cached;
+
+  const response = await fetch(request);
+  if (response.ok) {
+    const cache = await caches.open(CACHE_NAME);
+    cache.put(request, response.clone());
+  }
+  return response;
+}
+
+// Network-First — for API data and HTML pages
+async function networkFirst(request: Request): Promise<Response> {
+  try {
+    const response = await fetch(request);
+    if (response.ok) {
+      const cache = await caches.open(CACHE_NAME);
+      cache.put(request, response.clone());
+    }
+    return response;
+  } catch {
+    const cached = await caches.match(request);
+    return cached ?? caches.match('/offline.html') as Promise<Response>;
+  }
+}
+
+// Stale-While-Revalidate — for data that can be slightly stale
+async function staleWhileRevalidate(request: Request): Promise<Response> {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(request);
+
+  const fetchPromise = fetch(request).then((response) => {
+    if (response.ok) cache.put(request, response.clone());
+    return response;
+  });
+
+  return cached ?? fetchPromise;
+}
+
+// Route requests to strategies
+self.addEventListener('fetch', (event: FetchEvent) => {
+  const url = new URL(event.request.url);
+
+  if (STATIC_ASSETS.includes(url.pathname)) {
+    event.respondWith(cacheFirst(event.request));
+  } else if (url.pathname.startsWith('/api/')) {
+    event.respondWith(networkFirst(event.request));
+  } else {
+    event.respondWith(staleWhileRevalidate(event.request));
+  }
+});
+```
+
+### 4. Push Notifications
+
+```typescript
+// Client — subscribe to push
+async function subscribeToPush(): Promise<PushSubscription> {
+  const registration = await navigator.serviceWorker.ready;
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,  // required — must show a notification
+    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
+  });
+
+  // Send subscription to server
+  await fetch('/api/push/subscribe', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(subscription),
+  });
+
+  return subscription;
+}
+
+// Server — send push (using web-push library)
+import webpush from 'web-push';
+
+webpush.setVapidDetails('mailto:admin@myapp.com', VAPID_PUBLIC, VAPID_PRIVATE);
+
+async function sendPush(subscription: PushSubscription, payload: object) {
+  await webpush.sendNotification(subscription, JSON.stringify(payload));
+}
+
+// Service worker — handle push event
+self.addEventListener('push', (event: PushEvent) => {
+  const data = event.data?.json() ?? { title: 'New notification' };
+  event.waitUntil(
+    self.registration.showNotification(data.title, {
+      body: data.body,
+      icon: '/icons/192.png',
+      badge: '/icons/badge-72.png',
+      data: { url: data.url },
+    })
+  );
+});
+
+self.addEventListener('notificationclick', (event: NotificationEvent) => {
+  event.notification.close();
+  event.waitUntil(clients.openWindow(event.notification.data.url));
+});
+```
+
+### 5. Install Prompt
+
+```typescript
+let deferredPrompt: BeforeInstallPromptEvent | null = null;
+
+window.addEventListener('beforeinstallprompt', (e) => {
+  e.preventDefault(); // Suppress browser default prompt
+  deferredPrompt = e;
+  showInstallBanner(); // Show your custom UI
+});
+
+async function handleInstallClick() {
+  if (!deferredPrompt) return;
+  deferredPrompt.prompt();
+  const { outcome } = await deferredPrompt.userChoice;
+  console.log(`Install prompt outcome: ${outcome}`);
+  deferredPrompt = null;
+  hideInstallBanner();
+}
+
+// Detect if already installed
+window.addEventListener('appinstalled', () => {
+  hideInstallBanner();
+  analytics.track('pwa_installed');
+});
+```
+
+### 6. Offline Data Sync
+
+```typescript
+// Queue failed requests for retry when online
+const pendingRequests: Array<{ url: string; options: RequestInit }> = [];
+
+async function fetchWithOfflineQueue(url: string, options: RequestInit) {
+  try {
+    return await fetch(url, options);
+  } catch {
+    pendingRequests.push({ url, options });
+    saveToIndexedDB('pending-requests', pendingRequests);
+    throw new Error('Queued for offline sync');
+  }
+}
+
+// Sync when back online
+window.addEventListener('online', async () => {
+  const pending = await loadFromIndexedDB('pending-requests');
+  for (const req of pending) {
+    try {
+      await fetch(req.url, req.options);
+    } catch {
+      // Still offline or failed — keep in queue
+    }
+  }
+});
+```
+
+## Examples
+
+| Strategy | Assets | Behavior |
+|----------|--------|----------|
+| Cache-First | Fonts, icons, CSS, JS | Fast load, update in background |
+| Network-First | HTML pages, API data | Fresh data, offline fallback |
+| Stale-While-Revalidate | User content, feeds | Instant display, background refresh |
+
+## Checklist
+
+- [ ] Web app manifest with name, icons (192 + 512 + maskable), and display mode
+- [ ] Service worker registered with update checks
+- [ ] Static assets use Cache-First strategy
+- [ ] API/data routes use Network-First with offline fallback
+- [ ] Offline page displayed when network is unavailable
+- [ ] Push notification subscription sent to server with VAPID keys
+- [ ] Install prompt deferred and shown at appropriate moment
+- [ ] Cache versioning and old cache cleanup on service worker activate
+- [ ] Lighthouse PWA audit passes all checks
+- [ ] Failed mutations queued for retry when connection returns