@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,112 @@
+# Queues Gotchas & Troubleshooting
+
+## Idempotency Required
+
+At-least-once delivery means duplicates possible. Design consumers to handle duplicates:
+
+```typescript
+// ✅ GOOD: Track processed messages
+const processed = await env.PROCESSED_KV.get(msg.id);
+if (processed) { msg.ack(); continue; }
+await processMessage(msg.body);
+await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });
+msg.ack();
+```
+
+## Content Type Visibility
+
+- `json`: Visible in dashboard, works with pull consumers
+- `v8`: NOT decodable by pull consumers or dashboard
+- Use `json` for pull consumers
+
+```typescript
+// ✅ For pull consumers
+await env.MY_QUEUE.send(data, { contentType: 'json' });
+
+// ❌ Avoid v8 with pull
+await env.MY_QUEUE.send(new Date(), { contentType: 'v8' }); // Can't decode
+```
+
+## Retry Behavior
+
+```typescript
+// If you DON'T call ack() or retry(), message retries automatically
+async queue(batch: MessageBatch): Promise<void> {
+  for (const msg of batch.messages) {
+    try {
+      await processMessage(msg.body);
+      msg.ack(); // Explicit success
+    } catch (error) {
+      // Don't call retry() - auto-retries with configured delay
+      // OR call retry() with custom delay
+      msg.retry({ delaySeconds: 600 });
+    }
+  }
+}
+```
+
+## CPU Time Limits
+
+Default: 30s per consumer invocation. Increase if needed:
+
+```jsonc
+{ "limits": { "cpu_ms": 300000 } } // 5 minutes
+```
+
+## Cost Optimization
+
+Operations: write + read + delete = 3 ops per message  
+Retries add read ops  
+Formula: `((messages × 3) - 1M) / 1M × $0.40` per month
+
+```typescript
+// Keep messages <64 KB (charged per 64 KB chunk)
+// Batch aggressively to reduce frequency
+{ "max_batch_size": 100, "max_batch_timeout": 30 }
+```
+
+## Message Not Delivered
+
+```bash
+# Check queue paused
+wrangler queues list
+
+# Verify consumer configured
+wrangler queues consumer worker remove my-queue my-worker
+wrangler queues consumer add my-queue my-worker
+
+# Check logs for errors
+wrangler tail my-worker
+```
+
+## High DLQ Rate
+
+- Review consumer error logs
+- Check external dependency availability
+- Verify message format matches expectations
+- Increase retry delay: `"retry_delay": 300`
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max queues | 10,000 |
+| Message size | 128 KB |
+| Batch size (consumer) | 100 messages |
+| Batch size (sendBatch) | 100 msgs/256 KB |
+| Throughput | 5,000 msgs/sec/queue |
+| Retention | 4-14 days |
+| Max backlog | 25 GB |
+| Max delay | 12 hours (43,200s) |
+| Max retries | 100 |
+
+## Best Practices
+
+- ✅ Design for idempotency (at-least-once delivery)
+- ✅ Use `json` content type for visibility
+- ✅ Log failures with context
+- ✅ Configure DLQ for permanent failures
+- ✅ Use `waitUntil()` for non-blocking sends
+- ✅ Batch sends when possible
+- ❌ Don't use v8 with pull consumers
+- ❌ Don't rely on message ordering

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

