@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/argo-smart-routing/gotchas.md

@@ -0,0 +1,111 @@
+## Best Practices Summary
+
+**Smart Shield Note:** Argo Smart Routing evolving into Smart Shield. Best practices below remain applicable; monitor Cloudflare changelog for Smart Shield updates.
+
+1. **Always check editability** before attempting to enable/disable Argo
+2. **Set up billing notifications** to avoid unexpected costs
+3. **Combine with Tiered Cache** for maximum performance benefit
+4. **Use in production only** - disable for dev/staging to control costs
+5. **Monitor analytics** - require 500+ requests in 48h for detailed metrics
+6. **Handle errors gracefully** - check for billing, permissions, zone compatibility
+7. **Test configuration changes** in staging before production
+8. **Use TypeScript SDK** for type safety and better developer experience
+9. **Implement retry logic** for API calls in production systems
+10. **Document zone-specific settings** for team visibility
+
+## Common Errors
+
+### "Argo unavailable"
+
+**Problem:** API returns error "Argo Smart Routing is unavailable for this zone"
+
+**Cause:** Zone not eligible or billing not set up
+
+**Solution:**
+1. Verify zone has Enterprise or higher plan
+2. Check billing is configured in Account → Billing
+3. Ensure payment method is valid and current
+4. Contact Cloudflare support if eligibility unclear
+
+### "Cannot enable/disable"
+
+**Problem:** API call succeeds but status remains unchanged, or `editable: false` in GET response
+
+**Cause:** Insufficient permissions or zone restrictions
+
+**Solution:**
+1. Check API token has `Zone:Argo Smart Routing:Edit` permission
+2. Verify `editable: true` in GET response before attempting PATCH
+3. If `editable: false`, check:
+   - Billing configured for account
+   - Zone plan includes Argo (Enterprise+)
+   - No active zone holds or suspensions
+   - API token has correct scopes
+
+### `editable: false` Error
+
+**Problem:** GET request returns `"editable": false`, preventing enable/disable
+
+**Cause:** Zone-level restrictions from billing, plan, or permissions
+
+**Solution Pattern:**
+```typescript
+const status = await client.argo.smartRouting.get({ zone_id: zoneId });
+
+if (!status.editable) {
+  // Don't attempt to modify - will fail
+  console.error('Cannot modify Argo settings:');
+  console.error('- Check billing is configured');
+  console.error('- Verify zone has Enterprise+ plan');
+  console.error('- Confirm API token has Edit permission');
+  throw new Error('Argo is not editable for this zone');
+}
+
+// Safe to proceed with enable/disable
+await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
+```
+
+### Rate Limiting
+
+**Problem:** `429 Too Many Requests` error from API
+
+**Cause:** Exceeded API rate limits (typically 1200 requests per 5 minutes)
+
+**Solution:**
+```typescript
+import { RateLimitError } from 'cloudflare';
+
+try {
+  await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    const retryAfter = error.response?.headers.get('retry-after');
+    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
+    
+    // Implement exponential backoff
+    await new Promise(resolve => setTimeout(resolve, (retryAfter || 60) * 1000));
+    // Retry request
+  }
+}
+```
+
+## Limits
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| Min requests for analytics | 500 in 48h | For detailed metrics via GraphQL |
+| Zones supported | Enterprise+ | Check zone plan in dashboard |
+| Billing requirement | Must be configured | Before enabling; verify payment method |
+| API rate limit | 1200 req / 5 min | Per API token across all endpoints |
+| Spectrum apps | No hard limit | Each app can enable Argo independently |
+| Traffic counting | Proxied only | Only orange-clouded DNS records count |
+| DDoS/WAF exemption | Yes | Mitigated traffic excluded from billing |
+| Analytics latency | 1-5 minutes | Real-time metrics not available |
+
+## Additional Resources
+
+- [Official Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)
+- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)
+- [API Authentication](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
+- [Cloudflare TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)
+- [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python)

package/skills/cloudflare-deploy/references/argo-smart-routing/patterns.md

@@ -0,0 +1,104 @@
+# Integration Patterns
+
+## Enable Argo + Tiered Cache
+
+```typescript
+async function enableOptimalPerformance(client: Cloudflare, zoneId: string) {
+  await Promise.all([
+    client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),
+    client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),
+  ]);
+}
+```
+
+**Flow:** Visitor → Edge (Lower-Tier) → [Cache Miss] → Upper-Tier → [Cache Miss + Argo] → Origin
+
+**Impact:** Argo ~30% latency reduction + Tiered Cache 50-80% origin offload
+
+## Usage Analytics (GraphQL)
+
+```graphql
+query ArgoAnalytics($zoneTag: string!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequestsAdaptiveGroups(limit: 1000) {
+        sum { argoBytes, bytes }
+      }
+    }
+  }
+}
+```
+
+**Billing:** ~$0.10/GB. DDoS-mitigated and WAF-blocked traffic NOT charged.
+
+## Spectrum TCP Integration
+
+Enable Argo for non-HTTP traffic (databases, game servers, IoT):
+
+```typescript
+// Update existing app
+await client.spectrum.apps.update(appId, { zone_id: zoneId, argo_smart_routing: true });
+
+// Create new app with Argo
+await client.spectrum.apps.create({
+  zone_id: zoneId,
+  dns: { type: 'CNAME', name: 'tcp.example.com' },
+  origin_direct: ['tcp://origin.example.com:3306'],
+  protocol: 'tcp/3306',
+  argo_smart_routing: true,
+});
+```
+
+**Use cases:** MySQL/PostgreSQL (3306/5432), game servers, MQTT (1883), SSH (22)
+
+## Pre-Flight Validation
+
+```typescript
+async function validateArgoEligibility(client: Cloudflare, zoneId: string) {
+  const status = await client.argo.smartRouting.get({ zone_id: zoneId });
+  const zone = await client.zones.get({ zone_id: zoneId });
+  
+  const issues: string[] = [];
+  if (!status.editable) issues.push('Zone not editable');
+  if (['free', 'pro'].includes(zone.plan.legacy_id)) issues.push('Requires Business+ plan');
+  if (zone.status !== 'active') issues.push('Zone not active');
+  
+  return { canEnable: issues.length === 0, issues };
+}
+```
+
+## Post-Enable Verification
+
+```typescript
+async function verifyArgoEnabled(client: Cloudflare, zoneId: string): Promise<boolean> {
+  await new Promise(r => setTimeout(r, 2000)); // Wait for propagation
+  const status = await client.argo.smartRouting.get({ zone_id: zoneId });
+  return status.value === 'on';
+}
+```
+
+## Full Setup Pattern
+
+```typescript
+async function setupArgo(client: Cloudflare, zoneId: string) {
+  // 1. Validate
+  const { canEnable, issues } = await validateArgoEligibility(client, zoneId);
+  if (!canEnable) throw new Error(issues.join(', '));
+  
+  // 2. Enable both features
+  await Promise.all([
+    client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),
+    client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),
+  ]);
+  
+  // 3. Verify
+  const [argo, cache] = await Promise.all([
+    client.argo.smartRouting.get({ zone_id: zoneId }),
+    client.argo.tieredCaching.get({ zone_id: zoneId }),
+  ]);
+  
+  return { argo: argo.value === 'on', tieredCache: cache.value === 'on' };
+}
+```
+
+**When to combine:** High-traffic sites (>1TB/mo), global users, cacheable content.

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

@@ -0,0 +1,122 @@
+# Cloudflare Bindings Skill Reference
+
+Expert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources.
+
+## What Are Bindings?
+
+Bindings are how Workers access Cloudflare resources (storage, compute, services) via the `env` object. They're configured in `wrangler.jsonc`, type-safe via TypeScript, and zero-overhead at runtime.
+
+## Reading Order
+
+1. **This file** - Binding catalog and selection guide
+2. **[api.md](api.md)** - TypeScript types and env access patterns
+3. **[configuration.md](configuration.md)** - Complete wrangler.jsonc examples
+4. **[patterns.md](patterns.md)** - Best practices and common patterns
+5. **[gotchas.md](gotchas.md)** - Critical pitfalls and troubleshooting
+
+## Binding Catalog
+
+### Storage Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **KV** | Key-value cache, CDN-backed reads | `env.MY_KV.get(key)` |
+| **R2** | Object storage (S3-compatible) | `env.MY_BUCKET.get(key)` |
+| **D1** | SQL database (SQLite) | `env.DB.prepare(sql).all()` |
+| **Durable Objects** | Coordination, real-time state | `env.MY_DO.get(id)` |
+| **Vectorize** | Vector embeddings search | `env.VECTORIZE.query(vector)` |
+| **Queues** | Async message processing | `env.MY_QUEUE.send(msg)` |
+
+### Compute Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Service** | Worker-to-Worker RPC | `env.MY_SERVICE.fetch(req)` |
+| **Workers AI** | LLM inference | `env.AI.run(model, input)` |
+| **Browser Rendering** | Headless Chrome | `env.BROWSER.fetch(url)` |
+
+### Platform Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Analytics Engine** | Custom metrics | `env.ANALYTICS.writeDataPoint(data)` |
+| **mTLS** | Client certificates | `env.MY_CERT` (string) |
+| **Hyperdrive** | Database pooling | `env.HYPERDRIVE.connectionString` |
+| **Rate Limiting** | Request throttling | `env.RATE_LIMITER.limit(id)` |
+| **Workflows** | Long-running workflows | `env.MY_WORKFLOW.create()` |
+
+### Configuration Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Environment Variables** | Non-sensitive config | `env.API_URL` (string) |
+| **Secrets** | Sensitive values | `env.API_KEY` (string) |
+| **Text/Data Blobs** | Static files | `env.MY_BLOB` (string) |
+| **WASM** | WebAssembly modules | `env.MY_WASM` (WebAssembly.Module) |
+
+## Quick Selection Guide
+
+**Need persistent storage?**
+- Key-value < 25MB → **KV**
+- Files/objects → **R2**
+- Relational data → **D1**
+- Real-time coordination → **Durable Objects**
+
+**Need AI/compute?**
+- LLM inference → **Workers AI**
+- Scraping/PDFs → **Browser Rendering**
+- Call another Worker → **Service binding**
+
+**Need async processing?**
+- Background jobs → **Queues**
+
+**Need config?**
+- Public values → **Environment Variables**
+- Secrets → **Secrets** (never commit)
+
+## Quick Start
+
+1. **Add binding to wrangler.jsonc:**
+```jsonc
+{
+  "kv_namespaces": [
+    { "binding": "MY_KV", "id": "your-kv-id" }
+  ]
+}
+```
+
+2. **Generate types:**
+```bash
+npx wrangler types
+```
+
+3. **Access in Worker:**
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    await env.MY_KV.put('key', 'value');
+    return new Response('OK');
+  }
+}
+```
+
+## Type Safety
+
+Bindings are fully typed via `wrangler types`. See [api.md](api.md) for details.
+
+## Limits
+
+- 64 bindings max per Worker (all types combined)
+- See [gotchas.md](gotchas.md) for per-binding limits
+
+## Key Concepts
+
+**Zero-overhead access:** Bindings compiled into Worker, no network calls to access
+**Type-safe:** Full TypeScript support via `wrangler types`
+**Per-environment:** Different IDs for dev/staging/production
+**Secrets vs Vars:** Secrets encrypted at rest, never in config files
+
+## See Also
+
+- [Cloudflare Docs: Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/)
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)

package/skills/cloudflare-deploy/references/bindings/api.md

@@ -0,0 +1,203 @@
+# Bindings API Reference
+
+## TypeScript Types
+
+Cloudflare generates binding types via `npx wrangler types`. This creates `.wrangler/types/runtime.d.ts` with your Env interface.
+
+### Generated Env Interface
+
+After running `wrangler types`, TypeScript knows your bindings:
+
+```typescript
+interface Env {
+  // From wrangler.jsonc bindings
+  MY_KV: KVNamespace;
+  MY_BUCKET: R2Bucket;
+  DB: D1Database;
+  MY_SERVICE: Fetcher;
+  AI: Ai;
+  
+  // From vars
+  API_URL: string;
+  
+  // From secrets (set via wrangler secret put)
+  API_KEY: string;
+}
+```
+
+### Binding Types
+
+| Config | TypeScript Type | Package |
+|--------|-----------------|---------|
+| `kv_namespaces` | `KVNamespace` | `@cloudflare/workers-types` |
+| `r2_buckets` | `R2Bucket` | `@cloudflare/workers-types` |
+| `d1_databases` | `D1Database` | `@cloudflare/workers-types` |
+| `durable_objects.bindings` | `DurableObjectNamespace` | `@cloudflare/workers-types` |
+| `vectorize` | `VectorizeIndex` | `@cloudflare/workers-types` |
+| `queues.producers` | `Queue` | `@cloudflare/workers-types` |
+| `services` | `Fetcher` | `@cloudflare/workers-types` |
+| `ai` | `Ai` | `@cloudflare/workers-types` |
+| `browser` | `Fetcher` | `@cloudflare/workers-types` |
+| `analytics_engine_datasets` | `AnalyticsEngineDataset` | `@cloudflare/workers-types` |
+| `hyperdrive` | `Hyperdrive` | `@cloudflare/workers-types` |
+| `rate_limiting` | `RateLimit` | `@cloudflare/workers-types` |
+| `workflows` | `Workflow` | `@cloudflare/workers-types` |
+| `mtls_certificates` / `vars` / `text_blobs` / `data_blobs` | `string` | Built-in |
+| `wasm_modules` | `WebAssembly.Module` | Built-in |
+
+## Accessing Bindings
+
+### Method 1: fetch() Handler (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const value = await env.MY_KV.get('key');
+    return new Response(value);
+  }
+}
+```
+
+**Why:** Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.
+
+### Method 2: Hono Framework
+
+```typescript
+import { Hono } from 'hono';
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.get('/', async (c) => {
+  const value = await c.env.MY_KV.get('key');
+  return c.json({ value });
+});
+
+export default app;
+```
+
+**Why:** c.env auto-typed, ergonomic for routing-heavy apps.
+
+### Method 3: Module Workers (Legacy)
+
+```typescript
+export async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const value = await env.MY_KV.get('key');
+  return new Response(value);
+}
+
+addEventListener('fetch', (event) => {
+  // env not directly available - requires workarounds
+});
+```
+
+**Avoid:** Use fetch() handler instead (Method 1).
+
+## Type Generation Workflow
+
+### Initial Setup
+
+```bash
+# Install wrangler
+npm install -D wrangler
+
+# Generate types from wrangler.jsonc
+npx wrangler types
+```
+
+### After Changing Bindings
+
+```bash
+# Added/modified binding in wrangler.jsonc
+npx wrangler types
+
+# TypeScript now sees updated Env interface
+```
+
+**Note:** `wrangler types` outputs to `.wrangler/types/runtime.d.ts`. TypeScript picks this up automatically if `@cloudflare/workers-types` is in `tsconfig.json` `"types"` array.
+
+## Key Binding Methods
+
+**KV:**
+```typescript
+await env.MY_KV.get(key, { type: 'json' });  // text|json|arrayBuffer|stream
+await env.MY_KV.put(key, value, { expirationTtl: 3600 });
+await env.MY_KV.delete(key);
+await env.MY_KV.list({ prefix: 'user:' });
+```
+
+**R2:**
+```typescript
+await env.BUCKET.get(key);
+await env.BUCKET.put(key, value);
+await env.BUCKET.delete(key);
+await env.BUCKET.list({ prefix: 'images/' });
+```
+
+**D1:**
+```typescript
+await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+await env.DB.batch([stmt1, stmt2]);
+```
+
+**Service:**
+```typescript
+await env.MY_SERVICE.fetch(new Request('https://fake/path'));
+```
+
+**Workers AI:**
+```typescript
+await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });
+```
+
+**Queues:**
+```typescript
+await env.MY_QUEUE.send({ userId: 123, action: 'process' });
+```
+
+**Durable Objects:**
+```typescript
+const id = env.MY_DO.idFromName('user-123');
+const stub = env.MY_DO.get(id);
+await stub.fetch(new Request('https://fake/increment'));
+```
+
+## Runtime vs Build-Time Types
+
+| Type Source | When Generated | Use Case |
+|-------------|----------------|----------|
+| `@cloudflare/workers-types` | npm install | Base Workers APIs (Request, Response, etc.) |
+| `wrangler types` | After config change | Your specific bindings (Env interface) |
+
+**Install both:**
+```bash
+npm install -D @cloudflare/workers-types
+npx wrangler types
+```
+
+## Type Safety Best Practices
+
+1. **Never use `any` for env:**
+```typescript
+// ❌ BAD
+async fetch(request: Request, env: any) { }
+
+// ✅ GOOD
+async fetch(request: Request, env: Env) { }
+```
+
+2. **Run wrangler types after config changes:**
+```bash
+# After editing wrangler.jsonc
+npx wrangler types
+```
+
+3. **Check generated types match config:**
+```bash
+# View generated Env interface
+cat .wrangler/types/runtime.d.ts
+```
+
+## See Also
+
+- [Workers Types Package](https://www.npmjs.com/package/@cloudflare/workers-types)
+- [Wrangler Types Command](https://developers.cloudflare.com/workers/wrangler/commands/#types)