@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/web-analytics/integration.md

@@ -0,0 +1,60 @@
+# Framework Integration
+
+**Web Analytics is dashboard-only** - no programmatic API. This covers beacon integration.
+
+## Basic HTML
+
+```html
+<script defer src='https://static.cloudflareinsights.com/beacon.min.js' 
+        data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'></script>
+```
+
+Place before closing `</body>` tag.
+
+## Framework Examples
+
+| Framework | Location | Notes |
+|-----------|----------|-------|
+| React/Vite | `public/index.html` | Add `spa: true` |
+| Next.js App Router | `app/layout.tsx` | Use `<Script strategy="afterInteractive">` |
+| Next.js Pages | `pages/_document.tsx` | Use `<Script>` |
+| Nuxt 3 | `app.vue` with `useHead()` | Or use plugin |
+| Vue 3/Vite | `index.html` | Add `spa: true` |
+| Gatsby | `gatsby-browser.js` | `onClientEntry` hook |
+| SvelteKit | `src/app.html` | Before `</body>` |
+| Astro | Layout component | Before `</body>` |
+| Angular | `src/index.html` | Add `spa: true` |
+| Docusaurus | `docusaurus.config.js` | In `scripts` array |
+
+## Configuration
+
+```json
+{
+  "token": "YOUR_TOKEN",
+  "spa": true
+}
+```
+
+**Use `spa: true` for:** React Router, Vue Router, Next.js, Nuxt, Gatsby, SvelteKit, Angular
+
+**Use `spa: false` for:** Traditional server-rendered (PHP, Django, Rails, WordPress)
+
+## CSP Headers
+
+```
+script-src 'self' https://static.cloudflareinsights.com;
+connect-src 'self' https://cloudflareinsights.com;
+```
+
+## GDPR Consent
+
+```typescript
+// Load conditionally based on consent
+if (localStorage.getItem('analytics-consent') === 'true') {
+  const script = document.createElement('script');
+  script.src = 'https://static.cloudflareinsights.com/beacon.min.js';
+  script.defer = true;
+  script.setAttribute('data-cf-beacon', '{"token": "YOUR_TOKEN", "spa": true}');
+  document.body.appendChild(script);
+}
+```

package/skills/cloudflare-deploy/references/web-analytics/patterns.md

@@ -0,0 +1,91 @@
+# Web Analytics Patterns
+
+## Core Web Vitals Debugging
+
+Dashboard → Core Web Vitals → Click metric → Debug View shows top 5 problematic elements.
+
+### LCP Fixes
+
+```html
+<!-- Priority hints -->
+<img src="hero.jpg" loading="eager" fetchpriority="high" />
+<link rel="preload" as="image" href="/hero.jpg" fetchpriority="high" />
+```
+
+### CLS Fixes
+
+```css
+/* Reserve space */
+.ad-container { min-height: 250px; }
+img { width: 400px; height: 300px; } /* Explicit dimensions */
+```
+
+### INP Fixes
+
+```typescript
+// Debounce expensive operations
+const handleInput = debounce(search, 300);
+
+// Yield to main thread
+await task(); await new Promise(r => setTimeout(r, 0)); await task2();
+
+// Move to Web Worker for heavy computation
+```
+
+| Metric | Good | Poor |
+|--------|------|------|
+| LCP | ≤2.5s | >4s |
+| INP | ≤200ms | >500ms |
+| CLS | ≤0.1 | >0.25 |
+
+## GDPR Consent
+
+```typescript
+// Load beacon only after consent
+const consent = localStorage.getItem('analytics-consent');
+if (consent === 'accepted') {
+  const script = document.createElement('script');
+  script.src = 'https://static.cloudflareinsights.com/beacon.min.js';
+  script.setAttribute('data-cf-beacon', '{"token": "TOKEN", "spa": true}');
+  document.body.appendChild(script);
+}
+```
+
+Alternative: Dashboard → "Enable, excluding visitor data in the EU"
+
+## SPA Navigation
+
+```html
+<!-- REQUIRED for React/Vue/etc routing -->
+<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
+```
+
+Without `spa: true`: only initial pageload tracked.
+
+## Staging/Production Separation
+
+```typescript
+// Use env-specific tokens
+const token = process.env.NEXT_PUBLIC_CF_ANALYTICS_TOKEN;
+// .env.production: production token
+// .env.staging: staging token (or empty to disable)
+```
+
+## Bot Filtering
+
+Dashboard → Filters → "Exclude Bot Traffic"
+
+Filters: Search crawlers, monitoring services, known bots.  
+Not filtered: Headless browsers (Playwright/Puppeteer).
+
+## Ad-Blocker Impact
+
+~25-40% of users may block `cloudflareinsights.com`. No official workaround.
+Dashboard shows minimum baseline; use server logs for complete picture.
+
+## Limitations
+
+- No UTM parameter tracking
+- No webhooks/alerts/API
+- No custom beacon domains
+- Max 10 non-proxied sites

