opencodekit 0.15.4 → 0.15.5

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

@@ -0,0 +1,137 @@
+# Workers Runtime APIs
+
+## Fetch Handler
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (request.method === 'POST' && url.pathname === '/api') {
+      const body = await request.json();
+      return new Response(JSON.stringify({ id: 1 }), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+    return fetch(request);  // Subrequest to origin
+  },
+};
+```
+
+## Execution Context
+
+```typescript
+ctx.waitUntil(logAnalytics(request));  // Background work, don't block response
+ctx.passThroughOnException();  // Failover to origin on error
+```
+
+**Never** `await` background operations - use `ctx.waitUntil()`.
+
+## Bindings
+
+```typescript
+// KV
+await env.MY_KV.get('key');
+await env.MY_KV.put('key', 'value', { expirationTtl: 3600 });
+
+// R2
+const obj = await env.MY_BUCKET.get('file.txt');
+await env.MY_BUCKET.put('file.txt', 'content');
+
+// D1
+const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1).first();
+
+// Queues
+await env.MY_QUEUE.send({ timestamp: Date.now() });
+
+// Secrets/vars
+const key = env.API_KEY;
+```
+
+## Cache API
+
+```typescript
+const cache = caches.default;
+let response = await cache.match(request);
+
+if (!response) {
+  response = await fetch(request);
+  response = new Response(response.body, response);
+  response.headers.set('Cache-Control', 'max-age=3600');
+  ctx.waitUntil(cache.put(request, response.clone()));  // Clone before caching
+}
+```
+
+## HTMLRewriter
+
+```typescript
+return new HTMLRewriter()
+  .on('a[href]', {
+    element(el) {
+      const href = el.getAttribute('href');
+      if (href?.startsWith('http://')) {
+        el.setAttribute('href', href.replace('http://', 'https://'));
+      }
+    }
+  })
+  .transform(response);
+```
+
+**Use cases**: A/B testing, analytics injection, link rewriting
+
+## WebSockets
+
+```typescript
+const [client, server] = Object.values(new WebSocketPair());
+
+server.accept();
+server.addEventListener('message', event => {
+  server.send(`Echo: ${event.data}`);
+});
+
+return new Response(null, { status: 101, webSocket: client });
+```
+
+## Durable Objects
+
+```typescript
+export class Counter {
+  private value = 0;
+  
+  constructor(private state: DurableObjectState) {
+    state.blockConcurrencyWhile(async () => {
+      this.value = (await state.storage.get('value')) || 0;
+    });
+  }
+  
+  async fetch(request: Request): Promise<Response> {
+    if (new URL(request.url).pathname === '/increment') {
+      await this.state.storage.put('value', ++this.value);
+    }
+    return new Response(String(this.value));
+  }
+}
+
+// Usage: const stub = env.COUNTER.get(env.COUNTER.idFromName('global'));
+```
+
+**When to use**: Real-time collaboration, rate limiting, strongly consistent state
+
+## Other Handlers
+
+```typescript
+// Cron: async scheduled(event, env, ctx) { ctx.waitUntil(doCleanup(env)); }
+// Queue: async queue(batch) { for (const msg of batch.messages) { await process(msg.body); msg.ack(); } }
+// Tail: async tail(events, env) { for (const e of events) if (e.outcome === 'exception') await log(e); }
+```
+
+## Service Bindings
+
+```typescript
+return env.SERVICE_B.fetch(request);  // Worker-to-worker RPC, zero latency
+```
+
+## See Also
+
+- [Configuration](./configuration.md) - Binding setup
+- [Patterns](./patterns.md) - Common workflows
+- [KV](../kv/README.md), [D1](../d1/README.md), [R2](../r2/README.md), [Durable Objects](../durable-objects/README.md), [Queues](../queues/README.md)

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

@@ -0,0 +1,147 @@
+# Workers Configuration
+
+## wrangler.jsonc (Recommended)
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  
+  // Bindings (non-inheritable)
+  "vars": { "ENVIRONMENT": "production" },
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+  
+  // Environments
+  "env": {
+    "staging": {
+      "vars": { "ENVIRONMENT": "staging" },
+      "kv_namespaces": [{ "binding": "MY_KV", "id": "staging-id" }]
+    }
+  }
+}
+```
+
+## Configuration Rules
+
+**Inheritable**: `name`, `main`, `compatibility_date`, `routes`, `workers_dev`  
+**Non-inheritable**: All bindings (`vars`, `kv_namespaces`, `r2_buckets`, etc.)  
+**Top-level only**: `migrations`, `keep_vars`, `send_metrics`
+
+**ALWAYS set `compatibility_date` to current date for new projects**
+
+## Bindings
+
+```jsonc
+{
+  // Environment variables - access via env.VAR_NAME
+  "vars": { "ENVIRONMENT": "production" },
+  
+  // KV (key-value storage)
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
+  
+  // R2 (object storage)
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+  
+  // D1 (SQL database)
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+  
+  // Durable Objects (stateful coordination)
+  "durable_objects": {
+    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
+  },
+  
+  // Queues (message queues)
+  "queues": {
+    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
+    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }]
+  },
+  
+  // Service bindings (worker-to-worker RPC)
+  "services": [{ "binding": "SERVICE_B", "service": "service-b" }],
+  
+  // Analytics Engine
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }]
+}
+```
+
+### Secrets
+
+Set via CLI (never in config):
+
+```bash
+npx wrangler secret put API_KEY
+```
+
+Access: `env.API_KEY`
+
+### Automatic Provisioning (Beta)
+
+Bindings without IDs are auto-created:
+
+```jsonc
+{ "kv_namespaces": [{ "binding": "MY_KV" }] }  // ID added on deploy
+```
+
+## Routes & Triggers
+
+```jsonc
+{
+  "routes": [
+    { "pattern": "example.com/*", "zone_name": "example.com" }
+  ],
+  "triggers": {
+    "crons": ["0 */6 * * *"]  // Every 6 hours
+  }
+}
+```
+
+## TypeScript Setup
+
+```bash
+npm install -D @cloudflare/workers-types
+```
+
+`tsconfig.json`: `{ "compilerOptions": { "target": "ES2022", "lib": ["ES2022"], "types": ["@cloudflare/workers-types"] } }`
+
+Define environment interface:
+
+```typescript
+interface Env {
+  MY_KV: KVNamespace;
+  DB: D1Database;
+  API_KEY: string;
+}
+```
+
+## Advanced Options
+
+```jsonc
+{
+  // Auto-locate compute near data sources
+  "placement": { "mode": "smart" },
+  
+  // Enable Node.js built-ins
+  "compatibility_flags": ["nodejs_compat_v2"],
+  
+  // Observability (10% sampling)
+  "observability": { "enabled": true, "head_sampling_rate": 0.1 }
+}
+```
+
+## Deployment Commands
+
+```bash
+npx wrangler deploy              # Production
+npx wrangler deploy --env staging
+npx wrangler deploy --dry-run    # Validate only
+```
+
+## See Also
+
+- [API](./api.md) - Runtime APIs and bindings usage
+- [Patterns](./patterns.md) - Deployment strategies
+- [Wrangler](../wrangler/README.md) - CLI reference

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

