@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/gemini-cli/perf-performance-api/SKILL.md

@@ -0,0 +1,249 @@
+# Performance API
+
+> Master the browser Performance API — PerformanceObserver, Navigation Timing, Resource Timing, User Timing, Server Timing, and Element Timing — to build custom performance measurement, monitoring, and alerting into any web application.
+
+## When to Use
+
+- You need to measure custom business metrics (time-to-interactive for specific components, checkout flow duration)
+- `PerformanceObserver` is needed to collect Web Vitals data (LCP, CLS, INP) in production
+- Resource Timing data is needed to identify slow or large network requests
+- Navigation Timing is needed to measure TTFB, DOM parsing, or total page load time
+- Server Timing headers need to pass backend timing breakdowns to the frontend
+- You are building a RUM (Real User Monitoring) pipeline to collect field performance data
+- `performance.now()` is preferred over `Date.now()` for sub-millisecond precision
+- The `buffered: true` flag is needed to capture entries that occurred before observer registration
+- Long-lived SPAs need `performance.clearMarks()` and `performance.clearMeasures()` to prevent memory accumulation
+- Element Timing API is needed to measure render time of specific elements
+
+## Instructions
+
+1. **Use `PerformanceObserver` (not `getEntriesByType`).** The observer pattern is more reliable — it captures entries as they occur and supports the `buffered` flag to retrieve entries that happened before registration:
+
+   ```javascript
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       console.log(entry.entryType, entry.name, entry.startTime, entry.duration);
+     }
+   });
+
+   // buffered: true captures entries that occurred before this line
+   observer.observe({ type: 'resource', buffered: true });
+   ```
+
+2. **Measure custom business metrics with User Timing:**
+
+   ```javascript
+   // Mark the start of an operation
+   performance.mark('checkout-start');
+
+   // ... checkout logic ...
+
+   // Mark the end
+   performance.mark('checkout-end');
+
+   // Measure the duration between marks
+   const measure = performance.measure('checkout-duration', 'checkout-start', 'checkout-end');
+   console.log('Checkout took:', measure.duration, 'ms');
+
+   // Measure with metadata (User Timing Level 3)
+   performance.measure('api-call', {
+     start: 'api-start',
+     end: 'api-end',
+     detail: { endpoint: '/api/cart', method: 'POST' },
+   });
+   ```
+
+3. **Extract Navigation Timing data:**
+
+   ```javascript
+   const nav = performance.getEntriesByType('navigation')[0];
+
+   const metrics = {
+     // DNS lookup
+     dns: nav.domainLookupEnd - nav.domainLookupStart,
+     // TCP connection
+     tcp: nav.connectEnd - nav.connectStart,
+     // TLS negotiation
+     tls: nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0,
+     // Time to First Byte
+     ttfb: nav.responseStart - nav.requestStart,
+     // HTML download
+     download: nav.responseEnd - nav.responseStart,
+     // DOM parsing
+     domParsing: nav.domInteractive - nav.responseEnd,
+     // DOM content loaded
+     domContentLoaded: nav.domContentLoadedEventEnd - nav.domContentLoadedEventStart,
+     // Total page load
+     pageLoad: nav.loadEventEnd - nav.startTime,
+   };
+   ```
+
+4. **Analyze resource loading with Resource Timing:**
+
+   ```javascript
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       // transferSize = bytes over the network (0 means cache hit)
+       // encodedBodySize = compressed size
+       // decodedBodySize = uncompressed size
+       if (entry.transferSize === 0) {
+         console.log('Cache hit:', entry.name);
+       } else {
+         const compressionRatio = entry.decodedBodySize / entry.encodedBodySize;
+         console.log(
+           'Resource:',
+           entry.name,
+           'Size:',
+           entry.transferSize,
+           'Compression:',
+           compressionRatio.toFixed(2)
+         );
+       }
+     }
+   });
+   observer.observe({ type: 'resource', buffered: true });
+   ```
+
+5. **Read Server Timing from response headers:**
+
+   ```javascript
+   // Server sends: Server-Timing: db;dur=53, cache;desc="Cache Read";dur=2, app;dur=120
+   const resources = performance.getEntriesByType('resource');
+   for (const resource of resources) {
+     if (resource.serverTiming) {
+       for (const timing of resource.serverTiming) {
+         console.log(`${timing.name}: ${timing.duration}ms (${timing.description})`);
+         // db: 53ms, cache: 2ms (Cache Read), app: 120ms
+       }
+     }
+   }
+   ```
+
+6. **Use Element Timing for specific element render time:**
+
+   ```html
+   <!-- Add elementtiming attribute to elements you want to measure -->
+   <img src="/hero.jpg" elementtiming="hero-image" alt="Hero" />
+   <h1 elementtiming="main-heading">Page Title</h1>
+   ```
+
+   ```javascript
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       console.log(entry.identifier, 'rendered at:', entry.startTime, 'ms');
+     }
+   });
+   observer.observe({ type: 'element', buffered: true });
+   ```
+
+7. **Use `performance.now()` for high-resolution timing:**
+
+   ```javascript
+   // performance.now() — microsecond precision, monotonic (not affected by clock adjustments)
+   const start = performance.now();
+   doExpensiveWork();
+   const elapsed = performance.now() - start;
+   console.log(`Elapsed: ${elapsed.toFixed(3)}ms`);
+
+   // Date.now() — millisecond precision, wall clock (affected by NTP, manual adjustments)
+   // DO NOT use Date.now() for performance measurement
+   ```
+
+## Details
+
+### PerformanceEntry Types Reference
+
+| Entry Type                 | Source                        | Key Properties                                     |
+| -------------------------- | ----------------------------- | -------------------------------------------------- |
+| `navigation`               | Page load                     | `responseStart`, `domInteractive`, `loadEventEnd`  |
+| `resource`                 | Each network request          | `transferSize`, `encodedBodySize`, `serverTiming`  |
+| `mark`                     | `performance.mark()`          | `name`, `startTime`                                |
+| `measure`                  | `performance.measure()`       | `name`, `duration`, `detail`                       |
+| `longtask`                 | Tasks >50ms                   | `duration`, `attribution`                          |
+| `event`                    | User interactions             | `processingStart`, `processingEnd`, `duration`     |
+| `largest-contentful-paint` | LCP candidate                 | `element`, `url`, `size`, `startTime`              |
+| `layout-shift`             | Visual shifts                 | `value`, `hadRecentInput`, `sources`               |
+| `element`                  | Elements with `elementtiming` | `identifier`, `startTime`, `element`               |
+| `paint`                    | FP and FCP                    | `name` (`first-paint` or `first-contentful-paint`) |
+
+### Worked Example: Etsy Product Card Timing
+
+Etsy measures time-to-render for each product card on search results pages. They place `performance.mark('card-render-start')` before hydrating each card and `performance.mark('card-render-end')` after:
+
+```javascript
+function renderProductCard(card, index) {
+  performance.mark(`card-${index}-start`);
+  hydrateCard(card);
+  performance.mark(`card-${index}-end`);
+  performance.measure(`card-${index}-render`, `card-${index}-start`, `card-${index}-end`);
+}
+
+// Aggregate and send to analytics
+const measures = performance
+  .getEntriesByType('measure')
+  .filter((m) => m.name.includes('card'))
+  .map((m) => m.duration);
+const p50 = percentile(measures, 50);
+const p95 = percentile(measures, 95);
+sendToGrafana({ cardRenderP50: p50, cardRenderP95: p95 });
+```
+
+### Worked Example: Cloudflare Server Timing
+
+Cloudflare uses `Server-Timing` headers to pass backend timing breakdowns through to the browser. The edge server adds headers: `Server-Timing: edge;dur=2, origin;dur=150, db;dur=53`. The frontend Performance API reads these without any custom telemetry:
+
+```javascript
+const pageNav = performance.getEntriesByType('navigation')[0];
+if (pageNav.serverTiming) {
+  const timingMap = Object.fromEntries(pageNav.serverTiming.map((t) => [t.name, t.duration]));
+  // { edge: 2, origin: 150, db: 53 }
+  dashboard.update(timingMap);
+}
+```
+
+This gives frontend dashboards full-stack timing visibility: TTFB = 200ms, of which edge processing = 2ms, origin fetch = 150ms, database = 53ms.
+
+### Cross-Origin Timing Restrictions
+
+By default, Resource Timing entries for cross-origin resources have zero values for detailed timing (DNS, TCP, TLS, request/response). This is a privacy protection. To enable full timing:
+
+1. The cross-origin server must include `Timing-Allow-Origin: *` (or the specific origin) in response headers
+2. Without this header, only `startTime`, `duration`, `transferSize` (sometimes 0), and `encodedBodySize` (0) are available
+
+### Anti-Patterns
+
+**Polling `performance.getEntriesByType()` instead of using `PerformanceObserver`.** Polling wastes CPU, misses entries between polls, and does not capture entries that occur after the poll. `PerformanceObserver` fires exactly when entries are available.
+
+**Forgetting `buffered: true` on observer.** Without `buffered: true`, entries that occurred before observer registration are missed. For LCP, CLS, and navigation timing, these entries always occur before your observer code runs.
+
+**Not clearing marks and measures in SPAs.** In long-lived single-page applications, marks and measures accumulate in the performance buffer. Without `performance.clearMarks()` and `performance.clearMeasures()`, memory grows linearly with user actions. Clear after sending data to analytics.
+
+**Using `Date.now()` for performance measurement.** `Date.now()` has 1ms resolution, is affected by system clock adjustments (NTP sync, manual changes), and can go backward. `performance.now()` has 5-microsecond resolution (subject to cross-origin isolation), is monotonic, and is unaffected by clock adjustments.
+
+**Measuring in non-isolated contexts expecting full precision.** Without cross-origin isolation (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`), `performance.now()` is rounded to 100 microseconds (not 5 microseconds). For sub-millisecond measurements, enable cross-origin isolation.
+
+## Source
+
+- W3C Performance Timeline Level 2 — https://www.w3.org/TR/performance-timeline/
+- W3C User Timing Level 3 — https://www.w3.org/TR/user-timing/
+- W3C Resource Timing Level 2 — https://www.w3.org/TR/resource-timing-2/
+- W3C Navigation Timing Level 2 — https://www.w3.org/TR/navigation-timing-2/
+- MDN Performance API reference — https://developer.mozilla.org/en-US/docs/Web/API/Performance_API
+
+## 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.
+- Custom performance metrics are measured with User Timing API and sent to analytics.
+- PerformanceObserver is used with `buffered: true` for all metric collection.

package/dist/agents/skills/gemini-cli/perf-performance-api/skill.yaml

@@ -0,0 +1,41 @@
+name: perf-performance-api
+version: '1.0.0'
+description: Performance Observer and timing APIs — PerformanceEntry types, User Timing, Resource Timing, Navigation Timing
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-largest-contentful-paint
+  - perf-interaction-to-next-paint
+  - perf-cumulative-layout-shift
+  - perf-long-tasks
+  - perf-profiling-methodology
+  - otel-performance-insights
+  - test-performance-testing
+stack_signals: []
+keywords:
+  - Performance API
+  - PerformanceObserver
+  - User Timing
+  - Resource Timing
+  - Navigation Timing
+  - performance.mark
+  - performance.measure
+  - PerformanceEntry
+  - Server Timing
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-profiling-methodology/SKILL.md

@@ -0,0 +1,181 @@
+# Profiling Methodology
+
+> Apply a systematic, measurement-first profiling workflow — define metric, establish baseline, identify bottleneck, implement fix, verify improvement with statistical significance — to avoid wasted optimization effort and ensure every change demonstrably improves performance.
+
+## When to Use
+
+- Performance is perceived as slow but no one has measured what is actually slow
+- You need to establish a baseline before optimizing to prove the optimization worked
+- A flame chart or performance trace needs to be read and interpreted
+- Performance budgets need to be defined and enforced in CI
+- Lab data (Lighthouse) and field data (CrUX/RUM) disagree and you need to understand why
+- You are deciding between synthetic monitoring and Real User Monitoring
+- A performance regression needs to be detected and attributed to a specific commit
+- Single-run measurements are producing inconsistent results and statistical rigor is needed
+- Micro-benchmarking in isolation is misleading and end-to-end measurement is needed
+- The team is about to "optimize" without a clear bottleneck and you need to redirect effort
+
+## Instructions
+
+1. **Never optimize without a baseline.** Before changing any code, measure the current state with the exact metric you want to improve. Record at least 5 measurements to establish a stable baseline (performance varies 10-30% between runs):
+
+   ```bash
+   # Example: run Lighthouse 5 times and compute median
+   for i in {1..5}; do
+     npx lighthouse https://example.com --output=json --output-path=./run-$i.json --quiet
+   done
+   # Extract LCP from each run and compute median
+   ```
+
+2. **Follow the profiling workflow:**
+   1. **Define the metric** — what exactly are you measuring? (LCP, INP, bundle size, API p95 latency)
+   2. **Establish baseline** — measure 5+ runs, compute median and p95, record the values
+   3. **Identify bottleneck** — use DevTools Performance panel, flame chart, or profiler to find the slowest part
+   4. **Hypothesize cause** — formulate a specific theory ("style recalculation during scroll takes 40ms because of descendant selectors on body")
+   5. **Implement fix** — make exactly one change
+   6. **Measure again** — same conditions, 5+ runs
+   7. **Validate significance** — is the improvement larger than the natural variance? Use a statistical test if the effect is small
+
+3. **Read flame charts effectively.** In Chrome DevTools Performance panel:
+   - **Width** = time duration (wider = longer)
+   - **Depth** = call stack depth (deeper = more nested function calls)
+   - **Self time** = time spent in the function itself (not in its callees)
+   - **Total time** = self time + all callee time
+
+   The optimization target is the function with the largest **self time** that is on the critical path. Deep call stacks with small self times are not the bottleneck — the leaf functions are.
+
+4. **Use CPU throttling in DevTools.** Developer hardware is 5-10x faster than the median user device. Always profile with:
+   - CPU throttling: 4x slowdown (simulates mid-tier mobile)
+   - Network throttling: "Fast 3G" or "Slow 4G"
+   - This reveals bottlenecks that are invisible on high-end hardware
+
+5. **Set performance budgets and enforce in CI:**
+
+   ```javascript
+   // lighthouserc.js — Lighthouse CI configuration
+   module.exports = {
+     ci: {
+       assert: {
+         assertions: {
+           'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
+           interactive: ['error', { maxNumericValue: 3500 }],
+           'total-byte-weight': ['error', { maxNumericValue: 200000 }],
+           'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
+         },
+       },
+     },
+   };
+   ```
+
+6. **Understand lab vs field data:**
+
+   | Aspect     | Lab (Lighthouse, WebPageTest)        | Field (CrUX, RUM)                   |
+   | ---------- | ------------------------------------ | ----------------------------------- |
+   | Conditions | Controlled, reproducible             | Real user devices and networks      |
+   | Device     | Specified throttling                 | Actual user hardware                |
+   | Coverage   | Single page, one scenario            | All pages, all users                |
+   | Use for    | Debugging, regression detection      | Understanding real user experience  |
+   | Limitation | Does not reflect real-world variance | Cannot reproduce specific scenarios |
+
+   Lab and field data should agree directionally. If Lighthouse shows LCP of 1.5s but CrUX shows 4.0s, the lab test is not representative of real user conditions (likely missing slow devices or slow networks).
+
+7. **Measure with statistical significance:**
+
+   ```javascript
+   // Simple statistical validation for A/B performance tests
+   function isSignificant(controlSamples, treatmentSamples, confidenceLevel = 0.95) {
+     const controlMean = mean(controlSamples);
+     const treatmentMean = mean(treatmentSamples);
+     const controlStdDev = stddev(controlSamples);
+     const treatmentStdDev = stddev(treatmentSamples);
+     const n = controlSamples.length;
+
+     const pooledStdErr = Math.sqrt((controlStdDev ** 2 + treatmentStdDev ** 2) / n);
+     const tStat = (controlMean - treatmentMean) / pooledStdErr;
+     const criticalValue = 1.96; // for 95% confidence
+     return Math.abs(tStat) > criticalValue;
+   }
+   ```
+
+## Details
+
+### The Profiling Pyramid
+
+Optimize in this order (each level has 10x the impact of the one below):
+
+1. **Architecture** — SSR vs CSR, code splitting, caching strategy (impact: seconds)
+2. **Network** — CDN, compression, HTTP/2, image optimization (impact: hundreds of ms)
+3. **Rendering** — critical CSS, defer/async, layout containment (impact: tens of ms)
+4. **Code** — algorithm optimization, micro-optimization (impact: single ms)
+
+Most wasted optimization effort happens when teams optimize at level 4 (micro-optimizing a function from 2ms to 1ms) while the architecture at level 1 adds 3 seconds of unnecessary latency.
+
+### Worked Example: Pinterest A/B Testing Protocol
+
+Pinterest's performance team validates every optimization with an A/B test:
+
+1. The optimization is deployed to 1% of traffic
+2. Both control (original) and treatment (optimized) groups are monitored for 7 days
+3. Key metrics: LCP p50/p75/p95, INP p50/p75/p95, engagement rate, bounce rate
+4. Statistical significance test at p<0.05 is required before promotion
+5. Results are reviewed for selection bias (are the 1% representative?)
+
+This protocol caught a "30% LCP improvement" that was actually a 2% improvement. The initial benchmark ran on a fast internal network; the A/B test revealed the improvement was much smaller for real users on cellular networks. The fix was still shipped because 2% improvement for all users was valuable, but expectations were correctly calibrated.
+
+### Worked Example: Shopify Lighthouse CI
+
+Shopify runs Lighthouse CI on every PR for every storefront route. Each route has a performance budget:
+
+- Homepage: LCP < 2.0s, bundle < 150KB
+- Product page: LCP < 2.5s, bundle < 200KB
+- Cart page: INP < 150ms, CLS < 0.05
+
+Any PR that regresses a metric beyond its budget fails the build. The PR author receives a comparison report showing exactly which metric regressed, by how much, and which files contributed to the regression (via source map analysis).
+
+### Regression Detection Strategy
+
+Use a three-tier approach:
+
+1. **CI gate (per-PR)** — Lighthouse CI with per-route budgets. Catches large regressions before merge.
+2. **Synthetic monitoring (continuous)** — Run Lighthouse or WebPageTest hourly on production. Alerts when metrics deviate >10% from 7-day rolling average.
+3. **RUM alerting (field)** — Monitor CrUX or custom RUM data. Alert when p75 metrics cross thresholds (LCP > 2.5s, INP > 200ms, CLS > 0.1).
+
+### Anti-Patterns
+
+**Optimizing without measuring first.** "I bet the problem is the database" leads to weeks of database optimization when the real bottleneck is a 3MB uncompressed hero image. Always profile first, then optimize the actual bottleneck.
+
+**Testing on developer hardware without throttling.** A MacBook Pro on gigabit fiber does not represent the median user on a mid-tier Android phone on 4G. Always enable CPU throttling (4x) and network throttling (Fast 3G) in DevTools, or use WebPageTest with a real Moto G4 device.
+
+**Single-run measurements.** Performance varies 10-30% between runs due to background processes, network conditions, and GC timing. A single run showing 2.1s LCP could be 2.7s on the next run. Always take the median of 5+ runs.
+
+**Optimizing p50 when p95 is the real problem.** Median latency looks great at 500ms, but p95 is 8 seconds. Tail latencies affect 5% of users on every page load. Focus on percentile metrics, not averages.
+
+**Micro-benchmarking in isolation.** Optimizing a function from 1ms to 0.1ms is a 10x improvement that is completely irrelevant if the function is called once during a 3-second page load. Always measure the impact on the end-to-end metric, not the isolated function.
+
+**Premature optimization without profiling.** Adding `useMemo` to every React component, `will-change` to every element, or code-splitting every route "just in case" adds complexity without measured benefit. Profile first, optimize only the measured bottleneck.
+
+## Source
+
+- Google Lighthouse documentation — https://developer.chrome.com/docs/lighthouse
+- WebPageTest documentation — https://docs.webpagetest.org/
+- Chrome DevTools Performance panel guide — https://developer.chrome.com/docs/devtools/performance
+- Brendan Gregg, "Systems Performance" methodology — https://www.brendangregg.com/methodology.html
+- "How We Made the Web Faster" (Google)
+
+## 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.
+- Every optimization has a measured baseline, a measured result, and statistical validation.
+- Performance budgets are defined and enforced in CI.

package/dist/agents/skills/gemini-cli/perf-profiling-methodology/skill.yaml

@@ -0,0 +1,44 @@
+name: perf-profiling-methodology
+version: '1.0.0'
+description: Systematic profiling workflow — bottleneck identification, measurement discipline, before/after methodology
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-performance-api
+  - perf-heap-profiling
+  - perf-long-tasks
+  - perf-largest-contentful-paint
+  - perf-interaction-to-next-paint
+  - node-performance-profiling
+  - test-performance-testing
+  - otel-performance-insights
+stack_signals: []
+keywords:
+  - profiling
+  - bottleneck
+  - flame chart
+  - Chrome DevTools
+  - Lighthouse
+  - WebPageTest
+  - performance budget
+  - regression detection
+  - performance testing
+  - synthetic monitoring
+  - RUM
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []