pi-cloudflare 0.1.0

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

@@ -0,0 +1,160 @@
+# 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/skills/cloudflare/references/miniflare/patterns.md

@@ -0,0 +1,181 @@
+# 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/skills/cloudflare/references/network-interconnect/README.md

@@ -0,0 +1,99 @@
+# 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

package/skills/cloudflare/references/network-interconnect/api.md

@@ -0,0 +1,199 @@
+# CNI API Reference
+
+See [README.md](README.md) for overview.
+
+## Base
+
+```
+https://api.cloudflare.com/client/v4
+Auth: Authorization: Bearer <token>
+```
+
+## SDK Namespaces
+
+**Primary (recommended):**
+```typescript
+client.networkInterconnects.interconnects.*
+client.networkInterconnects.cnis.*
+client.networkInterconnects.slots.*
+```
+
+**Alternate (deprecated):**
+```typescript
+client.magicTransit.cfInterconnects.*
+```
+
+Use `networkInterconnects` namespace for all new code.
+
+## Interconnects
+
+```http
+GET    /accounts/{account_id}/cni/interconnects              # Query: page, per_page
+POST   /accounts/{account_id}/cni/interconnects              # Query: validate_only=true (optional)
+GET    /accounts/{account_id}/cni/interconnects/{icon}
+GET    /accounts/{account_id}/cni/interconnects/{icon}/status
+GET    /accounts/{account_id}/cni/interconnects/{icon}/loa   # Returns PDF
+DELETE /accounts/{account_id}/cni/interconnects/{icon}
+```
+
+**Create Body:** `account`, `slot_id`, `type`, `facility`, `speed`, `name`, `description`  
+**Status Values:** `active` | `healthy` | `unhealthy` | `pending` | `down`
+
+**Response Example:**
+```json
+{"result": [{"id": "icon_abc", "name": "prod", "type": "direct", "facility": "EWR1", "speed": "10G", "status": "active"}]}
+```
+
+## CNI Objects (BGP config)
+
+```http
+GET    /accounts/{account_id}/cni/cnis
+POST   /accounts/{account_id}/cni/cnis
+GET    /accounts/{account_id}/cni/cnis/{cni}
+PUT    /accounts/{account_id}/cni/cnis/{cni}
+DELETE /accounts/{account_id}/cni/cnis/{cni}
+```
+
+Body: `account`, `cust_ip`, `cf_ip`, `bgp_asn`, `bgp_password`, `vlan`
+
+## Slots
+
+```http
+GET /accounts/{account_id}/cni/slots
+GET /accounts/{account_id}/cni/slots/{slot}
+```
+
+Query: `facility`, `occupied`, `speed`
+
+## Health Checks
+
+Configure via Magic Transit/WAN tunnel endpoints (CNI v2).
+
+```typescript
+await client.magicTransit.tunnels.update(accountId, tunnelId, {
+  health_check: { enabled: true, target: '192.0.2.1', rate: 'high', type: 'request' },
+});
+```
+
+Rates: `high` | `medium` | `low`. Types: `request` | `reply`. See [Magic Transit docs](https://developers.cloudflare.com/magic-transit/how-to/configure-tunnel-endpoints/#add-tunnels).
+
+## Settings
+
+```http
+GET /accounts/{account_id}/cni/settings
+PUT /accounts/{account_id}/cni/settings
+```
+
+Body: `default_asn`
+
+## TypeScript SDK
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: process.env.CF_TOKEN });
+
+// List
+await client.networkInterconnects.interconnects.list({ account_id: id });
+
+// Create with validation
+await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  account: id,
+  slot_id: 'slot_abc',
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'prod-interconnect',
+}, {
+  query: { validate_only: true }, // Dry-run validation
+});
+
+// Create without validation
+await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  account: id,
+  slot_id: 'slot_abc',
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'prod-interconnect',
+});
+
+// Status
+await client.networkInterconnects.interconnects.get(accountId, iconId);
+
+// LOA (use fetch)
+const res = await fetch(`https://api.cloudflare.com/client/v4/accounts/${id}/cni/interconnects/${iconId}/loa`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+await fs.writeFile('loa.pdf', Buffer.from(await res.arrayBuffer()));
+
+// CNI object
+await client.networkInterconnects.cnis.create({
+  account_id: id,
+  account: id,
+  cust_ip: '192.0.2.1/31',
+  cf_ip: '192.0.2.0/31',
+  bgp_asn: 65000,
+  vlan: 100,
+});
+
+// Slots (filter by facility and speed)
+await client.networkInterconnects.slots.list({
+  account_id: id,
+  occupied: false,
+  facility: 'EWR1',
+  speed: '10G',
+});
+```
+
+## Python SDK
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token=os.environ["CF_TOKEN"])
+
+# List, create, status (same pattern as TypeScript)
+client.network_interconnects.interconnects.list(account_id=id)
+client.network_interconnects.interconnects.create(account_id=id, account=id, slot_id="slot_abc", type="direct", facility="EWR1", speed="10G")
+client.network_interconnects.interconnects.get(account_id=id, icon=icon_id)
+
+# CNI objects and slots
+client.network_interconnects.cnis.create(account_id=id, cust_ip="192.0.2.1/31", cf_ip="192.0.2.0/31", bgp_asn=65000)
+client.network_interconnects.slots.list(account_id=id, occupied=False)
+```
+
+## cURL
+
+```bash
+# List interconnects
+curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects" \
+  -H "Authorization: Bearer ${CF_TOKEN}"
+
+# Create interconnect
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects?validate_only=true" \
+  -H "Authorization: Bearer ${CF_TOKEN}" -H "Content-Type: application/json" \
+  -d '{"account": "id", "slot_id": "slot_abc", "type": "direct", "facility": "EWR1", "speed": "10G"}'
+
+# LOA PDF
+curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects/${ICON_ID}/loa" \
+  -H "Authorization: Bearer ${CF_TOKEN}" --output loa.pdf
+```
+
+## Not Available via API
+
+**Missing Capabilities:**
+- BGP session state query (use Dashboard or BGP logs)
+- Bandwidth utilization metrics (use external monitoring)
+- Traffic statistics per interconnect
+- Historical uptime/downtime data
+- Light level readings (contact account team)
+- Maintenance window scheduling (notifications only)
+
+## Resources
+
+- [API Docs](https://developers.cloudflare.com/api/resources/network_interconnects/)
+- [TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)
+- [Python SDK](https://github.com/cloudflare/cloudflare-python)