@@ -0,0 +1,99 @@
+# Workers Gotchas
+
+## CPU Time Limits
+
+**Standard**: 10ms CPU time  
+**Unbound**: 30ms CPU time
+
+**Solutions**:
+- Use `ctx.waitUntil()` for background work
+- Offload heavy compute to Durable Objects
+- Consider Workers AI for ML workloads
+
+## No Persistent State in Worker
+
+Workers are stateless between requests - module-level variables reset unpredictably.
+
+**Solution**: Use KV, D1, or Durable Objects for persistent state.
+
+## Response Bodies Are Streams
+
+```typescript
+// ❌ BAD
+const response = await fetch(url);
+await logBody(response.text());  // First read
+return response;  // Body already consumed!
+
+// ✅ GOOD
+const response = await fetch(url);
+const text = await response.text();
+await logBody(text);
+return new Response(text, response);
+```
+
+## No Node.js Built-ins (by default)
+
+```typescript
+// ❌ BAD
+import fs from 'fs';  // Not available
+
+// ✅ GOOD - use Workers APIs
+const data = await env.MY_BUCKET.get('file.txt');
+
+// OR enable Node.js compat
+{ "compatibility_flags": ["nodejs_compat_v2"] }
+```
+
+## Fetch in Global Scope Forbidden
+
+```typescript
+// ❌ BAD
+const config = await fetch('/config.json');  // Error!
+
+export default {
+  async fetch() { return new Response('OK'); },
+};
+
+// ✅ GOOD
+export default {
+  async fetch() {
+    const config = await fetch('/config.json');  // OK
+    return new Response('OK');
+  },
+};
+```
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Request size | 100 MB |
+| Response size | Unlimited (streaming) |
+| CPU time | 10ms (standard) / 30ms (unbound) |
+| Subrequests | 1000 per request |
+| KV reads | 1000 per request |
+| KV write size | 25 MB |
+| Environment size | 5 MB |
+
+## Common Errors
+
+### "Error: Body has already been used"
+
+**Cause**: Response body read twice  
+**Solution**: Clone response before reading: `response.clone()`
+
+### "Error: Too much CPU time used"
+
+**Cause**: Exceeded CPU limit  
+**Solution**: Use `ctx.waitUntil()` for background work
+
+### "Error: Subrequest depth limit exceeded"
+
+**Cause**: Too many nested subrequests  
+**Solution**: Flatten request chain, use service bindings
+
+## See Also
+
+- [Patterns](./patterns.md) - Best practices
+- [API](./api.md) - Runtime APIs
+- [Configuration](./configuration.md) - Setup

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

