opencodekit 0.15.4 → 0.15.5

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

@@ -0,0 +1,264 @@
+# Cloudflare C3 (create-cloudflare) Skill
+
+Expert guidance for using C3, the official CLI tool for scaffolding Cloudflare projects.
+
+## What is C3?
+
+C3 (`create-cloudflare`) is Cloudflare's CLI for project initialization. Creates Workers, Pages, and full-stack applications with templates, TypeScript, and instant deployment.
+
+## Installation & Usage
+
+```bash
+# NPM
+npm create cloudflare@latest
+
+# Yarn
+yarn create cloudflare
+
+# PNPM
+pnpm create cloudflare@latest
+
+# With project name
+npm create cloudflare@latest my-app
+
+# With template
+npm create cloudflare@latest -- --template=cloudflare/templates/workers-template
+```
+
+## Common Templates
+
+### Workers
+
+```bash
+# Basic Worker
+npm create cloudflare@latest -- --template=worker
+
+# TypeScript Worker
+npm create cloudflare@latest -- --template=worker-typescript
+
+# Durable Objects
+npm create cloudflare@latest -- --template=hello-world-do-template
+```
+
+### Full-Stack Apps
+
+```bash
+# Next.js
+npm create cloudflare@latest -- --template=next-starter-template
+
+# React Router
+npm create cloudflare@latest -- --template=react-router-starter-template
+
+# Remix
+npm create cloudflare@latest -- --template=remix-starter-template
+
+# Astro
+npm create cloudflare@latest -- --template=astro-blog-starter-template
+```
+
+### Database & Storage
+
+```bash
+# D1 SQLite
+npm create cloudflare@latest -- --template=d1-template
+
+# R2 Explorer
+npm create cloudflare@latest -- --template=r2-explorer-template
+
+# Postgres + Hyperdrive
+npm create cloudflare@latest -- --template=postgres-hyperdrive-template
+```
+
+### AI & ML
+
+```bash
+# Workers AI Chat
+npm create cloudflare@latest -- --template=llm-chat-app-template
+
+# Text-to-Image
+npm create cloudflare@latest -- --template=text-to-image-template
+```
+
+### Real-time & Multiplayer
+
+```bash
+# Chat with Durable Objects
+npm create cloudflare@latest -- --template=durable-chat-template
+
+# Multiplayer Globe
+npm create cloudflare@latest -- --template=multiplayer-globe-template
+```
+
+## Interactive Mode
+
+```bash
+npm create cloudflare@latest my-app
+```
+
+C3 prompts for:
+1. Application type (Website/API/scheduled worker/etc.)
+2. Framework choice (if applicable)
+3. TypeScript preference
+4. Git initialization
+5. Deployment option
+
+## Non-Interactive Mode
+
+```bash
+npm create cloudflare@latest my-worker \
+  --type=web-app \
+  --framework=next \
+  --ts \
+  --git \
+  --deploy
+```
+
+### Flags
+
+- `--type` - Application type: `web-app`, `hello-world`, `pre-existing`, `remote-template`
+- `--framework` - Framework: `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, etc.
+- `--template` - GitHub template URL or path
+- `--ts` / `--no-ts` - TypeScript
+- `--git` / `--no-git` - Initialize git repo
+- `--deploy` / `--no-deploy` - Deploy after creation
+- `--open` - Open in browser after deploy
+- `--existing-script` - Path to existing Worker script
+
+## CI/CD Usage
+
+```yaml
+# GitHub Actions
+- name: Create Cloudflare Project
+  run: |
+    npm create cloudflare@latest my-app -- \
+      --type=web-app \
+      --framework=next \
+      --ts \
+      --no-git \
+      --no-deploy
+```
+
+## Custom Templates
+
+```bash
+# From GitHub repo
+npm create cloudflare@latest -- --template=user/repo
+
+# From local path
+npm create cloudflare@latest -- --template=../my-template
+
+# From Cloudflare official templates
+npm create cloudflare@latest -- --template=cloudflare/templates/workers-template
+```
+
+## Project Structure Created
+
+```
+my-app/
+├── src/
+│   └── index.ts       # Worker entry point
+├── wrangler.toml      # Configuration
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Post-Creation
+
+```bash
+cd my-app
+
+# Local development
+npm run dev
+
+# Deploy
+npm run deploy
+
+# Type check
+npm run cf-typegen
+```
+
+## wrangler.toml Configuration
+
+C3 generates:
+
+```toml
+name = "my-app"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+# Bindings added based on template
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "..."
+
+[[d1_databases]]
+binding = "DB"
+database_id = "..."
+```
+
+## Best Practices
+
+1. **Use latest C3:** `npm create cloudflare@latest`
+2. **Choose TypeScript** for type safety
+3. **Enable git** for version control
+4. **Review generated wrangler.toml** before first deploy
+5. **Update dependencies** post-creation: `npm update`
+
+## Common Workflows
+
+### Quick Worker
+
+```bash
+npm create cloudflare@latest my-worker -- --type=hello-world --ts --deploy
+```
+
+### Full-Stack App with D1
+
+```bash
+npm create cloudflare@latest my-app -- \
+  --template=react-router-starter-template \
+  --ts \
+  --git
+cd my-app
+npx wrangler d1 create my-db
+# Add to wrangler.toml, then:
+npm run deploy
+```
+
+### Convert Existing Project
+
+```bash
+cd existing-project
+npm create cloudflare@latest . -- --existing-script=./dist/index.js
+```
+
+## Troubleshooting
+
+### `npm create cloudflare failed`
+
+- Ensure Node.js 16.13+
+- Clear npm cache: `npm cache clean --force`
+- Try with `npx`: `npx create-cloudflare@latest`
+
+### Template not found
+
+- Verify template name/path
+- Check network connection
+- Use full GitHub URL: `https://github.com/user/repo`
+
+### Deployment fails
+
+- Check Cloudflare account authentication: `wrangler login`
+- Verify `wrangler.toml` configuration
+- Check for naming conflicts in dashboard
+
+## Reference
+
+- [C3 GitHub](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare)
+- [Templates Repository](https://github.com/cloudflare/templates)
+- [Workers Docs](https://developers.cloudflare.com/workers/)
+
+---
+
+This skill focuses exclusively on C3 CLI tool usage. For Workers development, see `cloudflare-workers` skill.

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

@@ -0,0 +1,93 @@
+# Cloudflare Cache Reserve
+
+**Persistent cache storage built on R2 for long-term content retention**
+
+## Overview
+
+Cache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.
+
+## Core Concepts
+
+### What is Cache Reserve?
+
+- **Persistent storage layer**: Built on R2, sits above tiered cache hierarchy
+- **Long-term retention**: 30-day default retention, extended on each access
+- **Automatic operation**: Works seamlessly with existing CDN, no code changes required
+- **Origin shielding**: Dramatically reduces origin egress by serving cached content longer
+- **Usage-based pricing**: Pay only for storage + read/write operations
+
+### Cache Hierarchy
+
+```
+Visitor Request
+    ↓
+Lower-Tier Cache (closest to visitor)
+    ↓ (on miss)
+Upper-Tier Cache (closest to origin)
+    ↓ (on miss)
+Cache Reserve (R2 persistent storage)
+    ↓ (on miss)
+Origin Server
+```
+
+### How It Works
+
+1. **On cache miss**: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously
+2. **On edge eviction**: Content may be evicted from edge cache but remains in Cache Reserve
+3. **On subsequent request**: If edge cache misses but Cache Reserve hits → content restored to edge caches
+4. **Retention**: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)
+
+## Asset Eligibility
+
+Cache Reserve only stores assets meeting **ALL** criteria:
+
+- Cacheable per Cloudflare's standard rules
+- Minimum 10-hour TTL (36000 seconds)
+- `Content-Length` header present
+- Original files only (not transformed images)
+
+### Not Eligible
+
+- Assets with TTL < 10 hours
+- Responses without `Content-Length` header
+- Image transformation variants (original images are eligible)
+- Responses with `Set-Cookie` headers
+- Responses with `Vary: *` header
+- Assets from R2 public buckets on same zone
+- O2O (Orange-to-Orange) setup requests
+
+## Quick Start
+
+```bash
+# Enable via Dashboard
+https://dash.cloudflare.com/caching/cache-reserve
+# Click "Enable Storage Sync" or "Purchase" button
+```
+
+**Prerequisites:**
+- Paid Cache Reserve plan required
+- Tiered Cache strongly recommended
+
+## Essential 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"
+
+# Enable Cache Reserve
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+
+# Check asset cache status
+curl -I https://example.com/asset.jpg | grep -i cache
+```
+
+## See Also
+
+- [Configuration](./configuration.md) - Setup, API, and Cache Rules
+- [API Reference](./api.md) - Purging, monitoring, and management APIs
+- [Patterns](./patterns.md) - Best practices and architecture patterns
+- [Gotchas](./gotchas.md) - Common issues, troubleshooting, limits

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

@@ -0,0 +1,176 @@
+# Cache Reserve API
+
+## Workers Integration
+
+Cache Reserve works automatically with Workers Cache API, but requires specific patterns:
+
+### Standard Fetch (Recommended)
+
+```typescript
+// Cache Reserve works automatically via standard fetch
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Standard fetch uses Cache Reserve automatically
+    return await fetch(request);
+  }
+};
+```
+
+### Cache API Limitations
+
+**IMPORTANT**: `cache.put()` is **NOT compatible** with Cache Reserve or Tiered Cache.
+
+```typescript
+// ❌ WRONG: cache.put() bypasses Cache Reserve
+const cache = caches.default;
+let response = await cache.match(request);
+if (!response) {
+  response = await fetch(request);
+  await cache.put(request, response.clone()); // Bypasses Cache Reserve!
+}
+
+// ✅ CORRECT: Use standard fetch for Cache Reserve compatibility
+return await fetch(request);
+
+// ✅ CORRECT: Use Cache API only for custom cache namespaces
+const customCache = await caches.open('my-custom-cache');
+let response = await customCache.match(request);
+if (!response) {
+  response = await fetch(request);
+  await customCache.put(request, response.clone()); // Custom cache OK
+}
+```
+
+## Purging and Cache Management
+
+### Purge by URL (Instant)
+
+```typescript
+// Purge specific URL from Cache Reserve immediately
+const purgeCacheReserveByURL = async (
+  zoneId: string,
+  apiToken: string,
+  urls: string[]
+) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ files: urls })
+    }
+  );
+  return await response.json();
+};
+
+// Example usage
+await purgeCacheReserveByURL('zone123', 'token456', [
+  'https://example.com/image.jpg',
+  'https://example.com/video.mp4'
+]);
+```
+
+### Purge by Tag/Host/Prefix (Revalidation)
+
+```typescript
+// Purge by cache tag - forces revalidation, not immediate removal
+const purgeCacheReserveByTag = async (
+  zoneId: string,
+  apiToken: string,
+  tags: string[]
+) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ tags })
+    }
+  );
+  return await response.json();
+};
+
+// Note: Assets remain in Cache Reserve but will revalidate on next request
+// Storage costs continue until retention TTL expires
+```
+
+**Important purge behavior differences:**
+
+- **Purge by URL**: Immediately removes from Cache Reserve + edge cache
+- **Purge by tag/host/prefix**: Forces revalidation but assets remain in storage
+- **Storage costs**: Continue for tag/host/prefix purges until TTL expiry
+
+### Clear All Cache Reserve Data
+
+```typescript
+// Clear ALL Cache Reserve data (requires Cache Reserve to be OFF)
+const clearAllCacheReserve = async (zoneId: string, apiToken: string) => {
+  // Step 1: Verify Cache Reserve is off
+  const statusResponse = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve`,
+    { method: 'GET', headers: { 'Authorization': `Bearer ${apiToken}` } }
+  );
+  const status = await statusResponse.json();
+  
+  if (status.result.value !== 'off') {
+    throw new Error('Cache Reserve must be OFF before clearing data');
+  }
+  
+  // Step 2: Clear Cache Reserve data
+  const clearResponse = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve_clear`,
+    { method: 'POST', headers: { 'Authorization': `Bearer ${apiToken}` } }
+  );
+  return await clearResponse.json();
+};
+
+// Check clear status
+const getClearStatus = async (zoneId: string, apiToken: string) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve_clear`,
+    { method: 'GET', headers: { 'Authorization': `Bearer ${apiToken}` } }
+  );
+  return await response.json();
+  // Returns: { state: "In-progress" | "Completed", start_ts: "..." }
+};
+```
+
+**Clear process:**
+1. Disable Cache Reserve (`value: 'off'`)
+2. Call cache_reserve_clear endpoint
+3. Deletion takes up to 24 hours
+4. Re-enable Cache Reserve when ready
+
+## Monitoring and Analytics
+
+```typescript
+// Dashboard: egress savings, requests served (hits/misses), storage, operations (A/B)
+// Logpush field: CacheReserveUsed (boolean) - filter for Cache Reserve hits
+
+// Query Cache Reserve hits
+const query = `
+  SELECT ClientRequestHost, COUNT(*) as requests, SUM(EdgeResponseBytes) as bytes
+  FROM http_requests WHERE CacheReserveUsed = true
+  GROUP BY ClientRequestHost ORDER BY requests DESC
+`;
+```
+
+## Pricing
+
+```typescript
+// Storage: $0.015/GB-month | Class A (writes): $4.50/M | Class B (reads): $0.36/M
+// Cache miss: 1A + 1B | Cache hit: 1B | Assets >1GB: proportionally more ops
+```
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [Patterns](./patterns.md) - Best practices and optimization
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting

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

