update skills

.agents/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