@@ -0,0 +1,149 @@
+# Workers Patterns
+
+## Error Handling
+
+```typescript
+class HTTPError extends Error {
+  constructor(public status: number, message: string) { super(message); }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      return await handleRequest(request, env);
+    } catch (error) {
+      if (error instanceof HTTPError) {
+        return new Response(JSON.stringify({ error: error.message }), {
+          status: error.status, headers: { 'Content-Type': 'application/json' }
+        });
+      }
+      return new Response('Internal Server Error', { status: 500 });
+    }
+  },
+};
+```
+
+## CORS
+
+```typescript
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+};
+
+if (request.method === 'OPTIONS') return new Response(null, { headers: corsHeaders });
+// Add corsHeaders to response
+```
+
+## Routing
+
+```typescript
+const router = { 'GET /api/users': handleGetUsers, 'POST /api/users': handleCreateUser };
+
+const handler = router[`${request.method} ${url.pathname}`];
+return handler ? handler(request, env) : new Response('Not Found', { status: 404 });
+```
+
+**Production**: Use Hono, itty-router, or Worktop
+
+## Performance
+
+```typescript
+// ❌ Sequential
+const user = await fetch('/api/user/1');
+const posts = await fetch('/api/posts?user=1');
+
+// ✅ Parallel
+const [user, posts] = await Promise.all([fetch('/api/user/1'), fetch('/api/posts?user=1')]);
+```
+
+## Streaming
+
+```typescript
+const stream = new ReadableStream({
+  async start(controller) {
+    for (let i = 0; i < 1000; i++) {
+      controller.enqueue(new TextEncoder().encode(`Item ${i}\n`));
+      if (i % 100 === 0) await new Promise(r => setTimeout(r, 0));
+    }
+    controller.close();
+  }
+});
+```
+
+## Transform Streams
+
+```typescript
+response.body.pipeThrough(new TextDecoderStream()).pipeThrough(
+  new TransformStream({ transform(chunk, c) { c.enqueue(chunk.toUpperCase()); } })
+).pipeThrough(new TextEncoderStream());
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import worker from '../src/index';
+
+describe('Worker', () => {
+  it('returns 200', async () => {
+    const req = new Request('http://localhost/');
+    const env = { MY_VAR: 'test' };
+    const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };
+    expect((await worker.fetch(req, env, ctx)).status).toBe(200);
+  });
+});
+```
+
+## Deployment
+
+```bash
+npx wrangler deploy              # production
+npx wrangler deploy --env staging
+npx wrangler versions upload --message "Add feature"
+npx wrangler rollback
+```
+
+## Monitoring
+
+```typescript
+const start = Date.now();
+const response = await handleRequest(request, env);
+ctx.waitUntil(env.ANALYTICS.writeDataPoint({
+  doubles: [Date.now() - start], blobs: [request.url, String(response.status)]
+}));
+```
+
+## Security
+
+```typescript
+// Headers
+const security = {
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Content-Security-Policy': "default-src 'self'",
+};
+
+// Auth
+const auth = request.headers.get('Authorization');
+if (!auth?.startsWith('Bearer ')) return new Response('Unauthorized', { status: 401 });
+```
+
+## Rate Limiting
+
+See [Durable Objects](../durable-objects/README.md) for stateful rate limiting patterns.
+
+## Gradual Rollouts
+
+```typescript
+const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(userId));
+const bucket = new Uint8Array(hash)[0] % 100;
+if (bucket < rolloutPercent) return newFeature(request);
+```
+
+## See Also
+
+- [API](./api.md) - Runtime APIs
+- [Gotchas](./gotchas.md) - Common issues
+- [Configuration](./configuration.md) - Setup

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

