devstack 0.1.0

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

@@ -0,0 +1,174 @@
+# Configuration
+
+## Script Loading
+
+```js
+// Inline
+new Miniflare({ modules: true, script: `export default { ... }` });
+
+// File-based
+new Miniflare({ scriptPath: "worker.js" });
+
+// Multi-module
+new Miniflare({
+  scriptPath: "src/index.js",
+  modules: true,
+  modulesRules: [
+    { type: "ESModule", include: ["**/*.js"] },
+    { type: "Text", include: ["**/*.txt"] },
+  ],
+});
+```
+
+## Compatibility
+
+```js
+new Miniflare({
+  compatibilityDate: "2026-01-01", // Use recent date for latest features
+  compatibilityFlags: [
+    "nodejs_compat", // Node.js APIs (process, Buffer, etc)
+    "streams_enable_constructors", // Stream constructors
+  ],
+  upstream: "https://example.com", // Fallback for unhandled requests
+});
+```
+
+**Critical:** Use `compatibilityDate: "2026-01-01"` or latest to match production runtime. Old dates limit available APIs.
+
+## HTTP Server & Request.cf
+
+```js
+new Miniflare({
+  port: 8787, // Default: 8787
+  host: "127.0.0.1",
+  https: true, // Self-signed cert
+  liveReload: true, // Auto-reload HTML
+
+  cf: true, // Fetch live Request.cf data (cached)
+  // cf: "./cf.json",      // Or load from file
+  // cf: { colo: "DFW" },  // Or inline mock
+});
+```
+
+**Note:** For tests, use `dispatchFetch()` (no port conflicts).
+
+## Storage Bindings
+
+```js
+new Miniflare({
+  // KV
+  kvNamespaces: ["TEST_NAMESPACE", "CACHE"],
+  kvPersist: "./kv-data", // Optional: persist to disk
+
+  // R2
+  r2Buckets: ["BUCKET", "IMAGES"],
+  r2Persist: "./r2-data",
+
+  // Durable Objects
+  modules: true,
+  durableObjects: {
+    COUNTER: "Counter", // className
+    API_OBJECT: { className: "ApiObject", scriptName: "api-worker" },
+  },
+  durableObjectsPersist: "./do-data",
+
+  // D1
+  d1Databases: ["DB"],
+  d1Persist: "./d1-data",
+
+  // Cache
+  cache: true, // Default
+  cachePersist: "./cache-data",
+});
+```
+
+## Bindings
+
+```js
+new Miniflare({
+  // Environment variables
+  bindings: {
+    SECRET_KEY: "my-secret-value",
+    API_URL: "https://api.example.com",
+    DEBUG: true,
+  },
+
+  // Other bindings
+  wasmBindings: { ADD_MODULE: "./add.wasm" },
+  textBlobBindings: { TEXT: "./data.txt" },
+  queueProducers: ["QUEUE"],
+});
+```
+
+## Multiple Workers
+
+```js
+new Miniflare({
+  workers: [
+    {
+      name: "main",
+      kvNamespaces: { DATA: "shared" },
+      serviceBindings: { API: "api-worker" },
+      script: `export default { ... }`,
+    },
+    {
+      name: "api-worker",
+      kvNamespaces: { DATA: "shared" }, // Shared storage
+      script: `export default { ... }`,
+    },
+  ],
+});
+```
+
+**With routing:**
+
+```js
+workers: [
+  { name: "api", scriptPath: "./api.js", routes: ["api.example.com/*"] },
+  { name: "web", scriptPath: "./web.js", routes: ["example.com/*"] },
+],
+```
+
+## Logging & Performance
+
+```js
+import { Log, LogLevel } from "miniflare";
+
+new Miniflare({
+  log: new Log(LogLevel.DEBUG), // DEBUG | INFO | WARN | ERROR | NONE
+  scriptTimeout: 30000, // CPU limit (ms)
+  workersConcurrencyLimit: 10, // Max concurrent workers
+});
+```
+
+## Workers Sites
+
+```js
+new Miniflare({
+  sitePath: "./public",
+  siteInclude: ["**/*.html", "**/*.css"],
+  siteExclude: ["**/*.map"],
+});
+```
+
+## From wrangler.toml
+
+Miniflare doesn't auto-read `wrangler.toml`:
+
+```toml
+# wrangler.toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2026-01-01"
+[[kv_namespaces]]
+binding = "KV"
+```
+
+```js
+// Miniflare equivalent
+new Miniflare({
+  scriptPath: "src/index.ts",
+  compatibilityDate: "2026-01-01",
+  kvNamespaces: ["KV"],
+});
+```

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

