@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/resilience-retry-pattern/SKILL.md

@@ -0,0 +1,137 @@
+# Retry Pattern
+
+> Handle transient failures with configurable retry strategies, exponential backoff, and jitter
+
+## When to Use
+
+- Network requests failing due to transient errors (timeouts, 503s, connection resets)
+- Database connections dropping briefly during failovers
+- Rate-limited APIs that succeed on subsequent attempts
+- Any operation that can fail temporarily but succeeds on retry
+
+## Instructions
+
+1. Retry only transient failures. Non-transient errors (400 Bad Request, 404 Not Found, validation errors) should not be retried.
+2. Use exponential backoff: `delay = baseDelay * 2^attempt`. This prevents thundering herd.
+3. Add jitter (randomness) to backoff: `delay = baseDelay * 2^attempt * (0.5 + random())`. This spreads retry storms.
+4. Set a maximum retry count (typically 3-5) and a maximum total delay (e.g., 30 seconds).
+5. Make the operation idempotent before adding retries. Retrying a non-idempotent operation (like creating a resource) can cause duplicates.
+6. Log each retry attempt with the error reason for debugging.
+7. Combine with circuit breaker — retries handle transient blips; circuit breaker handles sustained failures.
+
+```typescript
+// utils/retry.ts
+interface RetryOptions {
+  maxAttempts: number;
+  baseDelay: number;
+  maxDelay: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  onRetry?: (error: unknown, attempt: number, delay: number) => void;
+}
+
+const DEFAULT_OPTIONS: RetryOptions = {
+  maxAttempts: 3,
+  baseDelay: 1000,
+  maxDelay: 30000,
+  shouldRetry: () => true,
+};
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: Partial<RetryOptions> = {}
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === opts.maxAttempts - 1) break;
+      if (!opts.shouldRetry!(error, attempt)) break;
+
+      // Exponential backoff with full jitter
+      const exponentialDelay = opts.baseDelay * Math.pow(2, attempt);
+      const jitter = Math.random();
+      const delay = Math.min(exponentialDelay * jitter, opts.maxDelay);
+
+      opts.onRetry?.(error, attempt + 1, delay);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+```
+
+```typescript
+// Usage
+import { withRetry } from './utils/retry';
+
+const user = await withRetry(
+  () =>
+    fetch('/api/users/123').then((r) => {
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      return r.json();
+    }),
+  {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    shouldRetry: (error) => {
+      if (error instanceof Error && error.message.includes('HTTP 4')) return false;
+      return true; // Retry 5xx and network errors
+    },
+    onRetry: (error, attempt, delay) => {
+      console.warn(`Retry ${attempt} after ${delay}ms: ${error}`);
+    },
+  }
+);
+```
+
+## Details
+
+**Backoff strategies:**
+
+- **Fixed delay:** Same delay every time. Simple but causes retry storms.
+- **Linear backoff:** `delay = baseDelay * attempt`. Gentle ramp-up.
+- **Exponential backoff:** `delay = baseDelay * 2^attempt`. Standard for APIs.
+- **Exponential with jitter:** Adds randomness to exponential. Best practice — prevents correlated retries.
+
+**Jitter types:**
+
+- **Full jitter:** `random(0, baseDelay * 2^attempt)` — most spread, lowest contention
+- **Equal jitter:** `baseDelay * 2^attempt / 2 + random(0, baseDelay * 2^attempt / 2)` — guaranteed minimum wait
+- **Decorrelated jitter:** `min(maxDelay, random(baseDelay, prevDelay * 3))` — Amazon recommendation
+
+**Retry-After header:** Some APIs return `Retry-After` with 429 or 503 responses. Always respect this header over your calculated backoff.
+
+**What NOT to retry:**
+
+- 400 Bad Request (client error — retrying will not fix it)
+- 401/403 Unauthorized/Forbidden (auth issue — retry with same credentials will fail)
+- 409 Conflict (state issue — needs resolution, not retry)
+- 422 Unprocessable Entity (validation — fix the payload)
+
+**Libraries:** `p-retry`, `async-retry`, `cockatiel` (composable policies), `axios-retry`.
+
+## Source
+
+https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+
+## 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/codex/resilience-retry-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: resilience-retry-pattern
+version: '1.0.0'
+description: Handle transient failures with configurable retry strategies and backoff
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/services/**'
+  - '**/clients/**'
+  - '**/http/**'
+  - '**/api/**'
+related_skills:
+  - resilience-circuit-breaker
+  - resilience-timeout-pattern
+  - resilience-fallback-pattern
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - retry
+  - backoff
+  - exponential-backoff
+  - jitter
+  - transient-failure
+metadata:
+  author: community
+  upstream: 'aws/architecture/exponential-backoff'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/resilience-timeout-pattern/SKILL.md

@@ -0,0 +1,148 @@
+# Timeout Pattern
+
+> Prevent resource exhaustion and hung requests with timeouts, AbortController, and deadline propagation
+
+## When to Use
+
+- HTTP requests that could hang indefinitely due to network issues
+- Database queries that could run longer than acceptable
+- Any async operation that should not block forever
+- Enforcing SLA response times across service boundaries
+
+## Instructions
+
+1. Set timeouts on every external call. Never rely on the default (which is often infinity).
+2. Use `AbortController` with `AbortSignal.timeout()` for fetch requests.
+3. Set connection timeouts AND request timeouts separately — connection timeout is for establishing the connection; request timeout is for receiving the response.
+4. Propagate deadlines across service boundaries — if service A has 5s remaining, service B should get less than 5s.
+5. Clean up resources (connections, streams, file handles) when a timeout fires.
+6. Return a meaningful error on timeout so callers can retry or fall back.
+
+```typescript
+// utils/timeout.ts
+export async function withTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+  errorMessage = 'Operation timed out'
+): Promise<T> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const result = await fn(controller.signal);
+    return result;
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new TimeoutError(errorMessage, timeoutMs);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export class TimeoutError extends Error {
+  constructor(
+    message: string,
+    public readonly timeoutMs: number
+  ) {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+```
+
+```typescript
+// Usage with fetch
+import { withTimeout } from './utils/timeout';
+
+const user = await withTimeout(
+  (signal) => fetch('/api/users/123', { signal }).then((r) => r.json()),
+  5000,
+  'User fetch timed out'
+);
+
+// Node.js built-in (Node 18+)
+const response = await fetch('/api/data', {
+  signal: AbortSignal.timeout(5000),
+});
+```
+
+```typescript
+// Deadline propagation across services
+async function handleRequest(req: Request) {
+  const deadline = Date.now() + 10000; // 10s total budget
+
+  const user = await withTimeout(
+    (signal) => userService.getUser(req.userId, signal),
+    3000 // 3s budget for user service
+  );
+
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new TimeoutError('Request deadline exceeded', 10000);
+
+  const orders = await withTimeout(
+    (signal) => orderService.getOrders(user.id, signal),
+    Math.min(remaining, 5000) // Remaining budget, capped at 5s
+  );
+
+  return { user, orders };
+}
+```
+
+## Details
+
+**AbortController in Node.js:** Supported natively since Node 16. `AbortSignal.timeout(ms)` is available since Node 18 — it creates a signal that automatically aborts after the specified time.
+
+**Timeout layering:** Set timeouts at multiple levels:
+
+- **HTTP client level:** `fetch` signal, Axios timeout config
+- **Service call level:** `withTimeout` wrapper
+- **Route handler level:** Express/Fastify request timeout
+- **Load balancer level:** Nginx/ALB timeout
+
+**Common timeout values:**
+
+- Internal microservice calls: 1-5 seconds
+- External API calls: 5-15 seconds
+- Database queries: 5-30 seconds
+- File uploads/downloads: 60-300 seconds
+- Background jobs: application-specific
+
+**Database timeouts:**
+
+```typescript
+// PostgreSQL via node-postgres
+const pool = new Pool({
+  connectionTimeoutMillis: 5000, // Wait for connection
+  query_timeout: 10000, // Query execution limit
+  statement_timeout: 10000, // Server-side timeout
+});
+```
+
+**Anti-patterns:**
+
+- No timeout at all (requests hang forever during outages)
+- Timeout too short (causes false failures under normal load)
+- Not cleaning up after timeout (leaks connections)
+- Not propagating the abort signal to child operations
+
+## Source
+
+https://nodejs.org/api/globals.html#class-abortcontroller
+
+## 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/codex/resilience-timeout-pattern/skill.yaml

@@ -0,0 +1,38 @@
+name: resilience-timeout-pattern
+version: '1.0.0'
+description: Prevent resource exhaustion with request timeouts and AbortController
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/services/**'
+  - '**/clients/**'
+  - '**/http/**'
+related_skills:
+  - resilience-retry-pattern
+  - resilience-circuit-breaker
+  - resilience-fallback-pattern
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - timeout
+  - AbortController
+  - deadline
+  - cancellation
+  - resource-exhaustion
+metadata:
+  author: community
+  upstream: 'nodejs/docs/abort-controller'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/state-context-pattern/SKILL.md

@@ -0,0 +1,143 @@
+# React Context Pattern
+
+> Manage shared state with React Context and useReducer for prop-drilling avoidance and scoped state
+
+## When to Use
+
+- Sharing state across a component subtree without passing props through intermediate components
+- Theme, locale, auth, or feature flag state that many components read but rarely changes
+- Scoped state that should reset when a part of the tree unmounts
+- Small applications where adding Zustand/Jotai/Redux is unnecessary overhead
+
+## Instructions
+
+1. Create a context with `createContext`. Provide a meaningful default or `null` with a type assertion.
+2. Create a Provider component that encapsulates state logic (useState or useReducer) and passes values via `value`.
+3. Create a custom hook (`useAuth`, `useTheme`) that calls `useContext` and throws if used outside the Provider.
+4. Split context into two: one for state, one for dispatch/actions. This prevents components that only dispatch from re-rendering on state changes.
+5. Memoize the context value with `useMemo` to prevent unnecessary re-renders of consumers.
+6. Keep context values small and stable — large objects that change frequently cause all consumers to re-render.
+
+```typescript
+// contexts/auth-context.tsx
+import { createContext, useContext, useReducer, useMemo, ReactNode } from 'react';
+
+interface User { id: string; name: string; }
+
+interface AuthState {
+  user: User | null;
+  isAuthenticated: boolean;
+}
+
+type AuthAction =
+  | { type: 'LOGIN'; user: User }
+  | { type: 'LOGOUT' };
+
+type AuthDispatch = (action: AuthAction) => void;
+
+const AuthStateContext = createContext<AuthState | null>(null);
+const AuthDispatchContext = createContext<AuthDispatch | null>(null);
+
+function authReducer(state: AuthState, action: AuthAction): AuthState {
+  switch (action.type) {
+    case 'LOGIN':
+      return { user: action.user, isAuthenticated: true };
+    case 'LOGOUT':
+      return { user: null, isAuthenticated: false };
+    default:
+      return state;
+  }
+}
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(authReducer, {
+    user: null,
+    isAuthenticated: false,
+  });
+
+  // Memoize to prevent re-renders when AuthProvider's parent re-renders
+  const stateValue = useMemo(() => state, [state]);
+
+  return (
+    <AuthStateContext.Provider value={stateValue}>
+      <AuthDispatchContext.Provider value={dispatch}>
+        {children}
+      </AuthDispatchContext.Provider>
+    </AuthStateContext.Provider>
+  );
+}
+
+export function useAuthState(): AuthState {
+  const context = useContext(AuthStateContext);
+  if (!context) throw new Error('useAuthState must be used within AuthProvider');
+  return context;
+}
+
+export function useAuthDispatch(): AuthDispatch {
+  const context = useContext(AuthDispatchContext);
+  if (!context) throw new Error('useAuthDispatch must be used within AuthProvider');
+  return context;
+}
+```
+
+```typescript
+// Usage
+function LoginButton() {
+  const dispatch = useAuthDispatch(); // Does NOT re-render when auth state changes
+  return <button onClick={() => dispatch({ type: 'LOGIN', user: { id: '1', name: 'Alice' } })}>Login</button>;
+}
+
+function UserBadge() {
+  const { user } = useAuthState(); // Re-renders when auth state changes
+  return user ? <span>{user.name}</span> : null;
+}
+```
+
+## Details
+
+**Why split state and dispatch contexts:** When the context value is `{ state, dispatch }`, every consumer re-renders when state changes — even components that only call dispatch. Separate contexts solve this.
+
+**Context vs external state libraries:**
+
+- Context re-renders ALL consumers when the value changes — no selector mechanism
+- Context is scoped to a subtree — external stores are global
+- Context requires no extra dependencies — it is built into React
+- Context is best for low-frequency updates (auth, theme). For high-frequency updates (forms, animations), use Zustand or Jotai
+
+**useReducer vs useState:** Use `useReducer` when state has multiple sub-values, when the next state depends on the previous state, or when you want to decouple state logic from the Provider component.
+
+**Performance optimization:** For large subtrees, wrap children in `React.memo` or use the split-context pattern. For truly high-performance needs, switch to an external store.
+
+**Testing:**
+
+```typescript
+function renderWithAuth(ui: ReactNode, initialState?: Partial<AuthState>) {
+  return render(<AuthProvider>{ui}</AuthProvider>);
+}
+```
+
+**Common mistakes:**
+
+- Putting too much in context (entire app state) — this defeats React's component-level rendering model
+- Creating context with an empty object default (`createContext({})`) — hides bugs where the provider is missing
+- Not memoizing the context value — a new object on every render causes all consumers to re-render
+
+## Source
+
+https://react.dev/learn/passing-data-deeply-with-context
+
+## 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/codex/state-context-pattern/skill.yaml

@@ -0,0 +1,38 @@
+name: state-context-pattern
+version: '1.0.0'
+description: Manage shared state with React Context and useReducer for prop-drilling avoidance
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/context/**'
+  - '**/contexts/**'
+  - '**/providers/**'
+related_skills:
+  - state-jotai-atoms
+  - state-zustand-store
+  - state-selection-patterns
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - context
+  - useContext
+  - useReducer
+  - provider
+  - prop-drilling
+metadata:
+  author: community
+  upstream: 'react/docs/context'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/state-jotai-atoms/SKILL.md

@@ -0,0 +1,153 @@
+# Jotai Atoms
+
+> Build bottom-up atomic state with Jotai for granular, composable React state management
+
+## When to Use
+
+- Managing state that is naturally composed of small independent pieces (form fields, toggles, filters)
+- Needing derived/computed state that automatically updates when dependencies change (like Recoil selectors)
+- Wanting React Context-like convenience without re-render performance problems
+- Building components that each need a small piece of global state without subscribing to everything
+
+## Instructions
+
+1. Create primitive atoms with `atom(initialValue)`. These are the smallest units of state.
+2. Create derived (read-only) atoms with `atom((get) => computation)`. They auto-update when dependencies change.
+3. Create writable derived atoms with `atom(readFn, writeFn)` for computed state with custom setters.
+4. Use `useAtom` in components — it returns `[value, setValue]` like `useState`.
+5. Use `useAtomValue` for read-only access and `useSetAtom` for write-only access to minimize subscriptions.
+6. Group related atoms in a file per domain (`atoms/auth.ts`, `atoms/cart.ts`).
+7. No Provider needed for basic usage — Jotai uses a default store. Add `<Provider>` only for scoped state or testing.
+
+```typescript
+// atoms/cart.ts
+import { atom } from 'jotai';
+
+interface CartItem {
+  id: string;
+  name: string;
+  price: number;
+  qty: number;
+}
+
+// Primitive atoms
+export const cartItemsAtom = atom<CartItem[]>([]);
+export const couponCodeAtom = atom<string | null>(null);
+
+// Derived atom (read-only) — auto-updates when cartItemsAtom changes
+export const cartTotalAtom = atom((get) => {
+  const items = get(cartItemsAtom);
+  return items.reduce((sum, item) => sum + item.price * item.qty, 0);
+});
+
+export const cartCountAtom = atom((get) => {
+  return get(cartItemsAtom).reduce((sum, item) => sum + item.qty, 0);
+});
+
+// Derived atom with discount applied
+export const discountedTotalAtom = atom((get) => {
+  const total = get(cartTotalAtom);
+  const coupon = get(couponCodeAtom);
+  return coupon ? total * 0.9 : total;
+});
+
+// Writable derived atom — custom setter
+export const addToCartAtom = atom(
+  null, // read value (null = write-only)
+  (get, set, newItem: Omit<CartItem, 'qty'>) => {
+    const items = get(cartItemsAtom);
+    const existing = items.find((i) => i.id === newItem.id);
+    if (existing) {
+      set(
+        cartItemsAtom,
+        items.map((i) => (i.id === newItem.id ? { ...i, qty: i.qty + 1 } : i))
+      );
+    } else {
+      set(cartItemsAtom, [...items, { ...newItem, qty: 1 }]);
+    }
+  }
+);
+```
+
+```typescript
+// Component usage
+import { useAtomValue, useSetAtom } from 'jotai';
+
+function CartSummary() {
+  const total = useAtomValue(discountedTotalAtom); // Read-only, re-renders only when total changes
+  const count = useAtomValue(cartCountAtom);
+  return <div>{count} items - ${total.toFixed(2)}</div>;
+}
+
+function AddButton({ product }: { product: { id: string; name: string; price: number } }) {
+  const addToCart = useSetAtom(addToCartAtom); // Write-only, never re-renders from this atom
+  return <button onClick={() => addToCart(product)}>Add to Cart</button>;
+}
+```
+
+## Details
+
+**Atom dependency graph:** Derived atoms automatically track which atoms they read via `get()`. When any dependency changes, the derived atom recomputes. This is reactive — no manual subscription management.
+
+**Async atoms:** Atoms can return promises. Jotai integrates with React Suspense:
+
+```typescript
+const userAtom = atom(async () => {
+  const res = await fetch('/api/user');
+  return res.json();
+});
+
+// Component suspends until data loads
+function User() {
+  const user = useAtomValue(userAtom); // Suspends, then returns data
+  return <div>{user.name}</div>;
+}
+```
+
+**atomWithStorage:** Persist atoms to localStorage:
+
+```typescript
+import { atomWithStorage } from 'jotai/utils';
+
+const themeAtom = atomWithStorage('theme', 'light');
+// Automatically reads from and writes to localStorage
+```
+
+**Jotai vs Zustand:** Jotai is bottom-up (compose small atoms into larger state). Zustand is top-down (define a store, select slices). Choose Jotai when state is naturally fragmented across many components. Choose Zustand when state is a cohesive domain object.
+
+**Jotai vs React Context:** Both are Provider-based. But Context re-renders all consumers when any value changes. Jotai only re-renders consumers of the specific atom that changed.
+
+**Testing:** Use `<Provider>` in tests to create isolated atom scopes:
+
+```typescript
+import { Provider, createStore } from 'jotai';
+
+const store = createStore();
+store.set(cartItemsAtom, mockItems);
+
+render(
+  <Provider store={store}>
+    <CartSummary />
+  </Provider>
+);
+```
+
+## Source
+
+https://jotai.org/docs/introduction
+
+## 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.