@@ -0,0 +1,116 @@
+# Cloudflare Workers AI Skill
+
+A comprehensive OpenCode skill for working with Cloudflare Workers AI.
+
+## What This Skill Covers
+
+This skill focuses **exclusively on Cloudflare Workers AI** - the serverless AI inference platform. It does NOT cover the broader Cloudflare platform (Workers, Pages, CDN, etc.) unless directly related to Workers AI usage.
+
+### Topics Included
+
+- **Core Concepts**: Bindings, model invocation patterns, naming conventions
+- **Task-Specific Implementations**: Text generation, embeddings, image generation, speech recognition, translation, etc.
+- **REST API Usage**: Authentication, endpoints, OpenAI compatibility
+- **Wrangler Integration**: Setup, configuration, deployment
+- **Pricing & Limits**: Neurons, rate limits, cost optimization
+- **Common Patterns**: RAG, streaming, batch processing, error handling
+- **AI Gateway**: Caching, rate limiting, analytics integration
+- **Function Calling**: Both traditional and embedded approaches
+- **Model Selection**: Guidelines for choosing the right model
+- **TypeScript Support**: Types, interfaces, best practices
+
+## How to Use This Skill
+
+### Installation
+
+1. Place `README.md` in your OpenCode skills directory
+2. Load the skill when working on Workers AI projects
+
+### When to Load This Skill
+
+Load this skill when:
+- Implementing AI inference in Cloudflare Workers
+- Building RAG systems with Workers AI + Vectorize
+- Optimizing Workers AI costs or performance
+- Debugging Workers AI integration issues
+- Setting up AI Gateway with Workers AI
+- Implementing function calling with LLMs
+
+### Example Usage
+
+```bash
+# In OpenCode CLI
+load-skill cloudflare-workers-ai
+
+# Then ask questions like:
+"How do I implement streaming with Workers AI?"
+"What's the best embedding model for semantic search?"
+"Show me how to do RAG with Vectorize"
+"How do I handle rate limits?"
+```
+
+## Skill Structure
+
+The skill is organized into these sections:
+
+1. **Overview** - What Workers AI is and when to use this skill
+2. **Core Concepts** - Bindings, invocation patterns, model naming
+3. **Task-Specific Patterns** - Code examples for each AI task type
+4. **REST API** - Using Workers AI via HTTP endpoints
+5. **Wrangler CLI** - Setup, config, deployment
+6. **Pricing & Neurons** - Cost model and optimization
+7. **Rate Limits** - Per-task and per-model limits
+8. **RAG Pattern** - Complete retrieval-augmented generation example
+9. **AI Gateway** - Integration patterns
+10. **Common Patterns** - Error handling, streaming, batching, etc.
+11. **Model Selection** - Choosing the right model
+12. **Debugging** - Monitoring and troubleshooting
+13. **Common Issues** - Known problems and solutions
+14. **Pages Integration** - Using Workers AI in Pages Functions
+15. **Advanced Topics** - LoRA adapters
+16. **Architecture Patterns** - System design approaches
+
+## Key Features
+
+- ✅ **Complete Code Examples**: Every pattern has working code
+- ✅ **TypeScript First**: Proper typing for all examples
+- ✅ **Real-World Patterns**: RAG, streaming, batch processing
+- ✅ **Cost Optimization**: Pricing info and model selection guidance
+- ✅ **Troubleshooting**: Common issues and solutions
+- ✅ **Best Practices**: Error handling, type safety, monitoring
+
+## What's NOT Covered
+
+This skill does NOT cover:
+- General Cloudflare Workers programming (use Workers skill)
+- Cloudflare Pages (unless specifically Workers AI integration)
+- Cloudflare CDN, DNS, security features
+- Vectorize (unless in context of Workers AI RAG)
+- D1, KV, R2, Durable Objects (unless AI-specific usage)
+
+## Maintenance
+
+To keep this skill up to date:
+- Check official docs: https://developers.cloudflare.com/workers-ai/
+- Monitor model catalog: https://developers.cloudflare.com/workers-ai/models/
+- Track pricing changes: https://developers.cloudflare.com/workers-ai/platform/pricing/
+
+## Contributing
+
+Found an issue or want to improve this skill?
+1. Test changes against official Cloudflare Workers AI docs
+2. Verify code examples work with latest Wrangler
+3. Update pricing/limits if changed
+4. Add new model examples as they're released
+
+## Version History
+
+- **v1.0** (2026-01-11): Initial comprehensive skill
+  - Full coverage of Workers AI API
+  - Code patterns for all task types
+  - Pricing, limits, troubleshooting
+  - RAG, streaming, function calling examples
+
+## License
+
+This skill documentation is provided as-is for use with OpenCode.

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