@@ -0,0 +1,179 @@
+# Gotchas & Troubleshooting
+
+## Miniflare Limitations
+
+**Not supported:**
+
+- Analytics Engine (use mocks)
+- Cloudflare Images/Stream
+- Browser Rendering API
+- Tail Workers
+- Workers for Platforms (partial support)
+
+**Behavior differences from production:**
+
+- Runs workerd locally, not Cloudflare edge
+- Storage is local (filesystem/memory), not distributed
+- `Request.cf` is cached/mocked, not real edge data
+- Performance differs from edge
+- Caching implementation may vary slightly
+
+## Common Errors
+
+### "Cannot find module"
+
+**Cause:** Module path wrong or `modulesRules` not configured  
+**Solution:**
+
+```js
+new Miniflare({
+  modules: true,
+  modulesRules: [{ type: "ESModule", include: ["**/*.js"] }],
+});
+```
+
+### "Data not persisting"
+
+**Cause:** Persist paths are files, not directories  
+**Solution:**
+
+```js
+kvPersist: "./data/kv",  // Directory, not file
+```
+
+### "Cannot run TypeScript"
+
+**Cause:** Miniflare doesn't transpile TypeScript  
+**Solution:** Build first with esbuild/tsc, then run compiled JS
+
+### "`request.cf` is undefined"
+
+**Cause:** CF data not configured  
+**Solution:**
+
+```js
+new Miniflare({ cf: true }); // Or cf: "./cf.json"
+```
+
+### "EADDRINUSE" port conflict
+
+**Cause:** Multiple instances using same port  
+**Solution:** Use `dispatchFetch()` (no HTTP server) or `port: 0` for auto-assign
+
+### "Durable Object not found"
+
+**Cause:** Class export doesn't match config name  
+**Solution:**
+
+```js
+export class Counter {} // Must match
+new Miniflare({ durableObjects: { COUNTER: "Counter" } });
+```
+
+## Debugging
+
+**Enable verbose logging:**
+
+```js
+import { Log, LogLevel } from "miniflare";
+new Miniflare({ log: new Log(LogLevel.DEBUG) });
+```
+
+**Chrome DevTools:**
+
+```js
+const url = await mf.getInspectorURL();
+console.log(`DevTools: ${url}`); // Open in Chrome
+```
+
+**Inspect bindings:**
+
+```js
+const env = await mf.getBindings();
+console.log(Object.keys(env));
+```
+
+**Verify storage:**
+
+```js
+const ns = await mf.getKVNamespace("TEST");
+const { keys } = await ns.list();
+```
+
+## Best Practices
+
+**✓ Do:**
+
+- Use `dispatchFetch()` for tests (no HTTP server)
+- In-memory storage for CI (omit persist options)
+- New instances per test for isolation
+- Type-safe bindings with interfaces
+- `await mf.dispose()` in cleanup
+
+**✗ Avoid:**
+
+- HTTP server in tests
+- Shared instances without cleanup
+- Old compatibility dates (use 2026+)
+
+## Migration Guides
+
+### From Miniflare 2.x to 3+
+
+Breaking changes in v3+:
+
+| v2                   | v3+                             |
+| -------------------- | ------------------------------- |
+| `getBindings()` sync | `getBindings()` returns Promise |
+| `ready` is void      | `ready` returns `Promise<URL>`  |
+| service-worker-mock  | Built on workerd                |
+| Different options    | Restructured constructor        |
+
+**Example migration:**
+
+```js
+// v2
+const bindings = mf.getBindings();
+mf.ready; // void
+
+// v3+
+const bindings = await mf.getBindings();
+const url = await mf.ready; // Promise<URL>
+```
+
+### From unstable_dev to Miniflare
+
+```js
+// Old (deprecated)
+import { unstable_dev } from "wrangler";
+const worker = await unstable_dev("src/index.ts");
+
+// New
+import { Miniflare } from "miniflare";
+const mf = new Miniflare({ scriptPath: "src/index.ts" });
+```
+
+### From Wrangler Dev
+
+Miniflare doesn't auto-read `wrangler.toml`:
+
+```js
+// Translate manually:
+new Miniflare({
+  scriptPath: "dist/worker.js",
+  compatibilityDate: "2026-01-01",
+  kvNamespaces: ["KV"],
+  bindings: { API_KEY: process.env.API_KEY },
+});
+```
+
+## Resource Limits
+
+| Limit      | Value            | Notes                            |
+| ---------- | ---------------- | -------------------------------- |
+| CPU time   | 30s default      | Configurable via `scriptTimeout` |
+| Storage    | Filesystem       | Performance varies by disk       |
+| Memory     | System dependent | No artificial limits             |
+| Request.cf | Cached/mocked    | Not live edge data               |
+
+See [patterns.md](./patterns.md) for testing examples.

package/vendor/skills/skills/cloudflare/references/miniflare/patterns.md

@@ -0,0 +1,187 @@
+# Testing Patterns
+
+## Choosing a Testing Approach
+
+| Approach                | Use Case                        | Speed  | Setup  | Runtime   |
+| ----------------------- | ------------------------------- | ------ | ------ | --------- |
+| **getPlatformProxy**    | Unit tests, logic testing       | Fast   | Low    | Miniflare |
+| **Miniflare API**       | Integration tests, full control | Medium | Medium | Miniflare |
+| **vitest-pool-workers** | Vitest runner integration       | Medium | Medium | workerd   |
+
+**Quick guide:**
+
+- Unit tests → getPlatformProxy
+- Integration tests → Miniflare API
+- Vitest workflows → vitest-pool-workers
+
+## getPlatformProxy
+
+Lightweight unit testing - provides bindings without full Worker runtime.
+
+```js
+// vitest.config.js
+export default { test: { environment: "node" } };
+```
+
+```js
+import { env } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Business logic", () => {
+  it("processes data with KV", async () => {
+    await env.KV.put("test", "value");
+    expect(await env.KV.get("test")).toBe("value");
+  });
+});
+```
+
+**Pros:** Fast, simple  
+**Cons:** No full runtime, can't test fetch handler
+
+## vitest-pool-workers
+
+Full Workers runtime in Vitest. Reads `wrangler.toml`.
+
+```bash
+npm i -D @cloudflare/vitest-pool-workers
+```
+
+```js
+// vitest.config.js
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: { workers: { wrangler: { configPath: "./wrangler.toml" } } },
+  },
+});
+```
+
+```js
+import { env, SELF } from "cloudflare:test";
+import { it, expect } from "vitest";
+
+it("handles fetch", async () => {
+  const res = await SELF.fetch("http://example.com/");
+  expect(res.status).toBe(200);
+});
+```
+
+**Pros:** Full runtime, uses wrangler.toml  
+**Cons:** Requires Wrangler config
+
+## Miniflare API (node:test)
+
+```js
+import assert from "node:assert";
+import test, { after, before } from "node:test";
+import { Miniflare } from "miniflare";
+
+let mf;
+before(() => {
+  mf = new Miniflare({ scriptPath: "src/index.js", kvNamespaces: ["TEST_KV"] });
+});
+
+test("fetch", async () => {
+  const res = await mf.dispatchFetch("http://localhost/");
+  assert.strictEqual(await res.text(), "Hello");
+});
+
+after(() => mf.dispose());
+```
+
+## Testing Durable Objects & Events
+
+```js
+// Durable Objects
+const ns = await mf.getDurableObjectNamespace("COUNTER");
+const stub = ns.get(ns.idFromName("test-counter"));
+await stub.fetch("http://localhost/increment");
+
+// Direct storage
+const storage = await mf.getDurableObjectStorage(ns.idFromName("test-counter"));
+const count = await storage.get("count");
+
+// Queue
+const worker = await mf.getWorker();
+await worker.queue("my-queue", [
+  { id: "msg1", timestamp: new Date(), body: { userId: 123 }, attempts: 1 },
+]);
+
+// Scheduled
+await worker.scheduled({ cron: "0 0 * * *" });
+```
+
+## Test Isolation & Mocking
+
+```js
+// Per-test isolation
+beforeEach(() => {
+  mf = new Miniflare({ kvNamespaces: ["TEST"] });
+});
+afterEach(() => mf.dispose());
+
+// Mock external APIs
+new Miniflare({
+  workers: [
+    { name: "main", serviceBindings: { API: "mock-api" }, script: `...` },
+    {
+      name: "mock-api",
+      script: `export default { async fetch() { return Response.json({mock: true}); } }`,
+    },
+  ],
+});
+```
+
+## Type Safety
+
+```ts
+import type { KVNamespace } from "@cloudflare/workers-types";
+
+interface Env {
+  KV: KVNamespace;
+  API_KEY: string;
+}
+
+const env = await mf.getBindings<Env>();
+await env.KV.put("key", "value"); // Typed!
+
+export default {
+  async fetch(req: Request, env: Env) {
+    return new Response(await env.KV.get("key"));
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## WebSocket Testing
+
+```js
+const res = await mf.dispatchFetch("http://localhost/ws", {
+  headers: { Upgrade: "websocket" },
+});
+assert.strictEqual(res.status, 101);
+```
+
+## Migration from unstable_dev
+
+```js
+// Old (deprecated)
+import { unstable_dev } from "wrangler";
+const worker = await unstable_dev("src/index.ts");
+
+// New
+import { Miniflare } from "miniflare";
+const mf = new Miniflare({ scriptPath: "src/index.ts" });
+```
+
+## CI/CD Tips
+
+```js
+// In-memory storage (faster)
+new Miniflare({ kvNamespaces: ["TEST"] }); // No persist = in-memory
+
+// Use dispatchFetch (no port conflicts)
+await mf.dispatchFetch("http://localhost/");
+```
+
+See [gotchas.md](./gotchas.md) for troubleshooting.

package/vendor/skills/skills/cloudflare/references/network-interconnect/README.md

@@ -0,0 +1,104 @@
+# Cloudflare Network Interconnect (CNI)
+
+Private, high-performance connectivity to Cloudflare's network. **Enterprise-only**.
+
+## Connection Types
+
+**Direct**: Physical fiber in shared datacenter. 10/100 Gbps. You order cross-connect.
+
+**Partner**: Virtual via Console Connect, Equinix, Megaport, etc. Managed via partner SDN.
+
+**Cloud**: AWS Direct Connect or GCP Cloud Interconnect. Magic WAN only.
+
+## Dataplane Versions
+
+**v1 (Classic)**: GRE tunnel support, VLAN/BFD/LACP, asymmetric MTU (1500↓/1476↑), peering support.
+
+**v2 (Beta)**: No GRE, 1500 MTU both ways, no VLAN/BFD/LACP yet, ECMP instead.
+
+## Use Cases
+
+- **Magic Transit DSR**: DDoS protection, egress via ISP (v1/v2)
+- **Magic Transit + Egress**: DDoS + egress via CF (v1/v2)
+- **Magic WAN + Zero Trust**: Private backbone (v1 needs GRE, v2 native)
+- **Peering**: Public routes at PoP (v1 only)
+- **App Security**: WAF/Cache/LB (v1/v2 over Magic Transit)
+
+## Prerequisites
+
+- Enterprise plan
+- IPv4 /24+ or IPv6 /48+ prefixes
+- BGP ASN for v1
+- See [locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-2026-01.pdf)
+
+## Specs
+
+- /31 point-to-point subnets
+- 10km max optical distance
+- 10G: 10GBASE-LR single-mode
+- 100G: 100GBASE-LR4 single-mode
+- **No SLA** (free service)
+- Backup Internet required
+
+## Throughput
+
+| Direction               | 10G                  | 100G                 |
+| ----------------------- | -------------------- | -------------------- |
+| CF → Customer           | 10 Gbps              | 100 Gbps             |
+| Customer → CF (peering) | 10 Gbps              | 100 Gbps             |
+| Customer → CF (Magic)   | 1 Gbps/tunnel or CNI | 1 Gbps/tunnel or CNI |
+
+## Timeline
+
+2-4 weeks typical. Steps: request → config review → order connection → configure → test → enable health checks → activate → monitor.
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - BGP, routing, setup
+- [api.md](./api.md) - API endpoints, SDKs
+- [patterns.md](./patterns.md) - HA, hybrid cloud, failover
+- [gotchas.md](./gotchas.md) - Troubleshooting, limits
+
+## Reading Order by Task
+
+| Task                        | Files to Load                      |
+| --------------------------- | ---------------------------------- |
+| Initial setup               | README → configuration.md → api.md |
+| Create interconnect via API | api.md → gotchas.md                |
+| Design HA architecture      | patterns.md → README               |
+| Troubleshoot connection     | gotchas.md → configuration.md      |
+| Cloud integration (AWS/GCP) | configuration.md → patterns.md     |
+| Monitor + alerts            | configuration.md                   |
+
+## Automation Boundary
+
+**API-Automatable:**
+
+- List/create/delete interconnects (Direct, Partner)
+- List available slots
+- Get interconnect status
+- Download LOA PDF
+- Create/update CNI objects (BGP config)
+- Query settings
+
+**Requires Account Team:**
+
+- Initial request approval
+- AWS Direct Connect setup (send LOA+VLAN to CF)
+- GCP Cloud Interconnect final activation
+- Partner interconnect acceptance (Equinix, Megaport)
+- VLAN assignment (v1)
+- Configuration document generation (v1)
+- Escalations + troubleshooting support
+
+**Cannot Be Automated:**
+
+- Physical cross-connect installation (Direct)
+- Partner portal operations (virtual circuit ordering)
+- AWS/GCP portal operations
+- Maintenance window coordination
+
+## See Also
+
+- [tunnel](../tunnel/) - Alternative for private network connectivity
+- [spectrum](../spectrum/) - Layer 4 proxy for TCP/UDP traffic