opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/workers-for-platforms/api.md

@@ -0,0 +1,169 @@
+# API Operations
+
+## Deploy User Worker
+
+```bash
+curl -X PUT \
+  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -F 'metadata={"main_module": "worker.mjs"};type=application/json' \
+  -F 'worker.mjs=@worker.mjs;type=application/javascript+module'
+```
+
+### TypeScript SDK
+```typescript
+import Cloudflare from "cloudflare";
+
+const client = new Cloudflare({ apiToken: process.env.API_TOKEN });
+
+const scriptFile = new File([scriptContent], `${scriptName}.mjs`, {
+  type: "application/javascript+module",
+});
+
+await client.workersForPlatforms.dispatch.namespaces.scripts.update(
+  namespace, scriptName,
+  {
+    account_id: accountId,
+    metadata: { main_module: `${scriptName}.mjs` },
+    files: [scriptFile],
+  }
+);
+```
+
+## Deploy with Bindings
+```bash
+curl -X PUT ".../scripts/$SCRIPT_NAME" \
+  -F 'metadata={
+    "main_module": "worker.mjs",
+    "bindings": [
+      {"type": "kv_namespace", "name": "MY_KV", "namespace_id": "'$KV_ID'"}
+    ],
+    "tags": ["customer-123", "production"],
+    "compatibility_date": "2024-01-01"
+  };type=application/json' \
+  -F 'worker.mjs=@worker.mjs;type=application/javascript+module'
+```
+
+## List/Delete Workers
+
+```bash
+# List
+curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# Delete by name
+curl -X DELETE ".../scripts/$SCRIPT_NAME" -H "Authorization: Bearer $API_TOKEN"
+
+# Delete by tag
+curl -X DELETE ".../scripts?tags=customer-123%3Ayes" -H "Authorization: Bearer $API_TOKEN"
+```
+
+## Static Assets
+
+**3-step process:** Create session → Upload files → Deploy Worker
+
+### 1. Create Upload Session
+```bash
+curl -X POST ".../scripts/$SCRIPT_NAME/assets-upload-session" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -d '{
+    "manifest": {
+      "/index.html": {"hash": "08f1dfda4574284ab3c21666d1ee8c7d4", "size": 1234}
+    }
+  }'
+# Returns: jwt, buckets
+```
+
+**Hash:** First 16 bytes (32 hex chars) of SHA-256
+
+### 2. Upload Files
+```bash
+curl -X POST ".../workers/assets/upload?base64=true" \
+  -H "Authorization: Bearer $UPLOAD_JWT" \
+  -F '08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_CONTENT>'
+# Returns: completion jwt
+```
+
+### 3. Deploy with Assets
+```bash
+curl -X PUT ".../scripts/$SCRIPT_NAME" \
+  -F 'metadata={
+    "main_module": "index.js",
+    "assets": {"jwt": "<COMPLETION_TOKEN>"},
+    "bindings": [{"type": "assets", "name": "ASSETS"}]
+  };type=application/json' \
+  -F 'index.js=export default {...};type=application/javascript+module'
+```
+
+**Asset Isolation:** Assets shared across namespace. For strict isolation, salt hash:
+```typescript
+const hash = sha256(accountId + fileContents).slice(0, 32);
+```
+
+## Dispatch Workers
+
+### Subdomain Routing
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userWorkerName = new URL(request.url).hostname.split(".")[0];
+    const userWorker = env.DISPATCHER.get(userWorkerName);
+    return await userWorker.fetch(request);
+  },
+};
+```
+
+### Path Routing
+```typescript
+const pathParts = new URL(request.url).pathname.split("/").filter(Boolean);
+const userWorker = env.DISPATCHER.get(pathParts[0]);
+return await userWorker.fetch(request);
+```
+
+### KV Routing
+```typescript
+const hostname = new URL(request.url).hostname;
+const userWorkerName = await env.ROUTING_KV.get(hostname);
+const userWorker = env.DISPATCHER.get(userWorkerName);
+return await userWorker.fetch(request);
+```
+
+## Outbound Workers
+
+Control external fetch from user Workers:
+
+### Configure
+```typescript
+const userWorker = env.DISPATCHER.get(
+  workerName, {},
+  { outbound: { customer_context: { customer_name: workerName, url: request.url } } }
+);
+```
+
+### Implement
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const customerName = env.customer_name;
+    const url = new URL(request.url);
+    
+    // Block domains
+    if (["malicious.com"].some(d => url.hostname.includes(d))) {
+      return new Response("Blocked", { status: 403 });
+    }
+    
+    // Inject auth
+    if (url.hostname === "api.example.com") {
+      const headers = new Headers(request.headers);
+      headers.set("Authorization", `Bearer ${generateJWT(customerName)}`);
+      return fetch(new Request(request, { headers }));
+    }
+    
+    return fetch(request);
+  },
+};
+```
+
+**Note:** Doesn't intercept DO/mTLS fetch.
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/dist/template/.opencode/skill/cloudflare/references/workers-for-platforms/configuration.md

