@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/perf-browser-cache/skill.yaml

@@ -0,0 +1,39 @@
+name: perf-browser-cache
+version: '1.0.0'
+description: Browser caching — Cache-Control directives, ETag validation, immutable assets, stale-while-revalidate, and cache partitioning
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-cdn-cache-control
+  - perf-cache-invalidation
+  - perf-service-worker-caching
+  - perf-cdn-strategies
+  - perf-compression
+stack_signals: []
+keywords:
+  - cache-control
+  - etag
+  - immutable
+  - stale-while-revalidate
+  - max-age
+  - browser cache
+  - cache partitioning
+  - conditional request
+  - 304 not modified
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/perf-bundle-analysis/SKILL.md

@@ -0,0 +1,217 @@
+# Bundle Analysis
+
+> Master bundle analysis techniques — visualization tools for chunk composition, size budget enforcement in CI, dependency cost evaluation, source map exploration, and continuous size tracking to prevent bundle bloat.
+
+## When to Use
+
+- Bundle size has grown and you need to identify the largest contributors
+- A new dependency was added and you need to assess its impact on bundle size
+- CI should fail when bundle size exceeds a defined budget
+- You need to compare bundle size between branches or releases
+- Lighthouse flags "Reduce unused JavaScript" but you do not know which modules to target
+- A production build takes unexpectedly long and you suspect large dependencies
+- Tree shaking is configured but you need to verify it is eliminating dead code
+- Evaluating whether to add a library or implement the functionality from scratch
+- Multiple chunks share duplicated code that should be in a common chunk
+- The team needs visibility into bundle size trends over time
+
+## Instructions
+
+1. **Generate a bundle visualization.** Use webpack-bundle-analyzer or vite-bundle-visualizer to see the treemap of every chunk and module:
+
+   ```bash
+   # Webpack
+   npx webpack-bundle-analyzer dist/stats.json
+
+   # Generate stats.json first if not present:
+   npx webpack --profile --json > dist/stats.json
+
+   # Vite
+   npx vite-bundle-visualizer
+
+   # Next.js
+   ANALYZE=true npx next build
+   # Requires: npm install @next/bundle-analyzer
+   ```
+
+   ```javascript
+   // next.config.js — integrate bundle analyzer
+   const withBundleAnalyzer = require('@next/bundle-analyzer')({
+     enabled: process.env.ANALYZE === 'true',
+   });
+   module.exports = withBundleAnalyzer({
+     /* next config */
+   });
+   ```
+
+2. **Explore bundle composition with source map explorer.** Source-map-explorer uses source maps to show exact byte-for-byte attribution:
+
+   ```bash
+   npx source-map-explorer dist/main.*.js
+   npx source-map-explorer dist/main.*.js --html result.html
+   npx source-map-explorer dist/*.js --tsv sizes.tsv  # machine-readable
+   ```
+
+3. **Evaluate dependency cost before installing.** Check the size impact of any npm package before adding it:
+
+   ```bash
+   # bundlephobia.com — check gzipped and minified size
+   # https://bundlephobia.com/package/date-fns@3.0.0
+
+   # package-size CLI — measure actual bundled size
+   npx package-size lodash-es/debounce
+   npx package-size date-fns/format date-fns/parseISO
+
+   # import-cost VS Code extension — inline size display next to imports
+   ```
+
+4. **Configure size budgets with size-limit.** Enforce maximum bundle sizes in CI:
+
+   ```json
+   // package.json
+   {
+     "size-limit": [
+       {
+         "name": "Entry point",
+         "path": "dist/index.js",
+         "limit": "50 KB",
+         "gzip": true
+       },
+       {
+         "name": "Full bundle",
+         "path": "dist/**/*.js",
+         "limit": "200 KB",
+         "gzip": true
+       },
+       {
+         "name": "CSS",
+         "path": "dist/**/*.css",
+         "limit": "30 KB",
+         "gzip": true
+       }
+     ],
+     "scripts": {
+       "size": "size-limit",
+       "size:check": "size-limit --why"
+     }
+   }
+   ```
+
+   ```yaml
+   # GitHub Actions CI integration
+   - name: Check bundle size
+     uses: andresz1/size-limit-action@v1
+     with:
+       github_token: ${{ secrets.GITHUB_TOKEN }}
+       skip_step: build
+       directory: dist
+   ```
+
+5. **Use webpack performance hints for build-time enforcement.**
+
+   ```javascript
+   // webpack.config.js
+   module.exports = {
+     performance: {
+       maxEntrypointSize: 250000, // 250KB
+       maxAssetSize: 200000, // 200KB per file
+       hints: process.env.NODE_ENV === 'production' ? 'error' : 'warning',
+       assetFilter: (filename) => {
+         return filename.endsWith('.js') || filename.endsWith('.css');
+       },
+     },
+   };
+   ```
+
+6. **Identify and eliminate duplicate dependencies.** Check for multiple versions of the same package bundled together:
+
+   ```bash
+   # webpack — duplicate package checker
+   npx duplicate-package-checker-webpack-plugin
+
+   # npm — list duplicates
+   npm ls --all | grep -E "deduped|invalid"
+
+   # pnpm — dedupe
+   pnpm dedupe
+
+   # yarn — dedupe
+   yarn dedupe
+   ```
+
+7. **Track bundle size over time.** Integrate size tracking into the PR workflow so every change shows its size impact:
+
+   ```bash
+   # bundlewatch — CI size tracking with GitHub status checks
+   npx bundlewatch --config .bundlewatch.config.js
+   ```
+
+   ```javascript
+   // .bundlewatch.config.js
+   module.exports = {
+     files: [
+       { path: 'dist/main.*.js', maxSize: '150KB' },
+       { path: 'dist/vendor.*.js', maxSize: '100KB' },
+       { path: 'dist/*.css', maxSize: '30KB' },
+     ],
+     ci: {
+       trackBranches: ['main'],
+       repoBranchBase: 'main',
+     },
+   };
+   ```
+
+## Details
+
+### Understanding Treemap Visualizations
+
+Bundle analyzer treemaps show nested rectangles where area is proportional to file size. The outer rectangles represent chunks (main, vendor, route-specific). Inner rectangles represent modules. Colors typically distinguish between application code and node_modules. When analyzing, look for: (1) unexpectedly large modules that suggest missing tree shaking, (2) duplicate modules appearing in multiple chunks, (3) node_modules that dominate the treemap relative to application code.
+
+### Gzipped vs Parsed vs Raw Size
+
+Bundle tools report three size metrics. **Raw size** is the uncompressed file on disk. **Parsed size** is the JavaScript the browser must parse and compile (after decompression, before execution). **Gzipped size** (or Brotli size) is the transfer size over the network. Parsed size most directly correlates with CPU cost (parsing/compilation). Gzipped size correlates with network transfer time. Budget both: a 500KB parsed file might compress to 100KB gzipped (fast download) but still take 200ms to parse on mobile.
+
+### Worked Example: Walmart Bundle Audit
+
+Walmart's web team used webpack-bundle-analyzer to discover that their checkout page bundled the full moment.js library (67KB gzipped) for a single date formatting call. Replacing it with a 2-line Intl.DateTimeFormat call eliminated the dependency entirely. They also found three different versions of lodash in the bundle (lodash, lodash-es, and lodash.merge). Deduplicating to lodash-es with direct function imports reduced the combined lodash footprint from 72KB to 8KB gzipped. Total savings: 129KB gzipped, reducing checkout TTI by 1.1 seconds on 3G.
+
+### Worked Example: Notion Size Budget Enforcement
+
+Notion enforces strict per-route bundle budgets in CI. Every PR shows a size comparison table in the GitHub check. If any route exceeds its budget, the PR is blocked. When a developer adds a new dependency, the CI check surfaces the exact byte increase and which route is affected. This prevents the gradual size creep that makes individual additions seem harmless while the cumulative effect degrades performance. Their main route budget is 180KB gzipped, and they have maintained it within 5% for two years.
+
+### Anti-Patterns
+
+**Analyzing only total bundle size.** A total size that stays constant can mask problems: one chunk grows while another shrinks. Always analyze per-chunk and per-route sizes.
+
+**Ignoring parsed/compile size.** A highly compressible library might be small over the wire but enormous to parse. Source maps and JSON blobs compress well but still impose parse cost. Budget parsed size independently.
+
+**Running analysis only in development mode.** Development builds include hot module replacement, React DevTools integration, and verbose error messages. Always analyze production builds.
+
+**Setting budgets too loose.** A 1MB budget never triggers. Start with the current size plus 10% headroom, then ratchet down. Effective budgets are ones that occasionally fail, prompting investigation.
+
+## Source
+
+- webpack-bundle-analyzer — https://github.com/webpack-contrib/webpack-bundle-analyzer
+- source-map-explorer — https://github.com/danvk/source-map-explorer
+- size-limit — https://github.com/ai/size-limit
+- Bundlephobia — https://bundlephobia.com/
+- bundlewatch — https://bundlewatch.io/
+
+## 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
+
+- Bundle visualization is generated and reviewed for unexpected large modules.
+- Size budgets are configured in CI and enforce per-chunk and per-route limits.
+- No duplicate dependencies exist in the production bundle.
+- New dependency additions include a size impact assessment.
+- Bundle size trends are tracked over time with visibility in PRs.

package/dist/agents/skills/cursor/perf-bundle-analysis/skill.yaml

@@ -0,0 +1,37 @@
+name: perf-bundle-analysis
+version: '1.0.0'
+description: Bundle analysis — Bundle visualization, size budgets, dependency cost analysis, and CI-integrated size tracking
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-code-splitting
+  - perf-tree-shaking
+  - perf-lazy-loading
+  - perf-compression
+stack_signals: []
+keywords:
+  - bundle analysis
+  - bundle size
+  - webpack-bundle-analyzer
+  - size budget
+  - dependency cost
+  - bundlephobia
+  - source map explorer
+  - size limit
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/perf-cache-invalidation/SKILL.md

@@ -0,0 +1,228 @@
+# Cache Invalidation
+
+> Solve the hardest problem in computer science — cache invalidation strategies including TTL-based expiry, event-driven invalidation, versioned cache keys, cache stampede prevention with locking and probabilistic early expiration, and fan-out invalidation for denormalized data.
+
+## When to Use
+
+- Users see stale data after content updates and you need faster cache freshness
+- Cache expiry causes thundering herd / stampede on the origin or database
+- A content management system needs real-time content updates across cached pages
+- Denormalized cache entries reference data that changes independently
+- You need to choose between TTL-based and event-driven invalidation
+- Cache miss storms after deploys or cache restarts overload the backend
+- Distributed caches across multiple regions need coordinated invalidation
+- Versioned cache keys are being considered to avoid explicit invalidation
+- Rate of content change varies by entity (some change hourly, some yearly)
+- Cache invalidation bugs cause data inconsistency between cache and database
+
+## Instructions
+
+1. **Choose an invalidation strategy.** Match the strategy to your consistency requirements:
+
+   | Strategy              | Freshness                      | Complexity | Best For                         |
+   | --------------------- | ------------------------------ | ---------- | -------------------------------- |
+   | TTL-based             | Eventual (up to TTL)           | Low        | Content that tolerates staleness |
+   | Event-driven          | Near-real-time                 | Medium     | CMS, user-facing content         |
+   | Versioned keys        | Immediate                      | Medium     | Immutable data, API responses    |
+   | Hybrid (TTL + events) | Near-real-time with safety net | High       | Most production systems          |
+
+2. **Implement TTL-based expiration with jitter.** Add random jitter to prevent synchronized expiry:
+
+   ```javascript
+   function setWithJitter(key, value, baseTTL) {
+     // Add +/- 10% jitter to prevent synchronized expiry
+     const jitter = baseTTL * 0.1 * (Math.random() * 2 - 1);
+     const ttl = Math.round(baseTTL + jitter);
+     return redis.setex(key, ttl, JSON.stringify(value));
+   }
+
+   // 300 items with baseTTL=3600 expire between 3240-3960 seconds
+   // instead of all expiring at exactly 3600 seconds
+   ```
+
+3. **Implement event-driven invalidation.** Publish invalidation events when source data changes:
+
+   ```javascript
+   // On data change: publish invalidation event
+   async function updateArticle(articleId, data) {
+     await db.articles.update(articleId, data);
+
+     // Publish invalidation event
+     await redis.publish(
+       'cache:invalidate',
+       JSON.stringify({
+         type: 'article',
+         id: articleId,
+         tags: ['homepage', `section:${data.section}`, `author:${data.authorId}`],
+       })
+     );
+   }
+
+   // Cache subscriber: listen for invalidation events
+   const subscriber = redis.duplicate();
+   subscriber.subscribe('cache:invalidate');
+   subscriber.on('message', (channel, message) => {
+     const event = JSON.parse(message);
+     // Delete specific cache entry
+     redis.del(`article:${event.id}`);
+     // Delete related cache entries
+     event.tags.forEach((tag) => invalidateByTag(tag));
+   });
+   ```
+
+4. **Use versioned cache keys for immutable patterns.** Instead of invalidating, change the key:
+
+   ```javascript
+   // Version stored in a lightweight metadata key
+   async function getArticle(articleId) {
+     const version = await redis.get(`article:${articleId}:version`);
+     const cacheKey = `article:${articleId}:v${version}`;
+
+     const cached = await redis.get(cacheKey);
+     if (cached) return JSON.parse(cached);
+
+     const article = await db.articles.findById(articleId);
+     await redis.setex(cacheKey, 86400, JSON.stringify(article));
+     return article;
+   }
+
+   async function updateArticle(articleId, data) {
+     await db.articles.update(articleId, data);
+     // Increment version — old key naturally expires via TTL
+     await redis.incr(`article:${articleId}:version`);
+   }
+   ```
+
+5. **Prevent cache stampede with locking.** When a cache entry expires, only one process should recompute:
+
+   ```javascript
+   async function getWithLock(key, computeFn, ttl = 3600) {
+     const cached = await redis.get(key);
+     if (cached) return JSON.parse(cached);
+
+     // Try to acquire lock
+     const lockKey = `lock:${key}`;
+     const acquired = await redis.set(lockKey, '1', 'NX', 'EX', 30);
+
+     if (acquired) {
+       try {
+         // This process recomputes
+         const value = await computeFn();
+         await redis.setex(key, ttl, JSON.stringify(value));
+         return value;
+       } finally {
+         await redis.del(lockKey);
+       }
+     } else {
+       // Another process is recomputing — wait and retry
+       await new Promise((resolve) => setTimeout(resolve, 100));
+       return getWithLock(key, computeFn, ttl);
+     }
+   }
+   ```
+
+6. **Implement probabilistic early expiration (XFetch).** Proactively refresh cache entries before they expire:
+
+   ```javascript
+   async function getWithXFetch(key, computeFn, ttl = 3600, beta = 1.0) {
+     const cached = await redis.get(key);
+     if (cached) {
+       const entry = JSON.parse(cached);
+       const now = Date.now();
+       const expiry = entry.expiry;
+       const delta = entry.computeTime; // ms to recompute
+
+       // Probabilistic early recomputation
+       // Higher beta = more aggressive early refresh
+       const shouldRefresh = now - delta * beta * Math.log(Math.random()) >= expiry;
+
+       if (!shouldRefresh) {
+         return entry.value;
+       }
+     }
+
+     // Recompute
+     const start = Date.now();
+     const value = await computeFn();
+     const computeTime = Date.now() - start;
+
+     await redis.setex(
+       key,
+       ttl,
+       JSON.stringify({
+         value,
+         expiry: Date.now() + ttl * 1000,
+         computeTime,
+       })
+     );
+
+     return value;
+   }
+   ```
+
+7. **Handle fan-out invalidation for denormalized data.** When a user updates their name, invalidate all cached entities that embed that name:
+
+   ```javascript
+   // Maintain a reverse index: entity → dependent cache keys
+   async function invalidateUser(userId) {
+     const dependents = await redis.smembers(`deps:user:${userId}`);
+     // dependents might be: ['article:123', 'comment:456', 'team:789']
+
+     if (dependents.length > 0) {
+       await redis.del(...dependents);
+       await redis.del(`deps:user:${userId}`);
+     }
+     await redis.del(`user:${userId}`);
+   }
+   ```
+
+## Details
+
+### The XFetch Algorithm
+
+The XFetch algorithm (from the paper "Optimal Probabilistic Cache Stampede Prevention") provides a mathematically optimal solution to cache stampede. Instead of waiting for expiry and then competing for a lock, XFetch probabilistically triggers recomputation before expiry. The probability increases as the entry approaches expiry and scales with the computation cost (expensive computations start refreshing earlier). The beta parameter controls aggressiveness: beta=1.0 is optimal for single-threaded access, beta=2.0+ for high-concurrency scenarios.
+
+### Worked Example: Facebook Lease-Based Invalidation
+
+Facebook's Memcache infrastructure (described in their "Scaling Memcache at Facebook" NSDI 2013 paper) implements lease-based cache invalidation. When a cache miss occurs, the client receives a lease token from Memcache. Only the lease holder can write the recomputed value back to cache — other concurrent requests for the same key receive a "wait" response and retry after a short delay (typically 10ms). This prevents the stampede problem without explicit locking: at most one backend request recomputes any given cache entry, regardless of how many concurrent cache misses occur. The lease has a 10-second timeout as a safety net.
+
+### Worked Example: Stripe Versioned Cache Keys
+
+Stripe uses versioned cache keys with monotonically increasing generation numbers for their API response caches. When underlying data changes, the generation number is incremented atomically (a single Redis INCR operation). Cache invalidation is therefore a metadata update, not a cache purge. Old cache entries naturally expire via TTL. This approach eliminates the race condition between "delete old entry" and "write new entry" — the new version is simply a different key. It also provides implicit cache warmup: the old version continues serving until the new version is populated.
+
+### Anti-Patterns
+
+**Invalidating by deleting without stampede protection.** If a popular cache entry is deleted, N concurrent requests all see a cache miss simultaneously. All N requests hit the database. With 1,000 concurrent users and a 500ms query, that is 1,000 simultaneous database queries for the same data. Use locking, XFetch, or stale-while-revalidate.
+
+**Using wallclock-based TTLs without jitter.** If 10,000 cache entries are all set with TTL=3600 at the same time (e.g., during cache warming), they all expire at the same second. Add 5-10% random jitter to spread expiry over a time window.
+
+**Invalidating parent caches without derived caches.** If a user's name changes and you invalidate `user:123` but not `article:456` (which embeds the user's name), the article shows stale author information. Maintain dependency tracking for denormalized caches.
+
+**Fire-and-forget invalidation without confirmation.** Network drops, Redis failovers, or message queue delays can silently prevent invalidation messages from arriving. Implement at-least-once delivery for critical invalidation events and use TTL as a safety net.
+
+## Source
+
+- "Scaling Memcache at Facebook" (NSDI 2013) — https://www.usenix.org/conference/nsdi13/technical-sessions/presentation/nishtala
+- "Optimal Probabilistic Cache Stampede Prevention" (XFetch algorithm) — https://cseweb.ucsd.edu/~avattani/papers/cache_stampede.pdf
+- Redis documentation on distributed locking (Redlock) — https://redis.io/docs/manual/patterns/distributed-locks/
+- Martin Kleppmann, "Designing Data-Intensive Applications" (O'Reilly), Chapter 5
+- CDN purging best practices — Fastly, Cloudflare, Akamai documentation
+
+## 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.
+- Cache stampede is prevented via locking, XFetch, or stale-while-revalidate on high-traffic entries.
+- TTL-based expiry uses jitter to prevent synchronized cache expiration storms.
+- Denormalized cache entries are invalidated when their source data changes.

package/dist/agents/skills/cursor/perf-cache-invalidation/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-cache-invalidation
+version: '1.0.0'
+description: Cache invalidation — TTL strategies, event-driven invalidation, cache stampede prevention, and versioned cache keys
+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-caching
+  - perf-browser-cache
+  - perf-cdn-cache-control
+  - perf-cdn-strategies
+stack_signals: []
+keywords:
+  - cache invalidation
+  - ttl
+  - cache stampede
+  - thundering herd
+  - event-driven invalidation
+  - versioned keys
+  - cache warming
+  - probabilistic early expiration
+  - lock-based invalidation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []