codexkit 1.0.0

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

@@ -0,0 +1,144 @@
+# Programmatic API
+
+## Miniflare Class
+
+```typescript
+class Miniflare {
+  constructor(options: MiniflareOptions);
+  ready: Promise<void>;
+  dispose(): Promise<void>;
+  setOptions(options: MiniflareOptions): Promise<void>;
+  
+  // Event dispatching
+  dispatchFetch(url: string, init?: RequestInit): Promise<Response>;
+  getWorker(): Promise<Worker>;
+  
+  // Bindings access
+  getBindings(): Promise<Record<string, any>>;
+  getKVNamespace(name: string): Promise<KVNamespace>;
+  getR2Bucket(name: string): Promise<R2Bucket>;
+  getDurableObjectNamespace(name: string): Promise<DurableObjectNamespace>;
+  getDurableObjectStorage(id: DurableObjectId): Promise<DurableObjectStorage>;
+  getD1Database(name: string): Promise<D1Database>;
+  getCaches(): Promise<CacheStorage>;
+  getQueueProducer(name: string): Promise<QueueProducer>;
+}
+```
+
+## Event Dispatching
+
+**Fetch (no HTTP server):**
+```js
+const res = await mf.dispatchFetch("http://localhost:8787/path", {
+  method: "POST",
+  headers: { "Authorization": "Bearer token" },
+  body: JSON.stringify({ data: "value" }),
+});
+```
+
+**Custom Host routing:**
+```js
+const res = await mf.dispatchFetch("http://localhost:8787/", {
+  headers: { "Host": "api.example.com" },
+});
+```
+
+**Scheduled:**
+```js
+const worker = await mf.getWorker();
+const result = await worker.scheduled({ cron: "30 * * * *" });
+// result: { outcome: "ok", noRetry: false }
+```
+
+**Queue:**
+```js
+const worker = await mf.getWorker();
+const result = await worker.queue("queue-name", [
+  { id: "msg1", timestamp: new Date(), body: "data", attempts: 1 },
+]);
+// result: { outcome: "ok", retryAll: false, ackAll: false, ... }
+```
+
+## Bindings Access
+
+**Environment variables:**
+```js
+const bindings = await mf.getBindings();
+console.log(bindings.SECRET_KEY);
+```
+
+**KV:**
+```js
+const ns = await mf.getKVNamespace("TEST_NAMESPACE");
+await ns.put("key", "value");
+const value = await ns.get("key");
+```
+
+**R2:**
+```js
+const bucket = await mf.getR2Bucket("BUCKET");
+await bucket.put("file.txt", "content");
+const object = await bucket.get("file.txt");
+```
+
+**Durable Objects:**
+```js
+const ns = await mf.getDurableObjectNamespace("COUNTER");
+const id = ns.idFromName("test");
+const stub = ns.get(id);
+const res = await stub.fetch("http://localhost/");
+
+// Access storage directly:
+const storage = await mf.getDurableObjectStorage(id);
+await storage.put("key", "value");
+```
+
+**D1:**
+```js
+const db = await mf.getD1Database("DB");
+await db.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`);
+await db.prepare("INSERT INTO users (name) VALUES (?)").bind("Alice").run();
+```
+
+**Cache:**
+```js
+const caches = await mf.getCaches();
+const defaultCache = caches.default;
+await defaultCache.put("http://example.com", new Response("cached"));
+```
+
+**Queue producer:**
+```js
+const producer = await mf.getQueueProducer("QUEUE");
+await producer.send({ body: "message data" });
+```
+
+## Lifecycle
+
+**Reload:**
+```js
+await mf.setOptions({
+  scriptPath: "worker.js",
+  bindings: { VERSION: "2.0" },
+});
+```
+
+**Watch (manual):**
+```js
+import { watch } from "fs";
+
+const config = { scriptPath: "worker.js" };
+const mf = new Miniflare(config);
+
+watch("worker.js", async () => {
+  console.log("Reloading...");
+  await mf.setOptions(config);
+});
+```
+
+**Cleanup:**
+```js
+await mf.dispose();
+```
+
+See [configuration.md](./configuration.md) for all constructor options.

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

@@ -0,0 +1,203 @@
+# Configuration
+
+## Script Loading
+
+**Inline:**
+```js
+new Miniflare({ modules: true, script: `export default { ... }` });
+```
+
+**File-based:**
+```js
+new Miniflare({ scriptPath: "worker.js" });
+```
+
+**Multi-module auto-crawl:**
+```js
+new Miniflare({
+  scriptPath: "src/index.js",
+  modules: true,
+  modulesRules: [
+    { type: "ESModule", include: ["**/*.js"] },
+    { type: "Text", include: ["**/*.txt"] },
+  ],
+});
+```
+
+**Explicit modules:**
+```js
+new Miniflare({
+  modules: [
+    { type: "ESModule", path: "src/index.js" },
+    { type: "Text", path: "data.txt" },
+  ],
+});
+```
+
+## Compatibility
+
+```js
+new Miniflare({
+  compatibilityDate: "2021-11-23",
+  compatibilityFlags: ["formdata_parser_supports_files"],
+  upstream: "https://example.com",
+});
+```
+
+## Server Options
+
+```js
+new Miniflare({
+  port: 8787,
+  host: "127.0.0.1",
+  https: true, // Self-signed cert
+  httpsKeyPath: "./key.pem",
+  httpsCertPath: "./cert.pem",
+});
+```
+
+**Request.cf:**
+```js
+cf: true,        // Fetch from Cloudflare
+cf: "cf.json",   // Load from file
+cf: false,       // Disable
+```
+
+## Storage Bindings
+
+**KV:**
+```js
+kvNamespaces: ["TEST_NAMESPACE", "CACHE"],
+kvPersist: "./kv-data", // Optional: persist to disk
+```
+
+**R2:**
+```js
+r2Buckets: ["BUCKET", "IMAGES"],
+r2Persist: "./r2-data",
+```
+
+**Durable Objects:**
+```js
+modules: true,
+durableObjects: {
+  COUNTER: "Counter", // className
+  API_OBJECT: { className: "ApiObject", scriptName: "api-worker" },
+},
+durableObjectsPersist: "./do-data",
+```
+
+**D1:**
+```js
+d1Databases: ["DB"],
+d1Persist: "./d1-data",
+```
+
+**Cache:**
+```js
+cache: true, // Default
+cachePersist: "./cache-data",
+cacheWarnUsage: true,
+```
+
+## Bindings
+
+**Environment variables:**
+```js
+bindings: {
+  SECRET_KEY: "my-secret-value",
+  API_URL: "https://api.example.com",
+  DEBUG: true,
+},
+```
+
+**WASM:**
+```js
+wasmBindings: { ADD_MODULE: "./add.wasm" },
+```
+
+**Text/Data blobs:**
+```js
+textBlobBindings: { TEXT: "./data.txt" },
+dataBlobBindings: { DATA: "./data.bin" },
+```
+
+**Queue producers:**
+```js
+queueProducers: ["QUEUE"],
+```
+
+## Multiple Workers
+
+```js
+new Miniflare({
+  host: "0.0.0.0",
+  port: 8787,
+  kvPersist: true,
+  
+  workers: [
+    {
+      name: "main-worker",
+      kvNamespaces: { DATA: "shared-data" },
+      serviceBindings: {
+        API: "api-worker",
+        async EXTERNAL(request) {
+          return new Response("External response");
+        },
+      },
+      modules: true,
+      script: `export default { ... }`,
+    },
+    {
+      name: "api-worker",
+      kvNamespaces: { DATA: "shared-data" }, // Shared
+      script: `addEventListener("fetch", ...)`,
+    },
+  ],
+});
+```
+
+## Routing
+
+```js
+workers: [
+  {
+    name: "api",
+    scriptPath: "./api/worker.js",
+    routes: ["http://127.0.0.1/api/*", "api.example.com/*"],
+  },
+  {
+    name: "web",
+    scriptPath: "./web/worker.js",
+    routes: ["example.com/*"],
+  },
+],
+```
+
+Update `/etc/hosts`: `127.0.0.1 api.example.com`
+
+## Advanced
+
+**Logging:**
+```js
+import { Log, LogLevel } from "miniflare";
+new Miniflare({ log: new Log(LogLevel.DEBUG) }); // DEBUG, INFO, WARN, ERROR
+```
+
+**Live reload:**
+```js
+liveReload: true, // Auto-reload HTML on worker reload
+```
+
+**Workers Site:**
+```js
+sitePath: "./public",
+siteInclude: ["**/*.html", "**/*.css"],
+siteExclude: ["node_modules/**"],
+```
+
+## CLI Options
+
+Miniflare doesn't read `wrangler.toml` - configure via API. For wrangler.toml configs, manually translate to Miniflare options.
+
+See [api.md](./api.md) for full API reference.

package/.codex/skills/cloudflare/references/miniflare/gotchas.md

@@ -0,0 +1,187 @@
+# Gotchas & Debugging
+
+## Compatibility Issues
+
+### Not Supported in Miniflare
+
+- Cloudflare Analytics Engine
+- Cloudflare Images
+- Live production data
+- True global distribution
+- Some advanced Workers features
+
+### Behavior Differences from Production
+
+1. **No actual edge:** Runs in workerd locally, not Cloudflare's global network
+2. **Persistence:** Local filesystem/in-memory, not distributed
+3. **Request.cf:** Fetched from cached endpoint or mocked, not real edge metadata
+4. **Performance:** Local performance ≠ edge performance
+5. **Caching:** May differ slightly from production
+
+## Common Issues
+
+### Module Resolution Errors
+
+**Problem:** `Cannot find module`
+
+**Fix:**
+```js
+// Use absolute paths or modulesRules
+new Miniflare({
+  scriptPath: "./src/index.js",
+  modules: true,
+  modulesRules: [
+    { type: "ESModule", include: ["**/*.js"], fallthrough: true },
+  ],
+});
+```
+
+### Persistence Not Working
+
+**Problem:** Data not persisting between runs
+
+**Fix:**
+```js
+// Ensure persist paths are directories, not files
+new Miniflare({
+  kvPersist: "./data/kv",           // Directory
+  r2Persist: "./data/r2",
+  durableObjectsPersist: "./data/do",
+});
+```
+
+### TypeScript Workers
+
+**Problem:** Cannot directly run TypeScript
+
+**Fix:**
+```js
+// Build before running
+import { spawnSync } from "node:child_process";
+
+before(() => {
+  const result = spawnSync("npm run build", { shell: true });
+  if (result.error) throw result.error;
+});
+
+new Miniflare({ scriptPath: "dist/worker.js" });
+```
+
+### Request.cf Undefined
+
+**Problem:** `request.cf` is undefined in worker
+
+**Fix:**
+```js
+new Miniflare({
+  cf: true, // Fetch from Cloudflare
+  // Or provide custom
+  cf: "./cf.json",
+});
+```
+
+### Port Already in Use
+
+**Problem:** `EADDRINUSE` error
+
+**Fix:**
+```js
+// Don't specify port for testing - use dispatchFetch
+new Miniflare({
+  scriptPath: "worker.js",
+  // No port/host
+});
+
+const res = await mf.dispatchFetch("http://localhost/");
+```
+
+### Durable Object Not Found
+
+**Problem:** `ReferenceError: Counter is not defined`
+
+**Fix:**
+```js
+// Ensure DO class is exported
+new Miniflare({
+  modules: true, // Required for DOs
+  script: `
+    export class Counter { /* ... */ } // Must export
+    export default { /* ... */ }
+  `,
+  durableObjects: {
+    COUNTER: "Counter", // Must match export name
+  },
+});
+```
+
+## Debugging Tips
+
+**Enable debug logging:**
+```js
+import { Log, LogLevel } from "miniflare";
+new Miniflare({ log: new Log(LogLevel.DEBUG) });
+```
+
+**Check binding names match:**
+```js
+const bindings = await mf.getBindings();
+console.log(Object.keys(bindings));
+```
+
+**Verify storage directly:**
+```js
+const ns = await mf.getKVNamespace("TEST");
+const keys = await ns.list();
+console.log(keys);
+```
+
+**Test HTTP server separately:**
+```js
+// Use dispatchFetch for tests, not HTTP server
+const res = await mf.dispatchFetch("http://localhost/");
+```
+
+## Migration Notes
+
+### From Wrangler Dev to Miniflare
+
+**Wrangler:**
+```bash
+wrangler dev
+```
+
+**Miniflare:**
+```js
+new Miniflare({
+  scriptPath: "dist/worker.js",
+  // Manually configure bindings (doesn't read wrangler.toml)
+  kvNamespaces: ["KV"],
+  bindings: { API_KEY: "..." },
+});
+```
+
+**Note:** Miniflare doesn't read `wrangler.toml` - configure everything via API.
+
+### From Miniflare 2 to 3
+
+Major changes:
+- Different API surface
+- Better workerd integration
+- Changed persistence options
+- See [official migration guide](https://developers.cloudflare.com/workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/)
+
+## When to Use
+
+**Use Miniflare when:**
+- Writing integration tests for Workers
+- Testing Worker bindings/storage locally
+- Testing multiple Workers with service bindings
+- Need direct access to bindings in tests
+- Dispatch events without HTTP
+
+**Use Wrangler instead for:**
+- Standard development workflow
+- Quick local dev server
+- Production deployments
+
+See [patterns.md](./patterns.md) for testing examples.