@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/resilience-health-checks/SKILL.md

@@ -0,0 +1,180 @@
+# Health Checks
+
+> Implement health check endpoints for service readiness, liveness, and dependency monitoring
+
+## When to Use
+
+- Deploying to Kubernetes or any orchestrator that uses health probes
+- Load balancers need to know if an instance can handle traffic
+- Monitoring dashboards need service status at a glance
+- Graceful shutdown requires draining connections before terminating
+
+## Instructions
+
+1. Implement three endpoints: `/health/live` (liveness), `/health/ready` (readiness), `/health/startup` (startup).
+2. **Liveness** — Is the process alive and not deadlocked? Should be lightweight (no dependency checks). Returns 200 if the process can respond.
+3. **Readiness** — Can this instance handle traffic? Checks database connections, cache availability, and critical dependencies. Returns 200 when ready, 503 when not.
+4. **Startup** — Has the service finished initializing? Used for slow-starting services to prevent premature liveness failures.
+5. Set the readiness check to return 503 during graceful shutdown to stop receiving new traffic.
+6. Health check responses should include component-level detail for debugging.
+
+```typescript
+// health/health-controller.ts
+interface HealthComponent {
+  name: string;
+  status: 'up' | 'down' | 'degraded';
+  latency?: number;
+  details?: string;
+}
+
+interface HealthResponse {
+  status: 'healthy' | 'unhealthy' | 'degraded';
+  uptime: number;
+  timestamp: string;
+  components: HealthComponent[];
+}
+
+export class HealthChecker {
+  private ready = false;
+  private shuttingDown = false;
+  private startTime = Date.now();
+  private checks: Array<{ name: string; check: () => Promise<HealthComponent> }> = [];
+
+  registerCheck(name: string, check: () => Promise<HealthComponent>) {
+    this.checks.push({ name, check });
+  }
+
+  setReady(ready: boolean) {
+    this.ready = ready;
+  }
+  setShuttingDown() {
+    this.shuttingDown = true;
+    this.ready = false;
+  }
+
+  async liveness(): Promise<{ status: number; body: object }> {
+    return {
+      status: 200,
+      body: { status: 'alive', uptime: Date.now() - this.startTime },
+    };
+  }
+
+  async readiness(): Promise<{ status: number; body: HealthResponse }> {
+    if (this.shuttingDown || !this.ready) {
+      return {
+        status: 503,
+        body: {
+          status: 'unhealthy',
+          uptime: Date.now() - this.startTime,
+          timestamp: new Date().toISOString(),
+          components: [
+            {
+              name: 'server',
+              status: 'down',
+              details: this.shuttingDown ? 'shutting down' : 'not ready',
+            },
+          ],
+        },
+      };
+    }
+
+    const components = await Promise.all(
+      this.checks.map(async ({ name, check }) => {
+        try {
+          return await check();
+        } catch (err) {
+          return { name, status: 'down' as const, details: String(err) };
+        }
+      })
+    );
+
+    const allUp = components.every((c) => c.status === 'up');
+    const anyDown = components.some((c) => c.status === 'down');
+
+    return {
+      status: anyDown ? 503 : 200,
+      body: {
+        status: anyDown ? 'unhealthy' : allUp ? 'healthy' : 'degraded',
+        uptime: Date.now() - this.startTime,
+        timestamp: new Date().toISOString(),
+        components,
+      },
+    };
+  }
+}
+```
+
+```typescript
+// Registering checks
+const health = new HealthChecker();
+
+health.registerCheck('database', async () => {
+  const start = Date.now();
+  await pool.query('SELECT 1');
+  return { name: 'database', status: 'up', latency: Date.now() - start };
+});
+
+health.registerCheck('redis', async () => {
+  const start = Date.now();
+  await redis.ping();
+  return { name: 'redis', status: 'up', latency: Date.now() - start };
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  health.setShuttingDown();
+  // Allow in-flight requests to complete
+  setTimeout(() => process.exit(0), 30000);
+});
+```
+
+## Details
+
+**Kubernetes probe configuration:**
+
+```yaml
+livenessProbe:
+  httpGet: { path: /health/live, port: 3000 }
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  failureThreshold: 3 # Restart after 3 failures
+
+readinessProbe:
+  httpGet: { path: /health/ready, port: 3000 }
+  periodSeconds: 5
+  failureThreshold: 2 # Remove from service after 2 failures
+
+startupProbe:
+  httpGet: { path: /health/startup, port: 3000 }
+  periodSeconds: 5
+  failureThreshold: 30 # Allow up to 150s for startup
+```
+
+**Liveness vs readiness:** Liveness failure triggers a pod restart. Readiness failure removes the pod from the service endpoint (no traffic routed to it). Making liveness too strict causes unnecessary restarts. Making readiness too lenient routes traffic to broken instances.
+
+**Health check anti-patterns:**
+
+- Checking dependencies in the liveness probe (a database outage restarts all pods)
+- Not setting timeouts on dependency checks (health check hangs)
+- Returning 200 during shutdown (new requests arrive after drain starts)
+- Exposing sensitive information in health responses (connection strings, credentials)
+
+## Source
+
+https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
+
+## 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.

