@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/images/configuration.md

@@ -0,0 +1,211 @@
+# Configuration
+
+## Wrangler Integration
+
+### Workers Binding Setup
+
+Add to `wrangler.toml`:
+
+```toml
+name = "my-image-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[images]
+binding = "IMAGES"
+```
+
+Access in Worker:
+
+```typescript
+interface Env {
+  IMAGES: ImageBinding;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return await env.IMAGES
+      .input(imageBuffer)
+      .transform({ width: 800 })
+      .output()
+      .response();
+  }
+};
+```
+
+### Upload via Script
+
+Wrangler doesn't have built-in Images commands, use REST API:
+
+```typescript
+// scripts/upload-image.ts
+import fs from 'fs';
+import FormData from 'form-data';
+
+async function uploadImage(filePath: string) {
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID!;
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN!;
+  
+  const formData = new FormData();
+  formData.append('file', fs.createReadStream(filePath));
+  
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v1`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+      },
+      body: formData,
+    }
+  );
+  
+  const result = await response.json();
+  console.log('Uploaded:', result);
+}
+
+uploadImage('./photo.jpg');
+```
+
+### Environment Variables
+
+Store account hash for URL construction:
+
+```toml
+[vars]
+IMAGES_ACCOUNT_HASH = "your-account-hash"
+ACCOUNT_ID = "your-account-id"
+```
+
+Access in Worker:
+
+```typescript
+const imageUrl = `https://imagedelivery.net/${env.IMAGES_ACCOUNT_HASH}/${imageId}/public`;
+```
+
+## Variants Configuration
+
+Variants are named presets for transformations.
+
+### Create Variant (Dashboard)
+
+1. Navigate to Images → Variants
+2. Click "Create Variant"
+3. Set name (e.g., `thumbnail`)
+4. Configure: `width=200,height=200,fit=cover`
+
+### Create Variant (API)
+
+```bash
+curl -X POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "thumbnail",
+    "options": {
+      "width": 200,
+      "height": 200,
+      "fit": "cover"
+    },
+    "neverRequireSignedURLs": true
+  }'
+```
+
+### Use Variant
+
+```
+https://imagedelivery.net/{account_hash}/{image_id}/thumbnail
+```
+
+### Common Variant Presets
+
+```json
+{
+  "thumbnail": {
+    "width": 200,
+    "height": 200,
+    "fit": "cover"
+  },
+  "avatar": {
+    "width": 128,
+    "height": 128,
+    "fit": "cover",
+    "gravity": "face"
+  },
+  "hero": {
+    "width": 1920,
+    "height": 1080,
+    "fit": "cover",
+    "quality": 90
+  },
+  "mobile": {
+    "width": 640,
+    "fit": "scale-down",
+    "quality": 80,
+    "format": "avif"
+  }
+}
+```
+
+## Authentication
+
+### API Token (Recommended)
+
+Generate at: Dashboard → My Profile → API Tokens
+
+Required permissions:
+- Account → Cloudflare Images → Edit
+
+```bash
+curl -H "Authorization: Bearer {api_token}" \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1
+```
+
+### API Key (Legacy)
+
+```bash
+curl -H "X-Auth-Email: {email}" \
+     -H "X-Auth-Key: {api_key}" \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1
+```
+
+## Signed URLs
+
+For private images, enable signed URLs:
+
+```bash
+# Upload with signed URLs required
+curl -X POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  -H "Authorization: Bearer {api_token}" \
+  -F file=@private.jpg \
+  -F requireSignedURLs=true
+```
+
+Generate signed URL:
+
+```typescript
+import { createHmac } from 'crypto';
+
+function signUrl(imageId: string, variant: string, expiry: number, key: string): string {
+  const path = `/${imageId}/${variant}`;
+  const toSign = `${path}${expiry}`;
+  const signature = createHmac('sha256', key)
+    .update(toSign)
+    .digest('hex');
+  
+  return `https://imagedelivery.net/{hash}${path}?exp=${expiry}&sig=${signature}`;
+}
+
+// Sign URL valid for 1 hour
+const signedUrl = signUrl('image-id', 'public', Date.now() + 3600, env.SIGNING_KEY);
+```
+
+## Local Development
+
+```bash
+npx wrangler dev --remote
+```
+
+Must use `--remote` for Images binding access.

package/skills/cloudflare-deploy/references/images/gotchas.md

@@ -0,0 +1,99 @@
+# Gotchas & Best Practices
+
+## Fit Modes
+
+| Mode | Best For | Behavior |
+|------|----------|----------|
+| `cover` | Hero images, thumbnails | Fills space, crops excess |
+| `contain` | Product images, artwork | Preserves full image, may add padding |
+| `scale-down` | User uploads | Never enlarges |
+| `crop` | Precise crops | Uses gravity |
+| `pad` | Fixed aspect ratio | Adds background |
+
+## Format Selection
+
+```typescript
+format: 'auto' // Recommended - negotiates best format
+```
+
+**Support:** AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)
+
+## Quality Settings
+
+| Use Case | Quality |
+|----------|---------|
+| Thumbnails | 75-80 |
+| Standard | 85 (default) |
+| High-quality | 90-95 |
+
+## Common Errors
+
+### 5403: "Image transformation failed"
+- Verify `width`/`height` ≤ 12000
+- Check `quality` 1-100, `dpr` 1-3
+- Don't combine incompatible options
+
+### 9413: "Rate limit exceeded"
+Implement caching and exponential backoff:
+```typescript
+for (let i = 0; i < 3; i++) {
+  try { return await env.IMAGES.input(buffer).transform({...}).output(); }
+  catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }
+}
+```
+
+### 5401: "Image too large"
+Pre-process images before upload (max 100MB, 12000×12000px)
+
+### 5400: "Invalid image format"
+Supported: JPEG, PNG, GIF, WebP, AVIF, SVG
+
+### 401/403: "Unauthorized"
+Verify API token has `Cloudflare Images → Edit` permission
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Max input size | 100MB |
+| Max dimensions | 12000×12000px |
+| Quality range | 1-100 |
+| DPR range | 1-3 |
+| API rate limit | ~1200 req/min |
+
+## AVIF Gotchas
+
+- **Slower encoding**: First request may have higher latency
+- **Browser detection**:
+```typescript
+const format = /image\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';
+```
+
+## Anti-Patterns
+
+```typescript
+// ❌ No caching - transforms every request
+return env.IMAGES.input(buffer).transform({...}).output().response();
+
+// ❌ cover without both dimensions
+transform({ width: 800, fit: 'cover' })
+
+// ✅ Always set both for cover
+transform({ width: 800, height: 600, fit: 'cover' })
+
+// ❌ Exposes API token to client
+// ✅ Use Direct Creator Upload (patterns.md)
+```
+
+## Debugging
+
+```typescript
+// Check response headers
+console.log('Content-Type:', response.headers.get('Content-Type'));
+
+// Test with curl
+// curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif"
+
+// Monitor logs
+// npx wrangler tail
+```

package/skills/cloudflare-deploy/references/images/patterns.md

@@ -0,0 +1,115 @@
+# Common Patterns
+
+## URL Transform Options
+
+```
+width=<PX>   height=<PX>   fit=scale-down|contain|cover|crop|pad
+quality=85   format=auto|webp|avif|jpeg|png   dpr=2
+gravity=auto|face|left|right|top|bottom   sharpen=2   blur=10
+rotate=90|180|270   background=white   metadata=none|copyright|keep
+```
+
+## Responsive Images (srcset)
+
+```html
+<img src="https://imagedelivery.net/{hash}/{id}/width=800"
+  srcset=".../{id}/width=400 400w, .../{id}/width=800 800w, .../{id}/width=1200 1200w"
+  sizes="(max-width: 600px) 400px, 800px" />
+```
+
+## Format Negotiation
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const accept = request.headers.get('Accept') || '';
+  const format = /image\/avif/.test(accept) ? 'avif' : /image\/webp/.test(accept) ? 'webp' : 'jpeg';
+  return env.IMAGES.input(buffer).transform({ format, quality: 85 }).output().response();
+}
+```
+
+## Direct Creator Upload
+
+```typescript
+// Backend: Generate upload URL
+const response = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/images/v2/direct_upload`,
+  { method: 'POST', headers: { 'Authorization': `Bearer ${env.API_TOKEN}` },
+    body: JSON.stringify({ requireSignedURLs: false, metadata: { userId } }) }
+);
+
+// Frontend: Upload to returned uploadURL
+const formData = new FormData();
+formData.append('file', file);
+await fetch(result.uploadURL, { method: 'POST', body: formData });
+// Use: https://imagedelivery.net/{hash}/${result.id}/public
+```
+
+## Transform & Store to R2
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const file = (await request.formData()).get('image') as File;
+  const transformed = await env.IMAGES
+    .input(await file.arrayBuffer())
+    .transform({ width: 800, format: 'avif', quality: 80 })
+    .output();
+  await env.R2.put(`images/${Date.now()}.avif`, transformed.response().body);
+  return Response.json({ success: true });
+}
+```
+
+## Watermarking
+
+```typescript
+const watermark = await env.ASSETS.fetch(new URL('/watermark.png', request.url));
+const result = await env.IMAGES
+  .input(await image.arrayBuffer())
+  .draw(env.IMAGES.input(watermark.body).transform({ width: 100 }), { bottom: 20, right: 20, opacity: 0.7 })
+  .transform({ format: 'avif' })
+  .output();
+return result.response();
+```
+
+## Device-Based Transforms
+
+```typescript
+const ua = request.headers.get('User-Agent') || '';
+const isMobile = /Mobile|Android|iPhone/i.test(ua);
+return env.IMAGES.input(buffer)
+  .transform({ width: isMobile ? 400 : 1200, quality: isMobile ? 75 : 85, format: 'avif' })
+  .output().response();
+```
+
+## Caching Strategy
+
+```typescript
+async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+  const cache = caches.default;
+  let response = await cache.match(request);
+  if (!response) {
+    response = await env.IMAGES.input(buffer).transform({ width: 800, format: 'avif' }).output().response();
+    response = new Response(response.body, { headers: { ...response.headers, 'Cache-Control': 'public, max-age=86400' } });
+    ctx.waitUntil(cache.put(request, response.clone()));
+  }
+  return response;
+}
+```
+
+## Batch Processing
+
+```typescript
+const results = await Promise.all(images.map(buffer =>
+  env.IMAGES.input(buffer).transform({ width: 800, fit: 'cover', format: 'avif' }).output()
+));
+```
+
+## Error Handling
+
+```typescript
+try {
+  return (await env.IMAGES.input(buffer).transform({ width: 800 }).output()).response();
+} catch (error) {
+  console.error('Transform failed:', error);
+  return new Response('Image processing failed', { status: 500 });
+}
+```

