opencodekit 0.15.4 → 0.15.5

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

@@ -0,0 +1,185 @@
+# Workerd Configuration
+
+## Basic Structure
+```capnp
+using Workerd = import "/workerd/workerd.capnp";
+
+const config :Workerd.Config = (
+  services = [(name = "main", worker = .mainWorker)],
+  sockets = [(name = "http", address = "*:8080", http = (), service = "main")]
+);
+
+const mainWorker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "src/index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+);
+```
+
+## Services
+**Worker**: Run JS/Wasm code
+```capnp
+(name = "api", worker = (
+  modules = [(name = "index.js", esModule = embed "index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+))
+```
+
+**Network**: Internet access
+```capnp
+(name = "internet", network = (allow = ["public"], tlsOptions = (trustBrowserCas = true)))
+```
+
+**External**: Reverse proxy
+```capnp
+(name = "backend", external = (address = "api.com:443", http = (style = tls)))
+```
+
+**Disk**: Static files
+```capnp
+(name = "assets", disk = (path = "/var/www", writable = false))
+```
+
+## Sockets
+```capnp
+# HTTP
+(name = "http", address = "*:8080", http = (), service = "main")
+
+# HTTPS
+(name = "https", address = "*:443",
+  https = (options = (), tlsOptions = (
+    keypair = (privateKey = embed "key.pem", certificateChain = embed "cert.pem")
+  )),
+  service = "main"
+)
+
+# Unix socket
+(name = "app", address = "unix:/tmp/app.sock", http = (), service = "main")
+```
+
+## Worker Formats
+**ES Modules** (recommended):
+```capnp
+modules = [
+  (name = "index.js", esModule = embed "src/index.js"),
+  (name = "wasm.wasm", wasm = embed "build/module.wasm"),
+  (name = "data.json", json = embed "data.json"),
+]
+```
+
+**Service Worker**:
+```capnp
+serviceWorkerScript = embed "worker.js"
+```
+
+**CommonJS**:
+```capnp
+(name = "legacy.js", commonJsModule = embed "legacy.js", namedExports = ["foo"])
+```
+
+## Bindings
+Bindings expose resources to workers. ES modules: `env.BINDING`, Service workers: globals.
+
+### Primitive Types
+```capnp
+(name = "API_KEY", text = "secret")                    # String
+(name = "CONFIG", json = '{"key":"val"}')              # Parsed JSON
+(name = "DATA", data = embed "data.bin")               # ArrayBuffer
+(name = "DATABASE_URL", fromEnvironment = "DB_URL")    # System env var
+```
+
+### Service Binding
+```capnp
+(name = "AUTH", service = "auth-worker")               # Basic
+(name = "API", service = (
+  name = "backend",
+  entrypoint = "adminApi",                             # Named export
+  props = (json = '{"role":"admin"}')                  # ctx.props
+))
+```
+
+### Storage
+```capnp
+(name = "CACHE", kvNamespace = "kv-service")           # KV
+(name = "STORAGE", r2Bucket = "r2-service")            # R2
+(name = "ROOMS", durableObjectNamespace = (
+  serviceName = "room-service",
+  className = "Room"
+))
+(name = "FAST", memoryCache = (
+  id = "cache-id",
+  limits = (maxKeys = 1000, maxValueSize = 1048576)
+))
+```
+
+### Other
+```capnp
+(name = "TASKS", queue = "queue-service")              # Queue
+(name = "ANALYTICS", analyticsEngine = "analytics")    # Analytics
+(name = "LOADER", workerLoader = (id = "dynamic"))     # Dynamic workers
+(name = "KEY", cryptoKey = (
+  format = raw,
+  algorithm = (name = "HMAC", hash = "SHA-256"),
+  keyData = embed "key.bin",
+  usages = [sign, verify],
+  extractable = false
+))
+(name = "TRACED", wrapped = (                          # Middleware
+  moduleName = "tracing",
+  entrypoint = "makeTracer",
+  innerBindings = [(name = "backend", service = "backend")]
+))
+```
+
+## Compatibility
+```capnp
+compatibilityDate = "2024-01-15"                       # Always set!
+compatibilityFlags = ["nodejs_compat", "streams_enable_constructors"]
+```
+
+Version = max compat date. Update carefully after testing.
+
+## Parameter Bindings (Inheritance)
+```capnp
+const base :Workerd.Worker = (
+  modules = [...],
+  compatibilityDate = "2024-01-15",
+  bindings = [
+    (name = "API_URL", parameter = (type = text)),
+    (name = "DB", parameter = (type = service)),
+  ]
+);
+
+const derived :Workerd.Worker = (
+  inherit = "base-service",
+  bindings = [
+    (name = "API_URL", text = "https://api.com"),
+    (name = "DB", service = "postgres"),
+  ]
+);
+```
+
+## Durable Objects Config
+```capnp
+const worker :Workerd.Worker = (
+  modules = [...],
+  compatibilityDate = "2024-01-15",
+  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
+  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
+  durableObjectStorage = (localDisk = "/var/do")
+);
+```
+
+## Logging & Debugging
+```capnp
+logging = (
+  structuredLogging = true,
+  stdoutPrefix = "OUT: ",
+  stderrPrefix = "ERR: "
+)
+
+v8Flags = ["--expose-gc", "--max-old-space-size=2048"]  # Use at own risk
+```
+
+See [patterns.md](./patterns.md) for multi-service examples, [gotchas.md](./gotchas.md) for config errors.

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

