opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/cache-reserve/gotchas.md

@@ -0,0 +1,203 @@
+# Cache Reserve Gotchas
+
+## Common Issues and Solutions
+
+### Issue: Assets Not Being Cached in Cache Reserve
+
+**Diagnostics:**
+
+```typescript
+const debugEligibility = {
+  checks: [
+    'Verify asset is cacheable (cf-cache-status header)',
+    'Check TTL >= 10 hours',
+    'Confirm Content-Length header present',
+    'Review Cache Rules configuration',
+    'Check for Set-Cookie or Vary: * headers'
+  ],
+  
+  tools: [
+    'curl -I https://example.com/asset.jpg',
+    'Check cf-cache-status header',
+    'Review Cloudflare Trace output',
+    'Check Logpush CacheReserveUsed field'
+  ]
+};
+```
+
+**Solutions:**
+
+```typescript
+// 1. Ensure minimum TTL (10+ hours)
+response.headers.set('Cache-Control', 'public, max-age=36000');
+
+// Or via Cache Rule:
+const rule = {
+  action_parameters: {
+    edge_ttl: { mode: 'override_origin', default: 36000 }
+  }
+};
+
+// 2. Add Content-Length
+response.headers.set('Content-Length', bodySize.toString());
+
+// 3. Remove blocking headers
+response.headers.delete('Set-Cookie');
+response.headers.set('Vary', 'Accept-Encoding'); // Not *
+```
+
+### Issue: High Class A Operations Costs
+
+**Cause**: Frequent cache misses, short TTLs, or frequent revalidation
+
+**Solutions:**
+
+```typescript
+// 1. Increase TTL for stable content
+const optimizedTTL = {
+  before: 3600,  // 1 hour (not eligible)
+  after: 86400   // 24 hours (eligible + fewer rewrites)
+};
+
+// 2. Enable Tiered Cache (reduces direct Cache Reserve misses)
+
+// 3. Use stale-while-revalidate (via fetch, not cache.put)
+response.headers.set(
+  'Cache-Control',
+  'public, max-age=86400, stale-while-revalidate=86400'
+);
+```
+
+### Issue: Purge Not Working as Expected
+
+**Understanding purge behavior:**
+
+```typescript
+const purgeBehavior = {
+  byURL: {
+    cacheReserve: 'Immediately removed',
+    edgeCache: 'Immediately removed',
+    cost: 'Free'
+  },
+  
+  byTag: {
+    cacheReserve: 'Revalidation triggered, NOT removed',
+    edgeCache: 'Immediately removed',
+    storage: 'Continues until TTL expires',
+    cost: 'Storage costs continue'
+  }
+};
+
+// Solution: Use purge by URL for immediate removal
+await purgeByURL(['https://example.com/asset.jpg']);
+
+// Or: Disable + clear for complete removal
+await disableCacheReserve(zoneId, token);
+await clearAllCacheReserve(zoneId, token);
+```
+
+### Issue: Cache Reserve Disabled But Can't Clear
+
+**Error**: "Cache Reserve must be OFF before clearing data"
+
+**Solution:**
+
+```typescript
+const clearProcess = async (zoneId: string, token: string) => {
+  // Step 1: Check current state
+  const status = await getCacheReserveStatus(zoneId, token);
+  
+  // Step 2: Disable if enabled
+  if (status.result.value !== 'off') {
+    await disableCacheReserve(zoneId, token);
+  }
+  
+  // Step 3: Wait briefly for propagation
+  await new Promise(resolve => setTimeout(resolve, 5000));
+  
+  // Step 4: Clear data
+  const clearResult = await clearAllCacheReserve(zoneId, token);
+  
+  // Step 5: Monitor clear progress (can take up to 24 hours)
+  let clearStatus;
+  do {
+    await new Promise(resolve => setTimeout(resolve, 60000));
+    clearStatus = await getClearStatus(zoneId, token);
+  } while (clearStatus.result.state === 'In-progress');
+};
+```
+
+## Troubleshooting
+
+### Diagnostic Commands
+
+```bash
+# Check Cache Reserve status
+curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN" | jq
+
+# Check asset cache status
+curl -I https://example.com/asset.jpg | grep -i cache
+```
+
+### Common Header Patterns
+
+```typescript
+// Successful: HIT + max-age >= 36000 + content-length present
+// Not eligible: TTL < 10hrs | missing content-length | has set-cookie | vary: *
+```
+
+## Limits
+
+### Minimum Requirements Checklist
+
+- [ ] Paid Cache Reserve plan active
+- [ ] Tiered Cache enabled (strongly recommended)
+- [ ] Assets cacheable per standard rules
+- [ ] TTL >= 10 hours (36000 seconds)
+- [ ] Content-Length header present
+- [ ] No Set-Cookie header (or using private directive)
+- [ ] No Vary: * header
+- [ ] Not an image transformation variant
+
+### Key Limits
+
+```typescript
+const limits = {
+  minTTL: 36000,              // 10 hours in seconds
+  retentionDefault: 2592000,  // 30 days in seconds
+  maxFileSize: Infinity,      // Same as R2 limits
+  purgeClearTime: 86400000,   // Up to 24 hours in milliseconds
+};
+```
+
+### API Endpoints
+
+```typescript
+const endpoints = {
+  status: 'GET /zones/:zone_id/cache/cache_reserve',
+  enable: 'PATCH /zones/:zone_id/cache/cache_reserve',
+  disable: 'PATCH /zones/:zone_id/cache/cache_reserve',
+  clear: 'POST /zones/:zone_id/cache/cache_reserve_clear',
+  clearStatus: 'GET /zones/:zone_id/cache/cache_reserve_clear',
+  purge: 'POST /zones/:zone_id/purge_cache',
+  cacheRules: 'PUT /zones/:zone_id/rulesets/phases/http_request_cache_settings/entrypoint'
+};
+```
+
+## Additional Resources
+
+- **Official Docs**: https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/
+- **API Reference**: https://developers.cloudflare.com/api/resources/cache/subresources/cache_reserve/
+- **Cache Rules**: https://developers.cloudflare.com/cache/how-to/cache-rules/
+- **Workers Cache API**: https://developers.cloudflare.com/workers/runtime-apis/cache/
+- **R2 Documentation**: https://developers.cloudflare.com/r2/
+- **Smart Shield**: https://developers.cloudflare.com/smart-shield/
+- **Tiered Cache**: https://developers.cloudflare.com/cache/how-to/tiered-cache/
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [API Reference](./api.md) - Purging and monitoring
+- [Patterns](./patterns.md) - Best practices and optimization

