@harness-engineering/cli 1.23.2 → 1.24.1

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

@@ -0,0 +1,38 @@
+name: perf-compression
+version: '1.0.0'
+description: Content compression — Brotli vs gzip comparison, compression levels, content-encoding negotiation, and static vs dynamic compression
+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-strategies
+  - perf-http2-multiplexing
+  - perf-bundle-analysis
+  - perf-cdn-cache-control
+stack_signals: []
+keywords:
+  - brotli
+  - gzip
+  - compression
+  - content-encoding
+  - transfer size
+  - zstd
+  - deflate
+  - compression ratio
+  - static compression
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-connection-costs/SKILL.md

@@ -0,0 +1,165 @@
+# Network Connection Costs
+
+> Understand and minimize the cumulative cost of DNS resolution, TCP handshake, and TLS negotiation — the invisible overhead that adds 100-500ms to every new connection before a single byte of application data transfers.
+
+## When to Use
+
+- Time to First Byte (TTFB) exceeds 600ms and network waterfall shows connection establishment as the bottleneck
+- DevTools shows DNS lookup, TCP connect, and TLS handshake consuming significant time per resource
+- A page connects to more than 4 unique origins (main domain, CDN, analytics, fonts, ads)
+- Mobile users report slow initial page loads, especially on high-latency cellular networks
+- You need to decide how many third-party origins to include on a page
+- Server-side applications make outbound HTTP requests to multiple microservices
+- TTFB is inconsistent across geographic regions, suggesting DNS or routing issues
+- You are optimizing the critical rendering path and need to reduce resource discovery latency
+- Connection reuse metrics show low keep-alive rates or frequent connection churn
+- TLS handshake time exceeds 100ms and certificate chain optimization is needed
+
+## Instructions
+
+1. **Measure connection costs.** In Chrome DevTools Network panel, hover over the Waterfall bar for any resource. The tooltip breaks down: DNS Lookup, TCP Connection (Initial connection), TLS Handshake (SSL), and TTFB (Waiting for server response). Use the Navigation Timing API for programmatic measurement:
+
+   ```javascript
+   const nav = performance.getEntriesByType('navigation')[0];
+   console.log({
+     dns: nav.domainLookupEnd - nav.domainLookupStart, // DNS resolution
+     tcp: nav.connectEnd - nav.connectStart, // TCP handshake
+     tls:
+       nav.secureConnectionStart > 0
+         ? nav.connectEnd - nav.secureConnectionStart // TLS negotiation
+         : 0,
+     ttfb: nav.responseStart - nav.requestStart, // Server processing
+   });
+   ```
+
+2. **Minimize unique origins.** Each unique origin requires a full DNS + TCP + TLS handshake. Audit all origins on your page:
+
+   ```bash
+   # Extract unique origins from a HAR file or DevTools
+   # Target: 4 or fewer unique origins for critical resources
+   ```
+
+   Decision thresholds:
+   - 1-3 origins: optimal, minimal connection overhead
+   - 4-6 origins: acceptable, use preconnect for non-primary origins
+   - 7+ origins: excessive, consolidate or defer non-critical third-party resources
+
+3. **Optimize DNS resolution.** DNS resolution involves recursive lookups through multiple nameservers. Typical cost: 20-120ms globally, but can exceed 200ms for uncached domains on mobile.
+
+   Mitigation strategies:
+   - **dns-prefetch** for origins needed soon: `<link rel="dns-prefetch" href="//cdn.example.com">`
+   - **Reduce DNS TTL carefully** — shorter TTL means more lookups, longer means slower failover
+   - **Use a fast DNS provider** — Cloudflare DNS (1.1.1.1): ~11ms median, Route 53: ~20ms median
+   - **DNS-over-HTTPS (DoH)** — encrypted but may add latency for first resolution
+
+4. **Reduce TCP handshake cost.** TCP requires a 3-way handshake (SYN, SYN-ACK, ACK) — one full round trip. Mitigation:
+   - **TCP Fast Open (TFO)** — sends data in the SYN packet on repeat connections, saving 1 RTT
+   - **Increase initial congestion window (initcwnd)** — default is 10 segments (~14.6KB); this determines how much data transfers in the first RTT after handshake
+   - **Connection reuse via keep-alive** — HTTP/1.1 defaults to keep-alive; HTTP/2 multiplexes over one connection
+
+   ```bash
+   # Check and set initcwnd on Linux
+   ip route show
+   ip route change default via <gateway> dev eth0 initcwnd 10 initrwnd 10
+   ```
+
+5. **Optimize TLS negotiation.** TLS adds 1-2 RTTs depending on version:
+   - **TLS 1.2**: 2 additional RTTs (ClientHello -> ServerHello -> Finished)
+   - **TLS 1.3**: 1 additional RTT (combined handshake), 0-RTT on resumption
+
+   Optimization checklist:
+   - Use TLS 1.3 (saves 1 RTT over TLS 1.2)
+   - Enable TLS session resumption (session tickets or session IDs)
+   - Use ECDSA certificates (256-byte signature vs 2048-byte RSA)
+   - Minimize certificate chain length (2-3 certificates maximum)
+   - Enable OCSP stapling (avoids client-side OCSP check adding 100-200ms)
+
+6. **Use preconnect for critical third-party origins.** Preconnect performs DNS + TCP + TLS ahead of time:
+
+   ```html
+   <!-- Preconnect to critical third-party origins -->
+   <link rel="preconnect" href="https://fonts.googleapis.com" />
+   <link rel="preconnect" href="https://cdn.example.com" />
+
+   <!-- Use dns-prefetch as fallback for browsers that don't support preconnect -->
+   <link rel="dns-prefetch" href="https://fonts.googleapis.com" />
+   ```
+
+7. **Enable connection pooling for server-side requests.** Backend services making HTTP requests to other services should reuse connections:
+
+   ```javascript
+   // Node.js: use an HTTP agent with keep-alive
+   const http = require('http');
+   const agent = new http.Agent({
+     keepAlive: true,
+     maxSockets: 50,
+     maxFreeSockets: 10,
+     timeout: 60000,
+   });
+   ```
+
+## Details
+
+### The Connection Cost Breakdown
+
+A new HTTPS connection to a remote server involves three sequential steps:
+
+| Step                | Roundtrips          | Typical Latency (100ms RTT) | Typical Latency (250ms RTT) |
+| ------------------- | ------------------- | --------------------------- | --------------------------- |
+| DNS Resolution      | 1 RTT (if uncached) | 20-120ms                    | 50-250ms                    |
+| TCP Handshake       | 1 RTT               | 100ms                       | 250ms                       |
+| TLS 1.3             | 1 RTT               | 100ms                       | 250ms                       |
+| TLS 1.2             | 2 RTT               | 200ms                       | 500ms                       |
+| **Total (TLS 1.3)** | **3 RTT**           | **220-320ms**               | **550-750ms**               |
+| **Total (TLS 1.2)** | **4 RTT**           | **320-420ms**               | **800-1000ms**              |
+
+Every unique origin incurs this cost for the first request. Subsequent requests on the same connection skip all of it.
+
+### TCP Slow Start and Initial Congestion Window
+
+After the TCP handshake, the connection starts in slow start mode. The initial congestion window (initcwnd) determines how many TCP segments can be sent before receiving an acknowledgment. With initcwnd=10 (the modern default), approximately 14.6KB of data can transfer in the first RTT. This is why inlining critical CSS under 14KB ensures it arrives in the first roundtrip.
+
+### Worked Example: LinkedIn TTFB Optimization
+
+LinkedIn reduced TTFB by 50% by implementing two changes: (1) adding `<link rel="preconnect">` for 3 third-party origins used for fonts, analytics, and advertising — this shifted 300ms of connection setup from the critical path to the preconnect phase, and (2) increasing their server's initcwnd from the legacy default of 3 to 10, allowing the initial HTML response to transfer 14.6KB in the first RTT instead of 4.4KB. Combined, these changes reduced the visible blank-screen time from 1.2s to 0.6s on median mobile connections.
+
+### Worked Example: Yahoo DNS Optimization
+
+Yahoo measured DNS lookup times averaging 20-120ms across global users. They reduced this by 70% through: (1) implementing `<link rel="dns-prefetch">` for all third-party origins in the document head, (2) reducing unique origins from 12 to 4 by consolidating CDN domains, (3) switching to a DNS provider with better global anycast coverage. The reduction in origins alone saved 4-8 full connection handshakes per page load (400-800ms on mobile).
+
+### Anti-Patterns
+
+**Connecting to too many unique origins.** Each origin requires a full handshake chain. A page with 12 unique origins spends 2-4 seconds just on connection establishment on mobile networks. Consolidate to 4 or fewer origins for critical path resources.
+
+**Oversized TLS certificate chains.** Certificate chains exceeding 3KB (3+ intermediate certificates or RSA-4096 keys) require multiple TCP roundtrips to deliver. Use ECDSA certificates (P-256: 64-byte key vs RSA-2048: 256-byte key) and minimize intermediates.
+
+**Not enabling TLS session resumption.** Without session tickets or session IDs, every connection performs a full TLS handshake. Session resumption reduces TLS to 1 RTT (TLS 1.2) or 0 RTT (TLS 1.3). Verify with: `openssl s_client -connect example.com:443 -reconnect`.
+
+**Relying on DNS TTL alone without prefetch hints.** DNS caches expire, and the first visitor after expiry pays the full lookup cost. Always add `dns-prefetch` hints for known third-party origins as a safety net.
+
+## Source
+
+- Ilya Grigorik, "High Performance Browser Networking" (O'Reilly), Chapters 1-4
+- RFC 7918: TLS False Start — https://www.rfc-editor.org/rfc/rfc7918
+- RFC 8446: TLS 1.3 — https://www.rfc-editor.org/rfc/rfc8446
+- Google Research: "An Argument for Increasing TCP's Initial Congestion Window" — https://research.google/pubs/pub36640/
+- W3C Resource Hints Specification — https://www.w3.org/TR/resource-hints/
+
+## 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.
+- Critical path origins are reduced to 4 or fewer with preconnect hints for necessary third-party origins.
+- TLS 1.3 is active with session resumption enabled and OCSP stapling configured.
+- Connection waterfall shows reuse (no repeat DNS/TCP/TLS for same-origin requests).

package/dist/agents/skills/gemini-cli/perf-connection-costs/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-connection-costs
+version: '1.0.0'
+description: Network connection overhead — DNS resolution, TCP handshake, TLS negotiation, connection reuse, and keep-alive strategies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-http2-multiplexing
+  - perf-http3-quic
+  - perf-resource-hints
+  - perf-cdn-strategies
+  - perf-critical-rendering-path
+  - node-performance-profiling
+stack_signals: []
+keywords:
+  - dns resolution
+  - tcp handshake
+  - tls negotiation
+  - connection reuse
+  - keep-alive
+  - time to first byte
+  - ttfb
+  - ssl certificate
+  - connection pooling
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-connection-pooling/SKILL.md

@@ -0,0 +1,250 @@
+# Connection Pooling
+
+> Master database connection pooling — pool sizing formulas, connection lifecycle overhead, PgBouncer transaction-mode pooling, serverless connection management, pool monitoring and diagnostics, and configuration for PostgreSQL, MySQL, and managed database services.
+
+## When to Use
+
+- Database connections are exhausted under load ("too many connections" errors)
+- Request latency includes 20-50ms for new connection establishment per query
+- Serverless functions create excessive database connections on cold starts
+- Connection pool is sized too large, consuming database memory and OS resources
+- Idle connections accumulate and hit the database's max_connections limit
+- A connection leak causes pool exhaustion over hours of uptime
+- Multiple application instances share a database with limited connection capacity
+- Database failover causes all pooled connections to become stale
+- Horizontal scaling of application servers multiplies connection count beyond limits
+- Query latency has high variance with spikes correlating to new connection creation
+
+## Instructions
+
+1. **Understand connection overhead.** Each PostgreSQL connection consumes ~5-10MB of RAM on the server and requires a TCP handshake plus TLS negotiation:
+
+   ```
+   Connection establishment cost:
+   - TCP handshake:      ~0.5ms (same datacenter), ~30ms (cross-region)
+   - TLS handshake:      ~2ms (same datacenter), ~60ms (cross-region)
+   - PostgreSQL auth:    ~5ms (password), ~10ms (SCRAM-SHA-256)
+   - Process creation:   ~2ms (PostgreSQL forks per connection)
+   - Total:              ~10ms (local) to ~100ms (cross-region)
+
+   Per-connection memory (PostgreSQL):
+   - work_mem:           4MB default (per operation, can be higher)
+   - Backend memory:     ~5-10MB base
+   - OS resources:       file descriptors, kernel buffers
+   ```
+
+2. **Size the pool correctly.** The optimal pool size depends on workload type, not application concurrency:
+
+   ```
+   Formula (Brian Brazeal / PostgreSQL wiki):
+   pool_size = (core_count * 2) + effective_spindle_count
+
+   For SSD-backed servers:
+   pool_size = core_count * 2 + 1
+
+   Example: 4-core database server with SSD
+   pool_size = (4 * 2) + 1 = 9 connections
+
+   For I/O-bound workloads (many external API calls during transactions):
+   pool_size = core_count * 4
+   ```
+
+   The counterintuitive rule: smaller pools perform better. A pool of 10 connections on a 4-core server outperforms a pool of 200 because fewer connections mean less context switching, less lock contention, and less memory pressure.
+
+3. **Configure application-level pooling.** Set min, max, idle timeout, and connection lifetime:
+
+   ```typescript
+   // Node.js with pg (node-postgres)
+   import { Pool } from 'pg';
+
+   const pool = new Pool({
+     host: process.env.DB_HOST,
+     max: 10, // maximum connections in pool
+     min: 2, // minimum idle connections
+     idleTimeoutMillis: 30000, // close idle connections after 30s
+     connectionTimeoutMillis: 5000, // fail if connection not acquired in 5s
+     maxLifetimeMillis: 1800000, // recycle connections every 30 min
+   });
+
+   // Always return connections to the pool
+   async function query(sql: string, params?: any[]) {
+     const client = await pool.connect();
+     try {
+       return await client.query(sql, params);
+     } finally {
+       client.release(); // CRITICAL: always release back to pool
+     }
+   }
+   ```
+
+   ```typescript
+   // Prisma connection pool configuration
+   // In DATABASE_URL:
+   // postgresql://user:pass@host:5432/db?connection_limit=10&pool_timeout=5
+
+   // Or in schema.prisma for more control:
+   const prisma = new PrismaClient({
+     datasources: {
+       db: {
+         url: process.env.DATABASE_URL + '?connection_limit=10&pool_timeout=5',
+       },
+     },
+   });
+   ```
+
+4. **Deploy PgBouncer for external pooling.** PgBouncer sits between the application and PostgreSQL, multiplexing many client connections onto fewer database connections:
+
+   ```ini
+   ; pgbouncer.ini
+   [databases]
+   myapp = host=pg-primary port=5432 dbname=myapp
+
+   [pgbouncer]
+   listen_addr = 0.0.0.0
+   listen_port = 6432
+   auth_type = scram-sha-256
+   auth_file = /etc/pgbouncer/userlist.txt
+
+   ; Pool mode: transaction (recommended), session, or statement
+   pool_mode = transaction
+
+   ; Pool sizing
+   default_pool_size = 20        ; connections per user/database pair
+   max_client_conn = 1000        ; total client connections accepted
+   max_db_connections = 50       ; max connections to actual PostgreSQL
+   reserve_pool_size = 5         ; extra connections for burst handling
+
+   ; Timeouts
+   server_idle_timeout = 60      ; close idle server connections after 60s
+   client_idle_timeout = 300     ; close idle client connections after 5min
+   query_timeout = 30            ; kill queries running longer than 30s
+   ```
+
+   ```
+   Architecture:
+   [App Server 1] ──┐                     ┌── [PostgreSQL]
+   [App Server 2] ──┤── [PgBouncer] ──────┤   max_connections = 100
+   [App Server 3] ──┘   1000 clients      └── 50 actual connections
+                        → 50 DB conns
+   ```
+
+5. **Handle serverless connection challenges.** Serverless functions create new connections on every cold start. Use external pooling:
+
+   ```typescript
+   // Neon serverless driver — uses WebSocket, handles pooling externally
+   import { neon } from '@neondatabase/serverless';
+   const sql = neon(process.env.DATABASE_URL);
+
+   // Supabase with connection pooling (uses PgBouncer internally)
+   // Use port 6543 for pooled connections instead of 5432
+   // postgresql://user:pass@host:6543/db?pgbouncer=true
+
+   // Prisma with Accelerate (managed connection pooling)
+   // DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=..."
+
+   // AWS RDS Proxy — managed connection pooling for Lambda
+   // Configure in AWS console, use proxy endpoint instead of RDS endpoint
+   ```
+
+6. **Monitor pool health.** Track pool metrics to diagnose issues before they cause outages:
+
+   ```typescript
+   // node-postgres pool events
+   pool.on('connect', () => {
+     metrics.increment('db.pool.connect');
+   });
+   pool.on('acquire', () => {
+     metrics.increment('db.pool.acquire');
+   });
+   pool.on('remove', () => {
+     metrics.increment('db.pool.remove');
+   });
+   pool.on('error', (err) => {
+     metrics.increment('db.pool.error');
+     console.error('Pool error:', err.message);
+   });
+
+   // Periodic health check
+   setInterval(() => {
+     metrics.gauge('db.pool.total', pool.totalCount);
+     metrics.gauge('db.pool.idle', pool.idleCount);
+     metrics.gauge('db.pool.waiting', pool.waitingCount);
+
+     if (pool.waitingCount > 0) {
+       console.warn(`${pool.waitingCount} queries waiting for connections`);
+     }
+   }, 5000);
+   ```
+
+7. **Handle connection failures gracefully.** Connections break due to network issues, database restarts, or failovers:
+
+   ```typescript
+   // Retry with exponential backoff for transient connection failures
+   async function resilientQuery(sql: string, params?: any[], retries = 3) {
+     for (let attempt = 0; attempt < retries; attempt++) {
+       try {
+         return await pool.query(sql, params);
+       } catch (err: any) {
+         const isTransient = [
+           '57P01', // admin_shutdown
+           '57P03', // cannot_connect_now
+           '08006', // connection_failure
+           '08001', // sqlclient_unable_to_establish_sqlconnection
+         ].includes(err.code);
+
+         if (!isTransient || attempt === retries - 1) throw err;
+         await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
+       }
+     }
+   }
+   ```
+
+## Details
+
+### Transaction Mode vs Session Mode (PgBouncer)
+
+In **transaction mode**, PgBouncer assigns a server connection for the duration of a transaction, then returns it to the pool. This achieves the highest multiplexing ratio (1000 clients on 20 connections). Limitation: session-level features (SET, LISTEN/NOTIFY, prepared statements, temporary tables) do not work across transactions. In **session mode**, a server connection is held for the entire client session. Lower multiplexing but full feature compatibility. Most applications should use transaction mode.
+
+### Worked Example: Discord Serverless Migration
+
+Discord migrated their message history API from dedicated servers to serverless functions, which caused connection storms — 10,000 concurrent Lambda invocations each opening a database connection. They deployed PgBouncer on a dedicated instance, configured with `pool_mode = transaction`, `default_pool_size = 25`, and `max_client_conn = 15000`. The PgBouncer instance multiplexes 15,000 Lambda connections onto 25 actual PostgreSQL connections. Result: PostgreSQL CPU dropped from 90% to 35%, and p99 latency decreased from 200ms to 45ms because the database was no longer thrashing with 10,000 concurrent connections.
+
+### Worked Example: Vercel Edge Functions + Neon
+
+Vercel's edge functions run in globally distributed isolates that cannot maintain persistent TCP connections. Neon's serverless driver uses HTTP/WebSocket transport instead of raw TCP, with connection pooling handled by Neon's proxy layer. Each edge function invocation sends a query over HTTP — no connection setup, no pool management. The proxy maintains a warm pool of PostgreSQL connections. Result: cold-start database queries complete in 5-10ms (HTTP overhead) versus 50-100ms (TCP connection establishment), and the PostgreSQL server sees a stable 50 connections regardless of edge function concurrency.
+
+### Anti-Patterns
+
+**Setting pool size equal to max_connections.** If pool_size matches max_connections, one application instance monopolizes all database connections, leaving zero for other services, migration scripts, or admin access. Always reserve 20-30% of max_connections for non-application use.
+
+**Not releasing connections back to the pool.** A missing `client.release()` (or failed `finally` block) causes a connection leak. The pool gradually exhausts. Always release in a finally block or use pool.query() which handles acquisition and release automatically.
+
+**Opening a new pool per request.** Creating a `new Pool()` in a request handler establishes a fresh pool for each request instead of reusing connections. Create the pool once at application startup and reuse it.
+
+**Oversizing the pool.** A pool of 100 connections on a 4-core database causes context-switching overhead and lock contention that degrades throughput. Start with `(cores * 2) + 1` and increase only with load testing evidence.
+
+## Source
+
+- PostgreSQL wiki: Number Of Database Connections — https://wiki.postgresql.org/wiki/Number_Of_Database_Connections
+- PgBouncer documentation — https://www.pgbouncer.org/config.html
+- node-postgres: Pooling — https://node-postgres.com/features/pooling
+- Neon serverless driver — https://neon.tech/docs/serverless/serverless-driver
+
+## 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
+
+- Connection pool size follows the (cores \* 2) + 1 formula as a starting point.
+- All database interactions use pooled connections with proper release handling.
+- External pooling (PgBouncer or managed proxy) is deployed for multi-instance or serverless architectures.
+- Pool metrics (total, idle, waiting) are monitored with alerts on exhaustion.
+- No connection leaks exist (verified by monitoring idle count stability over time).

package/dist/agents/skills/gemini-cli/perf-connection-pooling/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-connection-pooling
+version: '1.0.0'
+description: Connection pooling — Pool sizing, connection lifecycle overhead, PgBouncer, serverless pooling, and pool monitoring
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-query-optimization
+  - perf-n-plus-one
+  - perf-index-strategies
+  - node-performance-profiling
+stack_signals: []
+keywords:
+  - connection pool
+  - connection pooling
+  - PgBouncer
+  - pool size
+  - connection overhead
+  - serverless database
+  - connection limit
+  - idle timeout
+  - pool exhaustion
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []