@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

@@ -0,0 +1,144 @@
+# 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"
+    },
+    // Optional: Different namespace for preview/development
+    {
+      "binding": "MY_KV",
+      "preview_id": "preview-abc123"
+    }
+  ]
+}
+```
+
+## TypeScript Types
+
+**env.d.ts:**
+```typescript
+interface Env {
+  MY_KV: KVNamespace;
+  SESSIONS: KVNamespace;
+  CACHE: KVNamespace;
+}
+```
+
+**worker.ts:**
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // env.MY_KV is now typed as KVNamespace
+    const value = await env.MY_KV.get("key");
+    return new Response(value || "Not found");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+**Type-safe JSON operations:**
+```typescript
+interface UserProfile {
+  name: string;
+  email: string;
+  role: "admin" | "user";
+}
+
+const profile = await env.USERS.get<UserProfile>("user:123", "json");
+// profile: UserProfile | null (type-safe!)
+if (profile) {
+  console.log(profile.name); // TypeScript knows this is a string
+}
+```
+
+## 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
+
+### Single Operations
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiEmail: process.env.CLOUDFLARE_EMAIL,
+  apiKey: process.env.CLOUDFLARE_API_KEY
+});
+
+// Single key operations
+await client.kv.namespaces.values.update(namespaceId, 'key', {
+  account_id: accountId,
+  value: 'value',
+  expiration_ttl: 3600
+});
+```
+
+### Bulk Operations
+
+```typescript
+// Bulk update (up to 10,000 keys, max 100MB total)
+await client.kv.namespaces.bulkUpdate(namespaceId, {
+  account_id: accountId,
+  body: [
+    { key: "key1", value: "value1", expiration_ttl: 3600 },
+    { key: "key2", value: "value2", metadata: { version: 1 } },
+    { key: "key3", value: "value3" }
+  ]
+});
+
+// Bulk get (up to 100 keys)
+const results = await client.kv.namespaces.bulkGet(namespaceId, {
+  account_id: accountId,
+  keys: ["key1", "key2", "key3"]
+});
+
+// Bulk delete (up to 10,000 keys)
+await client.kv.namespaces.bulkDelete(namespaceId, {
+  account_id: accountId,
+  keys: ["key1", "key2", "key3"]
+});
+```

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

