claudeguide-engineer 1.14.8

package/.claude/skills/devops/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: devops
+description: Deploy and manage cloud infrastructure on Cloudflare (Workers, R2, D1, KV, Pages, Durable Objects, Browser Rendering), Docker containers, and Google Cloud Platform (Compute Engine, GKE, Cloud Run, App Engine, Cloud Storage). Use when deploying serverless functions to the edge, configuring edge computing solutions, managing Docker containers and images, setting up CI/CD pipelines, optimizing cloud infrastructure costs, implementing global caching strategies, working with cloud databases, or building cloud-native applications.
+license: MIT
+version: 1.0.0
+---
+
+# DevOps Skill
+
+Comprehensive guide for deploying and managing cloud infrastructure across Cloudflare edge platform, Docker containerization, and Google Cloud Platform.
+
+## When to Use This Skill
+
+Use this skill when:
+- Deploying serverless applications to Cloudflare Workers
+- Containerizing applications with Docker
+- Managing Google Cloud infrastructure with gcloud CLI
+- Setting up CI/CD pipelines across platforms
+- Optimizing cloud infrastructure costs
+- Implementing multi-region deployments
+- Building edge-first architectures
+- Managing container orchestration with Kubernetes
+- Configuring cloud storage solutions (R2, Cloud Storage)
+- Automating infrastructure with scripts and IaC
+
+## Platform Selection Guide
+
+### When to Use Cloudflare
+
+**Best For:**
+- Edge-first applications with global distribution
+- Ultra-low latency requirements (<50ms)
+- Static sites with serverless functions
+- Zero egress cost scenarios (R2 storage)
+- WebSocket/real-time applications (Durable Objects)
+- AI/ML at the edge (Workers AI)
+
+**Key Products:**
+- Workers (serverless functions)
+- R2 (object storage, S3-compatible)
+- D1 (SQLite database with global replication)
+- KV (key-value store)
+- Pages (static hosting + functions)
+- Durable Objects (stateful compute)
+- Browser Rendering (headless browser automation)
+
+**Cost Profile:** Pay-per-request, generous free tier, zero egress fees
+
+### When to Use Docker
+
+**Best For:**
+- Local development consistency
+- Microservices architectures
+- Multi-language stack applications
+- Traditional VPS/VM deployments
+- Kubernetes orchestration
+- CI/CD build environments
+- Database containerization (dev/test)
+
+**Key Capabilities:**
+- Application isolation and portability
+- Multi-stage builds for optimization
+- Docker Compose for multi-container apps
+- Volume management for data persistence
+- Network configuration and service discovery
+- Cross-platform compatibility (amd64, arm64)
+
+**Cost Profile:** Infrastructure cost only (compute + storage)
+
+### When to Use Google Cloud
+
+**Best For:**
+- Enterprise-scale applications
+- Data analytics and ML pipelines (BigQuery, Vertex AI)
+- Hybrid/multi-cloud deployments
+- Kubernetes at scale (GKE)
+- Managed databases (Cloud SQL, Firestore, Spanner)
+- Complex IAM and compliance requirements
+
+**Key Services:**
+- Compute Engine (VMs)
+- GKE (managed Kubernetes)
+- Cloud Run (containerized serverless)
+- App Engine (PaaS)
+- Cloud Storage (object storage)
+- Cloud SQL (managed databases)
+
+**Cost Profile:** Varied pricing, sustained use discounts, committed use contracts
+
+## Quick Start
+
+### Cloudflare Workers
+
+```bash
+# Install Wrangler CLI
+npm install -g wrangler
+
+# Create and deploy Worker
+wrangler init my-worker
+cd my-worker
+wrangler deploy
+```
+
+See: `references/cloudflare-workers-basics.md`
+
+### Docker Container
+
+```bash
+# Create Dockerfile
+cat > Dockerfile <<EOF
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+EOF
+
+# Build and run
+docker build -t myapp .
+docker run -p 3000:3000 myapp
+```
+
+See: `references/docker-basics.md`
+
+### Google Cloud Deployment
+
+```bash
+# Install and authenticate
+curl https://sdk.cloud.google.com | bash
+gcloud init
+gcloud auth login
+
+# Deploy to Cloud Run
+gcloud run deploy my-service \
+  --image gcr.io/project/image \
+  --region us-central1
+```
+
+See: `references/gcloud-platform.md`
+
+## Reference Navigation
+
+### Cloudflare Platform
+- `cloudflare-platform.md` - Edge computing overview, key components
+- `cloudflare-workers-basics.md` - Getting started, handler types, basic patterns
+- `cloudflare-workers-advanced.md` - Advanced patterns, performance, optimization
+- `cloudflare-workers-apis.md` - Runtime APIs, bindings, integrations
+- `cloudflare-r2-storage.md` - R2 object storage, S3 compatibility, best practices
+- `cloudflare-d1-kv.md` - D1 SQLite database, KV store, use cases
+- `browser-rendering.md` - Puppeteer/Playwright automation on Cloudflare
+
+### Docker Containerization
+- `docker-basics.md` - Core concepts, Dockerfile, images, containers
+- `docker-compose.md` - Multi-container apps, networking, volumes
+
+### Google Cloud Platform
+- `gcloud-platform.md` - GCP overview, gcloud CLI, authentication
+- `gcloud-services.md` - Compute Engine, GKE, Cloud Run, App Engine
+
+### Python Utilities
+- `scripts/cloudflare-deploy.py` - Automate Cloudflare Worker deployments
+- `scripts/docker-optimize.py` - Analyze and optimize Dockerfiles
+
+## Common Workflows
+
+### Edge + Container Hybrid
+
+```yaml
+# Cloudflare Workers (API Gateway)
+# -> Docker containers on Cloud Run (Backend Services)
+# -> R2 (Object Storage)
+
+# Benefits:
+# - Edge caching and routing
+# - Containerized business logic
+# - Global distribution
+```
+
+### Multi-Stage Docker Build
+
+```dockerfile
+# Build stage
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node
+CMD ["node", "dist/server.js"]
+```
+
+### CI/CD Pipeline Pattern
+
+```yaml
+# 1. Build: Docker multi-stage build
+# 2. Test: Run tests in container
+# 3. Push: Push to registry (GCR, Docker Hub)
+# 4. Deploy: Deploy to Cloudflare Workers / Cloud Run
+# 5. Verify: Health checks and smoke tests
+```
+
+## Best Practices
+
+### Security
+- Run containers as non-root user
+- Use service account impersonation (GCP)
+- Store secrets in environment variables, not code
+- Scan images for vulnerabilities (Docker Scout)
+- Use API tokens with minimal permissions
+
+### Performance
+- Multi-stage Docker builds to reduce image size
+- Edge caching with Cloudflare KV
+- Use R2 for zero egress cost storage
+- Implement health checks for containers
+- Set appropriate timeouts and resource limits
+
+### Cost Optimization
+- Use Cloudflare R2 instead of S3 for large egress
+- Implement caching strategies (edge + KV)
+- Right-size container resources
+- Use sustained use discounts (GCP)
+- Monitor usage with cloud provider dashboards
+
+### Development
+- Use Docker Compose for local development
+- Wrangler dev for local Worker testing
+- Named gcloud configurations for multi-environment
+- Version control infrastructure code
+- Implement automated testing in CI/CD
+
+## Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| Sub-50ms latency globally | Cloudflare Workers |
+| Large file storage (zero egress) | Cloudflare R2 |
+| SQL database (global reads) | Cloudflare D1 |
+| Containerized workloads | Docker + Cloud Run/GKE |
+| Enterprise Kubernetes | GKE |
+| Managed relational DB | Cloud SQL |
+| Static site + API | Cloudflare Pages |
+| WebSocket/real-time | Cloudflare Durable Objects |
+| ML/AI pipelines | GCP Vertex AI |
+| Browser automation | Cloudflare Browser Rendering |
+
+## Resources
+
+- **Cloudflare Docs:** https://developers.cloudflare.com
+- **Docker Docs:** https://docs.docker.com
+- **GCP Docs:** https://cloud.google.com/docs
+- **Wrangler CLI:** https://developers.cloudflare.com/workers/wrangler/
+- **gcloud CLI:** https://cloud.google.com/sdk/gcloud
+
+## Implementation Checklist
+
+### Cloudflare Workers
+- [ ] Install Wrangler CLI
+- [ ] Create Worker project
+- [ ] Configure wrangler.toml (bindings, routes)
+- [ ] Test locally with `wrangler dev`
+- [ ] Deploy with `wrangler deploy`
+
+### Docker
+- [ ] Write Dockerfile with multi-stage builds
+- [ ] Create .dockerignore file
+- [ ] Test build locally
+- [ ] Push to registry
+- [ ] Deploy to target platform
+
+### Google Cloud
+- [ ] Install gcloud CLI
+- [ ] Authenticate with service account
+- [ ] Create project and enable APIs
+- [ ] Configure IAM permissions
+- [ ] Deploy and monitor resources