@@ -0,0 +1,203 @@
+# Workerd Gotchas
+
+## Configuration Errors
+
+### Missing Compat Date
+❌ **Wrong**:
+```capnp
+const worker :Workerd.Worker = (
+  serviceWorkerScript = embed "worker.js"
+)
+```
+
+✅ **Correct**:
+```capnp
+const worker :Workerd.Worker = (
+  serviceWorkerScript = embed "worker.js",
+  compatibilityDate = "2024-01-15"  # Always set!
+)
+```
+
+### Wrong Binding Type
+❌ **Wrong** - text returns string:
+```capnp
+(name = "CONFIG", text = '{"key":"value"}')  # String, not parsed
+```
+
+✅ **Correct** - json returns object:
+```capnp
+(name = "CONFIG", json = '{"key":"value"}')  # Parsed object
+```
+
+### Service vs Namespace
+❌ **Wrong** - just a Fetcher:
+```capnp
+(name = "ROOM", service = "room-service")
+```
+
+✅ **Correct** - Durable Object namespace:
+```capnp
+(name = "ROOM", durableObjectNamespace = "Room")
+```
+
+### Module Name Mismatch
+❌ **Wrong** - import fails:
+```capnp
+modules = [(name = "src/index.js", esModule = embed "src/index.js")]
+```
+
+✅ **Correct** - use simple names:
+```capnp
+modules = [(name = "index.js", esModule = embed "src/index.js")]
+```
+
+## Network Access
+
+### No Global Outbound
+❌ **Wrong** - may fail without config:
+```javascript
+await fetch("https://api.example.com")
+```
+
+✅ **Correct** - configure network service:
+```capnp
+services = [
+  (name = "internet", network = (allow = ["public"])),
+  (name = "worker", worker = (
+    ...,
+    bindings = [(name = "API", service = "internet")]
+  ))
+]
+```
+
+Or use external service:
+```capnp
+bindings = [
+  (name = "API", service = (
+    name = "api-backend",
+    external = (address = "api.com:443", http = (style = tls))
+  ))
+]
+```
+
+## Debugging Issues
+
+### Worker Not Responding
+Check:
+1. Socket config: `address = "*:8080"`, service name matches
+2. Worker has `fetch()` handler
+3. Port available
+4. Service name in socket matches service definition
+
+### Binding Not Found
+Check:
+1. Binding name in config matches code (`env.BINDING` or global)
+2. Service exists in config
+3. ES module vs service worker syntax (env vs global)
+
+### Module Not Found
+Check:
+1. Module name in config matches import path
+2. `embed` path correct
+3. ES module syntax valid (no CommonJS in `.mjs`)
+
+### Compatibility Errors
+Check:
+1. `compatibilityDate` set
+2. API available on that date ([docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/))
+3. Required flags enabled (`compatibilityFlags`)
+
+## Performance Issues
+
+### High Memory Usage
+Try:
+1. V8 flags: `v8Flags = ["--max-old-space-size=2048"]`
+2. Reduce cache limits: `memoryCache.limits.maxTotalValueSize`
+3. Profile with `--verbose` logging
+
+### Slow Startup
+Try:
+1. Compile binary: `workerd compile config.capnp name -o binary`
+2. Check module count (many imports slow startup)
+3. Review compatibility flags (some have perf impact)
+
+### Request Timeouts
+Check:
+1. External service connectivity
+2. Network service DNS resolution
+3. TLS handshake issues (`tlsOptions`)
+
+## Build Issues
+
+### Cap'n Proto Errors
+- Install Cap'n Proto tools: `brew install capnp` / `apt install capnproto`
+- Check schema import path: `using Workerd = import "/workerd/workerd.capnp";`
+- Validate with: `capnp compile -I. config.capnp`
+
+### Embed Path Issues
+- Paths relative to config file location
+- Use absolute paths if needed: `embed "/full/path/file.js"`
+- Check file exists before running
+
+### V8 Flags Warning
+**Warning**: V8 flags (`v8Flags`) can break everything. Use only if necessary and test thoroughly. Not supported in production Cloudflare Workers.
+
+## Security Gotchas
+
+### Hardcoded Secrets
+❌ **Never** hardcode:
+```capnp
+(name = "API_KEY", text = "sk-1234567890")
+```
+
+✅ **Use env vars**:
+```capnp
+(name = "API_KEY", fromEnvironment = "API_KEY")
+```
+
+### Overly Broad Network Access
+❌ **Too permissive**:
+```capnp
+network = (allow = ["*"])  # Everything
+```
+
+✅ **Restrictive**:
+```capnp
+network = (allow = ["public"], deny = ["local"])
+```
+
+### Extractable Keys
+❌ **Extractable keys risky**:
+```capnp
+cryptoKey = (extractable = true, ...)
+```
+
+✅ **Non-extractable**:
+```capnp
+cryptoKey = (extractable = false, ...)
+```
+
+## Compatibility Changes
+
+### Breaking Change Migration
+When updating `compatibilityDate`:
+1. Review [compatibility dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/)
+2. Check flags enabled between old/new date
+3. Test locally with new date
+4. Update code for breaking changes
+5. Deploy with new date
+
+### Version Mismatch
+Workerd version = max compat date supported. If `compatibilityDate = "2025-01-01"` but workerd is v1.20241201.0, it fails. Update workerd binary.
+
+## Troubleshooting Steps
+
+1. **Enable verbose logging**: `workerd serve config.capnp --verbose`
+2. **Check logs**: Look for error messages, stack traces
+3. **Validate config**: `capnp compile -I. config.capnp`
+4. **Test bindings**: Log `Object.keys(env)` to verify
+5. **Check versions**: Workerd version vs compat date
+6. **Isolate issue**: Minimal repro config
+7. **Review schema**: [workerd.capnp](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp)
+
+See [configuration.md](./configuration.md) for config details, [patterns.md](./patterns.md) for working examples, [api.md](./api.md) for runtime APIs.

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

