packwise-skills 1.0.0

package/sub-skills/web/pwa.md

@@ -0,0 +1,220 @@
+# Progressive Web App (PWA) Build Sub-Skill
+
+Build installable web applications that work offline and feel like native apps.
+
+**Current version**: PWA standards (2025-2026) — Service Workers, Web App Manifest, Web Push
+
+## When to Use
+
+- Need cross-platform app from single web codebase
+- Offline support required
+- Push notifications needed
+- App-like experience without app store submission
+- Budget-constrained projects (one codebase for all platforms)
+
+## Key Features
+
+| Feature | Browser Support | Notes |
+|---------|---------------|-------|
+| Service Worker | All modern browsers | Offline caching, background sync |
+| Web App Manifest | All modern browsers | Home screen install, splash screen |
+| Web Push | Chrome/Firefox/Edge/Safari 16.4+ | Push notifications on all platforms |
+| Background Sync | Chrome/Edge | Sync data when connection restored |
+| Periodic Background Sync | Chrome/Edge only | Fetch updates in background |
+| File System Access | Chrome/Edge | Read/write local files |
+| Web Share API | Chrome/Edge/Safari | Native share dialog |
+
+## PWA Essentials
+
+### 1. Web App Manifest
+
+```json
+{
+  "name": "My PWA App",
+  "short_name": "MyApp",
+  "description": "My Progressive Web App",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#000000",
+  "orientation": "portrait",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
+    { "src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ],
+  "screenshots": [
+    { "src": "/screenshots/desktop.png", "sizes": "1280x720", "form_factor": "wide" },
+    { "src": "/screenshots/mobile.png", "sizes": "390x844", "form_factor": "narrow" }
+  ],
+  "categories": ["productivity"],
+  "shortcuts": [
+    { "name": "Settings", "url": "/settings", "icons": [{ "src": "/icons/settings-96.png", "sizes": "96x96" }] }
+  ]
+}
+```
+
+```html
+<!-- index.html -->
+<link rel="manifest" href="/manifest.json">
+<meta name="theme-color" content="#000000">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+<link rel="apple-touch-icon" href="/icons/icon-192.png">
+```
+
+### 2. Service Worker
+
+```javascript
+// sw.js — Cache-first strategy for static assets
+const CACHE_NAME = 'my-app-v1';
+const STATIC_ASSETS = ['/', '/index.html', '/styles.css', '/app.js', '/icons/icon-192.png'];
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
+  );
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
+    )
+  );
+  self.clients.claim();
+});
+
+self.addEventListener('fetch', (event) => {
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      const fetched = fetch(event.request).then((response) => {
+        const clone = response.clone();
+        caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
+        return response;
+      });
+      return cached || fetched;
+    })
+  );
+});
+```
+
+```javascript
+// Register in main app
+if ('serviceWorker' in navigator) {
+  navigator.serviceWorker.register('/sw.js');
+}
+```
+
+### 3. Web Push Notifications
+
+```javascript
+// Request permission and subscribe
+const registration = await navigator.serviceWorker.ready;
+const subscription = await registration.pushManager.subscribe({
+  userVisibleOnly: true,
+  applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
+});
+// Send subscription to your backend
+await fetch('/api/subscribe', { method: 'POST', body: JSON.stringify(subscription) });
+```
+
+## Build & Test
+
+```bash
+# Vite PWA plugin (vite-plugin-pwa 1.3+ supports Vite 3-8)
+npm install vite-plugin-pwa -D
+```
+
+```javascript
+// vite.config.js
+import { VitePWA } from 'vite-plugin-pwa';
+
+export default {
+  plugins: [
+    VitePWA({
+      registerType: 'autoUpdate',
+      workbox: {
+        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
+        runtimeCaching: [
+          {
+            urlPattern: /^https:\/\/api\.example\.com\//,
+            handler: 'NetworkFirst',
+            options: { cacheName: 'api-cache', expiration: { maxEntries: 50, maxAgeSeconds: 3600 } },
+          },
+        ],
+      },
+      manifest: { /* manifest.json content */ },
+    }),
+  ],
+};
+```
+
+```bash
+# Build
+npm run build
+# Output: dist/ directory with PWA-ready files
+
+# Test locally
+npx serve dist  # Serve over HTTP for testing
+# For full PWA testing: deploy to HTTPS server
+
+# Lighthouse audit
+npx lighthouse https://myapp.com --only-categories=pwa
+```
+
+## Framework-Specific PWA
+
+### Next.js (App Router)
+
+```typescript
+// next.config.js
+const withPWA = require('next-pwa')({
+  dest: 'public',
+  register: true,
+  skipWaiting: true,
+});
+module.exports = withPWA({ /* next config */ });
+```
+
+### Vue (Vite)
+
+```javascript
+// Same as Vite config above — use vite-plugin-pwa
+```
+
+### React (Create React App / Vite)
+
+```bash
+# CRA: use `cra-template-pwa`
+npx create-react-app my-app --template pwa
+
+# Vite: use vite-plugin-pwa (recommended)
+```
+
+## PWA vs Native App
+
+| Feature | PWA | Native App |
+|---------|-----|-----------|
+| Distribution | URL (no store) | App Store / Play Store |
+| Install | Browser prompt | Store download |
+| Offline | Yes (Service Worker) | Yes |
+| Push notifications | Yes (web push) | Yes |
+| Device access | Limited (camera, GPS, file) | Full |
+| Performance | Good (WASM, Web Workers) | Best |
+| Size | No install footprint | 20MB+ |
+| Updates | Instant (on next visit) | Store review |
+| iOS support | Limited (no full PWA on Safari < 16.4) | Full |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| PWA not installable | Ensure manifest.json is correct; serve over HTTPS; check Lighthouse PWA audit |
+| Service Worker not updating | Use `skipWaiting()` + `clients.claim()`; change cache version |
+| iOS push notifications not working | Requires Safari 16.4+; use web push with VAPID keys |
+| Cache serving stale content | Use NetworkFirst for API; CacheFirst for static assets |
+| Offline page not showing | Add fallback page in service worker `fetch` handler |
+| Maskable icon looks wrong | Test with maskable.app; ensure safe zone is respected |
+| Background sync not working | Only supported in Chrome/Edge; use IndexedDB for queued operations |