package/skills/cloudflare-deploy/references/kv/README.md

@@ -0,0 +1,89 @@
+# 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
+
+## When to Use KV
+
+| Need | Recommendation |
+|------|----------------|
+| Strong consistency | → [Durable Objects](../durable-objects/) |
+| SQL queries | → [D1](../d1/) |
+| Object storage (files) | → [R2](../r2/) |
+| High read, low write volume | → KV ✅ |
+| Sub-10ms global reads | → KV ✅ |
+
+**Quick comparison:**
+
+| Feature | KV | D1 | Durable Objects |
+|---------|----|----|-----------------|
+| Consistency | Eventual | Strong | Strong |
+| Read latency | <10ms | ~50ms | <1ms |
+| Write limit | 1/s per key | Unlimited | Unlimited |
+| Use case | Config, cache | Relational data | Coordination |
+
+## 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)
+
+## Reading Order
+
+| Task | Files to Read |
+|------|---------------|
+| Quick start | README → configuration.md |
+| Implement feature | README → api.md → patterns.md |
+| Debug issues | gotchas.md → api.md |
+| Batch operations | api.md (bulk section) → patterns.md |
+| Performance tuning | gotchas.md (performance) → patterns.md (caching) |
+
+## 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/skills/cloudflare-deploy/references/kv/api.md