@@ -0,0 +1,164 @@
+# Cache Reserve Configuration
+
+## Dashboard Setup
+
+**Minimum steps to enable:**
+
+```bash
+# Navigate to dashboard
+https://dash.cloudflare.com/caching/cache-reserve
+
+# Click "Enable Storage Sync" or "Purchase" button
+```
+
+**Prerequisites:**
+- Paid Cache Reserve plan required
+- Tiered Cache strongly recommended (Cache Reserve checks for this)
+
+## API Configuration
+
+```typescript
+// Enable Cache Reserve
+const enableCacheReserve = async (zoneId: string, apiToken: string) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve`,
+    {
+      method: 'PATCH',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ value: 'on' })
+    }
+  );
+  return await response.json();
+};
+
+// Check Cache Reserve status
+const getCacheReserveStatus = async (zoneId: string, apiToken: string) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve`,
+    {
+      method: 'GET',
+      headers: { 'Authorization': `Bearer ${apiToken}` }
+    }
+  );
+  return await response.json();
+};
+```
+
+### Required API Token Permissions
+
+- `Zone Settings Read`
+- `Zone Settings Write`
+- `Zone Read`
+- `Zone Write`
+
+## Cache Rules Integration
+
+Control Cache Reserve eligibility via Cache Rules:
+
+```typescript
+// Enable Cache Reserve for static assets with long TTL
+const staticAssetRule = {
+  action: 'set_cache_settings',
+  action_parameters: {
+    cache_reserve: {
+      eligible: true,
+      minimum_file_ttl: 86400 // 24 hours
+    },
+    edge_ttl: {
+      mode: 'override_origin',
+      default: 86400
+    },
+    cache: true
+  },
+  expression: '(http.request.uri.path matches "\\.(jpg|jpeg|png|gif|webp|pdf|zip)$")'
+};
+
+// Disable Cache Reserve for frequently updated content
+const dynamicContentRule = {
+  action: 'set_cache_settings',
+  action_parameters: {
+    cache_reserve: { eligible: false }
+  },
+  expression: '(http.request.uri.path matches "^/api/")'
+};
+
+// Cache Reserve for specific origin with minimum 12-hour TTL
+const specificOriginRule = {
+  action: 'set_cache_settings',
+  action_parameters: {
+    cache_reserve: {
+      eligible: true,
+      minimum_file_ttl: 43200 // 12 hours
+    },
+    edge_ttl: { mode: 'override_origin', default: 43200 },
+    cache: true
+  },
+  expression: '(http.host eq "cdn.example.com")'
+};
+```
+
+### Creating Rules via API
+
+```typescript
+const createCacheRule = async (
+  zoneId: string,
+  apiToken: string,
+  rule: CacheRuleWithReserve
+) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/rulesets/phases/http_request_cache_settings/entrypoint`,
+    {
+      method: 'PUT',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ rules: [rule] })
+    }
+  );
+  return await response.json();
+};
+```
+
+## Wrangler Integration
+
+Cache Reserve works automatically with Workers deployed via Wrangler. No special configuration needed.
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "cache-reserve-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-11", // Use current date for new projects
+  
+  // Cache Reserve works automatically with standard routes
+  "routes": [
+    { "pattern": "example.com/*", "zone_name": "example.com" }
+  ]
+  // No special Cache Reserve configuration needed
+  // Enable via Dashboard or API
+}
+```
+
+### Development and Testing
+
+```bash
+# Local development (Cache Reserve not active locally)
+npx wrangler dev
+
+# Deploy to production (Cache Reserve active if enabled for zone)
+npx wrangler deploy
+
+# View logs (including cache behavior)
+npx wrangler tail
+```
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [API Reference](./api.md) - Purging and monitoring APIs
+- [Patterns](./patterns.md) - Best practices and optimization
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting