opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/smart-placement/README.md

@@ -0,0 +1,91 @@
+# Cloudflare Workers Smart Placement
+
+Automatic workload placement optimization to minimize latency by running Workers closer to backend infrastructure rather than end users.
+
+## Core Concept
+
+Smart Placement automatically analyzes Worker request duration across Cloudflare's global network and intelligently routes requests to optimal data center locations. Instead of defaulting to the location closest to the end user, Smart Placement can forward requests to locations closer to backend infrastructure when this reduces overall request duration.
+
+### When to Use
+
+**Enable Smart Placement when:**
+- Worker makes multiple round trips to backend services/databases
+- Backend infrastructure is geographically concentrated
+- Request duration dominated by backend latency rather than network latency from user
+- Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)
+
+**Do NOT enable for:**
+- Workers serving only static content or cached responses
+- Workers without significant backend communication
+- Pure edge logic (auth checks, redirects, simple transformations)
+- Workers without fetch event handlers
+
+### Key Architecture Pattern
+
+**Recommended:** Split full-stack applications into separate Workers:
+```
+User → Frontend Worker (at edge, close to user)
+         ↓ Service Binding
+       Backend Worker (Smart Placement enabled, close to DB/API)
+         ↓
+       Database/Backend Service
+```
+
+This maintains fast, reactive frontends while optimizing backend latency.
+
+## Quick Start
+
+```toml
+# wrangler.toml
+[placement]
+mode = "smart"
+hint = "wnam"  # Optional: West North America
+```
+
+Deploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.
+
+## Requirements
+
+- Wrangler 2.20.0+
+- Analysis time: Up to 15 minutes after enabling
+- Traffic requirements: Consistent traffic from multiple global locations
+- Available on all Workers plans (Free, Paid, Enterprise)
+
+## Placement Status Values
+
+```typescript
+type PlacementStatus = 
+  | undefined  // Not yet analyzed
+  | 'SUCCESS'  // Successfully optimized
+  | 'INSUFFICIENT_INVOCATIONS'  // Not enough traffic
+  | 'UNSUPPORTED_APPLICATION';  // Made Worker slower (reverted)
+```
+
+## CLI Commands
+
+```bash
+# Deploy with Smart Placement
+wrangler deploy
+
+# Check placement status
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
+  | jq .result.placement_status
+
+# Monitor
+wrangler tail your-worker-name --header cf-placement
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.toml setup, placement hints, dashboard config
+- [api.md](./api.md) - Placement Status API, cf-placement header, monitoring
+- [patterns.md](./patterns.md) - Frontend/backend split, database workers, SSR patterns
+- [gotchas.md](./gotchas.md) - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handlers
+- [d1](../d1/) - D1 database that benefits from Smart Placement
+- [durable-objects](../durable-objects/) - Durable Objects with backend logic
+- [bindings](../bindings/) - Service bindings for frontend/backend split

package/dist/template/.opencode/skill/cloudflare/references/smart-placement/api.md

@@ -0,0 +1,139 @@
+# Smart Placement API
+
+## Placement Status API
+
+Query Worker placement status via Cloudflare API:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME}" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json"
+```
+
+Response includes `placement_status` field:
+
+```typescript
+type PlacementStatus = 
+  | undefined  // Not yet analyzed
+  | 'SUCCESS'  // Successfully optimized
+  | 'INSUFFICIENT_INVOCATIONS'  // Not enough traffic
+  | 'UNSUPPORTED_APPLICATION';  // Made Worker slower (reverted)
+```
+
+## Status Meanings
+
+**`undefined` (not present)**
+- Worker not yet analyzed
+- Always runs at default edge location closest to user
+
+**`SUCCESS`**
+- Analysis complete, Smart Placement active
+- Worker runs in optimal location (may be edge or remote)
+
+**`INSUFFICIENT_INVOCATIONS`**
+- Not enough requests to make placement decision
+- Requires consistent multi-region traffic
+- Always runs at default edge location
+
+**`UNSUPPORTED_APPLICATION`** (rare, <1% of Workers)
+- Smart Placement made Worker slower
+- Placement decision reverted
+- Always runs at edge location
+- Won't be re-analyzed until redeployed
+
+## cf-placement Header (Beta)
+
+Smart Placement adds response header indicating routing decision:
+
+```typescript
+// Remote placement (Smart Placement routed request)
+"cf-placement: remote-LHR"  // Routed to London
+
+// Local placement (default edge routing)  
+"cf-placement: local-EWR"   // Stayed at Newark edge
+```
+
+Format: `{placement-type}-{IATA-code}`
+- `remote-*` = Smart Placement routed to remote location
+- `local-*` = Stayed at default edge location
+- IATA code = nearest airport to data center
+
+**Warning:** Beta feature, may be removed before GA.
+
+## Detecting Smart Placement in Code
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const placementHeader = request.headers.get('cf-placement');
+    
+    if (placementHeader?.startsWith('remote-')) {
+      const location = placementHeader.split('-')[1];
+      console.log(`Smart Placement routed to ${location}`);
+    } else if (placementHeader?.startsWith('local-')) {
+      const location = placementHeader.split('-')[1];
+      console.log(`Running at edge location ${location}`);
+    }
+    
+    return new Response('OK');
+  }
+};
+```
+
+## Request Duration Metrics
+
+Available in Cloudflare dashboard when Smart Placement enabled:
+
+**Workers & Pages → [Your Worker] → Metrics → Request Duration**
+
+Shows histogram comparing:
+- Request duration WITH Smart Placement (99% of traffic)
+- Request duration WITHOUT Smart Placement (1% baseline)
+
+**Request Duration vs Execution Duration:**
+- **Request duration:** Total time from request arrival to response delivery (includes network latency)
+- **Execution duration:** Time Worker code actively executing (excludes network waits)
+
+Use request duration to measure Smart Placement impact.
+
+## Monitoring Commands
+
+```bash
+# Tail Worker logs
+wrangler tail your-worker-name
+
+# Tail with filters
+wrangler tail your-worker-name --status error
+wrangler tail your-worker-name --header cf-placement
+
+# Check placement status via API
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
+  | jq .result.placement_status
+```
+
+## TypeScript Types
+
+```typescript
+type PlacementStatus = 
+  | 'SUCCESS'
+  | 'INSUFFICIENT_INVOCATIONS'
+  | 'UNSUPPORTED_APPLICATION'
+  | undefined;
+
+interface WorkerMetadata {
+  placement_mode?: 'smart';
+  placement_status?: PlacementStatus;
+}
+
+interface Env {
+  BACKEND_SERVICE: Fetcher;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await env.BACKEND_SERVICE.fetch(request);
+    return response;
+  }
+} satisfies ExportedHandler<Env>;
+```

package/dist/template/.opencode/skill/cloudflare/references/smart-placement/configuration.md

@@ -0,0 +1,129 @@
+# Smart Placement Configuration
+
+## wrangler.toml Setup
+
+```toml
+# Basic Smart Placement
+[placement]
+mode = "smart"
+
+# With placement hint (preferred region)
+[placement]
+mode = "smart"
+hint = "wnam"  # West North America
+```
+
+## wrangler.json/wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "placement": {
+    "mode": "smart",
+    "hint": "wnam"  // Optional region hint
+  }
+}
+```
+
+## Placement Mode Values
+
+- `"smart"` - Enable Smart Placement optimization
+- Not specified - Default behavior (run at edge closest to user)
+
+## Placement Hints
+
+Optional region hints guide Smart Placement decisions:
+- `"wnam"` - West North America
+- `"enam"` - East North America  
+- `"weur"` - Western Europe
+- `"eeur"` - Eastern Europe
+- `"apac"` - Asia Pacific
+
+**Note:** Hints are suggestions, not guarantees. Smart Placement makes final decision based on performance data.
+
+## Frontend + Backend Split Configuration
+
+### Frontend Worker (No Smart Placement)
+
+```toml
+# frontend-worker/wrangler.toml
+name = "frontend"
+main = "frontend-worker.ts"
+
+# No [placement] - runs at edge
+
+[[services]]
+binding = "BACKEND"
+service = "backend-api"
+```
+
+### Backend Worker (Smart Placement Enabled)
+
+```toml
+# backend-api/wrangler.toml
+name = "backend-api"
+main = "backend-worker.ts"
+
+[placement]
+mode = "smart"
+
+[[d1_databases]]
+binding = "DATABASE"
+database_id = "xxx"
+```
+
+## Requirements & Limitations
+
+### Requirements
+- **Wrangler version:** 2.20.0+
+- **Analysis time:** Up to 15 minutes
+- **Traffic requirements:** Consistent multi-location traffic
+- **Workers plan:** All plans (Free, Paid, Enterprise)
+
+### What Smart Placement Affects
+- ✅ **Affects:** `fetch` event handlers only
+- ❌ **Does NOT affect:** RPC methods, named entrypoints, Workers without fetch handlers
+
+### Baseline Traffic
+Smart Placement automatically routes 1% of requests WITHOUT optimization as baseline for performance comparison.
+
+## Dashboard Configuration
+
+**Enable via Dashboard:**
+1. Navigate to **Workers & Pages** in Cloudflare dashboard
+2. Select your Worker
+3. Go to **Settings** → **General**
+4. Under **Placement**, select **Smart**
+5. Wait 15 minutes for analysis
+6. Check **Metrics** tab for request duration charts
+
+## TypeScript Environment Types
+
+```typescript
+interface Env {
+  // Backend Worker binding (Smart Placement enabled)
+  BACKEND: Fetcher;
+  DATABASE: D1Database;
+  CACHE: KVNamespace;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
+    return Response.json(data);
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Local Development
+
+```bash
+# Smart Placement does NOT affect local development
+wrangler dev
+
+# Local dev always runs in single location
+# Test Smart Placement by deploying to staging
+wrangler deploy --env staging
+```
+
+Smart Placement only activates in production deployments.

package/dist/template/.opencode/skill/cloudflare/references/smart-placement/gotchas.md

@@ -0,0 +1,87 @@
+# Smart Placement Gotchas
+
+## "INSUFFICIENT_INVOCATIONS" Status
+
+**Problem:** Not enough traffic for Smart Placement to analyze.
+
+**Solutions:**
+- Ensure Worker receives consistent global traffic
+- Wait longer (analysis takes up to 15 minutes)
+- Send test traffic from multiple global locations
+- Check Worker has fetch event handler
+
+## Smart Placement Making Things Slower
+
+**Problem:** `placement_status: "UNSUPPORTED_APPLICATION"`
+
+**Likely Causes:**
+- Worker doesn't make backend calls (runs faster at edge)
+- Backend calls are cached (network latency to user more important)
+- Backend service has poor global distribution
+
+**Solutions:**
+- Disable Smart Placement for this Worker
+- Review whether Worker actually benefits from Smart Placement
+- Consider caching strategy to reduce backend calls
+
+## No Request Duration Metrics
+
+**Problem:** Request duration chart not showing in dashboard.
+
+**Solutions:**
+- Ensure Smart Placement enabled in config
+- Wait 15+ minutes after deployment
+- Verify Worker has sufficient traffic
+- Check `placement_status` is `SUCCESS`
+
+## cf-placement Header Missing
+
+**Problem:** Header not present in responses.
+
+**Possible Causes:**
+- Smart Placement not enabled
+- Beta feature removed (check latest docs)
+- Worker hasn't been analyzed yet
+
+## Monolithic Full-Stack Worker
+
+**Problem:** Frontend and backend logic in single Worker with Smart Placement enabled.
+
+**Impact:** Smart Placement optimizes for backend latency but hurts frontend response time to users.
+
+**Solution:** Split into two Workers:
+- Frontend Worker (no Smart Placement) - runs at edge
+- Backend Worker (Smart Placement) - runs near database
+
+## Local Development Confusion
+
+**Issue:** Smart Placement doesn't work in `wrangler dev`.
+
+**Explanation:** Smart Placement only activates in production deployments, not local development.
+
+**Solution:** Test Smart Placement in staging environment: `wrangler deploy --env staging`
+
+## Baseline 1% Traffic
+
+**Note:** Smart Placement automatically routes 1% of requests WITHOUT optimization for performance comparison. This is expected behavior.
+
+## Analysis Time
+
+**Issue:** Smart Placement takes up to 15 minutes after enabling to complete analysis.
+
+**Impact:** During analysis, Worker runs at default edge location. Be patient and monitor `placement_status`.
+
+## Requirements
+
+- **Wrangler 2.20.0+** required
+- **Consistent multi-region traffic** needed for analysis
+- **Only affects fetch handlers** - RPC methods and named entrypoints not affected
+
+## When NOT to Use
+
+- Workers serving only static content or cached responses
+- Workers without significant backend communication
+- Pure edge logic (auth checks, redirects, simple transformations)
+- Workers without fetch event handlers
+
+These scenarios won't benefit and may perform worse with Smart Placement.

package/dist/template/.opencode/skill/cloudflare/references/smart-placement/patterns.md

@@ -0,0 +1,135 @@
+# Smart Placement Patterns
+
+## Backend Worker with Database Access
+
+```typescript
+// Smart Placement runs close to database - multiple round trips benefit
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const user = await env.DATABASE.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+    const orders = await env.DATABASE.prepare('SELECT * FROM orders WHERE user_id = ?').bind(userId).all();
+    return Response.json({ user, orders });
+  }
+};
+```
+
+```toml
+name = "backend-api"; [placement]; mode = "smart"; [[d1_databases]]; binding = "DATABASE"
+```
+
+## Frontend + Backend Split
+
+**Frontend (no Smart Placement):** Runs at edge for fast user response
+**Backend (Smart Placement):** Runs close to database
+
+```typescript
+// Frontend - forwards API requests to backend
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (new URL(request.url).pathname.startsWith('/api/')) return env.BACKEND.fetch(request);
+    return env.ASSETS.fetch(request);
+  }
+};
+
+// Backend - database operations
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return Response.json(await env.DATABASE.prepare('SELECT * FROM table').all());
+  }
+};
+```
+
+## External API Integration
+
+```typescript
+// Smart Placement runs closer to external API - multiple calls benefit
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiUrl = 'https://api.partner.com';
+    const headers = { 'Authorization': `Bearer ${env.API_KEY}` };
+    const [profile, transactions] = await Promise.all([
+      fetch(`${apiUrl}/profile`, { headers }),
+      fetch(`${apiUrl}/transactions`, { headers })
+    ]);
+    return Response.json({ profile: await profile.json(), transactions: await transactions.json() });
+  }
+};
+```
+
+```toml
+[placement]; mode = "smart"; hint = "enam"  # If API in East North America
+```
+
+## Multi-Service Aggregation
+
+```typescript
+// Aggregates data from multiple services in same region
+export default {
+  async fetch(request: Request, env: Env) {
+    const [orders, inventory, shipping] = await Promise.all([
+      fetch('https://orders.internal.api'), fetch('https://inventory.internal.api'), fetch('https://shipping.internal.api')
+    ]);
+    return Response.json({ orders: await orders.json(), inventory: await inventory.json(), shipping: await shipping.json() });
+  }
+};
+```
+
+## SSR with Backend Data
+
+```typescript
+// Frontend SSR (edge) - render close to user
+export default {
+  async fetch(request: Request, env: Env) {
+    const data = await env.BACKEND.fetch('/api/page-data');
+    return new Response(renderPage(await data.json()), { headers: { 'Content-Type': 'text/html' } });
+  }
+};
+
+// Backend (Smart Placement) - fetch data close to database
+export default {
+  async fetch(request: Request, env: Env) {
+    return Response.json(await env.DATABASE.prepare('SELECT * FROM pages WHERE id = ?').bind(pageId).first());
+  }
+};
+```
+
+## API Gateway
+
+```typescript
+// Gateway at edge - quick auth, forward to backend
+export default {
+  async fetch(request: Request, env: Env) {
+    if (!request.headers.get('Authorization')) return new Response('Unauthorized', { status: 401 });
+    return env.BACKEND_API.fetch(request);
+  }
+};
+
+// Backend with Smart Placement - heavy DB operations
+export default {
+  async fetch(request: Request, env: Env) {
+    return Response.json(await performDatabaseOperations(env.DATABASE));
+  }
+};
+```
+
+## Best Practices
+
+1. **Split Full-Stack Apps:** Frontend at edge, backend with Smart Placement
+2. **Use Service Bindings:** Connect frontend/backend Workers efficiently
+3. **Monitor Request Duration:** Compare before/after metrics
+4. **Enable for Backend Logic:** APIs, data aggregation, server-side processing
+5. **Don't Enable for Pure Edge:** Auth, redirects, static content
+6. **Test Before Production:** Deploy to staging, verify metrics
+7. **Consider Placement Hints:** Guide Smart Placement if you know backend location
+8. **Wait for Analysis:** 15+ minutes after enabling
+9. **Check Placement Status:** Verify `SUCCESS` via API
+10. **Combine with Caching:** Cache frequently accessed data
+
+## Anti-Patterns
+
+❌ **Enabling on static content Workers**
+❌ **Monolithic full-stack Worker with Smart Placement** (hurts frontend performance)
+❌ **Not monitoring placement status** after deploy
+
+✅ **Split architecture:** Frontend (edge) + Backend (Smart Placement)
+✅ **Verify status** via API and metrics

package/dist/template/.opencode/skill/cloudflare/references/snippets/README.md

@@ -0,0 +1,15 @@
+# Cloudflare Snippets Skill Reference
+
+## Description
+Expert guidance for **Cloudflare Snippets ONLY** - a lightweight JavaScript-based edge logic platform for modifying HTTP requests and responses. Snippets run as part of the Ruleset Engine and are included at no additional cost on paid plans (Pro, Business, Enterprise)....
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, deployment, configuration
+- **[api.md](./api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](./patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/)

package/dist/template/.opencode/skill/cloudflare/references/snippets/api.md

@@ -0,0 +1,47 @@
+### HTTP Methods
+```javascript
+request.method // GET, POST, PUT, DELETE, etc.
+```
+
+### Response Constructors
+```javascript
+// Plain text
+new Response("Hello", { status: 200 })
+
+// JSON
+Response.json({ key: "value" })
+
+// HTML
+new Response("<h1>Hi</h1>", { 
+  headers: { "Content-Type": "text/html" }
+})
+
+// Redirect
+Response.redirect("https://example.com", 301)
+```
+
+### Header Operations
+```javascript
+// Request headers
+request.headers.get("X-Header")
+request.headers.has("X-Header")
+request.headers.set("X-Header", "value")
+request.headers.delete("X-Header")
+
+// Response headers (must clone first)
+const res = new Response(response.body, response);
+res.headers.set("X-Header", "value")
+res.headers.append("Set-Cookie", "value")
+res.headers.delete("X-Header")
+```
+
+### URL Operations
+```javascript
+const url = new URL(request.url);
+url.hostname    // "example.com"
+url.pathname    // "/path/to/page"
+url.search      // "?query=value"
+url.searchParams.get("query") // "value"
+```
+
+### Cloudflare Pr

package/dist/template/.opencode/skill/cloudflare/references/snippets/configuration.md

@@ -0,0 +1,33 @@
+## Configuration Methods
+
+### 1. Dashboard (GUI)
+```
+1. Go to zone → Rules → Snippets
+2. Create Snippet or select template
+3. Enter snippet name (a-z, 0-9, _ only, cannot change later)
+4. Write JavaScript code (32KB max)
+5. Configure snippet rule:
+   - Expression Builder or Expression Editor
+   - Use Ruleset Engine filter expressions
+6. Deploy or Save as Draft
+```
+
+### 2. API
+```bash
+# Create/update snippet
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
+  --request PUT \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --form "files=@example.js" \
+  --form "metadata={\"main_module\": \"example.js\"}"
+
+# Create snippet rule
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/snippet_rules" \
+  --request PUT \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --json '{
+    "rules": [
+      {
+        "description": "Trigger snippet on specific cookie",
+        "enabled": true,
+        "expression": "http.cookie eq 

package/dist/template/.opencode/skill/cloudflare/references/snippets/gotchas.md

@@ -0,0 +1,21 @@
+## Best Practices
+
+### Performance
+1. **Keep code minimal**: 32KB limit, but aim for <10KB
+2. **Avoid blocking operations**: 5ms execution limit
+3. **Clone only when needed**: `new Request(request)` creates copy
+4. **Cache strategically**: Use `caches.default` for repeated data
+5. **Limit subrequests**: Plan-based limits (2-5)
+
+### Security
+1. **Validate input**: Never trust user data
+2. **Use Web Crypto API**: For cryptographic operations
+3. **Sanitize headers**: Remove sensitive information
+4. **Check bot scores**: Use `request.cf.botManagement.score`
+5. **Rate limit carefully**: Snippets run on every matching request
+
+### Debugging
+1. **Test in dashboard**: Use HTTP/Preview tabs
+2. **Start simple**: Test with basic logic first
+3. **Use custom headers**: Add debug headers to responses
+4.