@@ -0,0 +1,160 @@
+# 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 keys = ["user:1", "user:2", "user:3", "missing:key"];
+const results = await env.MY_KV.get(keys);
+// Returns Map<string, string | null>
+
+console.log(results.get("user:1"));     // "John" (if exists)
+console.log(results.get("missing:key")); // null
+
+// Process results with null handling
+for (const [key, value] of results) {
+  if (value !== null) {
+    // Handle found keys
+    console.log(`${key}: ${value}`);
+  }
+}
+
+// TypeScript with generics (type-safe JSON parsing)
+interface UserProfile { name: string; email: string; }
+const profile = await env.USERS.get<UserProfile>("user:123", "json");
+// profile is typed as UserProfile | null
+if (profile) {
+  console.log(profile.name); // Type-safe access
+}
+
+// Bulk get with type
+const configs = await env.MY_KV.get<Config>(["config:app", "config:feature"], "json");
+// Map<string, Config | null>
+```
+
+## 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 (bulk)
+const keys = ["key1", "key2", "key3"];
+const results = await env.MY_KV.getWithMetadata(keys);
+// Returns Map<string, { value, metadata, cacheStatus? }>
+
+for (const [key, result] of results) {
+  if (result.value) {
+    console.log(`${key}: ${result.value}`);
+    console.log(`Metadata: ${JSON.stringify(result.metadata)}`);
+    // cacheStatus field indicates cache hit/miss (when available)
+  }
+}
+
+// With type
+const result = await env.MY_KV.getWithMetadata<UserData>("user:123", "json");
+// result: { value: UserData | null, metadata: any | null, cacheStatus?: string }
+```
+
+## 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);
+```
+
+## Performance Considerations
+
+### Type Selection
+
+| Type | Use Case | Performance |
+|------|----------|-------------|
+| `stream` | Large values (>1MB) | Fastest - no buffering |
+| `arrayBuffer` | Binary data | Fast - single allocation |
+| `text` | String values | Medium |
+| `json` | Objects (parse overhead) | Slowest - parsing cost |
+
+### Parallel Reads
+
+```typescript
+// Efficient parallel reads with Promise.all()
+const [user, settings, cache] = await Promise.all([
+  env.USERS.get("user:123", "json"),
+  env.SETTINGS.get("config:app", "json"),
+  env.CACHE.get("data:latest")
+]);
+```
+
+## Error Handling
+
+- **Missing keys:** Return `null` (not an error)
+- **Rate limit (429):** Retry with exponential backoff (see gotchas.md)
+- **Response too large (413):** Values >25MB fail with 413 error
+
+See [gotchas.md](./gotchas.md) for detailed error patterns and solutions.