@@ -0,0 +1,216 @@
+# Workerd Patterns
+
+## Multi-Service Architecture
+```capnp
+const config :Workerd.Config = (
+  services = [
+    (name = "frontend", worker = (
+      modules = [(name = "index.js", esModule = embed "frontend/index.js")],
+      compatibilityDate = "2024-01-15",
+      bindings = [(name = "API", service = "api")]
+    )),
+    
+    (name = "api", worker = (
+      modules = [(name = "index.js", esModule = embed "api/index.js")],
+      compatibilityDate = "2024-01-15",
+      bindings = [
+        (name = "DB", service = "postgres"),
+        (name = "CACHE", kvNamespace = "kv"),
+      ]
+    )),
+    
+    (name = "postgres", external = (address = "db.internal:5432", http = ())),
+    (name = "kv", disk = (path = "/var/kv", writable = true)),
+  ],
+  
+  sockets = [(name = "http", address = "*:8080", http = (), service = "frontend")]
+);
+```
+
+## Durable Objects
+```capnp
+const config :Workerd.Config = (
+  services = [
+    (name = "app", worker = (
+      modules = [
+        (name = "index.js", esModule = embed "index.js"),
+        (name = "room.js", esModule = embed "room.js"),
+      ],
+      compatibilityDate = "2024-01-15",
+      bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
+      durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
+      durableObjectStorage = (localDisk = "/var/do")
+    ))
+  ],
+  sockets = [(name = "http", address = "*:8080", http = (), service = "app")]
+);
+```
+
+## Dev vs Prod Configs
+```capnp
+const devWorker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "src/index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [
+    (name = "API_URL", text = "http://localhost:3000"),
+    (name = "DEBUG", text = "true"),
+  ]
+);
+
+const prodWorker :Workerd.Worker = (
+  inherit = "dev-service",
+  bindings = [
+    (name = "API_URL", text = "https://api.prod.com"),
+    (name = "DEBUG", text = "false"),
+  ]
+);
+```
+
+## HTTP Reverse Proxy
+```capnp
+const config :Workerd.Config = (
+  services = [
+    (name = "proxy", worker = (
+      serviceWorkerScript = embed "proxy.js",
+      compatibilityDate = "2024-01-15",
+      bindings = [(name = "BACKEND", service = "backend")]
+    )),
+    (name = "backend", external = (address = "internal:8080", http = ()))
+  ],
+  sockets = [(name = "http", address = "*:80", http = (), service = "proxy")]
+);
+```
+
+## Local Development
+
+### Using Wrangler
+```bash
+export MINIFLARE_WORKERD_PATH="/path/to/workerd"
+wrangler dev
+```
+
+### Direct Workerd
+```bash
+workerd serve config.capnp --socket-addr http=*:3000 --verbose
+```
+
+### Environment Variables
+```capnp
+bindings = [
+  (name = "DATABASE_URL", fromEnvironment = "DATABASE_URL"),
+  (name = "API_KEY", fromEnvironment = "API_KEY"),
+]
+```
+
+```bash
+export DATABASE_URL="postgres://..."
+export API_KEY="secret"
+workerd serve config.capnp
+```
+
+## Testing
+
+### Test Config
+```capnp
+const testWorker :Workerd.Worker = (
+  modules = [
+    (name = "index.js", esModule = embed "src/index.js"),
+    (name = "test.js", esModule = embed "tests/test.js"),
+  ],
+  compatibilityDate = "2024-01-15"
+);
+```
+
+```bash
+workerd test config.capnp
+workerd test config.capnp --test-only=test.js
+```
+
+## Production Deployment
+
+### Systemd
+```ini
+# /etc/systemd/system/workerd.service
+[Unit]
+Description=workerd runtime
+After=network-online.target
+Requires=workerd.socket
+
+[Service]
+Type=exec
+ExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3
+Restart=always
+User=nobody
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```ini
+# /etc/systemd/system/workerd.socket
+[Socket]
+ListenStream=0.0.0.0:80
+
+[Install]
+WantedBy=sockets.target
+```
+
+### Docker
+```dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y ca-certificates
+COPY workerd /usr/local/bin/
+COPY config.capnp /etc/workerd/
+COPY src/ /etc/workerd/src/
+EXPOSE 8080
+CMD ["workerd", "serve", "/etc/workerd/config.capnp"]
+```
+
+### Compiled Binary
+```bash
+workerd compile config.capnp myConfig -o production-server
+./production-server
+```
+
+## Best Practices
+
+1. **Use ES modules** over service worker syntax
+2. **Explicit bindings** - no global namespace assumptions
+3. **Type safety** - define `Env` interfaces
+4. **Service isolation** - split concerns
+5. **Pin compat date** in production after testing
+6. **Use ctx.waitUntil()** for background tasks
+7. **Handle errors gracefully** with try/catch
+8. **Configure resource limits** on caches/storage
+
+## Error Handling Pattern
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      return await handleRequest(request, env);
+    } catch (error) {
+      console.error("Request failed", error);
+      return new Response("Internal Error", {status: 500});
+    }
+  }
+};
+```
+
+## Logging Pattern
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    console.log("Request", {method: request.method, url: request.url});
+    
+    ctx.waitUntil(
+      logToAnalytics(request, env)
+    );
+    
+    return new Response("OK");
+  }
+};
+```
+
+See [configuration.md](./configuration.md) for config syntax, [api.md](./api.md) for runtime APIs, [gotchas.md](./gotchas.md) for common errors.

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

@@ -0,0 +1,96 @@
+# Cloudflare Workers
+
+Expert guidance for building, deploying, and optimizing Cloudflare Workers applications.
+
+## Overview
+
+Cloudflare Workers run on V8 isolates (NOT containers/VMs):
+- Extremely fast cold starts (< 1ms)
+- Global deployment across 300+ locations
+- Web standards compliant (fetch, URL, Headers, Request, Response)
+- Support JS/TS, Python, Rust, and WebAssembly
+
+**Key principle**: Workers use web platform APIs wherever possible for portability.
+
+## Module Worker Pattern (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return new Response('Hello World!');
+  },
+};
+```
+
+**Handler parameters**:
+- `request`: Incoming HTTP request (standard Request object)
+- `env`: Environment bindings (KV, D1, R2, secrets, vars)
+- `ctx`: Execution context (`waitUntil`, `passThroughOnException`)
+
+## Essential Commands
+
+```bash
+npx wrangler dev                    # Local dev
+npx wrangler dev --remote           # Remote dev (actual resources)
+npx wrangler deploy                 # Production
+npx wrangler deploy --env staging   # Specific environment
+npx wrangler tail                   # Stream logs
+npx wrangler secret put API_KEY     # Set secret
+```
+
+## When to Use Workers
+
+- API endpoints at the edge
+- Request/response transformation
+- Authentication/authorization layers
+- Static asset optimization
+- A/B testing and feature flags
+- Rate limiting and security
+- Proxy/routing logic
+- WebSocket applications
+
+## Quick Start
+
+```bash
+npm create cloudflare@latest my-worker -- --type hello-world
+cd my-worker
+npx wrangler dev
+```
+
+## Handler Signatures
+
+```typescript
+// HTTP requests
+async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>
+
+// Cron triggers
+async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void>
+
+// Queue consumer
+async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void>
+
+// Tail consumer
+async tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promise<void>
+```
+
+## Resources
+
+**Docs**: https://developers.cloudflare.com/workers/  
+**Examples**: https://developers.cloudflare.com/workers/examples/  
+**Runtime APIs**: https://developers.cloudflare.com/workers/runtime-apis/
+
+## In This Reference
+
+- [Configuration](./configuration.md) - wrangler.jsonc setup, bindings, environments
+- [API](./api.md) - Runtime APIs, bindings, execution context
+- [Patterns](./patterns.md) - Common workflows, testing, optimization
+- [Gotchas](./gotchas.md) - Common issues, limits, troubleshooting
+
+## See Also
+
+- [KV](../kv/README.md) - Key-value storage
+- [D1](../d1/README.md) - SQL database
+- [R2](../r2/README.md) - Object storage
+- [Durable Objects](../durable-objects/README.md) - Stateful coordination
+- [Queues](../queues/README.md) - Message queues
+- [Wrangler](../wrangler/README.md) - CLI tool reference