opencodekit 0.15.4 → 0.15.5

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

@@ -0,0 +1,23 @@
+## Best Practices
+
+### 1. Use Appropriate Fit Modes
+- `cover`: Hero images, thumbnails, avatars (fills space, crops)
+- `contain`: Product images, artwork (preserves full image)
+- `scale-down`: Ensure images aren't unnecessarily enlarged
+
+### 2. Format Selection
+- Use `format=auto` for automatic AVIF/WebP/JPEG selection
+- For Workers, parse `Accept` header for format negotiation
+- AVIF: Best compression, use for modern browsers
+- WebP: Wide support, good compression
+- JPEG: Fallback for older browsers
+
+### 3. Quality Settings
+- `85`: Good default balance
+- `90-95`: High-quality images (portfolios, product photos)
+- `75-80`: Acceptable quality for faster loading
+- WebP lossless: `quality=100`
+
+### 4. Responsive Images
+- Use `srcset` with multiple widths (400w, 800w, 1200w)
+- Set appropriate 

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

@@ -0,0 +1,31 @@
+#### Common Options
+
+```
+width=<PIXELS>         # w=<PIXELS> (alias)
+height=<PIXELS>        # h=<PIXELS> (alias)
+fit=scale-down         # scale-down|contain|cover|crop|pad|squeeze
+quality=85             # q=85 (1-100)
+format=auto            # f=auto (auto|webp|avif|jpeg|png)
+dpr=2                  # Device Pixel Ratio (1-3)
+gravity=auto           # auto|left|right|top|bottom|face|0.5x0.5
+sharpen=2              # 0-10
+blur=10                # 1-250
+rotate=90              # 90|180|270
+background=white       # CSS color for pad fit mode
+metadata=none          # none|copyright|keep
+```
+
+### Transform via Workers
+
+Use Cloudflare Workers for programmatic control:
+
+```typescript
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    
+    // Parse Accept header for format negotiation
+    const accept = request.headers.get('Accept') || '';
+    let format: 'avif' | 'webp' | undefined;
+    if (/image\/avif/.test(accept)) {
+      format = 'a

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

@@ -0,0 +1,60 @@
+# Cloudflare Workers KV
+
+Globally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.
+
+## Overview
+
+KV provides:
+- Eventual consistency (60s global propagation)
+- Read-optimized performance
+- 25 MiB value limit per key
+- Auto-replication to Cloudflare edge
+- Metadata support (1024 bytes)
+
+**Use cases:** Config storage, user sessions, feature flags, caching, A/B testing
+
+## Quick Start
+
+```bash
+wrangler kv namespace create MY_NAMESPACE
+# Add binding to wrangler.jsonc
+```
+
+```typescript
+// Write
+await env.MY_KV.put("key", "value", { expirationTtl: 300 });
+
+// Read
+const value = await env.MY_KV.get("key");
+const json = await env.MY_KV.get<Config>("config", "json");
+```
+
+## Core Operations
+
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `get(key, type?)` | Single read | `string \| null` |
+| `get(keys, type?)` | Bulk read (≤100) | `Map<string, T \| null>` |
+| `put(key, value, options?)` | Write | `Promise<void>` |
+| `delete(key)` | Delete | `Promise<void>` |
+| `list(options?)` | List keys | `{ keys, list_complete, cursor? }` |
+| `getWithMetadata(key)` | Get + metadata | `{ value, metadata }` |
+
+## Consistency Model
+
+- **Write visibility:** Immediate in same location, ≤60s globally
+- **Read path:** Eventually consistent
+- **Write rate:** 1 write/second per key (429 on exceed)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, namespace creation, TypeScript types
+- [api.md](./api.md) - KV methods, bulk operations, cacheTtl, content types
+- [patterns.md](./patterns.md) - Caching, sessions, rate limiting, A/B testing
+- [gotchas.md](./gotchas.md) - Eventual consistency, concurrent writes, value limits
+
+## See Also
+
+- [workers](../workers/) - Worker runtime for KV access
+- [d1](../d1/) - Use D1 for strong consistency needs
+- [durable-objects](../durable-objects/) - Strongly consistent alternative

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

@@ -0,0 +1,114 @@
+# KV API Reference
+
+## Read Operations
+
+```typescript
+// Single key (string)
+const value = await env.MY_KV.get("user:123");
+
+// JSON type (auto-parsed)
+const config = await env.MY_KV.get<AppConfig>("config", "json");
+
+// ArrayBuffer for binary
+const buffer = await env.MY_KV.get("image", "arrayBuffer");
+
+// Stream for large values
+const stream = await env.MY_KV.get("large-file", "stream");
+
+// With cache TTL (min 60s)
+const value = await env.MY_KV.get("key", { type: "text", cacheTtl: 300 });
+
+// Bulk get (max 100 keys, counts as 1 operation)
+const values = await env.MY_KV.get(["user:1", "user:2", "user:3"]);
+// Returns Map<string, string | null>
+
+const configs = await env.MY_KV.get<Config>(["config:app", "config:feature"], "json");
+```
+
+## Write Operations
+
+```typescript
+// Basic put
+await env.MY_KV.put("key", "value");
+await env.MY_KV.put("config", JSON.stringify({ theme: "dark" }));
+
+// With expiration (UNIX timestamp)
+await env.MY_KV.put("session", token, {
+  expiration: Math.floor(Date.now() / 1000) + 3600
+});
+
+// With TTL (seconds from now, min 60)
+await env.MY_KV.put("cache", data, { expirationTtl: 300 });
+
+// With metadata (max 1024 bytes)
+await env.MY_KV.put("user:profile", userData, {
+  metadata: { version: 2, lastUpdated: Date.now() }
+});
+
+// Combined
+await env.MY_KV.put("temp", value, {
+  expirationTtl: 3600,
+  metadata: { temporary: true }
+});
+```
+
+## Get with Metadata
+
+```typescript
+// Single key
+const result = await env.MY_KV.getWithMetadata("user:profile");
+// { value: string | null, metadata: any | null }
+
+if (result.value && result.metadata) {
+  const { version, lastUpdated } = result.metadata;
+}
+
+// Multiple keys
+const results = await env.MY_KV.getWithMetadata(["key1", "key2"]);
+// Returns Map<string, { value, metadata }>
+
+// With type
+const result = await env.MY_KV.getWithMetadata<UserData>("user:123", "json");
+```
+
+## Delete Operations
+
+```typescript
+await env.MY_KV.delete("key"); // Always succeeds (even if key missing)
+```
+
+## List Operations
+
+```typescript
+// List all
+const keys = await env.MY_KV.list();
+// { keys: [...], list_complete: boolean, cursor?: string }
+
+// With prefix
+const userKeys = await env.MY_KV.list({ prefix: "user:" });
+
+// Pagination
+let cursor: string | undefined;
+let allKeys = [];
+do {
+  const result = await env.MY_KV.list({ cursor, limit: 1000 });
+  allKeys.push(...result.keys);
+  cursor = result.cursor;
+} while (!result.list_complete);
+```
+
+## Limits
+
+| Limit | Free | Paid |
+|-------|------|------|
+| Reads/day | 100,000 | Unlimited |
+| Writes/day | 1,000 | Unlimited |
+| Writes/second per key | 1 | 1 |
+| Operations per Worker | 1,000 | 1,000 |
+| Key size | 512 bytes | 512 bytes |
+| Value size | 25 MiB | 25 MiB |
+| Metadata size | 1024 bytes | 1024 bytes |
+| Min cacheTtl | 60s | 60s |
+| Bulk get max | 100 keys | 100 keys |
+
+**Note:** Bulk requests count as 1 operation against 1,000 limit.

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

@@ -0,0 +1,92 @@
+# KV Configuration
+
+## Create Namespace
+
+```bash
+wrangler kv namespace create MY_NAMESPACE
+# Output: { binding = "MY_NAMESPACE", id = "abc123..." }
+
+wrangler kv namespace create MY_NAMESPACE --preview  # For local dev
+```
+
+## Workers Binding
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "kv_namespaces": [
+    {
+      "binding": "MY_KV",
+      "id": "abc123xyz789"
+    }
+  ]
+}
+```
+
+**wrangler.toml:**
+```toml
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "abc123xyz789"
+```
+
+## TypeScript Types
+
+```typescript
+interface Env { MY_KV: KVNamespace; }
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const value = await env.MY_KV.get("key");
+    return new Response(value || "Not found");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## CLI Operations
+
+```bash
+# Put
+wrangler kv key put --binding=MY_KV "key" "value"
+wrangler kv key put --binding=MY_KV "key" --path=./file.json --ttl=3600
+
+# Get
+wrangler kv key get --binding=MY_KV "key"
+
+# Delete
+wrangler kv key delete --binding=MY_KV "key"
+
+# List
+wrangler kv key list --binding=MY_KV --prefix="user:"
+
+# Bulk operations (max 10,000 keys per file)
+wrangler kv bulk put data.json --binding=MY_KV
+wrangler kv bulk get keys.json --binding=MY_KV
+wrangler kv bulk delete keys.json --binding=MY_KV --force
+```
+
+## Local Development
+
+```bash
+wrangler dev                # Local KV (isolated)
+wrangler dev --remote       # Remote KV (production)
+
+# Or in wrangler.jsonc:
+# "kv_namespaces": [{ "binding": "MY_KV", "id": "...", "remote": true }]
+```
+
+## REST API
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiEmail: process.env.CLOUDFLARE_EMAIL,
+  apiKey: process.env.CLOUDFLARE_API_KEY
+});
+
+await client.kv.namespaces.values.update(namespaceId, 'key', {
+  account_id: accountId,
+  value: 'value'
+});
+```

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

@@ -0,0 +1,117 @@
+# KV Gotchas & Troubleshooting
+
+## Eventual Consistency
+
+```typescript
+// ❌ BAD: Read immediately after write (may see stale globally)
+await env.MY_KV.put("key", "value");
+const value = await env.MY_KV.get("key"); // May be null in other regions
+
+// ✅ GOOD: Return confirmation without reading
+await env.MY_KV.put("key", "value");
+return new Response("Updated", { status: 200 });
+
+// ✅ GOOD: Use local value
+const newValue = "updated";
+await env.MY_KV.put("key", newValue);
+return new Response(newValue);
+```
+
+**Propagation:** Writes visible immediately in same location, ≤60s globally.
+
+## Concurrent Writes
+
+```typescript
+// ❌ BAD: Concurrent writes to same key (429 rate limit)
+await Promise.all([
+  env.MY_KV.put("counter", "1"),
+  env.MY_KV.put("counter", "2")
+]); // 429 error
+
+// ✅ GOOD: Sequential writes
+await env.MY_KV.put("counter", "3");
+
+// ✅ GOOD: Unique keys for concurrent writes
+await Promise.all([
+  env.MY_KV.put("counter:1", "1"),
+  env.MY_KV.put("counter:2", "2")
+]);
+
+// ✅ GOOD: Retry with backoff
+async function putWithRetry(kv: KVNamespace, key: string, value: string) {
+  let delay = 1000;
+  for (let i = 0; i < 5; i++) {
+    try {
+      await kv.put(key, value);
+      return;
+    } catch (err) {
+      if (err.message.includes("429") && i < 4) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+        delay *= 2;
+      } else throw err;
+    }
+  }
+}
+```
+
+**Limit:** 1 write/second per key (all plans).
+
+## Bulk Operations
+
+```typescript
+// ❌ BAD: Multiple individual gets (uses 3 operations)
+const user1 = await env.USERS.get("user:1");
+const user2 = await env.USERS.get("user:2");
+const user3 = await env.USERS.get("user:3");
+
+// ✅ GOOD: Single bulk get (uses 1 operation)
+const users = await env.USERS.get(["user:1", "user:2", "user:3"]);
+```
+
+**Note:** Bulk write NOT available in Workers (only via CLI/API).
+
+## Null Handling
+
+```typescript
+// ❌ BAD: No null check
+const value = await env.MY_KV.get("key");
+const result = value.toUpperCase(); // Error if null
+
+// ✅ GOOD: Check for null
+const value = await env.MY_KV.get("key");
+if (value === null) return new Response("Not found", { status: 404 });
+return new Response(value);
+
+// ✅ GOOD: Provide default
+const value = (await env.MY_KV.get("config")) ?? "default-config";
+```
+
+## Value Limits
+
+- Key size: 512 bytes max
+- Value size: 25 MiB max
+- Metadata: 1024 bytes max
+- cacheTtl: 60s minimum
+
+## Pricing
+
+- **Reads:** $0.50 per 10M
+- **Writes:** $5.00 per 1M
+- **Deletes:** $5.00 per 1M
+- **Storage:** $0.50 per GB-month
+
+## When NOT to Use
+
+- ❌ Strong consistency required → Durable Objects
+- ❌ Write-heavy workloads → D1 or Durable Objects
+- ❌ Relational queries → D1
+- ❌ Large files (>25 MiB) → R2
+- ❌ Atomic operations → Durable Objects
+
+## When TO Use
+
+- ✅ Read-heavy workloads
+- ✅ Global distribution needed
+- ✅ Eventually consistent acceptable
+- ✅ Key-value access patterns
+- ✅ Low-latency reads critical

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

@@ -0,0 +1,139 @@
+# KV Patterns & Best Practices
+
+## API Response Caching
+
+```typescript
+async function getCachedData(env: Env, key: string, fetcher: () => Promise<any>): Promise<any> {
+  const cached = await env.MY_KV.get(key, "json");
+  if (cached) return cached;
+  
+  const data = await fetcher();
+  await env.MY_KV.put(key, JSON.stringify(data), { expirationTtl: 300 });
+  return data;
+}
+
+const apiData = await getCachedData(
+  env,
+  "cache:users",
+  () => fetch("https://api.example.com/users").then(r => r.json())
+);
+```
+
+## Session Management
+
+```typescript
+interface Session { userId: string; expiresAt: number; }
+
+async function createSession(env: Env, userId: string): Promise<string> {
+  const sessionId = crypto.randomUUID();
+  const expiresAt = Date.now() + (24 * 60 * 60 * 1000);
+  
+  await env.SESSIONS.put(
+    `session:${sessionId}`,
+    JSON.stringify({ userId, expiresAt }),
+    { expirationTtl: 86400, metadata: { createdAt: Date.now() } }
+  );
+  
+  return sessionId;
+}
+
+async function getSession(env: Env, sessionId: string): Promise<Session | null> {
+  const data = await env.SESSIONS.get<Session>(`session:${sessionId}`, "json");
+  if (!data || data.expiresAt < Date.now()) return null;
+  return data;
+}
+```
+
+## Feature Flags
+
+```typescript
+async function getFeatureFlags(env: Env): Promise<Record<string, boolean>> {
+  return await env.CONFIG.get<Record<string, boolean>>(
+    "features:flags",
+    { type: "json", cacheTtl: 600 }
+  ) || {};
+}
+
+export default {
+  async fetch(request, env): Promise<Response> {
+    const flags = await getFeatureFlags(env);
+    if (flags.beta_feature) return handleBetaFeature(request);
+    return handleStandardFlow(request);
+  }
+};
+```
+
+## Rate Limiting
+
+```typescript
+async function rateLimit(env: Env, identifier: string, limit: number, windowSeconds: number): Promise<boolean> {
+  const key = `ratelimit:${identifier}`;
+  const now = Date.now();
+  const data = await env.MY_KV.get<{ count: number, resetAt: number }>(key, "json");
+  
+  if (!data || data.resetAt < now) {
+    await env.MY_KV.put(key, JSON.stringify({ count: 1, resetAt: now + windowSeconds * 1000 }), { expirationTtl: windowSeconds });
+    return true;
+  }
+  
+  if (data.count >= limit) return false;
+  
+  await env.MY_KV.put(key, JSON.stringify({ count: data.count + 1, resetAt: data.resetAt }), { expirationTtl: Math.ceil((data.resetAt - now) / 1000) });
+  return true;
+}
+```
+
+## A/B Testing
+
+```typescript
+async function getVariant(env: Env, userId: string, testName: string): Promise<string> {
+  const assigned = await env.AB_TESTS.get(`test:${testName}:user:${userId}`);
+  if (assigned) return assigned;
+  
+  const test = await env.AB_TESTS.get<{ variants: string[], weights: number[] }>(`test:${testName}:config`, { type: "json", cacheTtl: 3600 });
+  if (!test) return "control";
+  
+  const hash = await hashString(userId);
+  const random = (hash % 100) / 100;
+  let cumulative = 0, variant = test.variants[0];
+  
+  for (let i = 0; i < test.variants.length; i++) {
+    cumulative += test.weights[i];
+    if (random < cumulative) { variant = test.variants[i]; break; }
+  }
+  
+  await env.AB_TESTS.put(`test:${testName}:user:${userId}`, variant, { expirationTtl: 2592000 });
+  return variant;
+}
+```
+
+## Coalesce Cold Keys
+
+```typescript
+// ❌ BAD: Many individual keys
+await env.KV.put("user:123:name", "John");
+await env.KV.put("user:123:email", "john@example.com");
+
+// ✅ GOOD: Single coalesced object
+await env.USERS.put("user:123:profile", JSON.stringify({
+  name: "John",
+  email: "john@example.com",
+  role: "admin"
+}));
+
+// Benefits: Hot key cache, single read, reduced operations
+// Trade-off: Harder to update individual fields
+```
+
+## Hierarchical Keys
+
+```typescript
+// Use prefixes for organization
+"user:123:profile"
+"user:123:settings"
+"cache:api:users"
+"session:abc-def"
+"feature:flags:beta"
+
+const userKeys = await env.MY_KV.list({ prefix: "user:123:" });
+```

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