@@ -0,0 +1,155 @@
+# Queues Patterns & Best Practices
+
+## Async Task Processing
+
+```typescript
+// Producer: Accept request, queue work
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const { userId, reportType } = await request.json();
+    await env.REPORT_QUEUE.send({ userId, reportType, requestedAt: Date.now() });
+    return Response.json({ message: 'Report queued', status: 'pending' });
+  }
+};
+
+// Consumer: Process reports
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      const { userId, reportType } = msg.body;
+      const report = await generateReport(userId, reportType, env);
+      await env.REPORTS_BUCKET.put(`${userId}/${reportType}.pdf`, report);
+      msg.ack();
+    }
+  }
+};
+```
+
+## Buffering API Calls
+
+```typescript
+// Producer: Queue log entries
+ctx.waitUntil(env.LOGS_QUEUE.send({
+  method: request.method,
+  url: request.url,
+  timestamp: Date.now()
+}));
+
+// Consumer: Batch write to external API
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  const logs = batch.messages.map(m => m.body);
+  await fetch(env.LOG_ENDPOINT, { method: 'POST', body: JSON.stringify({ logs }) });
+  batch.ackAll();
+}
+```
+
+## Rate Limiting Upstream
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    try {
+      await callRateLimitedAPI(msg.body);
+      msg.ack();
+    } catch (error) {
+      if (error.status === 429) {
+        const retryAfter = parseInt(error.headers.get('Retry-After') || '60');
+        msg.retry({ delaySeconds: retryAfter });
+      } else throw error;
+    }
+  }
+}
+```
+
+## Event-Driven Workflows
+
+```typescript
+// R2 event → Queue → Worker
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      const event = msg.body;
+      if (event.action === 'PutObject') {
+        await processNewFile(event.object.key, env);
+      } else if (event.action === 'DeleteObject') {
+        await cleanupReferences(event.object.key, env);
+      }
+      msg.ack();
+    }
+  }
+};
+```
+
+## Dead Letter Queue Pattern
+
+```typescript
+// Main queue: After max_retries, goes to DLQ automatically
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      try {
+        await riskyOperation(msg.body);
+        msg.ack();
+      } catch (error) {
+        console.error(`Failed after ${msg.attempts} attempts:`, error);
+      }
+    }
+  }
+};
+
+// DLQ consumer: Log and store failed messages
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      await env.FAILED_KV.put(msg.id, JSON.stringify(msg.body));
+      msg.ack();
+    }
+  }
+};
+```
+
+## Priority Queues
+
+High priority: `max_batch_size: 5, max_batch_timeout: 1`. Low priority: `max_batch_size: 100, max_batch_timeout: 30`.
+
+## Delayed Job Processing
+
+```typescript
+await env.EMAIL_QUEUE.send({ to, template, userId }, { delaySeconds: 3600 });
+```
+
+## Fan-out Pattern
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const event = await request.json();
+  
+  // Send to multiple queues for parallel processing
+  await Promise.all([
+    env.ANALYTICS_QUEUE.send(event),
+    env.NOTIFICATIONS_QUEUE.send(event),
+    env.AUDIT_LOG_QUEUE.send(event)
+  ]);
+  
+  return Response.json({ status: 'processed' });
+}
+```
+
+## Idempotency Pattern
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    // Check if already processed
+    const processed = await env.PROCESSED_KV.get(msg.id);
+    if (processed) {
+      msg.ack();
+      continue;
+    }
+    
+    await processMessage(msg.body);
+    await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });
+    msg.ack();
+  }
+}
+```

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

@@ -0,0 +1,61 @@
+# Cloudflare R2 Object Storage
+
+S3-compatible object storage with zero egress fees, optimized for large file storage and delivery.
+
+## Overview
+
+R2 provides:
+- S3-compatible API (Workers API + S3 REST)
+- Zero egress fees globally
+- Strong consistency for writes/deletes
+- Storage classes (Standard/Infrequent Access)
+- SSE-C encryption support
+
+**Use cases:** Media storage, backups, static assets, user uploads, data lakes
+
+## Quick Start
+
+```bash
+wrangler r2 bucket create my-bucket --location=enam
+wrangler r2 object put my-bucket/file.txt --file=./local.txt
+```
+
+```typescript
+// Upload
+await env.MY_BUCKET.put(key, data, {
+  httpMetadata: { contentType: 'image/jpeg' }
+});
+
+// Download
+const object = await env.MY_BUCKET.get(key);
+if (object) return new Response(object.body);
+```
+
+## Core Operations
+
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `put(key, value, options?)` | Upload object | `R2Object \| null` |
+| `get(key, options?)` | Download object | `R2ObjectBody \| R2Object \| null` |
+| `head(key)` | Get metadata only | `R2Object \| null` |
+| `delete(keys)` | Delete object(s) | `Promise<void>` |
+| `list(options?)` | List objects | `R2Objects` |
+
+## Storage Classes
+
+- **Standard**: Frequent access, low latency reads
+- **InfrequentAccess**: 30-day minimum storage, retrieval fees, lower storage cost
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc bindings, S3 SDK setup, location hints
+- [api.md](./api.md) - Workers API methods, multipart uploads, conditional requests
+- [patterns.md](./patterns.md) - Streaming, caching, presigned URLs, storage transitions
+- [gotchas.md](./gotchas.md) - List truncation, etag format, checksum limits, multipart pitfalls
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handlers
+- [kv](../kv/) - Metadata storage for R2 objects
+- [d1](../d1/) - Store R2 URLs in relational database
+- [queues](../queues/) - Process R2 uploads asynchronously

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

@@ -0,0 +1,127 @@
+# R2 API Reference
+
+## PUT (Upload)
+
+```typescript
+// Basic
+await env.MY_BUCKET.put(key, value);
+
+// With metadata
+await env.MY_BUCKET.put(key, value, {
+  httpMetadata: {
+    contentType: 'image/jpeg',
+    contentDisposition: 'attachment; filename="photo.jpg"',
+    cacheControl: 'max-age=3600'
+  },
+  customMetadata: { userId: '123', version: '2' },
+  storageClass: 'Standard', // or 'InfrequentAccess'
+  sha256: arrayBufferOrHex, // Integrity check
+  ssecKey: arrayBuffer32bytes // SSE-C encryption
+});
+
+// Value types: ReadableStream | ArrayBuffer | string | Blob
+```
+
+## GET (Download)
+
+```typescript
+const object = await env.MY_BUCKET.get(key);
+if (!object) return new Response('Not found', { status: 404 });
+
+// Body formats
+const buffer = await object.arrayBuffer();
+const text = await object.text();
+const json = await object.json();
+const stream = object.body; // ReadableStream
+
+// Ranged reads
+const object = await env.MY_BUCKET.get(key, {
+  range: { offset: 0, length: 1024 }
+});
+
+// Conditional GET
+const object = await env.MY_BUCKET.get(key, {
+  onlyIf: { etagMatches: '"abc123"' }
+});
+```
+
+## HEAD (Metadata Only)
+
+```typescript
+const object = await env.MY_BUCKET.head(key);
+console.log(object?.size, object?.etag, object?.storageClass);
+```
+
+## DELETE
+
+```typescript
+await env.MY_BUCKET.delete(key);
+await env.MY_BUCKET.delete([key1, key2, key3]); // Batch (max 1000)
+```
+
+## LIST
+
+```typescript
+const listed = await env.MY_BUCKET.list({
+  limit: 1000,
+  prefix: 'photos/',
+  cursor: cursorFromPrevious,
+  delimiter: '/',
+  include: ['httpMetadata', 'customMetadata']
+});
+
+// Pagination (always use truncated flag)
+while (listed.truncated) {
+  const next = await env.MY_BUCKET.list({ cursor: listed.cursor });
+  listed.objects.push(...next.objects);
+  listed.truncated = next.truncated;
+  listed.cursor = next.cursor;
+}
+```
+
+## Multipart Uploads
+
+```typescript
+const multipart = await env.MY_BUCKET.createMultipartUpload(key, {
+  httpMetadata: { contentType: 'video/mp4' }
+});
+
+const uploadedParts: R2UploadedPart[] = [];
+for (let i = 0; i < partCount; i++) {
+  const part = await multipart.uploadPart(i + 1, partData);
+  uploadedParts.push(part);
+}
+
+const object = await multipart.complete(uploadedParts);
+// OR: await multipart.abort();
+
+// Resume
+const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
+```
+
+## R2Object Interface
+
+```typescript
+interface R2Object {
+  key: string;
+  version: string;
+  size: number;
+  etag: string; // Unquoted
+  httpEtag: string; // Quoted (use for headers)
+  uploaded: Date;
+  httpMetadata: R2HTTPMetadata;
+  customMetadata: Record<string, string>;
+  storageClass: 'Standard' | 'InfrequentAccess';
+  checksums: R2Checksums;
+  writeHttpMetadata(headers: Headers): void;
+}
+```
+
+## CLI Operations
+
+```bash
+wrangler r2 object put my-bucket/file.txt --file=./local.txt --content-type=text/plain
+wrangler r2 object get my-bucket/file.txt --file=./download.txt
+wrangler r2 object delete my-bucket/file.txt
+wrangler r2 object list my-bucket --prefix=photos/ --delimiter=/
+```

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

@@ -0,0 +1,76 @@
+# R2 Configuration
+
+## Workers Binding
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "r2_buckets": [
+    {
+      "binding": "MY_BUCKET",
+      "bucket_name": "my-bucket-name"
+    }
+  ]
+}
+```
+
+**wrangler.toml:**
+```toml
+[[r2_buckets]]
+binding = 'MY_BUCKET'
+bucket_name = 'my-bucket-name'
+```
+
+## TypeScript Types
+
+```typescript
+interface Env { MY_BUCKET: R2Bucket; }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const object = await env.MY_BUCKET.get('file.txt');
+    return new Response(object?.body);
+  }
+}
+```
+
+## S3 SDK Setup
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+
+const s3 = new S3Client({
+  region: 'auto',
+  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+  credentials: {
+    accessKeyId: env.R2_ACCESS_KEY_ID,
+    secretAccessKey: env.R2_SECRET_ACCESS_KEY
+  }
+});
+
+await s3.send(new PutObjectCommand({
+  Bucket: 'my-bucket',
+  Key: 'file.txt',
+  Body: data,
+  StorageClass: 'STANDARD' // or 'STANDARD_IA'
+}));
+```
+
+## Location Hints
+
+```bash
+wrangler r2 bucket create my-bucket --location=enam
+
+# Hints: wnam, enam, weur, eeur, apac, oc
+# Jurisdictions (override hint): --jurisdiction=eu (or fedramp)
+```
+
+## Bucket Management
+
+```bash
+wrangler r2 bucket create my-bucket --location=enam --storage-class=Standard
+wrangler r2 bucket list
+wrangler r2 bucket info my-bucket
+wrangler r2 bucket delete my-bucket  # Must be empty
+wrangler r2 bucket update-storage-class my-bucket --storage-class=InfrequentAccess
+```

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

@@ -0,0 +1,94 @@
+# R2 Gotchas & Troubleshooting
+
+## List Truncation
+
+```typescript
+// ❌ WRONG: Don't compare object count when using include
+while (listed.objects.length < options.limit) { ... }
+
+// ✅ CORRECT: Always use truncated property
+while (listed.truncated) {
+  const next = await env.MY_BUCKET.list({ cursor: listed.cursor });
+  // ...
+}
+```
+
+**Reason:** `include` with metadata may return fewer objects per page to fit metadata.
+
+## ETag Format
+
+```typescript
+// ❌ WRONG: Using etag (unquoted) in headers
+headers.set('etag', object.etag); // Missing quotes
+
+// ✅ CORRECT: Use httpEtag (quoted)
+headers.set('etag', object.httpEtag);
+```
+
+## Checksum Limits
+
+Only ONE checksum algorithm allowed per PUT:
+
+```typescript
+// ❌ WRONG: Multiple checksums
+await env.MY_BUCKET.put(key, data, { md5: hash1, sha256: hash2 }); // Error
+
+// ✅ CORRECT: Pick one
+await env.MY_BUCKET.put(key, data, { sha256: hash });
+```
+
+## Multipart Requirements
+
+- All parts must be uniform size (except last part)
+- Part numbers start at 1 (not 0)
+- Uncompleted uploads auto-abort after 7 days
+- `resumeMultipartUpload` doesn't validate uploadId existence
+
+## Conditional Operations
+
+```typescript
+// Precondition failure returns object WITHOUT body
+const object = await env.MY_BUCKET.get(key, {
+  onlyIf: { etagMatches: '"wrong"' }
+});
+
+// Check for body, not just null
+if (!object) return new Response('Not found', { status: 404 });
+if (!object.body) return new Response(null, { status: 304 }); // Precondition failed
+```
+
+## Key Validation
+
+```typescript
+// ❌ DANGEROUS: Path traversal
+const key = url.pathname.slice(1); // Could be ../../../etc/passwd
+await env.MY_BUCKET.get(key);
+
+// ✅ SAFE: Validate keys
+if (!key || key.includes('..') || key.startsWith('/')) {
+  return new Response('Invalid key', { status: 400 });
+}
+```
+
+## Storage Class Pitfalls
+
+- InfrequentAccess: 30-day minimum billing (even if deleted early)
+- Can't transition IA → Standard via lifecycle (use S3 CopyObject)
+- Retrieval fees apply for IA reads
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Object size | 5 TB |
+| Multipart part count | 10,000 |
+| Batch delete | 1,000 keys |
+| List limit | 1,000 per request |
+| Key size | 1024 bytes |
+| Custom metadata | 2 KB per object |
+
+## Common Errors
+
+**"oldString not found"**: Object key doesn't exist  
+**List compatibility_date**: Set `compatibility_date >= 2022-08-04` or enable `r2_list_honor_include` flag  
+**Multipart part size**: Ensure uniform size except final part