codexkit 1.0.0

package/.codex/skills/cloudflare/references/wrangler/api.md

@@ -0,0 +1,140 @@
+# Wrangler Programmatic API
+
+Node.js APIs for testing and development.
+
+## unstable_startWorker (Testing)
+
+Starts Worker with real local bindings for integration tests.
+
+```typescript
+import { unstable_startWorker } from "wrangler";
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert";
+
+describe("worker", () => {
+  let worker;
+  
+  before(async () => {
+    worker = await unstable_startWorker({ config: "wrangler.jsonc" });
+  });
+  
+  after(async () => {
+    await worker.dispose();
+  });
+  
+  it("responds with 200", async () => {
+    const response = await worker.fetch("http://example.com");
+    assert.strictEqual(response.status, 200);
+  });
+});
+```
+
+Options: `config`, `environment`, `persist`, `bundle`
+
+## 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 Cases
+
+**Unit Tests**
+```typescript
+const { env, dispose } = await getPlatformProxy();
+
+describe("database", () => {
+  after(async () => await dispose());
+  
+  it("inserts user", async () => {
+    const result = await env.DB.prepare(
+      "INSERT INTO users (name) VALUES (?)"
+    ).bind("Alice").run();
+    assert.strictEqual(result.meta.changes, 1);
+  });
+});
+```
+
+**Scripts**
+```typescript
+const { env, dispose } = await getPlatformProxy({
+  persist: { path: ".wrangler/state" }
+});
+
+await env.DB.batch([
+  env.DB.prepare("CREATE TABLE users (id INTEGER PRIMARY KEY)"),
+  env.DB.prepare("INSERT INTO users (id) VALUES (1)")
+]);
+
+await dispose();
+```
+
+## Type Generation
+
+```bash
+wrangler types
+```
+
+Creates `worker-configuration.d.ts`:
+
+```typescript
+interface Env {
+  MY_KV: KVNamespace;
+  DB: D1Database;
+  API_KEY: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const value = await env.MY_KV.get("key");  // Type-safe
+    return Response.json({ value });
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## unstable_dev (Legacy)
+
+Use `unstable_startWorker` instead.
+
+```typescript
+import { unstable_dev } from "wrangler";
+
+const worker = await unstable_dev("src/index.ts", {
+  config: "wrangler.jsonc"
+});
+
+const response = await worker.fetch();
+await worker.stop();
+```
+
+## Best Practices
+
+- Use `unstable_startWorker` for integration tests (tests full Worker)
+- Use `getPlatformProxy` for unit tests (tests individual functions)
+- Enable `persist: true` for debugging (state survives runs)
+- Run `wrangler types` after config changes
+- Always `dispose()` to prevent resource leaks
+
+## See Also
+
+- [README.md](./README.md) - CLI commands
+- [configuration.md](./configuration.md) - Config
+- [patterns.md](./patterns.md) - Testing patterns

package/.codex/skills/cloudflare/references/wrangler/configuration.md

@@ -0,0 +1,128 @@
+# Wrangler Configuration
+
+Configuration reference for wrangler.jsonc (recommended) and wrangler.toml.
+
+## 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 Categories
+
+### Top-Level Only
+- `keep_vars`, `migrations`, `send_metrics`
+
+### Inheritable (can override per env)
+- `name`, `main`, `compatibility_date`, `account_id`
+- `workers_dev`, `routes`, `triggers`, `minify`, `observability`
+
+### Non-Inheritable (per-env required)
+- `vars`, `kv_namespaces`, `d1_databases`, `r2_buckets`
+- `durable_objects`, `vectorize`, `hyperdrive`, `services`, `queues`
+
+## 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": { "bindings": [{ "name": "COUNTER", "class_name": "Counter" }] } }
+{ "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)
+{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "hyper-id" }] }
+
+// Workers AI
+{ "ai": { "binding": "AI" } }
+```
+
+## Advanced
+
+```jsonc
+// Cron Triggers
+{ "triggers": { "crons": ["0 0 * * *"] } }
+
+// Observability
+{ "observability": { "enabled": true, "head_sampling_rate": 0.1 } }
+
+// Runtime Limits
+{ "limits": { "cpu_ms": 100 } }
+
+// Auto-Provisioning (Beta) - IDs written back on deploy
+{ "kv_namespaces": [{ "binding": "MY_KV" }] }
+
+// Static Assets
+{ "assets": { "directory": "./public", "binding": "ASSETS" } }
+
+// mTLS Certificates
+{ "mtls_certificates": [{ "binding": "CERT", "certificate_id": "cert-uuid" }] }
+```
+
+## 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/.codex/skills/cloudflare/references/wrangler/gotchas.md

@@ -0,0 +1,93 @@
+# Wrangler Common Issues
+
+Pitfalls, limits, and troubleshooting.
+
+## Common Gotchas
+
+### Binding IDs vs Names
+- Bindings use `binding` (code name) and `id`/`database_id`/`bucket_name` (resource ID)
+- Preview bindings need separate IDs: `preview_id`, `preview_database_id`
+
+### Environment Inheritance
+- Non-inheritable keys (bindings, vars) must be redefined per environment
+- Inheritable keys (routes, compatibility_date) can be overridden
+
+### Local vs Remote Dev
+- `wrangler dev` (default): Local simulation, fast, limited accuracy
+- `wrangler dev --remote`: Remote execution, slower, production-accurate
+
+### Compatibility Dates
+Always set `compatibility_date` to avoid unexpected runtime changes:
+```jsonc
+{ "compatibility_date": "2025-01-01" }
+```
+
+### Durable Objects Need script_name
+With `getPlatformProxy`, always specify `script_name`:
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "MY_DO", "class_name": "MyDO", "script_name": "my-worker" }
+    ]
+  }
+}
+```
+
+### Secrets in Local Dev
+Secrets set with `wrangler secret put` only work in deployed Workers. For local dev, use `.dev.vars`.
+
+### Node.js Compatibility
+Some bindings (Hyperdrive with `pg`) require Node.js compatibility:
+```jsonc
+{ "compatibility_flags": ["nodejs_compat_v2"] }
+```
+
+## 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
+```
+
+## 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

package/.codex/skills/cloudflare/references/wrangler/patterns.md

@@ -0,0 +1,150 @@
+# Wrangler Development Patterns
+
+Common workflows and best practices.
+
+## New Worker Project
+
+```bash
+wrangler init my-worker && cd my-worker
+wrangler dev              # Develop locally
+wrangler deploy           # Deploy
+```
+
+## Local Development
+
+```bash
+wrangler dev              # Local (fast, limited accuracy)
+wrangler dev --remote     # Remote (slower, production-accurate)
+wrangler dev --env staging
+wrangler dev --port 8787
+```
+
+## Secrets
+
+**Never commit secrets.** Use `wrangler secret put` for production, `.dev.vars` for local.
+
+```bash
+# Production
+echo "secret-value" | wrangler secret put SECRET_KEY
+wrangler secret list
+wrangler secret delete SECRET_KEY
+```
+
+`.dev.vars` (gitignored):
+```
+SECRET_KEY=local-dev-key
+```
+
+## Adding KV
+
+```bash
+wrangler kv namespace create MY_KV
+wrangler kv namespace create MY_KV --preview
+# Add to wrangler.jsonc: { "binding": "MY_KV", "id": "abc123" }
+wrangler deploy
+```
+
+## Adding D1
+
+```bash
+wrangler d1 create my-db
+wrangler d1 migrations create my-db "initial_schema"
+# Edit migration file, then:
+wrangler d1 migrations apply my-db --local
+wrangler deploy
+wrangler d1 migrations apply my-db --remote
+```
+
+## Multi-Environment
+
+```bash
+wrangler deploy --env staging
+wrangler deploy --env production
+```
+
+```jsonc
+{ "env": { "staging": { "vars": { "ENV": "staging" } } } }
+```
+
+## Testing
+
+```typescript
+import { unstable_startWorker } from "wrangler";
+
+const worker = await unstable_startWorker({ config: "wrangler.jsonc" });
+const response = await worker.fetch("/api/users");
+await worker.dispose();
+```
+
+## Monitoring
+
+```bash
+wrangler tail                 # Real-time logs
+wrangler tail --status error  # Filter errors
+wrangler tail --env production
+wrangler whoami               # Check auth
+```
+
+## Version Control
+
+```bash
+wrangler versions list
+wrangler deployments list
+wrangler rollback [id]
+```
+
+## TypeScript
+
+```bash
+wrangler types  # Generate types from config
+```
+
+```typescript
+interface Env {
+  MY_KV: KVNamespace;
+  DB: D1Database;
+  API_KEY: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const value = await env.MY_KV.get("key");
+    return Response.json({ value });
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Durable Objects Migration
+
+```jsonc
+{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] }
+```
+
+## Performance
+
+```jsonc
+{ "minify": true }
+```
+
+```typescript
+// KV caching
+const cached = await env.CACHE.get("key", { cacheTtl: 3600 });
+
+// Batch DB
+await env.DB.batch([
+  env.DB.prepare("SELECT * FROM users"),
+  env.DB.prepare("SELECT * FROM posts")
+]);
+
+// Edge caching
+return new Response(data, {
+  headers: { "Cache-Control": "public, max-age=3600" }
+});
+```
+
+## See Also
+
+- [README.md](./README.md) - Commands
+- [configuration.md](./configuration.md) - Config
+- [api.md](./api.md) - Programmatic API
+- [gotchas.md](./gotchas.md) - Issues