package/dist/agents/skills/cursor/resilience-health-checks/skill.yaml

@@ -0,0 +1,38 @@
+name: resilience-health-checks
+version: '1.0.0'
+description: Implement health check endpoints for service readiness and liveness monitoring
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/health/**'
+  - '**/routes/**'
+  - '**/api/**'
+related_skills:
+  - resilience-circuit-breaker
+  - resilience-fallback-pattern
+  - otel-metrics-pattern
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - health-check
+  - liveness
+  - readiness
+  - startup-probe
+  - kubernetes
+metadata:
+  author: community
+  upstream: 'kubernetes/docs/health-checks'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/resilience-idempotency/SKILL.md

@@ -0,0 +1,167 @@
+# Idempotency Pattern
+
+> Ensure safe retries by making operations produce the same result regardless of how many times they execute
+
+## When to Use
+
+- API endpoints that create resources (POST) need to be safely retryable
+- Payment processing where duplicate charges are unacceptable
+- Message consumers that may receive the same message twice (at-least-once delivery)
+- Any operation where network failures could cause the client to retry without knowing if the first request succeeded
+
+## Instructions
+
+1. Accept an `Idempotency-Key` header on non-idempotent endpoints (POST, PATCH). The client generates a unique key per logical operation.
+2. Before processing, check if the key has been seen. If yes, return the stored response.
+3. Process the request and store the response keyed by the idempotency key.
+4. Set a TTL on stored responses (24-48 hours). After expiry, the key can be reused.
+5. Handle concurrent requests with the same key — use a lock to prevent double processing.
+6. For message queues, use a message deduplication store keyed by message ID.
+
+```typescript
+// middleware/idempotency.ts
+interface StoredResponse {
+  statusCode: number;
+  body: unknown;
+  headers: Record<string, string>;
+  createdAt: number;
+}
+
+export class IdempotencyStore {
+  constructor(
+    private redis: Redis,
+    private ttlSeconds: number = 86400 // 24 hours
+  ) {}
+
+  async check(key: string): Promise<StoredResponse | null> {
+    const data = await this.redis.get(`idem:${key}`);
+    return data ? JSON.parse(data) : null;
+  }
+
+  async lock(key: string): Promise<boolean> {
+    // Set NX — only succeeds if key does not exist
+    const result = await this.redis.set(`idem:lock:${key}`, '1', 'EX', 60, 'NX');
+    return result === 'OK';
+  }
+
+  async store(key: string, response: StoredResponse): Promise<void> {
+    await this.redis.setex(`idem:${key}`, this.ttlSeconds, JSON.stringify(response));
+    await this.redis.del(`idem:lock:${key}`);
+  }
+
+  async unlock(key: string): Promise<void> {
+    await this.redis.del(`idem:lock:${key}`);
+  }
+}
+
+// Express middleware
+export function idempotencyMiddleware(store: IdempotencyStore) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const key = req.headers['idempotency-key'] as string;
+    if (!key) return next(); // No key = no idempotency protection
+
+    // Check for cached response
+    const cached = await store.check(key);
+    if (cached) {
+      Object.entries(cached.headers).forEach(([k, v]) => res.setHeader(k, v));
+      return res.status(cached.statusCode).json(cached.body);
+    }
+
+    // Acquire lock to prevent concurrent processing
+    const locked = await store.lock(key);
+    if (!locked) {
+      return res.status(409).json({ error: 'Request is being processed' });
+    }
+
+    // Intercept the response to store it
+    const originalJson = res.json.bind(res);
+    res.json = (body: unknown) => {
+      store.store(key, {
+        statusCode: res.statusCode,
+        body,
+        headers: { 'content-type': 'application/json' },
+        createdAt: Date.now(),
+      });
+      return originalJson(body);
+    };
+
+    next();
+  };
+}
+```
+
+```typescript
+// Client-side usage
+const idempotencyKey = crypto.randomUUID();
+
+const response = await fetch('/api/payments', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Idempotency-Key': idempotencyKey,
+  },
+  body: JSON.stringify({ amount: 1000, currency: 'usd' }),
+});
+
+// Safe to retry with the same key — will get the same response
+```
+
+## Details
+
+**Naturally idempotent operations:** GET, PUT, DELETE are idempotent by HTTP semantics. `PUT /users/123 { name: "Alice" }` always produces the same result. POST is not naturally idempotent — creating a resource twice creates two resources.
+
+**Database-level idempotency:** Use unique constraints and upserts:
+
+```sql
+-- Instead of INSERT (which fails on duplicate)
+INSERT INTO orders (idempotency_key, user_id, amount)
+VALUES ($1, $2, $3)
+ON CONFLICT (idempotency_key) DO NOTHING
+RETURNING *;
+```
+
+**Message deduplication:**
+
+```typescript
+async function processMessage(message: QueueMessage): Promise<void> {
+  const messageId = message.id;
+  const processed = await redis.set(`msg:${messageId}`, '1', 'EX', 3600, 'NX');
+  if (!processed) {
+    console.log(`Duplicate message ${messageId}, skipping`);
+    return;
+  }
+  await handleMessage(message.body);
+}
+```
+
+**Key generation strategies:**
+
+- Client-generated UUID (most common for APIs)
+- Hash of request body (deterministic but risks collision if body legitimately repeats)
+- Composite key (userId + operation + timestamp rounded to minute)
+
+**Edge cases:**
+
+- Request succeeds but response is lost (client retries, gets cached success response — correct)
+- Request fails (do not cache the error — let the client retry with the same key)
+- Concurrent requests with the same key (lock prevents double processing)
+
+## Source
+
+https://stripe.com/docs/api/idempotent_requests
+
+## 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.

package/dist/agents/skills/cursor/resilience-idempotency/skill.yaml

@@ -0,0 +1,38 @@
+name: resilience-idempotency
+version: '1.0.0'
+description: Ensure safe retries with idempotency keys and at-least-once delivery guarantees
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/services/**'
+  - '**/api/**'
+  - '**/middleware/**'
+related_skills:
+  - resilience-retry-pattern
+  - resilience-dead-letter
+  - resilience-circuit-breaker
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - idempotency
+  - idempotency-key
+  - at-least-once
+  - exactly-once
+  - deduplication
+metadata:
+  author: community
+  upstream: 'stripe/docs/idempotent-requests'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/resilience-rate-limiting/SKILL.md

@@ -0,0 +1,171 @@
+# Rate Limiting
+
+> Control request throughput with token bucket, sliding window, and fixed window algorithms to protect services from overload
+
+## When to Use
+
+- Protecting APIs from abuse, scraping, or accidental overload
+- Enforcing usage quotas per user, API key, or IP address
+- Preventing downstream services from being overwhelmed
+- Implementing tiered access (free tier: 100 req/min, pro tier: 1000 req/min)
+
+## Instructions
+
+1. Choose an algorithm: token bucket for burst-friendly limits, sliding window for smooth enforcement, fixed window for simplicity.
+2. Identify the rate limit key: IP address, user ID, API key, or combination.
+3. Return HTTP 429 (Too Many Requests) with `Retry-After` header when the limit is exceeded.
+4. Include rate limit headers in all responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+5. Use Redis for distributed rate limiting across multiple server instances.
+6. Apply different limits to different endpoints — authentication endpoints get stricter limits.
+
+```typescript
+// middleware/rate-limiter.ts — sliding window with Redis
+import { Redis } from 'ioredis';
+
+interface RateLimitConfig {
+  windowMs: number; // Window size in milliseconds
+  maxRequests: number; // Max requests per window
+  keyPrefix: string;
+}
+
+interface RateLimitResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number; // Unix timestamp (seconds)
+  retryAfter?: number; // Seconds until next allowed request
+}
+
+export class SlidingWindowRateLimiter {
+  constructor(
+    private redis: Redis,
+    private config: RateLimitConfig
+  ) {}
+
+  async check(key: string): Promise<RateLimitResult> {
+    const now = Date.now();
+    const windowStart = now - this.config.windowMs;
+    const redisKey = `${this.config.keyPrefix}:${key}`;
+
+    const pipeline = this.redis.pipeline();
+    pipeline.zremrangebyscore(redisKey, 0, windowStart); // Remove expired entries
+    pipeline.zadd(redisKey, now.toString(), `${now}:${Math.random()}`); // Add current request
+    pipeline.zcard(redisKey); // Count requests in window
+    pipeline.pexpire(redisKey, this.config.windowMs); // Set TTL
+
+    const results = await pipeline.exec();
+    const count = results![2][1] as number;
+
+    const allowed = count <= this.config.maxRequests;
+    const resetAt = Math.ceil((now + this.config.windowMs) / 1000);
+
+    if (!allowed) {
+      // Remove the request we just added since it's denied
+      await this.redis.zrem(redisKey, `${now}:${Math.random()}`);
+    }
+
+    return {
+      allowed,
+      limit: this.config.maxRequests,
+      remaining: Math.max(0, this.config.maxRequests - count),
+      resetAt,
+      retryAfter: allowed ? undefined : Math.ceil(this.config.windowMs / 1000),
+    };
+  }
+}
+```
+
+```typescript
+// Express middleware
+import { Request, Response, NextFunction } from 'express';
+
+const apiLimiter = new SlidingWindowRateLimiter(redis, {
+  windowMs: 60_000, // 1 minute
+  maxRequests: 100,
+  keyPrefix: 'rl:api',
+});
+
+export async function rateLimitMiddleware(req: Request, res: Response, next: NextFunction) {
+  const key = (req.headers['x-api-key'] as string) || req.ip;
+  const result = await apiLimiter.check(key);
+
+  res.setHeader('X-RateLimit-Limit', result.limit);
+  res.setHeader('X-RateLimit-Remaining', result.remaining);
+  res.setHeader('X-RateLimit-Reset', result.resetAt);
+
+  if (!result.allowed) {
+    res.setHeader('Retry-After', result.retryAfter!);
+    return res.status(429).json({ error: 'Too many requests' });
+  }
+
+  next();
+}
+```
+
+## Details
+
+**Algorithm comparison:**
+
+| Algorithm              | Burst handling              | Memory | Accuracy |
+| ---------------------- | --------------------------- | ------ | -------- |
+| Fixed window           | Allows 2x burst at boundary | Low    | Low      |
+| Sliding window log     | No burst                    | High   | High     |
+| Sliding window counter | Small burst                 | Medium | Medium   |
+| Token bucket           | Configurable burst          | Low    | High     |
+
+**Token bucket** (alternative implementation):
+
+```typescript
+class TokenBucket {
+  private tokens: number;
+  private lastRefill: number;
+
+  constructor(
+    private capacity: number,
+    private refillRate: number
+  ) {
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+  }
+
+  consume(count = 1): boolean {
+    this.refill();
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return true;
+    }
+    return false;
+  }
+
+  private refill() {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+    this.lastRefill = now;
+  }
+}
+```
+
+**Libraries:** `rate-limiter-flexible` (Redis/in-memory, multiple algorithms), `express-rate-limit` (simple Express middleware), `bottleneck` (client-side rate limiting for API calls).
+
+**Distributed considerations:** In-memory rate limiters only work for single-instance deployments. For multi-instance deployments, use Redis-backed rate limiting. The Lua script approach in Redis ensures atomicity.
+
+## Source
+
+https://cloud.google.com/architecture/rate-limiting-strategies-techniques
+
+## 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.

package/dist/agents/skills/cursor/resilience-rate-limiting/skill.yaml

@@ -0,0 +1,38 @@
+name: resilience-rate-limiting
+version: '1.0.0'
+description: Control request throughput with rate limiting using token bucket and sliding window algorithms
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/middleware/**'
+  - '**/api/**'
+  - '**/routes/**'
+related_skills:
+  - resilience-bulkhead-pattern
+  - resilience-circuit-breaker
+  - resilience-retry-pattern
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - rate-limiting
+  - token-bucket
+  - sliding-window
+  - throttle
+  - "429"
+metadata:
+  author: community
+  upstream: 'cloudflare/docs/rate-limiting'
+state:
+  persistent: false
+  files: []
+depends_on: []