skillrepo 2.0.0 → 3.0.0

package/src/lib/errors.mjs

@@ -0,0 +1,264 @@
+/**
+ * SkillRepo CLI exit codes, error types, and retry helper.
+ *
+ * Exit code matrix:
+ *
+ *   0 — success
+ *   1 — network / transient error (cannot reach server, DNS failure, etc.)
+ *   2 — auth error (invalid key, revoked, suspended account)
+ *   3 — disk error (cannot read or write a file/directory)
+ *   4 — scope error (key lacks the required scope for the requested action)
+ *   5 — validation error (bad CLI input — invalid flag, malformed identifier, etc.)
+ *
+ * These mirror the documented behavior in #683 and are the contract
+ * shell users and CI scripts can rely on.
+ *
+ * Retry policy (PR4, #683):
+ *
+ *   `withRetry(fn, options)` wraps a fetch-style operation and retries
+ *   transient failures — specifically 429, 502, 503, 504 responses
+ *   and raw networkErrors (DNS, TCP reset, timeout). 4xx auth/validation
+ *   errors (401, 403, 404, 405, 409, 422, ...) are NOT retried — they
+ *   will never succeed on a second attempt.
+ *
+ *   Backoff: exponential with full jitter. Attempt N sleeps in
+ *   [0, baseDelayMs * 2^(N-1)]. Default 3 attempts total with a base
+ *   delay of 500ms and a cap of 8000ms per sleep. Deterministic in
+ *   tests via the injected `sleepFn` and `randomFn`.
+ *
+ *   The retry layer is OFF by default on `safeFetch` — it's opt-in
+ *   per-call via `{ retry: true }` because some endpoints (e.g. the
+ *   idempotent add post-fetch) require the exact single-shot semantics
+ *   the tests were written against. Commands that naturally benefit
+ *   from retries (update, get, list, search) opt in by passing the
+ *   flag.
+ */
+
+export const EXIT_OK = 0;
+export const EXIT_NETWORK = 1;
+export const EXIT_AUTH = 2;
+export const EXIT_DISK = 3;
+export const EXIT_SCOPE = 4;
+export const EXIT_VALIDATION = 5;
+
+/**
+ * Base error class for typed CLI errors. Carries an exit code and
+ * optional cause/hint fields. Retry behavior is determined by
+ * `isRetryable()` inspecting the `exitCode` (EXIT_NETWORK is the
+ * only retryable class), not by subclass identity.
+ */
+export class CliError extends Error {
+  /**
+   * @param {string} message - User-facing error message.
+   * @param {number} exitCode - One of the EXIT_* constants.
+   * @param {object} [options]
+   * @param {Error} [options.cause] - Underlying cause (for --verbose).
+   * @param {string} [options.hint] - Optional next-step hint shown after the message.
+   */
+  constructor(message, exitCode, { cause, hint } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    if (cause !== undefined) this.cause = cause;
+    if (hint !== undefined) this.hint = hint;
+  }
+}
+
+/**
+ * Convenience constructors for each exit code class. Commands import
+ * these directly so call sites read like `throw networkError("...")`
+ * rather than `throw new CliError("...", EXIT_NETWORK)`.
+ */
+export function networkError(message, options) {
+  return new CliError(message, EXIT_NETWORK, options);
+}
+
+export function authError(message, options) {
+  return new CliError(message, EXIT_AUTH, options);
+}
+
+export function diskError(message, options) {
+  return new CliError(message, EXIT_DISK, options);
+}
+
+export function scopeError(message, options) {
+  return new CliError(message, EXIT_SCOPE, options);
+}
+
+export function validationError(message, options) {
+  return new CliError(message, EXIT_VALIDATION, options);
+}
+
+// ── Retry helper ───────────────────────────────────────────────────────
+
+/**
+ * HTTP status codes that are considered transient. A response with
+ * one of these statuses will be retried by `withRetry` when the
+ * caller returns a structured `{ transient: true, statusCode }`
+ * signal. 502/503/504 are bad gateway / service unavailable /
+ * gateway timeout — nearly always transient. 429 is rate-limiting;
+ * retrying with backoff respects the documented behavior of the
+ * v1 API.
+ *
+ * 500 is NOT in this set: "internal server error" is a catch-all
+ * that typically represents a real bug, not a transient condition.
+ * Retrying masks issues that should surface loudly.
+ */
+export const TRANSIENT_STATUS_CODES = new Set([429, 502, 503, 504]);
+
+/**
+ * Default backoff parameters. Exponential with full jitter.
+ * Attempt 1 fires immediately; attempt 2 sleeps in [0, 500ms);
+ * attempt 3 sleeps in [0, 1000ms). Capped at 8 seconds regardless
+ * of attempt number so pathological configurations don't stall
+ * the CLI for a minute.
+ */
+export const DEFAULT_RETRY_ATTEMPTS = 3;
+export const DEFAULT_RETRY_BASE_MS = 500;
+export const DEFAULT_RETRY_CAP_MS = 8000;
+
+/**
+ * Decide whether a thrown error or a returned response is worth
+ * retrying.
+ *
+ * Retryable:
+ *   - A `CliError` with `exitCode === EXIT_NETWORK` (networkError,
+ *     which wraps fetch failures and timeouts)
+ *   - A `Response`-shaped object whose `status` is in
+ *     `TRANSIENT_STATUS_CODES`
+ *
+ * NOT retryable:
+ *   - Any CliError with a different exit code — auth, scope,
+ *     validation, disk errors never succeed on retry
+ *   - Any non-transient response status (the caller's normal
+ *     error-mapping path handles these)
+ *
+ * This is exported so tests can assert the contract directly, and
+ * so higher-level callers (e.g. commands that wrap multiple fetches
+ * in one retry scope) can share the predicate.
+ */
+export function isRetryable(value) {
+  if (value instanceof CliError) {
+    return value.exitCode === EXIT_NETWORK;
+  }
+  if (value && typeof value === "object" && typeof value.status === "number") {
+    return TRANSIENT_STATUS_CODES.has(value.status);
+  }
+  return false;
+}
+
+/**
+ * Compute the sleep duration before attempt N (1-indexed). Uses
+ * full-jitter exponential backoff:
+ *
+ *   delay = random() * min(cap, base * 2^(attempt - 2))
+ *
+ * Attempt 1 always returns 0 (fire immediately — no sleep before
+ * the first call). Attempt 2 samples in [0, base). Attempt 3
+ * samples in [0, base*2). Attempt 4 samples in [0, base*4). Any
+ * attempt whose window exceeds `capMs` is clamped to `capMs`.
+ *
+ * `randomFn` is injectable so tests can make the backoff
+ * deterministic (pass `() => 0.999999` for the worst case,
+ * `() => 0` for the best case).
+ */
+export function computeBackoffDelay(attempt, options = {}) {
+  const {
+    baseMs = DEFAULT_RETRY_BASE_MS,
+    capMs = DEFAULT_RETRY_CAP_MS,
+    randomFn = Math.random,
+  } = options;
+  if (attempt <= 1) return 0;
+  const window = Math.min(capMs, baseMs * Math.pow(2, attempt - 2));
+  return Math.floor(randomFn() * window);
+}
+
+/**
+ * Retry a function on transient failures. The function must either
+ * return a value (success) or throw / return a retryable signal
+ * (see `isRetryable`).
+ *
+ * Two retry triggers are supported:
+ *
+ *   1. `fn()` throws a networkError-class CliError → caught and
+ *      retried. Any other thrown error propagates immediately.
+ *
+ *   2. `fn()` returns a `Response`-shaped object with a transient
+ *      status. The caller is expected to return the response from
+ *      its first `res.ok === false && TRANSIENT_STATUS_CODES.has(res.status)`
+ *      branch and withRetry will re-invoke `fn` up to the attempt
+ *      cap. On exhaustion, withRetry returns that last response so
+ *      the caller can map it to a typed CliError via its normal
+ *      mapErrorResponse path.
+ *
+ * This two-mode design lets `safeFetch` leave the status-to-CliError
+ * mapping in `mapErrorResponse` (where every endpoint uses it) while
+ * still participating in retry. The alternative — throwing a
+ * specially-typed error from safeFetch on 429 and catching it — would
+ * require every endpoint to special-case retry-exhausted errors
+ * instead of letting the existing error mapper do its job.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn - The async operation to retry
+ * @param {object} [options]
+ * @param {number} [options.attempts=3] - Total attempts (1 + retries)
+ * @param {number} [options.baseMs=500]
+ * @param {number} [options.capMs=8000]
+ * @param {(ms: number) => Promise<void>} [options.sleepFn] - Injectable for tests
+ * @param {() => number} [options.randomFn] - Injectable jitter source
+ * @param {(info: {attempt: number, delayMs: number, cause: unknown}) => void} [options.onRetry]
+ *        Optional callback fired BEFORE each retry — used by tests and
+ *        by --verbose mode to surface retry activity.
+ * @returns {Promise<T>}
+ */
+export async function withRetry(fn, options = {}) {
+  const {
+    attempts = DEFAULT_RETRY_ATTEMPTS,
+    baseMs = DEFAULT_RETRY_BASE_MS,
+    capMs = DEFAULT_RETRY_CAP_MS,
+    sleepFn = defaultSleep,
+    randomFn = Math.random,
+    onRetry,
+  } = options;
+
+  if (!Number.isInteger(attempts) || attempts < 1) {
+    throw validationError(`withRetry: attempts must be a positive integer, got ${attempts}`);
+  }
+
+  let lastValue;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const result = await fn();
+      // Response-shaped transient: retry if we have attempts left,
+      // otherwise return the last response so the caller maps it.
+      if (isRetryable(result)) {
+        lastValue = result;
+        if (attempt < attempts) {
+          const delay = computeBackoffDelay(attempt + 1, { baseMs, capMs, randomFn });
+          onRetry?.({ attempt, delayMs: delay, cause: result });
+          await sleepFn(delay);
+          continue;
+        }
+        return result;
+      }
+      return result;
+    } catch (err) {
+      if (!isRetryable(err)) throw err;
+      lastError = err;
+      if (attempt >= attempts) throw err;
+      const delay = computeBackoffDelay(attempt + 1, { baseMs, capMs, randomFn });
+      onRetry?.({ attempt, delayMs: delay, cause: err });
+      await sleepFn(delay);
+    }
+  }
+
+  // Unreachable — the loop either returns or throws. Defensive:
+  if (lastError) throw lastError;
+  return lastValue;
+}
+
+function defaultSleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}