package/sub-skills/web/serverless-edge.md

@@ -0,0 +1,295 @@
+# Serverless & Edge Build Sub-Skill
+
+Build and package applications for serverless platforms and edge runtimes.
+
+**Current versions**: AWS Lambda / Cloudflare Workers / Vercel Functions / Deno Deploy (2025-2026)
+
+## When to Use
+
+- Pay-per-request pricing model
+- Auto-scaling without infrastructure management
+- API backends with variable traffic
+- Edge computing (low latency globally)
+- Cron jobs / scheduled tasks
+- Webhook handlers
+
+## Platform Comparison
+
+| Platform | Language Support | Cold Start | Max Duration | Best For |
+|----------|-----------------|-----------|-------------|---------|
+| AWS Lambda | Node/Python/Go/Rust/Java/.NET | 100–500ms | 15 min | Enterprise, complex workflows |
+| Cloudflare Workers | JS/TS/WASM | < 1ms | 30s (CPU) / unlimited (I/O) | Edge compute, APIs |
+| Vercel Functions | Node/Python/Go/Ruby | 100–300ms | 60s (free) / 900s (pro) | Next.js apps, frontend APIs |
+| Deno Deploy | JS/TS | < 10ms | 50ms–60s | Lightweight APIs, edge |
+| Netlify Functions | Node/Go | 100–500ms | 10s (free) / 26s (pro) | JAMstack apps |
+| Azure Functions | Node/Python/C#/Java/PowerShell | 100–500ms | 10 min (consumption) | .NET ecosystem |
+| Google Cloud Functions | Node/Python/Go/Java/.NET/Ruby | 100–500ms | 60 min (gen2) | GCP ecosystem |
+
+---
+
+## AWS Lambda
+
+### Node.js Function
+
+```javascript
+// handler.js (Lambda Function URL or API Gateway)
+exports.handler = async (event) => {
+  const name = event.queryStringParameters?.name || 'World';
+  return {
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: `Hello, ${name}!` }),
+  };
+};
+```
+
+```bash
+# Package
+zip -r function.zip handler.js node_modules/
+
+# Deploy with AWS CLI
+aws lambda create-function \
+  --function-name my-function \
+  --runtime nodejs22.x \
+  --handler handler.handler \
+  --zip-file fileb://function.zip \
+  --role arn:aws:iam::ACCOUNT:role/lambda-role
+
+# Or with SAM (Serverless Application Model)
+sam build && sam deploy --guided
+```
+
+### Python Function
+
+```python
+# lambda_function.py
+import json
+
+def handler(event, context):
+    name = event.get('queryStringParameters', {}).get('name', 'World')
+    return {
+        'statusCode': 200,
+        'headers': {'Content-Type': 'application/json'},
+        'body': json.dumps({'message': f'Hello, {name}!'})
+    }
+```
+
+### Go Function
+
+```go
+package main
+
+import (
+    "context"
+    "github.com/aws/aws-lambda-go/events"
+    "github.com/aws/aws-lambda-go/lambda"
+)
+
+func handler(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
+    name := request.QueryStringParameters["name"]
+    if name == "" { name = "World" }
+    return events.APIGatewayProxyResponse{
+        StatusCode: 200,
+        Headers:    map[string]string{"Content-Type": "application/json"},
+        Body:       fmt.Sprintf(`{"message":"Hello, %s!"}`, name),
+    }, nil
+}
+
+func main() { lambda.Start(handler) }
+```
+
+```bash
+# Build and deploy
+GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
+zip function.zip bootstrap
+aws lambda create-function --function-name my-go-func --runtime provided.al2023 --handler bootstrap --zip-file fileb://function.zip
+```
+
+### Rust Function (Custom Runtime)
+
+```toml
+# Cargo.toml
+[dependencies]
+lambda_runtime = "0.13"
+tokio = { version = "1", features = ["macros"] }
+serde = { version = "1", features = ["derive"] }
+```
+
+```rust
+use lambda_runtime::{service_fn, LambdaEvent, Error};
+use serde_json::{json, Value};
+
+async fn handler(event: LambdaEvent<Value>) -> Result<Value, Error> {
+    let name = event.payload.get("name").and_then(|v| v.as_str()).unwrap_or("World");
+    Ok(json!({ "statusCode": 200, "body": format!("Hello, {}!", name) }))
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    lambda_runtime::run(service_fn(handler)).await
+}
+```
+
+---
+
+## Cloudflare Workers
+
+```bash
+# Create project
+npm create cloudflare@latest my-worker
+cd my-worker
+```
+
+```javascript
+// src/index.js
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    if (url.pathname === '/health') {
+      return new Response('OK', { status: 200 });
+    }
+    return new Response('Hello from the Edge!', { status: 200 });
+  },
+  // Scheduled handler (cron)
+  async scheduled(event, env, ctx) {
+    // Runs on cron schedule defined in wrangler.toml
+  },
+};
+```
+
+```toml
+# wrangler.toml
+name = "my-worker"
+main = "src/index.js"
+compatibility_date = "2025-01-01"
+
+[triggers]
+crons = ["*/5 * * * *"]  # Every 5 minutes
+
+# KV Storage
+[[kv_namespaces]]
+binding = "CACHE"
+id = "your-kv-namespace-id"
+
+# D1 Database
+[[d1_databases]]
+binding = "DB"
+database_name = "my-db"
+database_id = "your-d1-database-id"
+
+# R2 Storage (S3-compatible)
+[[r2_buckets]]
+binding = "STORAGE"
+bucket_name = "my-bucket"
+```
+
+```bash
+# Deploy
+npx wrangler deploy
+
+# Test locally
+npx wrangler dev
+```
+
+---
+
+## Vercel Functions
+
+```javascript
+// app/api/hello/route.js (Next.js App Router)
+export async function GET(request) {
+  return Response.json({ message: 'Hello from Vercel!' });
+}
+
+export async function POST(request) {
+  const body = await request.json();
+  return Response.json({ received: body });
+}
+```
+
+```bash
+# Deploy
+vercel deploy
+
+# Or: git push to connected repository (auto-deploy)
+```
+
+---
+
+## Deno Deploy
+
+```typescript
+// main.ts
+Deno.serve((req: Request) => {
+  const url = new URL(req.url);
+  if (url.pathname === "/health") {
+    return new Response("OK");
+  }
+  return new Response("Hello from Deno Deploy!");
+});
+```
+
+```bash
+# Deploy
+deployctl deploy --project=my-project main.ts
+```
+
+---
+
+## Serverless Framework (Multi-Cloud)
+
+```yaml
+# serverless.yml
+service: my-service
+frameworkVersion: '3'
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  region: us-east-1
+
+functions:
+  api:
+    handler: handler.handler
+    events:
+      - httpApi:
+          path: /{proxy+}
+          method: '*'
+      - schedule:
+          rate: rate(1 hour)
+```
+
+```bash
+npm install -g serverless
+serverless deploy
+serverless info  # Get endpoint URLs
+serverless logs -f api  # View logs
+```
+
+---
+
+## Selection Guide
+
+| Scenario | Recommended Platform | Why |
+|----------|---------------------|-----|
+| Next.js app | Vercel | First-class Next.js support |
+| Global API with low latency | Cloudflare Workers | Edge-first, < 1ms cold start |
+| Enterprise backend | AWS Lambda + API Gateway | Full AWS ecosystem |
+| .NET backend | Azure Functions | Native .NET support |
+| Cron jobs / scheduled tasks | Any (all support cron) | Pick based on existing infra |
+| AI inference at edge | Cloudflare Workers AI | GPU at the edge |
+| Simple webhook handler | Vercel/Netlify Functions | Easiest setup |
+| High-memory workloads | AWS Lambda (10GB) | Highest memory allocation |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Cold start too slow | Use provisioned concurrency (AWS); keep functions small |
+| Function timeout | Break into smaller functions; use async queues (SQS/Queues) |
+| Package too large | Use tree-shaking; exclude dev deps; use Lambda layers |
+| Environment variables not available | Set in platform dashboard; use secrets manager |
+| Database connection exhaustion | Use connection pooling (RDS Proxy, Neon, PlanetScale) |
+| CORS errors | Add CORS headers in function response |
+| Webhook replay attacks | Verify webhook signatures (Stripe, GitHub) |
+| Edge runtime limitations | No filesystem access; limited Node.js APIs; no native modules |