@@ -0,0 +1,48 @@
+# Cloudflare Workers for Platforms
+
+Multi-tenant platform with isolated customer code execution at scale.
+
+## Use Cases
+
+- Multi-tenant SaaS running customer code
+- AI-generated code execution in secure sandboxes
+- Programmable platforms with isolated compute
+- Edge functions/serverless platforms
+- Website builders with static + dynamic content
+- Unlimited app deployment at scale
+
+**NOT for general Workers** - only for Workers for Platforms architecture.
+
+## Architecture
+
+**4 Components:**
+1. **Dispatch Namespace** - Container for unlimited customer Workers, automatic isolation, untrusted mode
+2. **Dynamic Dispatch Worker** - Entry point, routes requests, enforces platform logic (auth, limits, validation)
+3. **User Workers** - Customer code in isolated sandboxes, API-deployed, optional bindings (KV/D1/R2/DO)
+4. **Outbound Worker** (optional) - Intercepts external fetch, controls egress, logs subrequests
+
+**Request Flow:**
+```
+Request → Dispatch Worker → Determines user Worker → env.DISPATCHER.get("customer") 
+→ User Worker executes (Outbound Worker for external fetch) → Response → Dispatch Worker → Client
+```
+
+## Key Features
+
+- Unlimited Workers per namespace (no script limits)
+- Automatic tenant isolation
+- Custom CPU/subrequest limits per customer
+- Hostname routing (subdomains/vanity domains)
+- Egress/ingress control
+- Static assets support
+- Tags for bulk operations
+
+## Quick Start
+
+See [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)
+
+## Refs
+
+- [Docs](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/)
+- [Starter Kit](https://github.com/cloudflare/templates/tree/main/worker-publisher-template)
+- [VibeSDK](https://github.com/cloudflare/vibesdk)