package/skills/cloudflare-deploy/references/workerd/README.md

@@ -0,0 +1,78 @@
+# Workerd Runtime
+
+V8-based JS/Wasm runtime powering Cloudflare Workers. Use as app server, dev tool, or HTTP proxy.
+
+## ⚠️ IMPORTANT SECURITY NOTICE
+**workerd is NOT a hardened sandbox.** Do not run untrusted code. It's designed for deploying YOUR code locally/self-hosted, not multi-tenant SaaS. Cloudflare production adds security layers not present in open-source workerd.
+
+## Decision Tree: When to Use What
+
+**95% of users:** Use Wrangler
+- Local development: `wrangler dev` (uses workerd internally)
+- Deployment: `wrangler deploy` (deploys to Cloudflare)
+- Types: `wrangler types` (generates TypeScript types)
+
+**Use raw workerd directly only if:**
+- Self-hosting Workers runtime in production
+- Embedding runtime in C++ application
+- Custom tooling/testing infrastructure
+- Debugging workerd-specific behavior
+
+**Never use workerd for:**
+- Running untrusted/user-submitted code
+- Multi-tenant isolation (not hardened)
+- Production without additional security layers
+
+## Key Features
+- **Standards-based**: Fetch API, Web Crypto, Streams, WebSocket
+- **Nanoservices**: Service bindings with local call performance
+- **Capability security**: Explicit bindings prevent SSRF
+- **Backwards compatible**: Version = max compat date supported
+
+## Architecture
+```
+Config (workerd.capnp)
+├── Services (workers/endpoints)
+├── Sockets (HTTP/HTTPS listeners)
+└── Extensions (global capabilities)
+```
+
+## Quick Start
+```bash
+workerd serve config.capnp
+workerd compile config.capnp myConfig -o binary
+workerd test config.capnp
+```
+
+## Platform Support & Beta Status
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux (x64) | Stable | Primary platform |
+| macOS (x64/ARM) | Stable | Full support |
+| Windows | Beta | Use WSL2 for best results |
+| Linux (ARM64) | Experimental | Limited testing |
+
+workerd is in **active development**. Breaking changes possible. Pin versions in production.
+
+## Core Concepts
+- **Service**: Named endpoint (worker/network/disk/external)
+- **Binding**: Capability-based resource access (KV/DO/R2/services)
+- **Compatibility date**: Feature gate (always set!)
+- **Modules**: ES modules (recommended) or service worker syntax
+
+## Reading Order (Progressive Disclosure)
+
+**Start here:**
+1. This README (overview, decision tree)
+2. [patterns.md](./patterns.md) - Common workflows, framework examples
+
+**When you need details:**
+3. [configuration.md](./configuration.md) - Config format, services, bindings
+4. [api.md](./api.md) - Runtime APIs, TypeScript types
+5. [gotchas.md](./gotchas.md) - Common errors, debugging
+
+## Related References
+- [workers](../workers/) - Workers runtime API documentation
+- [miniflare](../miniflare/) - Testing tool built on workerd
+- [wrangler](../wrangler/) - CLI that uses workerd for local dev

