skillrepo 2.0.0 → 3.1.0

package/src/lib/config.mjs

@@ -0,0 +1,238 @@
+/**
+ * Global skillrepo config reader/writer — ~/.claude/skillrepo/config.json
+ *
+ * Built for PR3b's `init` rewrite (#673). The config file is the
+ * single source of truth for credentials that every command resolves
+ * from when `--key`/`--url` are not provided. The existing
+ * `cli-config.mjs` helper already READS this file (via the
+ * `readGlobalConfig` helper inside `resolveFlags`); this module adds
+ * the WRITE side so `init` can persist credentials after a
+ * successful validation.
+ *
+ * Schema:
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "apiKey": "sk_live_...",
+ *     "serverUrl": "https://skillrepo.dev",
+ *     "accountSlug": "alice",
+ *     "accountId": "acc_...",
+ *     "userId": "user_...",
+ *     "writtenAt": "2026-04-15T00:00:00Z"
+ *   }
+ *
+ * Only `apiKey` and `serverUrl` are structurally required by the
+ * command layer (everything else is metadata for diagnostics). A
+ * missing field is treated as a corrupt-but-recoverable state — the
+ * reader returns null and the command layer falls back to env vars
+ * or prompts.
+ *
+ * File permissions: the config file contains a live access key.
+ * chmod 0600 on POSIX (owner read/write only). Skipped on Windows
+ * (where 0600 is a no-op anyway and chmod doesn't prevent
+ * Administrator reads).
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { platform } from "node:os";
+
+import { globalConfigPath } from "./paths.mjs";
+import { diskError, validationError } from "./errors.mjs";
+
+/**
+ * Current schema version. Bump this on any structural change.
+ * Readers treat unknown future versions as "ignore this file,
+ * do a full re-init" rather than crashing.
+ */
+export const CONFIG_SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} GlobalConfig
+ * @property {number} schemaVersion
+ * @property {string} apiKey
+ * @property {string} serverUrl
+ * @property {string} [accountSlug]
+ * @property {string} [accountId]
+ * @property {string} [userId]
+ * @property {string} [writtenAt]
+ */
+
+/**
+ * Read the global config file. Returns null if the file does not
+ * exist, is corrupt, or has an unrecognized schema version.
+ *
+ * Corrupt cases return null rather than throwing because the command
+ * layer has a well-defined fallback (env vars, interactive prompt)
+ * and we don't want a garbled config file to crash the CLI.
+ *
+ * @returns {GlobalConfig | null}
+ */
+export function readConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return null;
+
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+
+  // Reject unknown future schema versions. A null return here
+  // triggers the caller's prompt-for-new-config path — acceptable
+  // degradation for an old CLI reading a new-format file.
+  if (parsed.schemaVersion !== undefined && parsed.schemaVersion !== CONFIG_SCHEMA_VERSION) {
+    return null;
+  }
+
+  // Legacy fallback: the v2.0.0 CLI wrote config files WITHOUT a
+  // schemaVersion field. Accept those as schemaVersion 1 so the new
+  // CLI can transparently upgrade. The next writeConfig() call will
+  // add the explicit version field.
+  if (parsed.schemaVersion === undefined) {
+    parsed.schemaVersion = CONFIG_SCHEMA_VERSION;
+  }
+
+  // Required fields
+  if (typeof parsed.apiKey !== "string" || !parsed.apiKey) return null;
+  if (typeof parsed.serverUrl !== "string" || !parsed.serverUrl) return null;
+
+  return parsed;
+}
+
+/**
+ * Write the global config file atomically. Creates the parent
+ * directory if missing. Chmods the file to 0600 on POSIX.
+ *
+ * Throws `diskError` on any filesystem failure so the init command
+ * can surface a clean error with exit code 3.
+ *
+ * @param {Partial<GlobalConfig>} config - Caller-provided fields.
+ *        Required: apiKey, serverUrl. Optional: everything else.
+ * @returns {"created" | "updated"} Whether the file existed before.
+ */
+export function writeConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw validationError("writeConfig: config object is required");
+  }
+  if (typeof config.apiKey !== "string" || !config.apiKey) {
+    throw validationError("writeConfig: apiKey is required");
+  }
+  if (typeof config.serverUrl !== "string" || !config.serverUrl) {
+    throw validationError("writeConfig: serverUrl is required");
+  }
+
+  const path = globalConfigPath();
+  const existed = existsSync(path);
+  const dir = dirname(path);
+
+  // Ensure the parent dir exists — the dir itself holds other
+  // CLI state (.last-sync, maybe more in the future), so creating
+  // it is expected.
+  try {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  } catch (err) {
+    throw diskError(`Cannot create ${dir}: ${err.message}`, { cause: err });
+  }
+
+  // Build the persisted shape. Preserve unknown fields from the
+  // existing file if any — a future CLI version might add fields
+  // that this writer doesn't know about.
+  let existing = {};
+  if (existed) {
+    const current = readConfig();
+    if (current) existing = current;
+  }
+  const merged = {
+    ...existing,
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    apiKey: config.apiKey,
+    serverUrl: config.serverUrl,
+    writtenAt: new Date().toISOString(),
+  };
+  // Copy optional fields if provided
+  for (const key of ["accountSlug", "accountId", "userId"]) {
+    if (config[key] !== undefined) merged[key] = config[key];
+  }
+
+  // Atomic write via temp-file + rename. Matches the file-write.mjs
+  // pattern: the config file is never in a half-written state, so
+  // a crash mid-write can't leave it corrupted.
+  const tmpPath = `${path}.tmp`;
+  try {
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+  } catch (err) {
+    throw diskError(`Cannot write ${tmpPath}: ${err.message}`, { cause: err });
+  }
+
+  // chmod the temp file before renaming so the destination never
+  // exists with world-readable perms (which would be a brief
+  // credential leak window on a shared system).
+  if (platform() !== "win32") {
+    try {
+      chmodSync(tmpPath, 0o600);
+    } catch {
+      // Non-fatal — chmod failure doesn't corrupt the file, it just
+      // means permissions are looser than we'd like. We intentionally
+      // DON'T emit a warning here: the round-1 review caught that
+      // the warning used the tmp path (which doesn't exist after
+      // rename), and mixing stream output into a pure I/O helper
+      // leaks concerns across layers. Callers that care about
+      // permissions can stat the file themselves after the write.
+    }
+  }
+
+  try {
+    // renameSync on POSIX is atomic on the same filesystem
+    renameSync(tmpPath, path);
+  } catch (err) {
+    // Round-1 review fix: clean up the stale .tmp file on rename
+    // failure so a live access key isn't left behind on disk. The
+    // unlink is best-effort — if IT also fails, the original
+    // rename error is still the one we surface to the caller.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* best-effort */
+    }
+    throw diskError(`Cannot install ${path}: ${err.message}`, { cause: err });
+  }
+
+  return existed ? "updated" : "created";
+}
+
+/**
+ * Delete the global config file. Returns true if the file existed
+ * and was removed, false if it wasn't there. Used by tests and
+ * future `skillrepo logout` (not yet implemented).
+ */
+export function clearConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return false;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    throw diskError(`Cannot delete ${path}: ${err.message}`, { cause: err });
+  }
+}

package/src/lib/detect-ides.mjs

@@ -42,22 +42,3 @@ export function formatDetectedIdes(detected) {
     { name: "VS Code + Copilot", key: "vscode", detected: detected.vscode },
   ];
 }
-
-/**
- * Get the list of IDE keys that were detected.
- * If none detected, defaults to Claude Code + Cursor (most common pair).
- * @param {DetectedIdes} detected
- * @returns {string[]}
- */
-export function getDetectedIdeKeys(detected) {
-  const keys = Object.entries(detected)
-    .filter(([, v]) => v)
-    .map(([k]) => k);
-
-  // Default to Claude Code + Cursor if nothing detected
-  if (keys.length === 0) {
-    return ["claudeCode", "cursor"];
-  }
-
-  return keys;
-}

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));
+}