skillrepo 2.0.0 → 3.0.0

package/src/test/lib/config.test.mjs

@@ -0,0 +1,257 @@
+/**
+ * Unit tests for src/lib/config.mjs (PR3b of #646).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+  statSync,
+  chmodSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  readConfig,
+  writeConfig,
+  clearConfig,
+  CONFIG_SCHEMA_VERSION,
+} from "../../lib/config.mjs";
+import { globalConfigPath } from "../../lib/paths.mjs";
+import { CliError, EXIT_VALIDATION, EXIT_DISK } from "../../lib/errors.mjs";
+
+let sandbox;
+let originalHome;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-config-mjs-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalHome = process.env.HOME;
+  process.env.HOME = join(sandbox, "home");
+}
+
+function teardownSandbox() {
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ── readConfig ─────────────────────────────────────────────────────────
+
+describe("readConfig", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns null when the file does not exist", () => {
+    assert.equal(readConfig(), null);
+  });
+
+  it("reads a valid config file", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        schemaVersion: CONFIG_SCHEMA_VERSION,
+        apiKey: "sk_live_abc",
+        serverUrl: "https://example.com",
+        accountSlug: "alice",
+      }),
+    );
+    const result = readConfig();
+    assert.equal(result.apiKey, "sk_live_abc");
+    assert.equal(result.serverUrl, "https://example.com");
+    assert.equal(result.accountSlug, "alice");
+  });
+
+  it("accepts a legacy v2.0.0 config file with no schemaVersion", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        apiKey: "sk_live_abc",
+        serverUrl: "https://example.com",
+      }),
+    );
+    const result = readConfig();
+    assert.equal(result.apiKey, "sk_live_abc");
+    assert.equal(result.schemaVersion, CONFIG_SCHEMA_VERSION);
+  });
+
+  it("returns null on corrupt JSON", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, "not json {{{");
+    assert.equal(readConfig(), null);
+  });
+
+  it("returns null on unknown future schema version", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        schemaVersion: 999,
+        apiKey: "sk_live_abc",
+        serverUrl: "https://example.com",
+      }),
+    );
+    assert.equal(readConfig(), null);
+  });
+
+  it("returns null when apiKey is missing", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, JSON.stringify({ serverUrl: "https://example.com" }));
+    assert.equal(readConfig(), null);
+  });
+
+  it("returns null when serverUrl is missing", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, JSON.stringify({ apiKey: "sk_live_abc" }));
+    assert.equal(readConfig(), null);
+  });
+
+  it("returns null when file is an empty object", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, "{}");
+    assert.equal(readConfig(), null);
+  });
+
+  it("returns null when file is a JSON array (not object)", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, "[]");
+    assert.equal(readConfig(), null);
+  });
+});
+
+// ── writeConfig ────────────────────────────────────────────────────────
+
+describe("writeConfig", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("creates a new config file", () => {
+    const action = writeConfig({
+      apiKey: "sk_live_abc",
+      serverUrl: "https://example.com",
+      accountSlug: "alice",
+    });
+    assert.equal(action, "created");
+    const result = readConfig();
+    assert.equal(result.apiKey, "sk_live_abc");
+    assert.equal(result.accountSlug, "alice");
+    assert.equal(result.schemaVersion, CONFIG_SCHEMA_VERSION);
+    assert.ok(result.writtenAt); // timestamp present
+  });
+
+  it("updates an existing config file", () => {
+    writeConfig({ apiKey: "sk_live_old", serverUrl: "https://old.com" });
+    const action = writeConfig({
+      apiKey: "sk_live_new",
+      serverUrl: "https://new.com",
+    });
+    assert.equal(action, "updated");
+    const result = readConfig();
+    assert.equal(result.apiKey, "sk_live_new");
+    assert.equal(result.serverUrl, "https://new.com");
+  });
+
+  it("creates parent directory if missing", () => {
+    // sandbox HOME has no .claude/skillrepo/ yet
+    writeConfig({ apiKey: "sk_live_abc", serverUrl: "https://example.com" });
+    assert.ok(existsSync(globalConfigPath()));
+  });
+
+  it("preserves unknown fields from an existing config", () => {
+    const path = globalConfigPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        schemaVersion: CONFIG_SCHEMA_VERSION,
+        apiKey: "sk_live_old",
+        serverUrl: "https://old.com",
+        futureField: "preserve me",
+      }),
+    );
+    writeConfig({
+      apiKey: "sk_live_new",
+      serverUrl: "https://new.com",
+    });
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    assert.equal(raw.futureField, "preserve me");
+    assert.equal(raw.apiKey, "sk_live_new");
+  });
+
+  it("sets 0600 permissions on POSIX", { skip: process.platform === "win32" || process.getuid?.() === 0 }, () => {
+    writeConfig({ apiKey: "sk_live_abc", serverUrl: "https://example.com" });
+    const path = globalConfigPath();
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600, `Expected 0o600, got ${mode.toString(8)}`);
+  });
+
+  it("throws validationError on missing apiKey", () => {
+    assert.throws(
+      () => writeConfig({ serverUrl: "https://example.com" }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("throws validationError on missing serverUrl", () => {
+    assert.throws(
+      () => writeConfig({ apiKey: "sk_live_abc" }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("throws validationError on null config", () => {
+    assert.throws(
+      () => writeConfig(null),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("throws diskError when parent dir is read-only", { skip: process.platform === "win32" || process.getuid?.() === 0 }, () => {
+    // Create the grandparent dir and make the parent path non-writable
+    const grandParent = join(process.env.HOME, ".claude");
+    mkdirSync(grandParent, { recursive: true });
+    chmodSync(grandParent, 0o555);
+
+    try {
+      assert.throws(
+        () => writeConfig({ apiKey: "sk_live_abc", serverUrl: "https://example.com" }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_DISK,
+      );
+    } finally {
+      chmodSync(grandParent, 0o755);
+    }
+  });
+});
+
+// ── clearConfig ────────────────────────────────────────────────────────
+
+describe("clearConfig", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns false when no config exists", () => {
+    assert.equal(clearConfig(), false);
+  });
+
+  it("removes an existing config file", () => {
+    writeConfig({ apiKey: "sk_live_abc", serverUrl: "https://example.com" });
+    assert.ok(existsSync(globalConfigPath()));
+    assert.equal(clearConfig(), true);
+    assert.ok(!existsSync(globalConfigPath()));
+  });
+});

package/src/test/lib/errors.test.mjs

@@ -0,0 +1,359 @@
+/**
+ * Unit tests for src/lib/errors.mjs (PR1 of #646).
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  EXIT_OK,
+  EXIT_NETWORK,
+  EXIT_AUTH,
+  EXIT_DISK,
+  EXIT_SCOPE,
+  EXIT_VALIDATION,
+  CliError,
+  networkError,
+  authError,
+  diskError,
+  scopeError,
+  validationError,
+  isRetryable,
+  computeBackoffDelay,
+  withRetry,
+  TRANSIENT_STATUS_CODES,
+  DEFAULT_RETRY_ATTEMPTS,
+  DEFAULT_RETRY_BASE_MS,
+  DEFAULT_RETRY_CAP_MS,
+} from "../../lib/errors.mjs";
+
+describe("errors.mjs — exit code constants", () => {
+  it("exposes the documented exit code matrix", () => {
+    assert.equal(EXIT_OK, 0);
+    assert.equal(EXIT_NETWORK, 1);
+    assert.equal(EXIT_AUTH, 2);
+    assert.equal(EXIT_DISK, 3);
+    assert.equal(EXIT_SCOPE, 4);
+    assert.equal(EXIT_VALIDATION, 5);
+  });
+});
+
+describe("errors.mjs — CliError", () => {
+  it("carries an exit code and message", () => {
+    const err = new CliError("nope", EXIT_NETWORK);
+    assert.equal(err.message, "nope");
+    assert.equal(err.exitCode, EXIT_NETWORK);
+    assert.equal(err.name, "CliError");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof CliError);
+  });
+
+  it("captures an optional cause", () => {
+    const inner = new Error("inner");
+    const err = new CliError("outer", EXIT_DISK, { cause: inner });
+    assert.equal(err.cause, inner);
+  });
+
+  it("captures an optional hint", () => {
+    const err = new CliError("nope", EXIT_AUTH, { hint: "create a new key" });
+    assert.equal(err.hint, "create a new key");
+  });
+
+  it("does not set hint or cause when omitted", () => {
+    const err = new CliError("nope", EXIT_NETWORK);
+    assert.equal(err.hint, undefined);
+    // cause defaults to undefined unless provided
+    assert.equal(err.cause, undefined);
+  });
+});
+
+describe("errors.mjs — convenience constructors", () => {
+  it("networkError exits 1", () => {
+    assert.equal(networkError("no network").exitCode, EXIT_NETWORK);
+  });
+  it("authError exits 2", () => {
+    assert.equal(authError("no auth").exitCode, EXIT_AUTH);
+  });
+  it("diskError exits 3", () => {
+    assert.equal(diskError("no disk").exitCode, EXIT_DISK);
+  });
+  it("scopeError exits 4", () => {
+    assert.equal(scopeError("no scope").exitCode, EXIT_SCOPE);
+  });
+  it("validationError exits 5", () => {
+    assert.equal(validationError("bad input").exitCode, EXIT_VALIDATION);
+  });
+
+  it("convenience constructors carry hint and cause", () => {
+    const inner = new TypeError("boom");
+    const err = networkError("connection refused", { cause: inner, hint: "retry later" });
+    assert.equal(err.cause, inner);
+    assert.equal(err.hint, "retry later");
+    assert.equal(err.exitCode, EXIT_NETWORK);
+    assert.ok(err instanceof CliError);
+  });
+});
+
+// ── Retry helpers (PR4 of #646, #683) ──────────────────────────────────
+
+describe("errors.mjs — TRANSIENT_STATUS_CODES", () => {
+  it("contains the four documented transient codes", () => {
+    assert.equal(TRANSIENT_STATUS_CODES.size, 4);
+    assert.ok(TRANSIENT_STATUS_CODES.has(429));
+    assert.ok(TRANSIENT_STATUS_CODES.has(502));
+    assert.ok(TRANSIENT_STATUS_CODES.has(503));
+    assert.ok(TRANSIENT_STATUS_CODES.has(504));
+  });
+
+  it("does NOT include 500 (internal server error is NOT transient)", () => {
+    // 500 is a catch-all that usually signals a real bug. Retrying
+    // masks issues that should surface loudly. This assertion locks
+    // the decision so nobody quietly adds 500 later.
+    assert.equal(TRANSIENT_STATUS_CODES.has(500), false);
+  });
+
+  it("does NOT include 4xx auth/validation codes", () => {
+    for (const code of [400, 401, 403, 404, 405, 409, 422]) {
+      assert.equal(TRANSIENT_STATUS_CODES.has(code), false, `${code} must not be retryable`);
+    }
+  });
+});
+
+describe("errors.mjs — isRetryable", () => {
+  it("returns true for CliError with EXIT_NETWORK", () => {
+    assert.equal(isRetryable(networkError("connect ECONNREFUSED")), true);
+  });
+
+  it("returns false for CliError with other exit codes", () => {
+    assert.equal(isRetryable(authError("bad key")), false);
+    assert.equal(isRetryable(diskError("EACCES")), false);
+    assert.equal(isRetryable(scopeError("no scope")), false);
+    assert.equal(isRetryable(validationError("bad arg")), false);
+  });
+
+  it("returns true for Response-shaped objects with transient status", () => {
+    assert.equal(isRetryable({ status: 429 }), true);
+    assert.equal(isRetryable({ status: 502 }), true);
+    assert.equal(isRetryable({ status: 503 }), true);
+    assert.equal(isRetryable({ status: 504 }), true);
+  });
+
+  it("returns false for Response-shaped objects with non-transient status", () => {
+    assert.equal(isRetryable({ status: 200 }), false);
+    assert.equal(isRetryable({ status: 401 }), false);
+    assert.equal(isRetryable({ status: 404 }), false);
+    assert.equal(isRetryable({ status: 500 }), false); // explicitly NOT retried
+  });
+
+  it("returns false for plain errors (TypeError, RangeError, etc.)", () => {
+    assert.equal(isRetryable(new TypeError("bad")), false);
+    assert.equal(isRetryable(new Error("generic")), false);
+  });
+
+  it("returns false for non-objects", () => {
+    assert.equal(isRetryable(null), false);
+    assert.equal(isRetryable(undefined), false);
+    assert.equal(isRetryable("string"), false);
+    assert.equal(isRetryable(42), false);
+  });
+});
+
+describe("errors.mjs — computeBackoffDelay", () => {
+  it("attempt 1 always returns 0 (no sleep before first call)", () => {
+    assert.equal(computeBackoffDelay(1), 0);
+    assert.equal(computeBackoffDelay(0), 0); // defensive lower bound
+    assert.equal(computeBackoffDelay(-5), 0);
+  });
+
+  it("attempt 2 samples in [0, baseMs)", () => {
+    // Pin randomFn to 0.999... to see the worst-case upper bound
+    const maxAt2 = computeBackoffDelay(2, { baseMs: 500, randomFn: () => 0.999999 });
+    assert.ok(maxAt2 < 500);
+    assert.ok(maxAt2 >= 499);
+    // Pin randomFn to 0 for the best case
+    assert.equal(computeBackoffDelay(2, { baseMs: 500, randomFn: () => 0 }), 0);
+  });
+
+  it("attempt N grows exponentially until capMs", () => {
+    // Use 0.999999 to approximate "near max" — randomFn returns
+    // in [0, 1) so the sampled delay is always strictly less
+    // than its window upper bound.
+    const near = (attempt) =>
+      computeBackoffDelay(attempt, { baseMs: 500, capMs: 8000, randomFn: () => 0.999999 });
+    // Windows (baseMs=500, formula: base * 2^(attempt-2)):
+    //   attempt 2 = min(8000, 500)     = 500
+    //   attempt 3 = min(8000, 1000)    = 1000
+    //   attempt 4 = min(8000, 2000)    = 2000
+    //   attempt 5 = min(8000, 4000)    = 4000
+    //   attempt 6 = min(8000, 8000)    = 8000
+    //   attempt 7 = min(8000, 16000)   = 8000 (capped)
+    assert.ok(near(2) < 500);
+    assert.ok(near(3) < 1000);
+    assert.ok(near(4) < 2000);
+    assert.ok(near(5) < 4000);
+    assert.ok(near(6) < 8000);
+    assert.ok(near(7) < 8000, "cap should hold at high attempt numbers");
+  });
+
+  it("uses DEFAULT_RETRY_BASE_MS and DEFAULT_RETRY_CAP_MS when unspecified", () => {
+    assert.equal(DEFAULT_RETRY_BASE_MS, 500);
+    assert.equal(DEFAULT_RETRY_CAP_MS, 8000);
+    assert.equal(DEFAULT_RETRY_ATTEMPTS, 3);
+  });
+});
+
+describe("errors.mjs — withRetry", () => {
+  function makeSleepTracker() {
+    const calls = [];
+    const fn = async (ms) => {
+      calls.push(ms);
+    };
+    fn.calls = calls;
+    return fn;
+  }
+
+  it("returns the result immediately on first success", async () => {
+    const sleepFn = makeSleepTracker();
+    const result = await withRetry(async () => "ok", { sleepFn });
+    assert.equal(result, "ok");
+    assert.equal(sleepFn.calls.length, 0, "no sleep on first success");
+  });
+
+  it("retries a thrown networkError and eventually succeeds", async () => {
+    let attempts = 0;
+    const sleepFn = makeSleepTracker();
+    const result = await withRetry(
+      async () => {
+        attempts++;
+        if (attempts < 3) throw networkError("ECONNRESET");
+        return "eventually ok";
+      },
+      { sleepFn, randomFn: () => 0 }, // zero-jitter for determinism
+    );
+    assert.equal(result, "eventually ok");
+    assert.equal(attempts, 3);
+    assert.equal(sleepFn.calls.length, 2, "slept between each retry");
+  });
+
+  it("retries a transient Response and eventually succeeds", async () => {
+    let attempts = 0;
+    const sleepFn = makeSleepTracker();
+    const result = await withRetry(
+      async () => {
+        attempts++;
+        if (attempts < 2) return { status: 503 };
+        return { status: 200, ok: true };
+      },
+      { sleepFn, randomFn: () => 0 },
+    );
+    assert.equal(result.status, 200);
+    assert.equal(attempts, 2);
+    assert.equal(sleepFn.calls.length, 1);
+  });
+
+  it("rethrows the last networkError after exhausting attempts", async () => {
+    let attempts = 0;
+    const sleepFn = makeSleepTracker();
+    await assert.rejects(
+      () =>
+        withRetry(
+          async () => {
+            attempts++;
+            throw networkError(`attempt ${attempts}`);
+          },
+          { attempts: 3, sleepFn, randomFn: () => 0 },
+        ),
+      (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK && err.message === "attempt 3",
+    );
+    assert.equal(attempts, 3);
+    // Slept between attempt 1→2 and attempt 2→3. No sleep after the
+    // final failing attempt — the retry loop throws immediately.
+    assert.equal(sleepFn.calls.length, 2);
+  });
+
+  it("returns the final transient Response after exhausting attempts", async () => {
+    let attempts = 0;
+    const sleepFn = makeSleepTracker();
+    // Retry exhausted: the caller will map the final 503 via
+    // mapErrorResponse — withRetry does NOT convert the Response
+    // into an error itself.
+    const result = await withRetry(
+      async () => {
+        attempts++;
+        return { status: 503 };
+      },
+      { attempts: 2, sleepFn, randomFn: () => 0 },
+    );
+    assert.equal(result.status, 503);
+    assert.equal(attempts, 2);
+    assert.equal(sleepFn.calls.length, 1);
+  });
+
+  it("does NOT retry non-transient CliErrors (auth, disk, scope, validation)", async () => {
+    const sleepFn = makeSleepTracker();
+    let attempts = 0;
+    await assert.rejects(
+      () =>
+        withRetry(
+          async () => {
+            attempts++;
+            throw authError("bad key");
+          },
+          { sleepFn, randomFn: () => 0 },
+        ),
+      (err) => err.exitCode === EXIT_AUTH,
+    );
+    assert.equal(attempts, 1, "auth error must not retry");
+    assert.equal(sleepFn.calls.length, 0);
+  });
+
+  it("does NOT retry plain errors (TypeError, bugs in callee)", async () => {
+    const sleepFn = makeSleepTracker();
+    let attempts = 0;
+    await assert.rejects(
+      () =>
+        withRetry(async () => {
+          attempts++;
+          throw new TypeError("programmer error");
+        }, { sleepFn }),
+      (err) => err instanceof TypeError,
+    );
+    assert.equal(attempts, 1);
+  });
+
+  it("fires onRetry callback before each retry with attempt + delay", async () => {
+    const calls = [];
+    let attempts = 0;
+    await withRetry(
+      async () => {
+        attempts++;
+        if (attempts < 3) throw networkError("fail");
+        return "ok";
+      },
+      {
+        sleepFn: async () => {},
+        randomFn: () => 0.5,
+        onRetry: (info) => calls.push(info),
+      },
+    );
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0].attempt, 1);
+    assert.equal(calls[1].attempt, 2);
+    assert.ok(calls[0].cause instanceof CliError);
+  });
+
+  it("rejects non-positive attempts count", async () => {
+    await assert.rejects(
+      () => withRetry(async () => "ok", { attempts: 0 }),
+      (err) => err.exitCode === EXIT_VALIDATION,
+    );
+    await assert.rejects(
+      () => withRetry(async () => "ok", { attempts: -1 }),
+      (err) => err.exitCode === EXIT_VALIDATION,
+    );
+    await assert.rejects(
+      () => withRetry(async () => "ok", { attempts: 1.5 }),
+      (err) => err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});