package/skills/cloudflare-deploy/references/workerd/api.md

@@ -0,0 +1,185 @@
+# Workerd APIs
+
+## Worker Code (JS/TS)
+
+### ES Modules (Recommended)
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const value = await env.KV.get("key");           // Bindings in env
+    const response = await env.API.fetch(request);   // Service binding
+    ctx.waitUntil(logRequest(request));              // Background task
+    return new Response("OK");
+  },
+  async adminApi(request, env, ctx) { /* Named entrypoint */ },
+  async queue(batch, env, ctx) { /* Queue consumer */ },
+  async scheduled(event, env, ctx) { /* Cron handler */ }
+};
+```
+
+### TypeScript Types
+
+**Generate from wrangler.toml (Recommended):**
+```bash
+wrangler types  # Output: worker-configuration.d.ts
+```
+
+**Manual types:**
+```typescript
+interface Env {
+  API: Fetcher;
+  CACHE: KVNamespace;
+  STORAGE: R2Bucket;
+  ROOMS: DurableObjectNamespace;
+  API_KEY: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return new Response(await env.CACHE.get("key"));
+  }
+};
+```
+
+**Setup:**
+```bash
+npm install -D @cloudflare/workers-types
+```
+
+```json
+// tsconfig.json
+{"compilerOptions": {"types": ["@cloudflare/workers-types"]}}
+```
+
+### Service Worker Syntax (Legacy)
+```javascript
+addEventListener('fetch', event => {
+  event.respondWith(handleRequest(event.request));
+});
+
+async function handleRequest(request) {
+  const value = await KV.get("key");  // Bindings as globals
+  return new Response("OK");
+}
+```
+
+### Durable Objects
+```javascript
+export class Room {
+  constructor(state, env) { this.state = state; this.env = env; }
+  
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname === "/increment") {
+      const value = (await this.state.storage.get("counter")) || 0;
+      await this.state.storage.put("counter", value + 1);
+      return new Response(String(value + 1));
+    }
+    return new Response("Not found", {status: 404});
+  }
+}
+```
+
+### RPC Between Services
+```javascript
+// Caller: env.AUTH.validateToken(token) returns structured data
+const user = await env.AUTH.validateToken(request.headers.get("Authorization"));
+
+// Callee: export methods that return data
+export default {
+  async validateToken(token) { return {id: 123, name: "Alice"}; }
+};
+```
+
+## Web Platform APIs
+
+### Fetch
+- `fetch()`, `Request`, `Response`, `Headers`
+- `AbortController`, `AbortSignal`
+
+### Streams
+- `ReadableStream`, `WritableStream`, `TransformStream`
+- Byte streams, BYOB readers
+
+### Web Crypto
+- `crypto.subtle` (encrypt/decrypt/sign/verify)
+- `crypto.randomUUID()`, `crypto.getRandomValues()`
+
+### Encoding
+- `TextEncoder`, `TextDecoder`
+- `atob()`, `btoa()`
+
+### Web Standards
+- `URL`, `URLSearchParams`
+- `Blob`, `File`, `FormData`
+- `WebSocket`
+
+### Server-Sent Events (EventSource)
+```javascript
+// Server-side SSE
+const { readable, writable } = new TransformStream();
+const writer = writable.getWriter();
+writer.write(new TextEncoder().encode('data: Hello\n\n'));
+return new Response(readable, {headers: {'Content-Type': 'text/event-stream'}});
+```
+
+### HTMLRewriter (HTML Parsing/Transformation)
+```javascript
+const response = await fetch('https://example.com');
+return new HTMLRewriter()
+  .on('a[href]', {
+    element(el) {
+      el.setAttribute('href', `/proxy?url=${encodeURIComponent(el.getAttribute('href'))}`);
+    }
+  })
+  .on('script', { element(el) { el.remove(); } })
+  .transform(response);
+```
+
+### TCP Sockets (Experimental)
+```javascript
+const socket = await connect({ hostname: 'example.com', port: 80 });
+const writer = socket.writable.getWriter();
+await writer.write(new TextEncoder().encode('GET / HTTP/1.1\r\n\r\n'));
+const reader = socket.readable.getReader();
+const { value } = await reader.read();
+return new Response(value);
+```
+
+### Performance
+- `performance.now()`, `performance.timeOrigin`
+- `setTimeout()`, `setInterval()`, `queueMicrotask()`
+
+### Console
+- `console.log()`, `console.error()`, `console.warn()`
+
+### Node.js Compat (`nodejs_compat` flag)
+```javascript
+import { Buffer } from 'node:buffer';
+import { randomBytes } from 'node:crypto';
+
+const buf = Buffer.from('Hello');
+const random = randomBytes(16);
+```
+
+**Available:** `node:buffer`, `node:crypto`, `node:stream`, `node:util`, `node:events`, `node:assert`, `node:path`, `node:querystring`, `node:url`
+**NOT available:** `node:fs`, `node:http`, `node:net`, `node:child_process`
+
+## CLI Commands
+
+```bash
+workerd serve config.capnp [constantName]          # Start server
+workerd serve config.capnp --socket-addr http=*:3000 --verbose
+workerd compile config.capnp constantName -o binary  # Compile to binary
+workerd test config.capnp [--test-only=test.js]    # Run tests
+```
+
+## Wrangler Integration
+
+Use Wrangler for development:
+```bash
+wrangler dev     # Uses workerd internally
+wrangler types   # Generate TypeScript types from wrangler.toml
+```
+
+See [patterns.md](./patterns.md) for usage examples, [configuration.md](./configuration.md) for config details.

package/skills/cloudflare-deploy/references/workerd/configuration.md

@@ -0,0 +1,183 @@
+# Workerd Configuration
+
+## Basic Structure
+```capnp
+using Workerd = import "/workerd/workerd.capnp";
+
+const config :Workerd.Config = (
+  services = [(name = "main", worker = .mainWorker)],
+  sockets = [(name = "http", address = "*:8080", http = (), service = "main")]
+);
+
+const mainWorker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "src/index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+);
+```
+
+## Services
+**Worker**: Run JS/Wasm code
+```capnp
+(name = "api", worker = (
+  modules = [(name = "index.js", esModule = embed "index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+))
+```
+
+**Network**: Internet access
+```capnp
+(name = "internet", network = (allow = ["public"], tlsOptions = (trustBrowserCas = true)))
+```
+
+**External**: Reverse proxy
+```capnp
+(name = "backend", external = (address = "api.com:443", http = (style = tls)))
+```
+
+**Disk**: Static files
+```capnp
+(name = "assets", disk = (path = "/var/www", writable = false))
+```
+
+## Sockets
+```capnp
+(name = "http", address = "*:8080", http = (), service = "main")
+(name = "https", address = "*:443", https = (options = (), tlsOptions = (keypair = (...))), service = "main")
+(name = "app", address = "unix:/tmp/app.sock", http = (), service = "main")
+```
+
+## Worker Formats
+```capnp
+# ES Modules (recommended)
+modules = [(name = "index.js", esModule = embed "src/index.js"), (name = "wasm.wasm", wasm = embed "build/module.wasm")]
+
+# Service Worker (legacy)
+serviceWorkerScript = embed "worker.js"
+
+# CommonJS
+(name = "legacy.js", commonJsModule = embed "legacy.js", namedExports = ["foo"])
+```
+
+## Bindings
+Bindings expose resources to workers. ES modules: `env.BINDING`, Service workers: globals.
+
+### Primitive Types
+```capnp
+(name = "API_KEY", text = "secret")                    # String
+(name = "CONFIG", json = '{"key":"val"}')              # Parsed JSON
+(name = "DATA", data = embed "data.bin")               # ArrayBuffer
+(name = "DATABASE_URL", fromEnvironment = "DB_URL")    # System env var
+```
+
+### Service Binding
+```capnp
+(name = "AUTH", service = "auth-worker")               # Basic
+(name = "API", service = (
+  name = "backend",
+  entrypoint = "adminApi",                             # Named export
+  props = (json = '{"role":"admin"}')                  # ctx.props
+))
+```
+
+### Storage
+```capnp
+(name = "CACHE", kvNamespace = "kv-service")           # KV
+(name = "STORAGE", r2Bucket = "r2-service")            # R2
+(name = "ROOMS", durableObjectNamespace = (
+  serviceName = "room-service",
+  className = "Room"
+))
+(name = "FAST", memoryCache = (
+  id = "cache-id",
+  limits = (maxKeys = 1000, maxValueSize = 1048576)
+))
+```
+
+### Other
+```capnp
+(name = "TASKS", queue = "queue-service")
+(name = "ANALYTICS", analyticsEngine = "analytics")
+(name = "LOADER", workerLoader = (id = "dynamic"))
+(name = "KEY", cryptoKey = (format = raw, algorithm = (name = "HMAC", hash = "SHA-256"), keyData = embed "key.bin", usages = [sign, verify], extractable = false))
+(name = "TRACED", wrapped = (moduleName = "tracing", entrypoint = "makeTracer", innerBindings = [(name = "backend", service = "backend")]))
+```
+
+## Compatibility
+```capnp
+compatibilityDate = "2024-01-15"                       # Always set!
+compatibilityFlags = ["nodejs_compat", "streams_enable_constructors"]
+```
+
+Version = max compat date. Update carefully after testing.
+
+## Parameter Bindings (Inheritance)
+```capnp
+const base :Workerd.Worker = (
+  modules = [...], compatibilityDate = "2024-01-15",
+  bindings = [(name = "API_URL", parameter = (type = text)), (name = "DB", parameter = (type = service))]
+);
+
+const derived :Workerd.Worker = (
+  inherit = "base-service",
+  bindings = [(name = "API_URL", text = "https://api.com"), (name = "DB", service = "postgres")]
+);
+```
+
+## Durable Objects Config
+```capnp
+const worker :Workerd.Worker = (
+  modules = [...],
+  compatibilityDate = "2024-01-15",
+  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
+  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
+  durableObjectStorage = (localDisk = "/var/do")
+);
+```
+
+## Remote Bindings (Development)
+
+Connect local workerd to production Cloudflare resources:
+
+```capnp
+bindings = [
+  # Remote KV (requires API token)
+  (name = "PROD_KV", kvNamespace = (
+    remote = (
+      accountId = "your-account-id",
+      namespaceId = "your-namespace-id",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  )),
+  
+  # Remote R2
+  (name = "PROD_R2", r2Bucket = (
+    remote = (
+      accountId = "your-account-id",
+      bucketName = "my-bucket",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  )),
+  
+  # Remote Durable Object
+  (name = "PROD_DO", durableObjectNamespace = (
+    remote = (
+      accountId = "your-account-id",
+      scriptName = "my-worker",
+      className = "MyDO",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  ))
+]
+```
+
+**Note:** Remote bindings require network access and valid Cloudflare API credentials.
+
+## Logging & Debugging
+```capnp
+logging = (structuredLogging = true, stdoutPrefix = "OUT: ", stderrPrefix = "ERR: ")
+v8Flags = ["--expose-gc", "--max-old-space-size=2048"]  # ⚠️ Unsupported in production
+```
+
+See [patterns.md](./patterns.md) for multi-service examples, [gotchas.md](./gotchas.md) for config errors.