@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/claude-code/perf-edge-rendering/SKILL.md

@@ -0,0 +1,222 @@
+# Edge Rendering
+
+> Master edge rendering — deploying server-side rendering to edge locations for minimal latency, understanding edge runtime constraints, regional deployment strategies, edge middleware patterns, data locality considerations, and platform-specific optimization for Cloudflare Workers, Vercel Edge, and Deno Deploy.
+
+## When to Use
+
+- Users are geographically distributed and origin server latency varies by region
+- TTFB is high for users far from the origin server (>200ms)
+- Server-side rendering is needed but origin-only deployment adds latency
+- Personalization (A/B tests, geo-targeting, localization) needs to happen before content delivery
+- Authentication and authorization checks could run closer to the user
+- API responses could be transformed or enriched at the edge
+- Static generation is too stale but full origin SSR adds unnecessary latency
+- Edge middleware is needed for redirects, rewrites, or header manipulation
+- A global application needs consistent sub-100ms TTFB worldwide
+- Feature flags need to be evaluated before page rendering without a client-side flash
+
+## Instructions
+
+1. **Understand edge versus origin architecture.** Edge functions run in data centers close to the user (200+ locations) instead of a single origin:
+
+   ```
+   Origin-only SSR:
+   User (Tokyo) → CDN → Origin (US-East) → DB → Render → Response
+   Network RTT: ~150ms  |  TTFB: ~350ms
+
+   Edge Rendering:
+   User (Tokyo) → Edge (Tokyo) → Render → Response
+   Network RTT: ~5ms  |  TTFB: ~50ms
+
+   Edge + Origin Data:
+   User (Tokyo) → Edge (Tokyo) → Origin API (US-East) → Edge Render → Response
+   Network RTT: ~5ms + ~150ms (data)  |  TTFB: ~200ms
+   (Still faster: user sees shell immediately via streaming)
+   ```
+
+2. **Deploy edge functions on Cloudflare Workers.** Workers run on V8 isolates with sub-millisecond cold starts:
+
+   ```typescript
+   // src/worker.ts — Cloudflare Worker
+   export default {
+     async fetch(request: Request, env: Env): Promise<Response> {
+       const url = new URL(request.url);
+
+       // Edge-rendered HTML
+       const html = await renderPage(url.pathname, {
+         userCountry: request.cf?.country,
+         userCity: request.cf?.city,
+       });
+
+       return new Response(html, {
+         headers: {
+           'Content-Type': 'text/html; charset=utf-8',
+           'Cache-Control': 'public, max-age=60, s-maxage=300',
+         },
+       });
+     },
+   };
+
+   // wrangler.toml
+   // name = "my-app"
+   // main = "src/worker.ts"
+   // compatibility_date = "2024-01-01"
+   ```
+
+3. **Use Vercel Edge Runtime for Next.js.** Mark routes to run on the edge instead of Node.js:
+
+   ```typescript
+   // app/api/geo/route.ts — Edge API route
+   export const runtime = 'edge';
+
+   export async function GET(request: Request) {
+     const country = request.headers.get('x-vercel-ip-country') || 'US';
+     const city = request.headers.get('x-vercel-ip-city') || 'Unknown';
+
+     return Response.json({
+       country,
+       city,
+       timestamp: Date.now(),
+     });
+   }
+
+   // middleware.ts — geo-redirects and A/B tests at the edge
+   // Use request.geo?.country for geo-routing, cookies for A/B persistence
+   // Configure matcher to exclude static assets: /((?!_next/static|favicon).*)
+   ```
+
+4. **Handle edge runtime constraints.** Edge runtimes use a limited Web API subset (no Node.js APIs):
+
+   ```typescript
+   // Available at the edge:
+   // - fetch(), Request, Response, Headers
+   // - URL, URLSearchParams, URLPattern
+   // - crypto.subtle, crypto.getRandomValues
+   // - TextEncoder, TextDecoder
+   // - structuredClone, atob, btoa
+   // - setTimeout (limited), Promises, async/await
+   // - Web Streams API
+
+   // NOT available at the edge:
+   // - fs, path, child_process (no file system)
+   // - Buffer (use Uint8Array instead)
+   // - net, http (use fetch instead)
+   // - Most npm packages that use Node.js APIs
+
+   // Edge-compatible alternatives:
+   // Database: Neon serverless, PlanetScale, Turso (HTTP-based)
+   // KV Store: Cloudflare KV, Vercel KV, Upstash Redis
+   // ORM: Drizzle (with HTTP adapter), Prisma (with Accelerate)
+   ```
+
+5. **Implement edge caching for dynamic content.** Cache rendered pages at the edge with smart invalidation:
+
+   ```typescript
+   // Cloudflare Workers — Cache API
+   async function handleRequest(request: Request): Promise<Response> {
+     const cache = caches.default;
+     const cacheKey = new Request(request.url, request);
+
+     // Check edge cache
+     let response = await cache.match(cacheKey);
+     if (response) {
+       return response;
+     }
+
+     // Render at the edge
+     const html = await renderPage(request);
+     response = new Response(html, {
+       headers: {
+         'Content-Type': 'text/html',
+         'Cache-Control': 'public, s-maxage=300', // cache at edge for 5 min
+       },
+     });
+
+     // Store in edge cache (non-blocking)
+     const cacheResponse = response.clone();
+     await cache.put(cacheKey, cacheResponse);
+
+     return response;
+   }
+   ```
+
+6. **Manage data locality.** Edge rendering is fast only if data access is also fast. Strategies for reducing data latency:
+
+   ```typescript
+   // Strategy 1: Edge KV for read-heavy data
+   // Cloudflare KV: eventually consistent, <10ms reads globally
+   const config = await env.CONFIG_KV.get('site-config', 'json');
+
+   // Strategy 2: Edge-local database replicas
+   // Turso (libSQL): read replicas in 30+ regions
+   // Read from local replica, write to primary
+   import { createClient } from '@libsql/client';
+   const db = createClient({
+     url: 'libsql://db-name-region.turso.io',
+     authToken: '...',
+   });
+
+   // Strategy 3: Cache at the edge, fetch from origin
+   // Best for: data that changes infrequently, high read volume
+   const data = await env.CACHE.get(key, 'json');
+   if (!data) {
+     const fresh = await fetch('https://origin.example.com/api/data');
+     await env.CACHE.put(key, await fresh.text(), { expirationTtl: 300 });
+   }
+
+   // Strategy 4: Smart routing — render at the edge closest to the database
+   // Vercel: configure function regions to match database location
+   // export const preferredRegion = 'iad1'; // US East, near the DB
+   ```
+
+7. **Monitor edge function performance.** Instrument with `Date.now()` timing, log the edge location (`request.cf?.colo` on Cloudflare), and always fall back to `fetch(request)` on error. Track cold start frequency, P99 execution time, and cache hit rates via platform analytics (Cloudflare Analytics Engine, Vercel Analytics).
+
+## Details
+
+### Edge Runtime Cold Starts
+
+Cloudflare Workers use V8 isolates with sub-millisecond cold starts; Vercel Edge Functions ~5ms. Both are far faster than Lambda (100-1000ms). Trade-off: no file system, no native modules, limited memory (128MB), and limited CPU time (10-50ms free tier). Design edge functions to be lightweight.
+
+### Worked Example: Cloudflare Blog
+
+Runs entirely on Workers with streaming SSR. Blog posts render from Markdown in Workers KV, cached at the edge. First request renders and caches; subsequent requests serve in <5ms globally. Webhook-based cache purging on content updates. Result: <50ms TTFB worldwide, zero origin load for reads.
+
+### Worked Example: Shopify Oxygen
+
+Deploys Remix storefronts to Cloudflare Workers. Edge rendering takes 20-50ms, Storefront API responds in 50-100ms, yielding 70-150ms total TTFB vs 200-400ms origin-only. Stale-while-revalidate caching drops frequently-accessed pages to <10ms TTFB.
+
+### Anti-Patterns
+
+**Edge rendering with origin-only databases.** If every request queries a database in US-East, the edge latency advantage is negated. Use edge-local data stores (KV, replicas) or accept the benefit is limited to non-data-dependent content.
+
+**Heavy computation at the edge.** Edge runtimes have strict CPU time limits (10-50ms on free tiers). Offload image processing and heavy transformations to origin functions. Use the edge for lightweight rendering, routing, and personalization.
+
+**Not falling back to origin on edge failure.** Always implement a fallback path to the origin server for when edge functions fail due to platform issues or resource limits.
+
+**Deploying globally when data is in one region.** If most traffic is regional and the DB is in US-East, 200+ edge locations add no benefit. Use `preferredRegion` to deploy near the database for data-heavy pages.
+
+## Source
+
+- Cloudflare Workers — https://developers.cloudflare.com/workers/
+- Vercel Edge Functions — https://vercel.com/docs/functions/edge-functions
+- Deno Deploy — https://deno.com/deploy
+- web.dev: Edge Rendering — https://web.dev/articles/rendering-on-the-web#edge_rendering
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Edge functions achieve <100ms TTFB for users in the primary geographic region.
+- Edge runtime constraints are respected (no Node.js-only APIs in edge functions).
+- Data access strategy accounts for edge-to-origin latency (KV, replicas, or regional deployment).
+- Edge caching is configured with appropriate TTLs and invalidation mechanisms.
+- Fallback to origin is implemented for edge function failures.

