skillrepo 2.0.0 → 3.1.0

package/src/test/commands/update.test.mjs

@@ -0,0 +1,322 @@
+/**
+ * Unit/integration tests for src/commands/update.mjs (PR2 of #646).
+ *
+ * Tests run the runUpdate function directly against an in-process mock
+ * server. Captures stdout via a stream override.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runUpdate } from "../../commands/update.mjs";
+import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import { createMockServer } from "../e2e/mock-server.mjs";
+import { createCaptureStream } from "../helpers/capture-stream.mjs";
+
+let sandbox;
+let server;
+let serverUrl;
+let originalCwd;
+let originalHome;
+let stdout;
+const VALID_KEY = "sk_live_test";
+
+function makeSkill(name) {
+  return {
+    owner: "alice",
+    name,
+    version: "1.0.0",
+    description: `${name} description`,
+    files: [
+      {
+        path: "SKILL.md",
+        content: `---\nname: ${name}\ndescription: ${name} description\n---\n\nbody\n`,
+        sha256: "x",
+        size: 50,
+        contentType: "text/markdown",
+      },
+    ],
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+async function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-cmd-update-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHome = process.env.HOME;
+  process.chdir(join(sandbox, "project"));
+  process.env.HOME = join(sandbox, "home");
+  delete process.env.SKILLREPO_ACCESS_KEY;
+  delete process.env.SKILLREPO_URL;
+
+  server = createMockServer({});
+  const port = await server.start();
+  serverUrl = `http://127.0.0.1:${port}`;
+
+  stdout = createCaptureStream();
+}
+
+async function teardown() {
+  if (server) await server.stop();
+  process.chdir(originalCwd);
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  server = null;
+}
+
+describe("runUpdate — happy path", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("syncs an empty library and prints up-to-date", async () => {
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(stdout.text(), /up to date/);
+  });
+
+  it("syncs a single skill and prints add count", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("first")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(stdout.text(), /1 added/);
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "first")));
+  });
+
+  it("--json outputs structured summary", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("first"), makeSkill("second")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.added, 2);
+    assert.equal(json.removed, 0);
+    assert.equal(json.notModified, false);
+  });
+});
+
+describe("runUpdate — credential resolution", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("reads from the global config file when no flags", async () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", "config.json"),
+      JSON.stringify({ apiKey: VALID_KEY, serverUrl }),
+    );
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate([], { stdout });
+    assert.match(stdout.text(), /up to date/);
+  });
+
+  it("throws authError when no key and no config", async () => {
+    await assert.rejects(
+      () => runUpdate([]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+});
+
+describe("runUpdate — flag handling", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("rejects unknown flag", async () => {
+    await assert.rejects(
+      () => runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--bogus"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("--global writes to the global skills dir", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("global-test")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--global"]);
+    const dir = resolvePlacementDir("claudeGlobal", "global-test");
+    assert.ok(existsSync(dir));
+    assert.ok(dir.startsWith(process.env.HOME));
+  });
+
+  it("--ide cursor writes to the project /skills/ fallback", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("cursor-test")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--ide", "cursor"]);
+    const dir = resolvePlacementDir("projectFallback", "cursor-test");
+    assert.ok(existsSync(dir));
+  });
+});
+
+// ── --session-hook mode (#884) ────────────────────────────────────────
+//
+// Session-hook mode is what the Claude Code SessionStart hook #884's
+// installer writes invokes: `skillrepo update --session-hook`. The
+// contract: exit 0 on ALL errors, silent on 304, one-line summary on
+// changes, one-line failure message on error. A sync failure must
+// NEVER block a session start.
+//
+// Architect pre-flight review flagged the flag-acceptance bug as
+// "most likely silent-failure bug" — if `resolveFlags` rejects the
+// flag before the exit-0 contract activates, every session-start
+// hook silently fails with a symptom indistinguishable from 304.
+// Tests in this suite specifically guard against that.
+
+describe("runUpdate — --session-hook contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("accepts the --session-hook flag without throwing a validation error", async () => {
+    // THE architect-flagged regression guard. If a future refactor
+    // removes the acceptPositional callback from update.mjs,
+    // resolveFlags throws `Unknown argument: --session-hook` before
+    // the exit-0 contract has a chance to fire. The `|| true` shell
+    // backstop would catch it, but the user would lose the failure
+    // message AND every sync would silently no-op. This test makes
+    // that class of regression fail loudly at unit-test time.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+          { stdout },
+        ),
+      "update --session-hook must NOT throw Unknown argument",
+    );
+  });
+
+  it("is silent on 304 / up-to-date (no 'Syncing' output every session)", async () => {
+    // INTENT: 304 means nothing changed. Printing "Syncing..." on
+    // every session start with no value to show would clutter the
+    // system-message surface. The contract is SILENCE on 304.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(
+      stdout.text(),
+      "",
+      "session-hook mode must emit zero output when there's nothing to sync",
+    );
+  });
+
+  it("prints one line on successful sync with changes", async () => {
+    // INTENT: when content CHANGES, surface exactly one actionable
+    // line so the user knows their library updated. No banners, no
+    // multi-line output — a single line the hook runner can render
+    // as a system message.
+    server.setLibraryResponse({
+      skills: [makeSkill("sync-hook-test")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    const out = stdout.text();
+    assert.match(out, /^\[SkillRepo\] Library synced: \d+ added, \d+ updated, \d+ removed\.\n$/);
+  });
+
+  it("exits 0 with a failure message on a server error instead of throwing", async () => {
+    // THE load-bearing contract. A sync failure must NEVER block a
+    // session start. runUpdate called with --session-hook against an
+    // unreachable server must return normally (no throw) and emit a
+    // one-line failure message.
+    //
+    // We simulate an unreachable server by pointing at an invalid
+    // port. Without the exit-0 contract, this would throw
+    // networkError from runSync; WITH the contract, the catch block
+    // swallows it and prints a failure message.
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", "http://127.0.0.1:1", "--session-hook"],
+          { stdout },
+        ),
+      "session-hook mode must NEVER throw — session start must proceed",
+    );
+    const out = stdout.text();
+    assert.match(out, /^\[SkillRepo\] Sync failed: .+\n$/);
+  });
+
+  it("exits 0 with a failure message on auth error (invalid key)", async () => {
+    // Auth error is non-retryable AND non-blocking for session start.
+    // If the user's key was rotated, we want them to see "access key
+    // invalid" in their session system message, but the session must
+    // still open normally.
+    server.setForcedStatus(401, { error: "Invalid access key" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+          { stdout },
+        ),
+    );
+    const out = stdout.text();
+    assert.match(out, /Sync failed/);
+  });
+
+  it("exits 0 with a failure message when no access key is configured", async () => {
+    // INTENT: the VERY first session after installing skillrepo, if
+    // init hasn't run yet, has no key. The hook must not block the
+    // session. This is a genuine first-run scenario, not a synthetic
+    // edge case — users who set up Claude Code before running
+    // `skillrepo init` will hit exactly this.
+    //
+    // No --key flag, no cached config, no env var. resolveFlags
+    // normally throws authError in this case. Session-hook mode
+    // must catch that and exit 0 anyway.
+    await assert.doesNotReject(
+      () =>
+        runUpdate(["--url", serverUrl, "--session-hook"], { stdout }),
+      "session-hook mode with no key must NEVER throw",
+    );
+    const out = stdout.text();
+    assert.match(out, /Sync failed/, "failure message must still surface");
+  });
+
+  it("exits 0 when the --session-hook flag appears after other flags", async () => {
+    // INTENT: flag ordering is not part of the contract. The installer
+    // writes a specific order today, but a user hand-editing their
+    // settings (or a future refactor moving flags around) must not
+    // break the exit-0 behavior.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--session-hook", "--key", VALID_KEY, "--url", serverUrl],
+          { stdout },
+        ),
+    );
+    assert.equal(stdout.text(), "", "still silent on 304 regardless of flag order");
+  });
+
+  it("exits 0 silently when the server returns zero deltas (empty success, not 304)", async () => {
+    // INTENT: 304 isn't the only silent-success case. A 200 response
+    // with zero added/updated/removed (a fresh sync that happened to
+    // produce no work) is also silent — same UX reasoning as 304.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(stdout.text(), "", "zero-delta 200 is silent");
+  });
+});

package/src/test/detect-ides.test.mjs

@@ -53,18 +53,13 @@ describe("IDE detection", () => {
     // windsurf depends on home dir, skip assertion
   });
 
-  it("defaults to claudeCode + cursor when nothing detected", async () => {
-    const { getDetectedIdeKeys } = await import("../lib/detect-ides.mjs");
-
-    // Override windsurf detection too
-    const keys = getDetectedIdeKeys({ claudeCode: false, cursor: false, windsurf: false, vscode: false });
-    assert.deepEqual(keys, ["claudeCode", "cursor"]);
-  });
-
-  it("returns only detected IDEs", async () => {
-    const { getDetectedIdeKeys } = await import("../lib/detect-ides.mjs");
-
-    const keys = getDetectedIdeKeys({ claudeCode: true, cursor: false, windsurf: false, vscode: true });
-    assert.deepEqual(keys, ["claudeCode", "vscode"]);
-  });
+  // PR4 cross-review cleanup: the old v2.0.0 `getDetectedIdeKeys`
+  // helper with a "default to claudeCode + cursor when nothing
+  // detected" fallback was dead code — the plan explicitly
+  // removed the silent fallback in PR3b, and no command called
+  // this helper. It was exported and had tests asserting the
+  // v2.0.0 behavior, which contradicted the actual v3.0.0 code
+  // path. Deleted; init now refuses with a --ide hint when
+  // nothing is detected (see the "refuses with clear error when
+  // no IDE detected and no --ide flag" test in init.test.mjs).
 });

package/src/test/dispatcher.test.mjs

@@ -0,0 +1,224 @@
+/**
+ * Unit tests for bin/skillrepo.mjs (PR1 of #646).
+ *
+ * Spawns the real binary as a subprocess and asserts on stdout, stderr,
+ * and exit code for each documented routing path. Intentionally thin —
+ * the dispatcher should be a pure routing layer, so most logic lives in
+ * the command modules tested elsewhere.
+ *
+ * IMPORTANT: keep these tests fast — they run as part of `npm run check`
+ * and a slow dispatcher suite slows down every commit.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = resolve(__dirname, "../../bin/skillrepo.mjs");
+const PKG_PATH = resolve(__dirname, "../../package.json");
+
+/**
+ * Run the CLI dispatcher and capture stdout, stderr, and exit code.
+ * Always resolves — never rejects — so tests can assert on failures.
+ *
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @param {object} [opts.env] - Extra env vars (merged onto process.env).
+ *        Useful for tests that need to point HOME at an empty dir to
+ *        prove "no global config" code paths fire correctly. Pass
+ *        SKILLREPO_ACCESS_KEY: "" explicitly to override an inherited
+ *        env var from the developer's shell.
+ */
+function runCli(args = [], opts = {}) {
+  return new Promise((resolve) => {
+    const baseEnv = {
+      ...process.env,
+      NO_COLOR: "1",
+      // Default tests to "no key in env" so the no-config code paths
+      // are exercised reliably across developer machines that may
+      // have SKILLREPO_ACCESS_KEY set in their shell.
+      SKILLREPO_ACCESS_KEY: "",
+      // Short timeout so the network-failure case fails fast rather
+      // than waiting 30s on the default safeFetch timeout.
+      SKILLREPO_TIMEOUT_MS: "2000",
+    };
+    execFile(
+      process.execPath,
+      [CLI_BIN, ...args],
+      {
+        encoding: "utf-8",
+        timeout: 10_000,
+        env: { ...baseEnv, ...(opts.env || {}) },
+      },
+      (err, stdout, stderr) => {
+        resolve({
+          stdout: stdout ?? "",
+          stderr: stderr ?? "",
+          status: err ? err.code ?? 1 : 0,
+        });
+      },
+    );
+  });
+}
+
+describe("dispatcher — top-level help", () => {
+  it("`skillrepo` with no args prints top-level help and exits 0", async () => {
+    const r = await runCli([]);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /SkillRepo CLI/);
+    // All 7 commands listed
+    for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+      assert.match(r.stdout, new RegExp(`\\b${cmd}\\b`), `expected to see "${cmd}" in help`);
+    }
+  });
+
+  it("`skillrepo --help` is the same as no args", async () => {
+    const r = await runCli(["--help"]);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /SkillRepo CLI/);
+  });
+
+  it("`skillrepo -h` is the same as --help", async () => {
+    const r = await runCli(["-h"]);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /SkillRepo CLI/);
+  });
+});
+
+describe("dispatcher — version", () => {
+  it("`skillrepo --version` prints the package.json version", async () => {
+    const r = await runCli(["--version"]);
+    assert.equal(r.status, 0);
+    const pkg = JSON.parse(readFileSync(PKG_PATH, "utf-8"));
+    assert.equal(r.stdout.trim(), pkg.version);
+  });
+
+  it("`skillrepo -v` is the same as --version", async () => {
+    const r = await runCli(["-v"]);
+    assert.equal(r.status, 0);
+    const pkg = JSON.parse(readFileSync(PKG_PATH, "utf-8"));
+    assert.equal(r.stdout.trim(), pkg.version);
+  });
+});
+
+describe("dispatcher — unknown command", () => {
+  it("exits with EXIT_VALIDATION (5) and prints a hint", async () => {
+    const r = await runCli(["nonsense"]);
+    assert.equal(r.status, 5);
+    assert.match(r.stderr, /Unknown command/);
+    assert.match(r.stderr, /skillrepo --help/);
+  });
+
+  it("rejects unknown flags as commands too", async () => {
+    const r = await runCli(["--bogus"]);
+    assert.equal(r.status, 5);
+    assert.match(r.stderr, /Unknown command/);
+  });
+});
+
+describe("dispatcher — per-command help", () => {
+  // PR1 only ships init for real; the other 6 are stubs but still
+  // route --help correctly.
+  for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+    it(`\`skillrepo ${cmd} --help\` prints command-specific help`, async () => {
+      const r = await runCli([cmd, "--help"]);
+      assert.equal(r.status, 0);
+      assert.match(r.stdout, new RegExp(`skillrepo ${cmd}`));
+      assert.match(r.stdout, /Usage:/);
+    });
+  }
+});
+
+// All 7 commands are implemented as of PR3a. No stubs remain.
+// (PR1 shipped init; PR2 shipped update/get/list/search; PR3a ships add/remove.)
+
+describe("dispatcher — implemented commands route to their modules", () => {
+  // These commands have real implementations as of PR2. The dispatcher
+  // routing test verifies the binary doesn't fall through to the stub
+  // factory — we expect a "real" failure (validation/auth/network)
+  // rather than the "Not yet implemented" stub message.
+  //
+  // Each command is invoked WITHOUT credentials in a directory where
+  // there is no global config, so the expected outcome is an authError
+  // (exit 2, "No access key configured") OR a validationError (exit 5)
+  // for commands that require a positional argument.
+  it("`skillrepo update` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["update"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    // Either auth (no key) or network (no server) — both prove routing worked
+    assert.ok([1, 2, 5].includes(r.status), `expected 1/2/5, got ${r.status}`);
+  });
+
+  it("`skillrepo get` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["get", "@alice/pdf-helper"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([1, 2, 5].includes(r.status));
+  });
+
+  it("`skillrepo get` without an identifier exits 5 with a usage hint", async () => {
+    // Missing positional should fail validation BEFORE attempting
+    // credential resolution — proves the dispatcher passes argv
+    // through and the command's positional check fires.
+    const r = await runCli(["get"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    // Either validation (missing positional) or auth (no key, depending
+    // on which check fires first) — both prove the stub is gone.
+    assert.ok([2, 5].includes(r.status));
+  });
+
+  it("`skillrepo list` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["list"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([1, 2, 5].includes(r.status));
+  });
+
+  it("`skillrepo search` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["search", "test"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([1, 2, 5].includes(r.status));
+  });
+
+  it("`skillrepo search` without a query exits with a usage hint", async () => {
+    const r = await runCli(["search"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([2, 5].includes(r.status));
+  });
+
+  it("`skillrepo add` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["add", "@alice/pdf-helper"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([1, 2, 5].includes(r.status));
+  });
+
+  it("`skillrepo remove` is wired to the real module (not a stub)", async () => {
+    const r = await runCli(["remove", "@alice/pdf-helper"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([1, 2, 5].includes(r.status));
+  });
+
+  it("`skillrepo add` without identifier exits 2 or 5 (usage hint)", async () => {
+    const r = await runCli(["add"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([2, 5].includes(r.status));
+  });
+
+  it("`skillrepo remove` without identifier exits 2 or 5 (usage hint)", async () => {
+    const r = await runCli(["remove"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([2, 5].includes(r.status));
+  });
+});
+
+describe("dispatcher — init still works (PR1 keeps existing init untouched)", () => {
+  it("`skillrepo init --help` prints init help", async () => {
+    const r = await runCli(["init", "--help"]);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /skillrepo init/);
+  });
+  // Real init flow is exercised by src/test/e2e/cli-init.test.mjs
+  // against the mock server. We don't duplicate that here.
+});