@@ -0,0 +1,64 @@
+# Miniflare
+
+Local simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.
+
+## Features
+
+- Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues
+- Fully-local: test without internet, instant reload
+- TypeScript-native: detailed logging, source maps
+- Advanced testing: dispatch events without HTTP, simulate Worker connections
+
+## When to Use
+
+- Integration tests for Workers
+- Advanced use cases requiring fine-grained control
+- Testing bindings/storage locally
+- Multiple Workers with service bindings
+
+**Note:** Most users should use Wrangler. Miniflare for advanced testing.
+
+## Setup
+
+```bash
+npm i -D miniflare
+```
+
+Requires ES modules in `package.json`:
+```json
+{"type": "module"}
+```
+
+## Quick Start
+
+```js
+import { Miniflare } from "miniflare";
+
+const mf = new Miniflare({
+  modules: true,
+  script: `
+    export default {
+      async fetch(request, env, ctx) {
+        return new Response("Hello Miniflare!");
+      }
+    }
+  `,
+});
+
+const res = await mf.dispatchFetch("http://localhost:8787/");
+console.log(await res.text()); // Hello Miniflare!
+await mf.dispose();
+```
+
+## See Also
+
+- [configuration.md](./configuration.md) - Config options, bindings, wrangler.toml
+- [api.md](./api.md) - Programmatic API, methods, event dispatching
+- [patterns.md](./patterns.md) - Testing patterns, CI, mocking
+- [gotchas.md](./gotchas.md) - Compatibility issues, limits, debugging
+
+## Resources
+
+- [Miniflare Docs](https://developers.cloudflare.com/workers/testing/miniflare/)
+- [Miniflare GitHub](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare)
+- [Vitest Integration](https://developers.cloudflare.com/workers/testing/vitest-integration/) (recommended)