package/dist/agents/skills/claude-code/perf-edge-rendering/skill.yaml

@@ -0,0 +1,39 @@
+name: perf-edge-rendering
+version: '1.0.0'
+description: Edge rendering — Edge compute platforms, regional deployment, latency optimization, and edge-specific constraints
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-server-side-rendering
+  - perf-cdn-strategies
+  - perf-static-generation
+  - perf-streaming-rendering
+  - perf-client-side-rendering
+stack_signals: []
+keywords:
+  - edge computing
+  - edge rendering
+  - edge runtime
+  - Cloudflare Workers
+  - Vercel Edge
+  - Deno Deploy
+  - regional deployment
+  - edge latency
+  - edge middleware
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-event-loop/SKILL.md

@@ -0,0 +1,203 @@
+# Event Loop
+
+> Understand the browser and Node.js event loop processing model — task queues, microtask queue, rendering steps, and task prioritization — to write code that cooperates with the rendering pipeline instead of blocking it.
+
+## When to Use
+
+- You need to understand the execution order of `setTimeout`, `Promise.then`, `queueMicrotask`, and `requestAnimationFrame`
+- A recursive microtask chain freezes the page because microtasks drain completely before rendering
+- `setTimeout(fn, 0)` does not fire immediately and you need to understand why (4ms clamp)
+- You are choosing between `setTimeout`, `requestAnimationFrame`, `requestIdleCallback`, or `scheduler.postTask` for scheduling work
+- Animations stutter because non-visual work competes with `requestAnimationFrame` callbacks
+- You need to understand why a `Promise.resolve().then()` callback runs before the browser paints
+- Node.js code behaves differently from browser code regarding microtask and I/O ordering
+- `MutationObserver` callbacks fire at unexpected times relative to rendering
+- You are implementing cooperative yielding and need to choose the right scheduling primitive
+- `setInterval` drift causes visual inconsistencies in animations
+
+## Instructions
+
+1. **Understand the event loop processing model.** Each iteration of the event loop follows this sequence:
+   1. Pick one task from the task queue (oldest task from the highest-priority queue)
+   2. Execute the task to completion
+   3. Drain the microtask queue — execute all microtasks, including microtasks queued by microtasks
+   4. If it is time to render (typically every ~16.67ms at 60Hz):
+      a. Run `requestAnimationFrame` callbacks
+      b. Recalculate styles
+      c. Layout
+      d. Paint
+   5. If idle, run `requestIdleCallback` callbacks
+
+2. **Know what creates tasks vs microtasks:**
+
+   **Tasks (macrotasks):**
+   - `setTimeout` / `setInterval`
+   - DOM event handlers (click, input, load)
+   - `MessageChannel.port.postMessage()`
+   - `fetch` completion callbacks (not the Promise, but the network callback)
+   - I/O callbacks (Node.js)
+
+   **Microtasks:**
+   - `Promise.then` / `catch` / `finally`
+   - `queueMicrotask(fn)`
+   - `MutationObserver` callbacks
+   - `async`/`await` continuations
+
+3. **Use the right scheduling primitive for each job:**
+
+   ```javascript
+   // Visual update — runs before next paint
+   requestAnimationFrame(() => {
+     element.style.transform = `translateX(${x}px)`;
+   });
+
+   // Non-urgent work — runs when browser is idle
+   requestIdleCallback((deadline) => {
+     while (deadline.timeRemaining() > 5 && tasks.length > 0) {
+       processTask(tasks.shift());
+     }
+   });
+
+   // Yield to browser for input processing — high-priority reschedule
+   await scheduler.yield();
+
+   // Background priority work — low priority
+   scheduler.postTask(() => analytics.flush(), { priority: 'background' });
+
+   // Immediate microtask — runs before any rendering
+   queueMicrotask(() => cleanupState());
+   ```
+
+4. **Never create infinite microtask loops.** Microtasks drain completely before the browser can render or process input. A recursive microtask chain blocks rendering indefinitely:
+
+   ```javascript
+   // CATASTROPHIC — freezes the browser, no rendering ever occurs
+   function processNextItem() {
+     if (items.length > 0) {
+       processItem(items.shift());
+       queueMicrotask(processNextItem); // queues another microtask before render
+     }
+   }
+
+   // FIXED — yields to the event loop between items
+   function processNextItem() {
+     if (items.length > 0) {
+       processItem(items.shift());
+       setTimeout(processNextItem, 0); // schedules a task, allowing render between items
+     }
+   }
+   ```
+
+5. **Understand `setTimeout(fn, 0)` clamping.** Browsers clamp `setTimeout` to a minimum of 4ms after 5 nested calls. This means `setTimeout(fn, 0)` is not truly zero-delay:
+
+   ```javascript
+   // First 4 calls: ~0ms delay
+   // After 5th nesting: minimum 4ms delay
+   // For yielding: use scheduler.yield() or MessageChannel instead
+   const channel = new MessageChannel();
+   channel.port1.onmessage = () => resumeWork();
+   channel.port2.postMessage(null); // fires before setTimeout, no 4ms clamp
+   ```
+
+## Details
+
+### The Rendering Pipeline in the Event Loop
+
+The browser does not render after every task. It renders at the display's refresh rate (typically 60Hz = every 16.67ms). Between renders, multiple tasks and microtask drains can occur. The rendering steps are:
+
+1. Run `requestAnimationFrame` callbacks (in order of registration)
+2. Recalculate styles (run style invalidation)
+3. Layout
+4. Paint (create paint records)
+5. Composite (send layers to GPU)
+
+If all rAF callbacks and rendering complete in under 16.67ms, the frame is on time. If they exceed 16.67ms, the frame is late and the user sees jank.
+
+### Worked Example: Recursive Microtask Rendering Starvation
+
+A data processing module used `queueMicrotask` to process items "asynchronously" without blocking the current task. With 10,000 items, each microtask processed one item and queued the next:
+
+```javascript
+// BROKEN — 10,000 microtasks drain without rendering
+function processChunk() {
+  if (queue.length > 0) {
+    process(queue.shift());
+    queueMicrotask(processChunk); // never yields to render
+  }
+}
+```
+
+The browser froze for 2 seconds (10,000 items \* 0.2ms each). No frames were painted because microtasks drain completely before rendering. Fix: replace `queueMicrotask` with `setTimeout(fn, 0)` or `scheduler.yield()` to yield to the event loop between chunks.
+
+### Worked Example: React useEffect Microtask Timing
+
+A React component's `useEffect` cleanup ran as a microtask (in React 18's concurrent mode). The effect modified the DOM, and the cleanup restored it. Because the cleanup ran as a microtask before paint, this sequence occurred:
+
+1. Effect fires: sets `element.textContent = 'Loading...'`
+2. Component re-renders, queuing cleanup as microtask
+3. Cleanup fires (microtask): sets `element.textContent = 'Done'`
+4. Browser paints: user only sees 'Done', never sees 'Loading...'
+
+The developer expected the user to see the loading state. The fix: use `setTimeout` in the effect to ensure the DOM update renders before the next operation.
+
+### Browser vs Node.js Event Loop
+
+The browser event loop has rendering steps integrated. The Node.js event loop has phases:
+
+1. **Timers** — `setTimeout`, `setInterval` callbacks
+2. **Pending callbacks** — deferred I/O callbacks
+3. **Poll** — retrieve new I/O events, execute I/O callbacks
+4. **Check** — `setImmediate` callbacks
+5. **Close callbacks** — `socket.on('close')`
+
+Key difference: Node.js has `process.nextTick()` which runs before any other microtask in the microtask queue. In the browser, `queueMicrotask` and `Promise.then` are equivalent in priority.
+
+### Task Prioritization (Scheduler API)
+
+The Scheduler API provides three priority levels:
+
+- `user-blocking` — interaction responses, should run within the current frame
+- `user-visible` — updates the user will notice (default)
+- `background` — analytics, prefetch, non-urgent work
+
+```javascript
+await scheduler.postTask(() => updateUI(), { priority: 'user-blocking' });
+await scheduler.postTask(() => prefetchData(), { priority: 'background' });
+```
+
+### Anti-Patterns
+
+**Using `Promise.resolve().then()` for deferral when you mean `setTimeout(fn, 0)`.** Microtasks run before rendering. If you want to defer work until after the browser paints, use `setTimeout` or `requestAnimationFrame` + `setTimeout` (double-rAF pattern). A Promise-based deferral runs immediately in the microtask checkpoint, before any rendering.
+
+**Infinite microtask loops.** Any recursive pattern using `Promise.then` or `queueMicrotask` that does not eventually yield creates an infinite microtask loop. The browser cannot render, process input, or run timers until the microtask queue is empty.
+
+**Assuming `setTimeout(fn, 0)` fires immediately.** After 5 nested `setTimeout` calls, the minimum delay is clamped to 4ms in browsers. For time-sensitive yielding, use `MessageChannel` or `scheduler.yield()` which do not have this clamp.
+
+**Using `setInterval` for animations instead of `requestAnimationFrame`.** `setInterval` fires at fixed wall-clock intervals regardless of the display refresh rate. It can fire between frames (wasted work) or multiple times in one frame (duplicate work). `requestAnimationFrame` fires exactly once per frame, synchronized with the display.
+
+**Blocking the event loop with synchronous I/O in Node.js.** `fs.readFileSync`, `crypto.pbkdf2Sync`, and other sync APIs block the entire event loop. All pending I/O, timers, and HTTP requests are stalled. Use async equivalents.
+
+## Source
+
+- HTML Living Standard, Section 8.1.7: Event loop processing model — https://html.spec.whatwg.org/multipage/webappapis.html#event-loops
+- Jake Archibald, "In The Loop" (JSConf 2018) — https://www.youtube.com/watch?v=cCOL7MC4Pl0
+- Node.js Event Loop documentation — https://nodejs.org/en/guides/event-loop-timers-and-nexttick
+- Scheduler API specification — https://wicg.github.io/scheduling-apis/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- The correct scheduling primitive is chosen for each type of work (visual, idle, yielding, background).
+- No microtask-based rendering starvation occurs in the application.

package/dist/agents/skills/claude-code/perf-event-loop/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-event-loop
+version: '1.0.0'
+description: Event loop architecture — task queues, microtask queue, rendering steps, task prioritization
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-long-tasks
+  - perf-interaction-to-next-paint
+  - perf-critical-rendering-path
+  - ts-performance-patterns
+stack_signals: []
+keywords:
+  - event loop
+  - task queue
+  - microtask queue
+  - macrotask
+  - requestAnimationFrame
+  - setTimeout
+  - Promise
+  - queueMicrotask
+  - rendering steps
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []