@mohanscodex/spectra-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,188 @@
+# Wrangler Programmatic API
+
+Node.js APIs for testing and development.
+
+## startWorker (Testing)
+
+Starts Worker with real local bindings for integration tests. Stable API (replaces `unstable_startWorker`).
+
+```typescript
+import { startWorker } from "wrangler";
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert";
+
+describe("worker", () => {
+  let worker;
+  
+  before(async () => {
+    worker = await startWorker({
+      config: "wrangler.jsonc",
+      environment: "development"
+    });
+  });
+  
+  after(async () => {
+    await worker.dispose();
+  });
+  
+  it("responds with 200", async () => {
+    const response = await worker.fetch("http://example.com");
+    assert.strictEqual(response.status, 200);
+  });
+});
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `config` | `string` | Path to wrangler.jsonc |
+| `environment` | `string` | Environment name from config |
+| `persist` | `boolean \| { path: string }` | Enable persistent state |
+| `bundle` | `boolean` | Enable bundling (default: true) |
+| `remote` | `false \| true \| "minimal"` | Remote mode: `false` (local), `true` (full remote), `"minimal"` (remote bindings only) |
+
+### Remote Mode
+
+```typescript
+// Local mode (default) - fast, simulated
+const worker = await startWorker({ config: "wrangler.jsonc" });
+
+// Full remote mode - production-like, slower
+const worker = await startWorker({ 
+  config: "wrangler.jsonc",
+  remote: true 
+});
+
+// Minimal remote mode - remote bindings, local Worker
+const worker = await startWorker({ 
+  config: "wrangler.jsonc",
+  remote: "minimal"
+});
+```
+
+## getPlatformProxy
+
+Emulate bindings in Node.js without starting Worker.
+
+```typescript
+import { getPlatformProxy } from "wrangler";
+
+const { env, dispose, caches } = await getPlatformProxy<Env>({
+  configPath: "wrangler.jsonc",
+  environment: "production",
+  persist: { path: ".wrangler/state" }
+});
+
+// Use bindings
+const value = await env.MY_KV.get("key");
+await env.DB.prepare("SELECT * FROM users").all();
+await env.ASSETS.put("file.txt", "content");
+
+// Platform APIs
+await caches.default.put("https://example.com", new Response("cached"));
+
+await dispose();
+```
+
+Use for unit tests (test functions, not full Worker) or scripts that need bindings.
+
+## Type Generation
+
+Generate types from config: `wrangler types` → creates `worker-configuration.d.ts`
+
+## Event System
+
+Listen to Worker lifecycle events for advanced workflows.
+
+```typescript
+import { startWorker } from "wrangler";
+
+const worker = await startWorker({
+  config: "wrangler.jsonc",
+  bundle: true
+});
+
+// Bundle events
+worker.on("bundleStart", (details) => {
+  console.log("Bundling started:", details.config);
+});
+
+worker.on("bundleComplete", (details) => {
+  console.log("Bundle ready:", details.duration);
+});
+
+// Reconfiguration events
+worker.on("reloadStart", () => {
+  console.log("Worker reloading...");
+});
+
+worker.on("reloadComplete", () => {
+  console.log("Worker reloaded");
+});
+
+await worker.dispose();
+```
+
+### Dynamic Reconfiguration
+
+```typescript
+import { startWorker } from "wrangler";
+
+const worker = await startWorker({ config: "wrangler.jsonc" });
+
+// Replace entire config
+await worker.setConfig({
+  config: "wrangler.staging.jsonc",
+  environment: "staging"
+});
+
+// Patch specific fields
+await worker.patchConfig({
+  vars: { DEBUG: "true" }
+});
+
+await worker.dispose();
+```
+
+## unstable_dev (Deprecated)
+
+Use `startWorker` instead.
+
+## Multi-Worker Registry
+
+Test multiple Workers with service bindings.
+
+```typescript
+import { startWorker } from "wrangler";
+
+const auth = await startWorker({ config: "./auth/wrangler.jsonc" });
+const api = await startWorker({
+  config: "./api/wrangler.jsonc",
+  bindings: { AUTH: auth }  // Service binding
+});
+
+const response = await api.fetch("http://example.com/api/login");
+// API Worker calls AUTH Worker via env.AUTH.fetch()
+
+await api.dispose();
+await auth.dispose();
+```
+
+## Best Practices
+
+- Use `startWorker` for integration tests (tests full Worker)
+- Use `getPlatformProxy` for unit tests (tests individual functions)
+- Use `remote: true` when debugging production-specific issues
+- Use `remote: "minimal"` for faster tests with real bindings
+- Enable `persist: true` for debugging (state survives runs)
+- Run `wrangler types` after config changes
+- Always `dispose()` to prevent resource leaks
+- Listen to bundle events for build monitoring
+- Use multi-worker registry for testing service bindings
+
+## See Also
+
+- [README.md](./README.md) - CLI commands
+- [configuration.md](./configuration.md) - Config
+- [patterns.md](./patterns.md) - Testing patterns

package/skills/cloudflare-deploy/references/wrangler/auth.md

@@ -0,0 +1,73 @@
+# Authentication
+
+Authenticate with Cloudflare before deploying Workers or Pages.
+
+## Quick Decision Tree
+
+```
+Need to authenticate?
+├─ Interactive/local dev → wrangler login (recommended)
+├─ CI/CD or headless → CLOUDFLARE_API_TOKEN env var
+└─ Terraform/Pulumi → See respective references
+```
+
+## wrangler login (Recommended)
+
+One-time OAuth flow for local development:
+
+```bash
+npx wrangler login     # Opens browser, completes OAuth
+npx wrangler whoami    # Verify: shows email + account ID
+```
+
+Credentials stored locally. Works for all subsequent commands.
+
+## API Token (CI/CD)
+
+For automated pipelines or environments without browser access:
+
+1. Go to: **https://dash.cloudflare.com/profile/api-tokens**
+2. Click **Create Token**
+3. Use template: **"Edit Cloudflare Workers"** (covers Workers, Pages, KV, D1, R2)
+4. Copy the token (shown only once)
+5. Set environment variable:
+
+```bash
+export CLOUDFLARE_API_TOKEN="your-token-here"
+```
+
+### Minimal Permissions by Task
+
+| Task | Template / Permissions |
+|------|------------------------|
+| Deploy Workers/Pages | "Edit Cloudflare Workers" template |
+| Read-only access | "Read All Resources" template |
+| Custom scope | Account:Read + Workers Scripts:Edit + specific resources |
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Not logged in" | No credentials | `wrangler login` or set `CLOUDFLARE_API_TOKEN` |
+| "Authentication error" | Invalid/expired token | Regenerate token in dashboard |
+| "Missing account" | Wrong account selected | `wrangler whoami` to check, add `account_id` to wrangler.jsonc |
+| Token works locally, fails CI | Token scoped to wrong account | Verify account ID matches in both places |
+| "Insufficient permissions" | Token lacks required scope | Create new token with correct permissions |
+
+## Verifying Authentication
+
+```bash
+npx wrangler whoami
+```
+
+Output shows:
+- Email (if OAuth login)
+- Account ID and name
+- Token scopes (if API token)
+
+Non-zero exit code means not authenticated.
+
+## See Also
+
+- [terraform/README.md](../terraform/README.md) - Terraform provider auth
+- [pulumi/README.md](../pulumi/README.md) - Pulumi provider auth

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

@@ -0,0 +1,197 @@
+# Wrangler Configuration
+
+Configuration reference for wrangler.jsonc (recommended).
+
+## Config Format
+
+**wrangler.jsonc recommended** (v3.91.0+) - provides schema validation.
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",  // Use current date
+  "vars": { "API_KEY": "dev-key" },
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }]
+}
+```
+
+## Field Inheritance
+
+Inheritable: `name`, `main`, `compatibility_date`, `routes`, `triggers`
+Non-inheritable (define per env): `vars`, bindings (KV, D1, R2, etc.)
+
+## Environments
+
+```jsonc
+{
+  "name": "my-worker",
+  "vars": { "ENV": "dev" },
+  "env": {
+    "production": {
+      "name": "my-worker-prod",
+      "vars": { "ENV": "prod" },
+      "route": { "pattern": "example.com/*", "zone_name": "example.com" }
+    }
+  }
+}
+```
+
+Deploy: `wrangler deploy --env production`
+
+## Routing
+
+```jsonc
+// Custom domain (recommended)
+{ "routes": [{ "pattern": "api.example.com", "custom_domain": true }] }
+
+// Zone-based
+{ "routes": [{ "pattern": "api.example.com/*", "zone_name": "example.com" }] }
+
+// workers.dev
+{ "workers_dev": true }
+```
+
+## Bindings
+
+```jsonc
+// Variables
+{ "vars": { "API_URL": "https://api.example.com" } }
+
+// KV
+{ "kv_namespaces": [{ "binding": "CACHE", "id": "abc123" }] }
+
+// D1
+{ "d1_databases": [{ "binding": "DB", "database_id": "abc-123" }] }
+
+// R2
+{ "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }] }
+
+// Durable Objects
+{ "durable_objects": { 
+  "bindings": [{ 
+    "name": "COUNTER", 
+    "class_name": "Counter",
+    "script_name": "my-worker"  // Required for external DOs
+  }] 
+} }
+{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] }
+
+// Service Bindings
+{ "services": [{ "binding": "AUTH", "service": "auth-worker" }] }
+
+// Queues
+{ "queues": {
+  "producers": [{ "binding": "TASKS", "queue": "task-queue" }],
+  "consumers": [{ "queue": "task-queue", "max_batch_size": 10 }]
+} }
+
+// Vectorize
+{ "vectorize": [{ "binding": "VECTORS", "index_name": "embeddings" }] }
+
+// Hyperdrive (requires nodejs_compat_v2 for pg/postgres)
+{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "hyper-id" }] }
+{ "compatibility_flags": ["nodejs_compat_v2"] }  // For pg/postgres
+
+// Workers AI
+{ "ai": { "binding": "AI" } }
+
+// Workflows
+{ "workflows": [{ "binding": "WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" }] }
+
+// Secrets Store (centralized secrets)
+{ "secrets_store": [{ "binding": "SECRETS", "id": "store-id" }] }
+
+// Constellation (AI inference)
+{ "constellation": [{ "binding": "MODEL", "project_id": "proj-id" }] }
+```
+
+## Workers Assets (Static Files)
+
+Recommended for serving static files (replaces old `site` config).
+
+```jsonc
+{
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+    "html_handling": "auto-trailing-slash",  // or "none", "force-trailing-slash"
+    "not_found_handling": "single-page-application"  // or "404-page", "none"
+  }
+}
+```
+
+Access in Worker:
+```typescript
+export default {
+  async fetch(request, env) {
+    // Try serving static asset first
+    const asset = await env.ASSETS.fetch(request);
+    if (asset.status !== 404) return asset;
+    
+    // Custom logic for non-assets
+    return new Response("API response");
+  }
+}
+```
+
+## Placement
+
+Control where Workers run geographically.
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart"  // or "off"
+  }
+}
+```
+
+- `"smart"`: Run Worker near data sources (D1, Durable Objects) to reduce latency
+- `"off"`: Default distribution (run everywhere)
+
+## Auto-Provisioning (Beta)
+
+Omit resource IDs - Wrangler creates them and writes back to config on deploy.
+
+```jsonc
+{ "kv_namespaces": [{ "binding": "MY_KV" }] }  // No id - auto-provisioned
+```
+
+After deploy, ID is added to config automatically.
+
+## Advanced
+
+```jsonc
+// Cron Triggers
+{ "triggers": { "crons": ["0 0 * * *"] } }
+
+// Observability (tracing)
+{ "observability": { "enabled": true, "head_sampling_rate": 0.1 } }
+
+// Runtime Limits
+{ "limits": { "cpu_ms": 100 } }
+
+// Browser Rendering
+{ "browser": { "binding": "BROWSER" } }
+
+// mTLS Certificates
+{ "mtls_certificates": [{ "binding": "CERT", "certificate_id": "cert-uuid" }] }
+
+// Logpush (stream logs to R2/S3)
+{ "logpush": true }
+
+// Tail Consumers (process logs with another Worker)
+{ "tail_consumers": [{ "service": "log-worker" }] }
+
+// Unsafe bindings (access to arbitrary bindings)
+{ "unsafe": { "bindings": [{ "name": "MY_BINDING", "type": "plain_text", "text": "value" }] } }
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview and commands
+- [api.md](./api.md) - Programmatic API
+- [patterns.md](./patterns.md) - Workflows
+- [gotchas.md](./gotchas.md) - Common issues

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

@@ -0,0 +1,197 @@
+# Wrangler Common Issues
+
+## Common Errors
+
+### "Binding ID vs name mismatch"
+
+**Cause:** Confusion between binding name (code) and resource ID
+**Solution:** Bindings use `binding` (code name) and `id`/`database_id`/`bucket_name` (resource ID). Preview bindings need separate IDs: `preview_id`, `preview_database_id`
+
+### "Environment not inheriting config"
+
+**Cause:** Non-inheritable keys not redefined per environment
+**Solution:** Non-inheritable keys (bindings, vars) must be redefined per environment. Inheritable keys (routes, compatibility_date) can be overridden
+
+### "Local dev behavior differs from production"
+
+**Cause:** Using local simulation instead of remote execution
+**Solution:** Choose appropriate remote mode:
+- `wrangler dev` (default): Local simulation, fast, limited accuracy
+- `wrangler dev --remote`: Full remote execution, production-accurate, slower
+- Use `remote: "minimal"` in tests for fast tests with real remote bindings
+
+### "startWorker doesn't match production"
+
+**Cause:** Using local mode when remote resources needed
+**Solution:** Use `remote` option:
+```typescript
+const worker = await startWorker({ 
+  config: "wrangler.jsonc",
+  remote: true  // or "minimal" for faster tests
+});
+```
+
+### "Unexpected runtime changes"
+
+**Cause:** Missing compatibility_date
+**Solution:** Always set `compatibility_date`:
+```jsonc
+{ "compatibility_date": "2025-01-01" }
+```
+
+### "Durable Object binding not working"
+
+**Cause:** Missing script_name for external DOs
+**Solution:** Always specify `script_name` for external Durable Objects:
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "MY_DO", "class_name": "MyDO", "script_name": "my-worker" }
+    ]
+  }
+}
+```
+
+For local DOs in same Worker, `script_name` is optional.
+
+### "Auto-provisioned resources not appearing"
+
+**Cause:** IDs written back to config on first deploy, but config not reloaded
+**Solution:** After first deploy with auto-provisioning, config file is updated with IDs. Commit the updated config. On subsequent deploys, existing resources are reused.
+
+### "Secrets not available in local dev"
+
+**Cause:** Secrets set with `wrangler secret put` only work in deployed Workers
+**Solution:** For local dev, use `.dev.vars`
+
+### "Node.js compatibility error"
+
+**Cause:** Missing Node.js compatibility flag
+**Solution:** Some bindings (Hyperdrive with `pg`) require:
+```jsonc
+{ "compatibility_flags": ["nodejs_compat_v2"] }
+```
+
+### "Workers Assets 404 errors"
+
+**Cause:** Asset path mismatch or incorrect `html_handling`
+**Solution:** 
+- Check `assets.directory` points to correct build output
+- Set `html_handling: "auto-trailing-slash"` for SPAs
+- Use `not_found_handling: "single-page-application"` to serve index.html for 404s
+```jsonc
+{
+  "assets": {
+    "directory": "./dist",
+    "html_handling": "auto-trailing-slash",
+    "not_found_handling": "single-page-application"
+  }
+}
+```
+
+### "Placement not reducing latency"
+
+**Cause:** Misunderstanding of Smart Placement
+**Solution:** Smart Placement only helps when Worker accesses D1 or Durable Objects. It doesn't affect KV, R2, or external API latency.
+```jsonc
+{ "placement": { "mode": "smart" } }  // Only beneficial with D1/DOs
+```
+
+### "unstable_startWorker not found"
+
+**Cause:** Using outdated API
+**Solution:** Use stable `startWorker` instead:
+```typescript
+import { startWorker } from "wrangler";  // Not unstable_startWorker
+```
+
+### "outboundService not mocking fetch"
+
+**Cause:** Mock function not returning Response
+**Solution:** Always return Response, use `fetch(req)` for passthrough:
+```typescript
+const worker = await startWorker({
+  outboundService: (req) => {
+    if (shouldMock(req)) {
+      return new Response("mocked");
+    }
+    return fetch(req);  // Required for non-mocked requests
+  }
+});
+```
+
+## Limits
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| Bindings per Worker | 64 | Total across all types |
+| Environments | Unlimited | Named envs in config |
+| Config file size | ~1MB | Keep reasonable |
+| Workers Assets size | 25 MB | Per deployment |
+| Workers Assets files | 20,000 | Max number of files |
+| Script size (compressed) | 1 MB | Free, 10 MB paid |
+| CPU time | 10-50ms | Free, 50-500ms paid |
+| Subrequest limit | 50 | Free, 1000 paid |
+
+## Troubleshooting
+
+### Authentication Issues
+```bash
+wrangler logout
+wrangler login
+wrangler whoami
+```
+
+### Configuration Errors
+```bash
+wrangler check  # Validate config
+```
+Use wrangler.jsonc with `$schema` for validation.
+
+### Binding Not Available
+- Check binding exists in config
+- For environments, ensure binding defined for that env
+- Local dev: some bindings need `--remote`
+
+### Deployment Failures
+```bash
+wrangler tail              # Check logs
+wrangler deploy --dry-run  # Validate
+wrangler whoami            # Check account limits
+```
+
+### Local Development Issues
+```bash
+rm -rf .wrangler/state     # Clear local state
+wrangler dev --remote      # Use remote bindings
+wrangler dev --persist-to ./local-state  # Custom persist location
+wrangler dev --inspector-port 9229  # Enable debugging
+```
+
+### Testing Issues
+```bash
+# If tests hang, ensure dispose() is called
+worker.dispose()  // Always cleanup
+
+# If bindings don't work in tests
+const worker = await startWorker({ 
+  config: "wrangler.jsonc",
+  remote: "minimal"  // Use remote bindings
+});
+```
+
+## Resources
+
+- Docs: https://developers.cloudflare.com/workers/wrangler/
+- Config: https://developers.cloudflare.com/workers/wrangler/configuration/
+- Commands: https://developers.cloudflare.com/workers/wrangler/commands/
+- Examples: https://github.com/cloudflare/workers-sdk/tree/main/templates
+- Discord: https://discord.gg/cloudflaredev
+
+## See Also
+
+- [README.md](./README.md) - Commands
+- [configuration.md](./configuration.md) - Config
+- [api.md](./api.md) - Programmatic API
+- [patterns.md](./patterns.md) - Workflows