package/dist/template/.opencode/skill/cloudflare/references/cache-reserve/patterns.md

@@ -0,0 +1,180 @@
+# Cache Reserve Patterns
+
+## Best Practices
+
+### 1. Always Enable Tiered Cache
+
+```typescript
+// Cache Reserve is designed for use WITH Tiered Cache
+const configuration = {
+  tieredCache: 'enabled',    // Required for optimal performance
+  cacheReserve: 'enabled',   // Works best with Tiered Cache
+  
+  hierarchy: [
+    'Lower-Tier Cache (visitor)',
+    'Upper-Tier Cache (origin region)',
+    'Cache Reserve (persistent)',
+    'Origin'
+  ]
+};
+```
+
+### 2. Set Appropriate Cache-Control Headers
+
+```typescript
+// Origin response headers for Cache Reserve eligibility
+const originHeaders = {
+  'Cache-Control': 'public, max-age=86400', // 24 hours minimum 10 hours
+  'Content-Length': '1024000', // Required for eligibility
+  'Cache-Tag': 'images,product-123', // Optional: For purging
+  'ETag': '"abc123"', // Optional: Support revalidation
+  'Last-Modified': 'Wed, 21 Oct 2025 07:28:00 GMT',
+  
+  // Avoid: Prevents caching
+  // 'Set-Cookie': 'session=xyz',  // Remove or use private directive
+  // 'Vary': '*',                  // Not compatible
+};
+```
+
+### 3. Use Cache Rules for Fine-Grained Control
+
+```typescript
+// Different TTLs for different content types
+const cacheRules = [
+  {
+    description: 'Long-term cache for immutable assets',
+    expression: '(http.request.uri.path matches "^/static/.*\\.[a-f0-9]{8}\\.")',
+    action_parameters: {
+      cache_reserve: { eligible: true },
+      edge_ttl: { mode: 'override_origin', default: 2592000 }, // 30 days
+      cache: true
+    }
+  },
+  {
+    description: 'Moderate cache for regular images',
+    expression: '(http.request.uri.path matches "\\.(jpg|png|webp)$")',
+    action_parameters: {
+      cache_reserve: { eligible: true },
+      edge_ttl: { mode: 'override_origin', default: 86400 }, // 24 hours
+      cache: true
+    }
+  },
+  {
+    description: 'Exclude API from Cache Reserve',
+    expression: '(http.request.uri.path matches "^/api/")',
+    action_parameters: { cache_reserve: { eligible: false }, cache: false }
+  }
+];
+```
+
+### 4. Ensuring Cache Reserve Eligibility in Workers
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await fetch(request);
+    
+    if (response.ok) {
+      const headers = new Headers(response.headers);
+      
+      // Set minimum 10-hour cache
+      headers.set('Cache-Control', 'public, max-age=36000');
+      
+      // Remove Set-Cookie if present (prevents caching)
+      headers.delete('Set-Cookie');
+      
+      // Ensure Content-Length is present
+      if (!headers.has('Content-Length')) {
+        const blob = await response.blob();
+        headers.set('Content-Length', blob.size.toString());
+        
+        return new Response(blob, {
+          status: response.status,
+          statusText: response.statusText,
+          headers
+        });
+      }
+      
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+      });
+    }
+    
+    return response;
+  }
+};
+```
+
+### 5. Hostname Best Practices
+
+```typescript
+// ✅ CORRECT: Use Worker's hostname for efficient caching
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return await fetch(request); // Keep the Worker's hostname
+  }
+};
+
+// ❌ WRONG: Overriding hostname causes unnecessary DNS lookups
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    url.hostname = 'different-host.com'; // Avoid this!
+    return await fetch(url.toString());
+  }
+};
+```
+
+## Architecture Patterns
+
+### Multi-Tier Caching + Immutable Assets
+
+```typescript
+// Optimal: L1 (visitor) → L2 (region) → L3 (Cache Reserve) → Origin
+// Each miss backfills all upstream layers
+
+// Immutable asset optimization with content hashing
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const isImmutable = /\.[a-f0-9]{8,}\.(js|css|jpg|png|woff2)$/.test(url.pathname);
+    
+    const response = await fetch(request);
+    
+    if (isImmutable) {
+      const headers = new Headers(response.headers);
+      headers.set('Cache-Control', 'public, max-age=31536000, immutable'); // 1 year
+      return new Response(response.body, { status: response.status, headers });
+    }
+    
+    return response;
+  }
+};
+```
+
+## Cost Optimization
+
+```typescript
+// Typical savings: 50-80% reduction in origin egress
+// Origin cost (AWS: $0.09/GB) vs Cache Reserve ($0.015/GB-month + $0.36/M reads)
+
+// 1. Set appropriate TTLs
+const optimizeTTL = {
+  tooShort: 3600,    // 1 hour - not eligible
+  optimal: 86400,    // 24 hours - reduces rewrites
+  tooLong: 2592000   // 30 days - use cautiously
+};
+
+// 2. Cache high-value, stable assets: images, media, fonts, archives
+// 3. Exclude frequently changing: /api/, user-specific, JSON data
+// 4. Note: Cache Reserve requests uncompressed from origin, compresses for visitors
+```
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [API Reference](./api.md) - Purging and monitoring
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting

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

@@ -0,0 +1,16 @@
+# Cloudflare Containers Skill Reference
+
+**APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers**
+
+Use when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patter...
+
+## 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/containers/api.md

@@ -0,0 +1,43 @@
+### HTTP Requests
+
+**Default port (recommended):**
+```typescript
+// Uses defaultPort from Container class
+const container = env.MY_CONTAINER.getByName("id");
+const response = await container.fetch(request);
+```
+
+**Specific port:**
+```typescript
+const port = this.ctx.container.getTcpPort(8080);
+const response = await port.fetch("http://container/api", {
+  method: "POST",
+  body: JSON.stringify(data)
+});
+```
+
+### TCP Connections
+
+```typescript
+const port = this.ctx.container.getTcpPort(8080);
+const conn = port.connect('10.0.0.1:8080');
+await conn.opened;
+
+try {
+  if (request.body) {
+    await request.body.pipeTo(conn.writable);
+  }
+  return new Response(conn.readable);
+} catch (err) {
+  return new Response("Failed to proxy", { status: 502 });
+}
+```
+
+### WebSocket Forwarding
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const upgradeHeader = request.headers.get("Upgrade");
+    if (upgradeHeader === "websocket") {
+      const container = env.MY_CONTAINER.g

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

@@ -0,0 +1,56 @@
+## Wrangler Configuration
+
+### Basic Container Config
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-10",
+  "containers": [
+    {
+      "class_name": "MyContainer",
+      "image": "./Dockerfile",  // or path to directory with Dockerfile
+      "max_instances": 10
+    }
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "MY_CONTAINER",
+        "class_name": "MyContainer"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["MyContainer"]  // Must use new_sqlite_classes
+    }
+  ]
+}
+```
+
+### TOML Format
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2026-01-10"
+
+[[containers]]
+class_name = "MyContainer"
+image = "./Dockerfile"
+max_instances = 10
+
+[[durable_objects.bindings]]
+name = "MY_CONTAINER"
+class_name = "MyContainer"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyContainer"]
+```
+
+Key config requirements:
+- `image` - Path to Dockerfile or directory conta

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

@@ -0,0 +1,21 @@
+## Best Practices
+
+1. **Use `@cloudflare/containers` package** - Cleaner API than raw Durable Object methods
+
+2. **Set appropriate `sleepAfter`** - Balance resource usage vs cold start latency
+   - Short-lived jobs: "5m"
+   - Session-based: "30m" - "2h"
+   - Long-running services: "2h" or longer
+
+3. **Choose routing pattern based on use case:**
+   - Stateless services → `getRandom()` load balancing
+   - Stateful sessions → `getByName()` with session/user ID
+   - Short-lived jobs → Unique IDs with explicit lifecycle control
+
+4. **Pass secrets securely:**
+   - Use Worker Secrets or Secret Store, not hard-coded values
+   - Read KV/secrets asynchronously when starting containers
+   - Don't log sensitive environment variables
+
+5. **Design for container restarts:**
+   - Containers can stop after

package/dist/template/.opencode/skill/cloudflare/references/containers/patterns.md

@@ -0,0 +1,40 @@
+## Common Use Cases
+
+### Stateful Backend (Session-based)
+
+```typescript
+import { Container } from "@cloudflare/containers";
+
+export class SessionBackend extends Container {
+  defaultPort = 3000;
+  sleepAfter = "30m";
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const { sessionId } = await request.json();
+    // Each session gets dedicated container instance
+    const container = env.SESSION_BACKEND.getByName(sessionId);
+    return container.fetch(request);
+  }
+}
+```
+
+### Short-Lived Code Execution
+
+```typescript
+export class CodeSandbox extends Container {
+  defaultPort = 8080;
+  sleepAfter = "5m";  // Quick cleanup
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const { code, executionId } = await request.json();
+    
+    const container = env.CODE_SANDBOX.getByName(executionId);
+    await container.startAndWaitForPorts({
+      startOptions: {
+        envVars: {
+          USER_CODE: Buffer.from(code).toString('base64'),
+          TIMEOUT: "3

package/dist/template/.opencode/skill/cloudflare/references/cron-triggers/README.md

@@ -0,0 +1,85 @@
+# Cloudflare Cron Triggers
+
+Schedule Workers execution using cron expressions. Runs on Cloudflare's global network during underutilized periods.
+
+## Key Features
+
+- **UTC-only execution** - All schedules run on UTC time
+- **5-field cron syntax** - Quartz scheduler extensions (L, W, #)
+- **Global propagation** - 15min deployment delay
+- **At-least-once delivery** - Rare duplicate executions possible
+- **Workflow integration** - Trigger long-running multi-step tasks
+
+## Cron Syntax
+
+```
+ ┌─────────── minute (0-59)
+ │ ┌───────── hour (0-23)
+ │ │ ┌─────── day of month (1-31)
+ │ │ │ ┌───── month (1-12, JAN-DEC)
+ │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday)
+ * * * * *
+```
+
+**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)
+
+## Common Schedules
+
+```bash
+*/5 * * * *        # Every 5 minutes
+0 * * * *          # Hourly
+0 2 * * *          # Daily 2am UTC (off-peak)
+0 9 * * MON-FRI    # Weekdays 9am UTC
+0 0 1 * *          # Monthly 1st midnight UTC
+0 9 L * *          # Last day of month 9am UTC
+0 10 * * MON#2     # 2nd Monday 10am UTC
+*/10 9-17 * * MON-FRI  # Every 10min, 9am-5pm weekdays
+```
+
+## Quick Start
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["*/5 * * * *", "0 2 * * *"]
+  }
+}
+```
+
+**Handler:**
+```typescript
+export default {
+  async scheduled(
+    controller: ScheduledController,
+    env: Env,
+    ctx: ExecutionContext,
+  ): Promise<void> {
+    console.log("Cron:", controller.cron);
+    console.log("Time:", new Date(controller.scheduledTime));
+    
+    ctx.waitUntil(asyncTask(env)); // Non-blocking
+  },
+};
+```
+
+**Test locally:**
+```bash
+npx wrangler dev
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+```
+
+## Limits
+
+- **Free:** 3 triggers/worker, 10ms CPU
+- **Paid:** Unlimited triggers, 50ms CPU
+- **Propagation:** 15min global deployment
+- **Timezone:** UTC only
+
+## See Also
+
+- [configuration.md](./configuration.md) - wrangler config, env-specific schedules
+- [api.md](./api.md) - ScheduledController, handler params
+- [patterns.md](./patterns.md) - Use cases, batch processing, monitoring
+- [gotchas.md](./gotchas.md) - Timezone issues, debugging, limits