@@ -0,0 +1,136 @@
+# Configuration
+
+## Dispatch Namespace Binding
+
+### wrangler.jsonc
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "dispatch_namespaces": [{
+    "binding": "DISPATCHER",
+    "namespace": "production"
+  }]
+}
+```
+
+### wrangler.toml
+```toml
+[[dispatch_namespaces]]
+binding = "DISPATCHER"
+namespace = "production"
+```
+
+### With Outbound Worker
+```jsonc
+{
+  "dispatch_namespaces": [{
+    "binding": "DISPATCHER",
+    "namespace": "production",
+    "outbound": {
+      "service": "outbound-worker",
+      "parameters": ["customer_context"]
+    }
+  }]
+}
+```
+
+## Wrangler Commands
+
+```bash
+wrangler dispatch-namespace list
+wrangler dispatch-namespace get production
+wrangler dispatch-namespace create production
+wrangler dispatch-namespace delete staging
+wrangler dispatch-namespace rename old new
+```
+
+## Custom Limits
+
+Set CPU time and subrequest limits per invocation:
+
+```typescript
+const userWorker = env.DISPATCHER.get(
+  workerName,
+  {},
+  {
+    limits: { 
+      cpuMs: 10,        // Max CPU ms
+      subRequests: 5    // Max fetch() calls
+    }
+  }
+);
+```
+
+Handle limit violations:
+```typescript
+try {
+  return await userWorker.fetch(request);
+} catch (e) {
+  if (e.message.includes("CPU time limit")) {
+    return new Response("CPU limit exceeded", { status: 429 });
+  }
+  throw e;
+}
+```
+
+## Static Assets
+
+Deploy HTML/CSS/images with Workers. See [api.md](./api.md#static-assets) for upload process.
+
+### Wrangler
+```jsonc
+{
+  "name": "customer-site",
+  "main": "./src/index.js",
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS"
+  }
+}
+```
+
+```bash
+npx wrangler deploy --name customer-site --dispatch-namespace production
+```
+
+## Bindings
+
+Supported: KV, D1, R2, Durable Objects, Analytics Engine, Service, Assets
+
+Add via API metadata (see [api.md](./api.md#deploy-with-bindings)):
+```json
+{
+  "bindings": [
+    {"type": "kv_namespace", "name": "USER_KV", "namespace_id": "..."},
+    {"type": "r2_bucket", "name": "STORAGE", "bucket_name": "..."},
+    {"type": "d1", "name": "DB", "id": "..."}
+  ]
+}
+```
+
+Preserve existing bindings:
+```json
+{
+  "bindings": [{"type": "r2_bucket", "name": "STORAGE", "bucket_name": "new"}],
+  "keep_bindings": ["kv_namespace", "d1"]
+}
+```
+
+## Tags
+
+Organize/search Workers (max 8/script):
+
+```bash
+# Set tags
+curl -X PUT ".../tags" -d '["customer-123", "pro", "production"]'
+
+# Filter by tag
+curl ".../scripts?tags=production%3Ayes"
+
+# Delete by tag
+curl -X DELETE ".../scripts?tags=customer-123%3Ayes"
+```
+
+Common patterns: `customer-123`, `free|pro|enterprise`, `production|staging`
+
+See [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/dist/template/.opencode/skill/cloudflare/references/workers-for-platforms/gotchas.md

@@ -0,0 +1,130 @@
+# Gotchas & Limits
+
+## Limits
+
+- **Max 8 tags per Worker**
+- **Upload session JWT valid 1 hour**
+- **Completion token valid 1 hour**
+- **No limits on Workers per namespace** (unlike regular Workers)
+- **User Workers run in untrusted mode** (no `request.cf` access)
+- **Outbound Workers don't intercept DO/mTLS fetch**
+
+## Security
+
+### User Worker Restrictions
+- Run in untrusted mode
+- No access to `request.cf` object
+- Automatic isolation from other customers
+- Never share cache
+
+### Outbound Worker Gaps
+- Doesn't intercept Durable Object fetch
+- Doesn't intercept mTLS binding fetch
+- Plan accordingly for complete egress control
+
+### Asset Isolation
+Assets shared across namespace by hash. For strict isolation:
+```typescript
+const hash = sha256(accountId + fileContents).slice(0, 32);
+```
+
+Never expose upload JWTs to clients.
+
+## Error Handling
+
+### Worker Not Found
+```typescript
+try {
+  const userWorker = env.DISPATCHER.get(name);
+  return await userWorker.fetch(request);
+} catch (e) {
+  if (e.message.startsWith("Worker not found")) {
+    return new Response("Worker not found", { status: 404 });
+  }
+  return new Response(e.message, { status: 500 });
+}
+```
+
+### Limit Violations
+```typescript
+try {
+  return await userWorker.fetch(request);
+} catch (e) {
+  if (e.message.includes("CPU time limit")) {
+    env.ANALYTICS.writeDataPoint({
+      indexes: [workerName],
+      blobs: ["cpu_limit_exceeded"],
+    });
+    return new Response("CPU limit exceeded", { status: 429 });
+  }
+  throw e;
+}
+```
+
+## Troubleshooting
+
+### Hostname Routing Issues
+- Use `*/*` wildcard route to avoid DNS proxy issues
+- Orange-to-orange: Customer proxied through CF → your CF domain
+- Wildcard works regardless of proxy settings
+
+### Binding Preservation
+- Use `keep_bindings` to avoid losing existing bindings on update
+- Document which resources bound to which Workers
+
+### Tag Filtering
+- URL encode tags: `tags=production%3Ayes`
+- Avoid special chars: `,` and `&`
+
+### Deploy Failures
+- ES modules require multipart form upload
+- Must specify `main_module` in metadata
+- File type: `application/javascript+module`
+
+### Static Assets
+- Hash must be first 16 bytes (32 hex chars) of SHA-256
+- Upload must happen within 1 hour of session creation
+- Deploy must happen within 1 hour of upload completion
+- Base64 encode file contents for upload
+
+## TypeScript Types
+
+```typescript
+interface Env {
+  DISPATCHER: DispatchNamespace;
+  ROUTING_KV: KVNamespace;
+  CUSTOMERS_KV: KVNamespace;
+  ANALYTICS: AnalyticsEngineDataset;
+}
+
+interface DispatchNamespace {
+  get(
+    name: string,
+    options?: Record<string, unknown>,
+    config?: {
+      limits?: {
+        cpuMs?: number;
+        subRequests?: number;
+      };
+      outbound?: Record<string, unknown>;
+    }
+  ): Fetcher;
+}
+
+interface Fetcher {
+  fetch(request: Request): Promise<Response>;
+}
+```
+
+## Common Mistakes
+
+1. **Creating namespace per customer** → Use one namespace per environment
+2. **Not handling Worker not found** → Always catch and handle gracefully
+3. **Forgetting `keep_bindings`** → Existing bindings lost on update
+4. **Not tagging Workers** → Can't bulk delete/filter
+5. **Exposing upload JWTs** → Keep server-side only
+6. **No limit tracking** → Use Analytics Engine for violations
+7. **Not using wildcard routes** → Hit route limits, DNS issues
+8. **Assuming DO/mTLS interception** → Outbound Worker doesn't catch these
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)

package/dist/template/.opencode/skill/cloudflare/references/workers-for-platforms/patterns.md

@@ -0,0 +1,170 @@
+# Multi-Tenant Patterns
+
+## Billing by Plan
+
+```typescript
+interface Env {
+  DISPATCHER: DispatchNamespace;
+  CUSTOMERS_KV: KVNamespace;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userWorkerName = new URL(request.url).hostname.split(".")[0];
+    const customerPlan = await env.CUSTOMERS_KV.get(userWorkerName);
+    
+    const plans = {
+      enterprise: { cpuMs: 50, subRequests: 50 },
+      pro: { cpuMs: 20, subRequests: 20 },
+      free: { cpuMs: 10, subRequests: 5 },
+    };
+    const limits = plans[customerPlan as keyof typeof plans] || plans.free;
+    
+    const userWorker = env.DISPATCHER.get(userWorkerName, {}, { limits });
+    return await userWorker.fetch(request);
+  },
+};
+```
+
+## Resource Isolation
+
+**Complete isolation:** Create unique resources per customer
+- KV namespace per customer
+- D1 database per customer
+- R2 bucket per customer
+
+```typescript
+const bindings = [{
+  type: "kv_namespace",
+  name: "USER_KV",
+  namespace_id: `customer-${customerId}-kv`
+}];
+```
+
+## Hostname Routing
+
+### Wildcard Route (Recommended)
+Configure `*/*` route on SaaS domain → dispatch Worker
+
+**Benefits:**
+- Supports subdomains + custom vanity domains
+- No route limits
+- Programmatic control
+- Works with any DNS proxy settings
+
+**Setup:**
+1. Cloudflare for SaaS custom hostnames
+2. Fallback origin (dummy `A 192.0.2.0` if Worker is origin)
+3. DNS CNAME to SaaS domain
+4. `*/*` route → dispatch Worker
+5. Routing logic in dispatch Worker
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const hostname = new URL(request.url).hostname;
+    const hostnameData = await env.ROUTING_KV.get(`hostname:${hostname}`, { type: "json" });
+    
+    if (!hostnameData?.workerName) {
+      return new Response("Hostname not configured", { status: 404 });
+    }
+    
+    const userWorker = env.DISPATCHER.get(hostnameData.workerName);
+    return await userWorker.fetch(request);
+  },
+};
+```
+
+### Subdomain-Only
+1. Wildcard DNS: `*.saas.com` → origin
+2. Route: `*.saas.com/*` → dispatch Worker
+3. Extract subdomain for routing
+
+**Orange-to-Orange:** When customers use Cloudflare and CNAME to your domain, use `*/*` wildcard for consistent behavior.
+
+## Observability
+
+### Logpush
+- Enable on dispatch Worker → captures all user Worker logs
+- Filter by `Outcome` or `Script Name`
+
+### Tail Workers
+- Real-time logs with custom formatting
+- Receives HTTP status, `console.log()`, exceptions, diagnostics
+
+### Analytics Engine
+```typescript
+// Track violations
+env.ANALYTICS.writeDataPoint({
+  indexes: [customerName],
+  blobs: ["cpu_limit_exceeded"],
+});
+```
+
+### GraphQL
+```graphql
+query {
+  viewer {
+    accounts(filter: {accountTag: $accountId}) {
+      workersInvocationsAdaptive(filter: {dispatchNamespaceName: "production"}) {
+        sum { requests errors cpuTime }
+      }
+    }
+  }
+}
+```
+
+## Use Case Implementations
+
+### AI Code Execution
+```typescript
+async function deployGeneratedCode(name: string, code: string) {
+  const file = new File([code], `${name}.mjs`, { type: "application/javascript+module" });
+  await client.workersForPlatforms.dispatch.namespaces.scripts.update("production", name, {
+    account_id: accountId,
+    metadata: { main_module: `${name}.mjs`, tags: [name, "ai-generated"] },
+    files: [file],
+  });
+}
+
+// Short limits for untrusted code
+const userWorker = env.DISPATCHER.get(sessionId, {}, { limits: { cpuMs: 5, subRequests: 3 } });
+```
+
+### Edge Functions Platform
+```typescript
+// Route: /customer-id/function-name
+const [customerId, functionName] = new URL(request.url).pathname.split("/").filter(Boolean);
+const workerName = `${customerId}-${functionName}`;
+const userWorker = env.DISPATCHER.get(workerName);
+```
+
+### Website Builder
+- Deploy static assets + Worker code
+- See [api.md](./api.md#static-assets) for full implementation
+- Salt hashes for asset isolation
+
+## Best Practices
+
+### Architecture
+- One namespace per environment (production, staging)
+- Platform logic in dispatch Worker (auth, rate limiting, validation)
+- Isolation automatic (no shared cache, untrusted mode)
+
+### Routing
+- Use `*/*` wildcard routes
+- Store mappings in KV
+- Handle missing Workers gracefully
+
+### Limits & Security
+- Set custom limits by plan
+- Track violations with Analytics Engine
+- Use outbound Workers for egress control
+- Sanitize responses
+
+### Tags
+- Tag all Workers: customer ID, plan, environment
+- Enable bulk operations
+- Filter efficiently
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

package/dist/template/.opencode/skill/cloudflare/references/workers-playground/README.md

@@ -0,0 +1,16 @@
+# Cloudflare Workers Playground Skill Reference
+
+## Overview
+
+Cloudflare Workers Playground is a browser-based sandbox for instantly experimenting with, testing, and deploying Cloudflare Workers without authentication or setup. This skill provides patterns, APIs, and best practices specifically for Workers Playground development....
+
+## 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/workers-playground/api.md

@@ -0,0 +1,20 @@
+### HTTP Test Panel
+
+Switch to **HTTP** tab to test raw HTTP requests:
+- Change HTTP method (GET, POST, PUT, DELETE, etc.)
+- Add/edit headers
+- Modify request body
+- Send request to Worker
+
+### Sharing Code
+
+Click **Copy Link** to generate shareable URL with embedded code. Links never expire and can be bookmarked.
+
+### Deploy from Playground
+
+Click **Deploy** button to:
+1. Log in to Cloudflare account (if not already)
+2. Review Worker code
+3. Deploy to Cloudflare's global network
+4. Get unique `*.workers.dev` URL
+5. Add custom domains, bindings, etc. from dashboard

package/dist/template/.opencode/skill/cloudflare/references/workers-playground/configuration.md

@@ -0,0 +1,3 @@
+# Configuration
+
+See main documentation.

package/dist/template/.opencode/skill/cloudflare/references/workers-playground/gotchas.md

@@ -0,0 +1,35 @@
+## Best Practices
+
+### 1. Use Async/Await
+Always use `async/await` for cleaner asynchronous code:
+
+```javascript
+// Good
+export default {
+  async fetch(request, env, ctx) {
+    const response = await fetch('https://api.example.com');
+    const data = await response.json();
+    return new Response(JSON.stringify(data));
+  },
+};
+
+// Avoid
+export default {
+  fetch(request, env, ctx) {
+    return fetch('https://api.example.com')
+      .then(response => response.json())
+      .then(data => new Response(JSON.stringify(data)));
+  },
+};
+```
+
+### 2. Clone Responses Before Reading
+Response bodies can only be read once:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const response = await fetch('https://api.example.com');
+    
+    // Clone before caching
+    ctx.waitUntil(cach