@@ -0,0 +1,131 @@
+# KV Gotchas & Troubleshooting
+
+## Common Errors
+
+### "Stale Read After Write"
+
+**Cause:** Eventual consistency means writes may not be immediately visible in other regions  
+**Solution:** Don't read immediately after write; return confirmation without reading or use the local value you just wrote. Writes visible immediately in same location, ≤60s globally
+
+```typescript
+// ❌ BAD: Read immediately after write
+await env.KV.put("key", "value");
+const value = await env.KV.get("key"); // May be null in other regions!
+
+// ✅ GOOD: Use the value you just wrote
+const newValue = "value";
+await env.KV.put("key", newValue);
+return new Response(newValue); // Don't re-read
+```
+
+### "429 Rate Limit on Concurrent Writes"
+
+**Cause:** Multiple concurrent writes to same key exceeding 1 write/second limit  
+**Solution:** Use sequential writes, unique keys for concurrent operations, or implement retry with exponential backoff
+
+```typescript
+async function putWithRetry(
+  kv: KVNamespace,
+  key: string,
+  value: string,
+  maxAttempts = 5
+): Promise<void> {
+  let delay = 1000;
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      await kv.put(key, value);
+      return;
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("429")) {
+        if (i === maxAttempts - 1) throw err;
+        await new Promise(r => setTimeout(r, delay));
+        delay *= 2; // Exponential backoff
+      } else {
+        throw err;
+      }
+    }
+  }
+}
+```
+
+### "Inefficient Multiple Gets"
+
+**Cause:** Making multiple individual get() calls instead of bulk operation  
+**Solution:** Use bulk get with array of keys: `env.USERS.get(["user:1", "user:2", "user:3"])` to reduce to 1 operation
+
+### "Null Reference Error"
+
+**Cause:** Attempting to use value without checking for null when key doesn't exist  
+**Solution:** Always handle null returns - KV returns `null` for missing keys, not undefined
+
+```typescript
+// ❌ BAD: Assumes value exists
+const config = await env.KV.get("config", "json");
+return config.theme; // TypeError if null!
+
+// ✅ GOOD: Null checks
+const config = await env.KV.get("config", "json");
+return config?.theme ?? "default";
+
+// ✅ GOOD: Early return
+const config = await env.KV.get("config", "json");
+if (!config) return new Response("Not found", { status: 404 });
+return new Response(config.theme);
+```
+
+### "Negative Lookup Caching"
+
+**Cause:** Keys that don't exist are cached as "not found" for up to 60s  
+**Solution:** Creating a key after checking won't be visible until cache expires
+
+```typescript
+// Check → create pattern has race condition
+const exists = await env.KV.get("key"); // null, cached as "not found"
+if (!exists) {
+  await env.KV.put("key", "value");
+  // Next get() may still return null for ~60s due to negative cache
+}
+
+// Alternative: Always assume key may not exist, use defaults
+const value = await env.KV.get("key") ?? "default-value";
+```
+
+## Performance Tips
+
+| Scenario | Recommendation | Why |
+|----------|----------------|-----|
+| Large values (>1MB) | Use `stream` type | Avoids buffering entire value in memory |
+| Many small keys | Coalesce into one JSON object | Reduces operations, improves cache hit rate |
+| High write volume | Spread across different keys | Avoid 1 write/second per-key limit |
+| Cold reads | Increase `cacheTtl` parameter | Reduces latency for frequently-read data |
+| Bulk operations | Use array form of get() | Single operation, better performance |
+
+## Cost Examples
+
+**Free tier:**
+- 100K reads/day = 3M/month ✅
+- 1K writes/day = 30K/month ✅
+- 1GB storage ✅
+
+**Example paid workload:**
+- 10M reads/month = $5.00
+- 100K writes/month = $0.50
+- 1GB storage = $0.50
+- **Total: ~$6/month**
+
+## Limits
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Key size | 512 bytes | Maximum key length |
+| Value size | 25 MiB | Maximum value; 413 error if exceeded |
+| Metadata size | 1024 bytes | Maximum metadata per key |
+| cacheTtl minimum | 60s | Minimum cache TTL |
+| Write rate per key | 1 write/second | All plans; 429 error if exceeded |
+| Propagation time | ≤60s | Global propagation time |
+| Bulk get max | 100 keys | Maximum keys per bulk operation |
+| Operations per Worker | 1,000 | Per request (bulk counts as 1) |
+| Reads pricing | $0.50 per 10M | Per million reads |
+| Writes pricing | $5.00 per 1M | Per million writes |
+| Deletes pricing | $5.00 per 1M | Per million deletes |
+| Storage pricing | $0.50 per GB-month | Per GB per month |

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

@@ -0,0 +1,196 @@
+# KV Patterns & Best Practices
+
+## Multi-Tier Caching
+
+```typescript
+// Memory → KV → Origin (3-tier cache)
+const memoryCache = new Map<string, { data: any; expires: number }>();
+
+async function getCached(env: Env, key: string): Promise<any> {
+  const now = Date.now();
+  
+  // L1: Memory cache (fastest)
+  const cached = memoryCache.get(key);
+  if (cached && cached.expires > now) {
+    return cached.data;
+  }
+  
+  // L2: KV cache (fast)
+  const kvValue = await env.CACHE.get(key, "json");
+  if (kvValue) {
+    memoryCache.set(key, { data: kvValue, expires: now + 60000 }); // 1min in memory
+    return kvValue;
+  }
+  
+  // L3: Origin (slow)
+  const origin = await fetch(`https://api.example.com/${key}`).then(r => r.json());
+  
+  // Backfill caches
+  await env.CACHE.put(key, JSON.stringify(origin), { expirationTtl: 300 }); // 5min in KV
+  memoryCache.set(key, { data: origin, expires: now + 60000 });
+  
+  return origin;
+}
+```
+
+## 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;
+}
+```
+
+## 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
+```
+
+## Prefix-Based Namespacing
+
+```typescript
+// Logical partitioning within single namespace
+const PREFIXES = {
+  users: "user:",
+  sessions: "session:",
+  cache: "cache:",
+  features: "feature:"
+} as const;
+
+// Write with prefix
+async function setUser(env: Env, id: string, data: any) {
+  await env.KV.put(`${PREFIXES.users}${id}`, JSON.stringify(data));
+}
+
+// Read with prefix
+async function getUser(env: Env, id: string) {
+  return await env.KV.get(`${PREFIXES.users}${id}`, "json");
+}
+
+// List by prefix
+async function listUserIds(env: Env): Promise<string[]> {
+  const result = await env.KV.list({ prefix: PREFIXES.users });
+  return result.keys.map(k => k.name.replace(PREFIXES.users, ""));
+}
+
+// Example hierarchy
+"user:123:profile"
+"user:123:settings"
+"cache:api:users"
+"session:abc-def"
+"feature:flags:beta"
+```
+
+## Metadata Versioning
+
+```typescript
+interface VersionedData {
+  version: number;
+  data: any;
+}
+
+async function migrateIfNeeded(env: Env, key: string) {
+  const result = await env.DATA.getWithMetadata(key, "json");
+  
+  if (!result.value) return null;
+  
+  const currentVersion = result.metadata?.version || 1;
+  const targetVersion = 2;
+  
+  if (currentVersion < targetVersion) {
+    // Migrate data format
+    const migrated = migrate(result.value, currentVersion, targetVersion);
+    
+    // Store with new version
+    await env.DATA.put(key, JSON.stringify(migrated), {
+      metadata: { version: targetVersion, migratedAt: Date.now() }
+    });
+    
+    return migrated;
+  }
+  
+  return result.value;
+}
+
+function migrate(data: any, from: number, to: number): any {
+  if (from === 1 && to === 2) {
+    // V1 → V2: Rename field
+    return { ...data, userName: data.name };
+  }
+  return data;
+}
+```
+
+## Error Boundary Pattern
+
+```typescript
+// Resilient get with fallback
+async function resilientGet<T>(
+  env: Env,
+  key: string,
+  fallback: T
+): Promise<T> {
+  try {
+    const value = await env.KV.get<T>(key, "json");
+    return value ?? fallback;
+  } catch (err) {
+    console.error(`KV error for ${key}:`, err);
+    return fallback;
+  }
+}
+
+// Usage
+const config = await resilientGet(env, "config:app", {
+  theme: "light",
+  maxItems: 10
+});
+```

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

@@ -0,0 +1,105 @@
+# 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
+
+**Decision tree for testing Workers:**
+
+```
+Need to test Workers?
+│
+├─ Unit tests for business logic only?
+│  └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)
+│     Fast, no HTTP, direct binding access
+│
+├─ Integration tests with full runtime?
+│  ├─ Single Worker?
+│  │  └─ Miniflare API → [Quick Start](#quick-start)
+│  │     Full control, programmatic access
+│  │
+│  ├─ Multiple Workers + service bindings?
+│  │  └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)
+│  │     Shared storage, inter-worker calls
+│  │
+│  └─ Vitest test runner integration?
+│     └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)
+│        Full Workers env in Vitest
+│
+└─ Local dev server?
+   └─ wrangler dev (not Miniflare)
+      Hot reload, automatic config
+```
+
+**Use Miniflare for:**
+- Integration tests with full Worker runtime
+- Testing bindings/storage locally
+- Multiple Workers with service bindings
+- Programmatic event dispatch (fetch, queue, scheduled)
+
+**Use getPlatformProxy for:**
+- Fast unit tests of business logic
+- Testing without HTTP overhead
+- Vitest/Jest environments
+
+**Use Wrangler for:**
+- Local development workflow
+- Production deployments
+
+## 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();
+```
+
+## Reading Order
+
+**New to Miniflare?** Start here:
+1. [Quick Start](#quick-start) - Running in 2 minutes
+2. [When to Use](#when-to-use) - Choose your testing approach
+3. [patterns.md](./patterns.md) - Testing patterns (getPlatformProxy, Vitest, node:test)
+4. [configuration.md](./configuration.md) - Configure bindings, storage, multiple workers
+
+**Troubleshooting:**
+- [gotchas.md](./gotchas.md) - Common errors and debugging
+
+**API reference:**
+- [api.md](./api.md) - Complete method reference
+
+## See Also
+- [wrangler](../wrangler/) - CLI tool that embeds Miniflare for `wrangler dev`
+- [workerd](../workerd/) - Runtime that powers Miniflare
+- [workers](../workers/) - Workers runtime API documentation