package/.claude/skills/devops/references/browser-rendering.md

@@ -0,0 +1,305 @@
+# Cloudflare Browser Rendering
+
+Headless browser automation with Puppeteer/Playwright on Cloudflare Workers.
+
+## Setup
+
+**wrangler.toml:**
+```toml
+name = "browser-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+browser = { binding = "MYBROWSER" }
+```
+
+## Basic Screenshot Worker
+
+```typescript
+import puppeteer from '@cloudflare/puppeteer';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    const page = await browser.newPage();
+
+    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
+    const screenshot = await page.screenshot({ type: 'png' });
+
+    await browser.close();
+
+    return new Response(screenshot, {
+      headers: { 'Content-Type': 'image/png' }
+    });
+  }
+};
+```
+
+## Session Reuse (Cost Optimization)
+
+```typescript
+// Disconnect instead of close
+await browser.disconnect();
+
+// Retrieve and reconnect
+const sessions = await puppeteer.sessions(env.MYBROWSER);
+const freeSession = sessions.find(s => !s.connectionId);
+
+if (freeSession) {
+  const browser = await puppeteer.connect(env.MYBROWSER, freeSession.sessionId);
+}
+```
+
+## PDF Generation
+
+```typescript
+const browser = await puppeteer.launch(env.MYBROWSER);
+const page = await browser.newPage();
+
+await page.setContent(`
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <style>
+        body { font-family: Arial; padding: 50px; }
+        h1 { color: #2c3e50; }
+      </style>
+    </head>
+    <body>
+      <h1>Certificate</h1>
+      <p>Awarded to: <strong>John Doe</strong></p>
+    </body>
+  </html>
+`);
+
+const pdf = await page.pdf({
+  format: 'A4',
+  printBackground: true,
+  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' }
+});
+
+await browser.close();
+
+return new Response(pdf, {
+  headers: { 'Content-Type': 'application/pdf' }
+});
+```
+
+## Durable Objects for Persistent Sessions
+
+```typescript
+export class Browser {
+  state: DurableObjectState;
+  browser: any;
+  lastUsed: number;
+
+  constructor(state: DurableObjectState, env: Env) {
+    this.state = state;
+    this.lastUsed = Date.now();
+  }
+
+  async fetch(request: Request, env: Env) {
+    if (!this.browser) {
+      this.browser = await puppeteer.launch(env.MYBROWSER);
+    }
+
+    this.lastUsed = Date.now();
+    await this.state.storage.setAlarm(Date.now() + 10000);
+
+    const page = await this.browser.newPage();
+    const url = new URL(request.url).searchParams.get('url');
+    await page.goto(url);
+    const screenshot = await page.screenshot();
+    await page.close();
+
+    return new Response(screenshot, {
+      headers: { 'Content-Type': 'image/png' }
+    });
+  }
+
+  async alarm() {
+    if (Date.now() - this.lastUsed > 60000) {
+      await this.browser?.close();
+      this.browser = null;
+    } else {
+      await this.state.storage.setAlarm(Date.now() + 10000);
+    }
+  }
+}
+```
+
+## AI-Powered Web Scraper
+
+```typescript
+import { Ai } from '@cloudflare/ai';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    const page = await browser.newPage();
+    await page.goto('https://news.ycombinator.com');
+    const content = await page.content();
+    await browser.close();
+
+    const ai = new Ai(env.AI);
+    const response = await ai.run('@cf/meta/llama-3-8b-instruct', {
+      messages: [
+        {
+          role: 'system',
+          content: 'Extract top 5 article titles and URLs as JSON'
+        },
+        { role: 'user', content: content }
+      ]
+    });
+
+    return Response.json(response);
+  }
+};
+```
+
+## Crawler with Queues
+
+```typescript
+export default {
+  async queue(batch: MessageBatch<any>, env: Env): Promise<void> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+
+    for (const message of batch.messages) {
+      const page = await browser.newPage();
+      await page.goto(message.body.url);
+
+      const links = await page.evaluate(() => {
+        return Array.from(document.querySelectorAll('a')).map(a => a.href);
+      });
+
+      for (const link of links) {
+        await env.QUEUE.send({ url: link });
+      }
+
+      await page.close();
+      message.ack();
+    }
+
+    await browser.close();
+  }
+};
+```
+
+## Configuration
+
+### Timeout
+```typescript
+await page.goto(url, {
+  timeout: 60000,  // 60 seconds max
+  waitUntil: 'networkidle2'
+});
+
+await page.waitForSelector('.content', { timeout: 45000 });
+```
+
+### Viewport
+```typescript
+await page.setViewport({ width: 1920, height: 1080 });
+```
+
+### Screenshot Options
+```typescript
+const screenshot = await page.screenshot({
+  type: 'png',       // 'png' | 'jpeg' | 'webp'
+  quality: 90,       // JPEG/WebP only
+  fullPage: true,    // Full scrollable page
+  clip: {            // Crop
+    x: 0, y: 0,
+    width: 800,
+    height: 600
+  }
+});
+```
+
+## Limits & Pricing
+
+### Free Plan
+- 10 minutes/day
+- 3 concurrent browsers
+- 3 new browsers/minute
+
+### Paid Plan
+- 10 hours/month included
+- 30 concurrent browsers
+- 30 new browsers/minute
+- $0.09/hour overage
+- $2.00/concurrent browser overage
+
+### Cost Optimization
+1. Use `disconnect()` instead of `close()`
+2. Enable Keep-Alive (10 min max)
+3. Pool tabs with browser contexts
+4. Cache auth state with KV
+5. Implement Durable Objects cleanup
+
+## Best Practices
+
+### Session Management
+- Always use `disconnect()` for reuse
+- Implement session pooling
+- Track session IDs and states
+
+### Performance
+- Cache content in KV
+- Use browser contexts vs multiple browsers
+- Choose appropriate `waitUntil` strategy
+- Set realistic timeouts
+
+### Error Handling
+- Handle timeout errors gracefully
+- Check session availability before connecting
+- Validate responses before caching
+
+### Security
+- Validate user-provided URLs
+- Implement authentication
+- Sanitize extracted content
+- Set appropriate CORS headers
+
+## Troubleshooting
+
+**Timeout Errors:**
+```typescript
+await page.goto(url, {
+  timeout: 60000,
+  waitUntil: 'domcontentloaded'  // Faster than networkidle2
+});
+```
+
+**Memory Issues:**
+```typescript
+await page.close();  // Close pages
+await browser.disconnect();  // Reuse session
+```
+
+**Font Rendering:**
+Use supported fonts (Noto Sans, Roboto, etc.) or inject custom:
+```html
+<link href="https://fonts.googleapis.com/css2?family=Poppins" rel="stylesheet">
+```
+
+## Key Methods
+
+### Puppeteer
+- `puppeteer.launch(binding)` - Start browser
+- `puppeteer.connect(binding, sessionId)` - Reconnect
+- `puppeteer.sessions(binding)` - List sessions
+- `browser.newPage()` - Create page
+- `browser.disconnect()` - Disconnect (keep alive)
+- `browser.close()` - Close (terminate)
+- `page.goto(url, options)` - Navigate
+- `page.screenshot(options)` - Capture
+- `page.pdf(options)` - Generate PDF
+- `page.content()` - Get HTML
+- `page.evaluate(fn)` - Execute JS
+
+## Resources
+
+- Docs: https://developers.cloudflare.com/browser-rendering/
+- Puppeteer: https://pptr.dev/
+- Examples: https://developers.cloudflare.com/workers/examples/

package/.claude/skills/devops/references/cloudflare-d1-kv.md

@@ -0,0 +1,123 @@
+# Cloudflare D1 & KV
+
+## D1 (SQLite Database)
+
+### Setup
+```bash
+# Create database
+wrangler d1 create my-database
+
+# Add to wrangler.toml
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "YOUR_DATABASE_ID"
+
+# Apply schema
+wrangler d1 execute my-database --file=./schema.sql
+```
+
+### Usage
+
+```typescript
+// Query
+const result = await env.DB.prepare(
+  "SELECT * FROM users WHERE id = ?"
+).bind(userId).first();
+
+// Insert
+await env.DB.prepare(
+  "INSERT INTO users (name, email) VALUES (?, ?)"
+).bind("Alice", "alice@example.com").run();
+
+// Batch (atomic)
+await env.DB.batch([
+  env.DB.prepare("UPDATE accounts SET balance = balance - 100 WHERE id = ?").bind(user1),
+  env.DB.prepare("UPDATE accounts SET balance = balance + 100 WHERE id = ?").bind(user2)
+]);
+
+// All results
+const { results } = await env.DB.prepare("SELECT * FROM users").all();
+```
+
+### Features
+- Global read replication (low-latency reads)
+- Single-writer consistency
+- Standard SQLite syntax
+- 25GB database size limit
+- ACID transactions with batch
+
+## KV (Key-Value Store)
+
+### Setup
+```bash
+# Create namespace
+wrangler kv:namespace create MY_KV
+
+# Add to wrangler.toml
+[[kv_namespaces]]
+binding = "KV"
+id = "YOUR_NAMESPACE_ID"
+```
+
+### Usage
+
+```typescript
+// Put with TTL
+await env.KV.put("session:token", JSON.stringify(data), {
+  expirationTtl: 3600,
+  metadata: { userId: "123" }
+});
+
+// Get
+const value = await env.KV.get("session:token");
+const json = await env.KV.get("session:token", "json");
+const buffer = await env.KV.get("session:token", "arrayBuffer");
+const stream = await env.KV.get("session:token", "stream");
+
+// Get with metadata
+const { value, metadata } = await env.KV.getWithMetadata("session:token");
+
+// Delete
+await env.KV.delete("session:token");
+
+// List
+const list = await env.KV.list({ prefix: "user:" });
+```
+
+### Features
+- Sub-millisecond reads (edge-cached)
+- Eventual consistency (~60 seconds globally)
+- 25MB value size limit
+- Automatic expiration (TTL)
+
+## Use Cases
+
+### D1
+- Relational data
+- Complex queries with JOINs
+- ACID transactions
+- User accounts, orders, inventory
+
+### KV
+- Cache
+- Sessions
+- Feature flags
+- Rate limiting
+- Real-time counters
+
+## Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| SQL queries | D1 |
+| Sub-millisecond reads | KV |
+| ACID transactions | D1 |
+| Large values (>25MB) | R2 |
+| Strong consistency | D1 (writes), Durable Objects |
+| Automatic expiration | KV |
+
+## Resources
+
+- D1: https://developers.cloudflare.com/d1/
+- KV: https://developers.cloudflare.com/kv/