skillrepo 3.0.0 → 3.1.0

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

@@ -162,3 +162,161 @@ describe("runUpdate — flag handling", () => {
     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/lib/artifact-registry.test.mjs

@@ -0,0 +1,268 @@
+/**
+ * CI enforcement test for the artifact registry (#885).
+ *
+ * Architect tightening #1: the artifact-registry test must be
+ * BIDIRECTIONAL. It's not enough to iterate registry entries and
+ * assert each has a matching remover — that catches "descriptor
+ * without implementation" but misses the more dangerous direction,
+ * "new merger writes a file we never catalogued."
+ *
+ * The checks below:
+ *
+ *   1. Filesystem → registry:
+ *      - Every file in `src/lib/mergers/*.mjs` (installer modules)
+ *        must be declared in MERGER_EXPECTED, which maps installer
+ *        names to the registry ids they produce. A new merger file
+ *        without an expected-set entry FAILS this test.
+ *      - Every file in `src/lib/removers/*.mjs` (uninstaller
+ *        modules) must be declared in REMOVER_EXPECTED, which
+ *        maps remover names to the registry ids they delete. A new
+ *        remover file without an expected-set entry FAILS.
+ *
+ *   2. Registry → filesystem:
+ *      - Every descriptor id in ARTIFACT_REGISTRY must appear in
+ *        REMOVER_EXPECTED or DIRECTORY_ARTIFACT_IDS (the inline-
+ *        handled directory removals in uninstall.mjs). A new
+ *        descriptor without a remover mapping FAILS.
+ *
+ *   3. Mutual consistency:
+ *      - Every registry id in MERGER_EXPECTED also appears in
+ *        REMOVER_EXPECTED or DIRECTORY_ARTIFACT_IDS. A merger that
+ *        writes an artifact with no remover path FAILS.
+ *
+ * When this test fails, the fix is always either (a) update the
+ * expected-set in this test because the change was intentional
+ * (adding a new merger/remover pair), or (b) update the registry
+ * because the implementation drifted. NEVER silence the test — that
+ * defeats the entire drift-protection mechanism.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ARTIFACT_REGISTRY } from "../../lib/artifact-registry.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LIB_DIR = join(__dirname, "..", "..", "lib");
+const MERGERS_DIR = join(LIB_DIR, "mergers");
+const REMOVERS_DIR = join(LIB_DIR, "removers");
+
+/**
+ * Maps each installer merger file (by basename without `.mjs`) to
+ * the registry descriptor ids it produces. The init flow writes
+ * through these mergers; every installed artifact must correspond
+ * to a catalogued descriptor so the uninstaller can find it.
+ *
+ * UPDATE this table in the same PR that adds a new merger. The
+ * "filesystem → registry" assertion below reads the directory and
+ * requires every file to appear here. A missing entry fails with:
+ *
+ *   "merger X.mjs has no entry in MERGER_EXPECTED"
+ *
+ * which points directly at this file.
+ */
+const MERGER_EXPECTED = Object.freeze({
+  "claude-mcp": ["claude-mcp-entry"],
+  "cursor-mcp": ["cursor-mcp-entry"],
+  "vscode-mcp": ["vscode-mcp-entry", "vscode-mcp-input"],
+  "windsurf-mcp": ["windsurf-mcp-entry"],
+  "env-local": ["env-local-key"],
+  gitignore: ["gitignore-entries"],
+  // Session-sync installer added by #884. Writes the hook entry that
+  // the `settings` remover (src/lib/removers/settings.mjs) identifies
+  // via SESSION_HOOK_FINGERPRINT. One installer module, two target
+  // paths: project-local (`.claude/settings.local.json`) when called
+  // without --global, user-wide (`~/.claude/settings.local.json`)
+  // with --global. Each path has its own registry descriptor so
+  // `skillrepo uninstall` and `skillrepo uninstall --global` both
+  // know to look in the right place. Round-trip contracts are
+  // verified in src/test/mergers/session-hook.test.mjs.
+  "session-hook": ["settings-session-hook", "settings-session-hook-global"],
+});
+
+/**
+ * Maps each remover file (by basename without `.mjs`) to the
+ * registry descriptor ids it tears down. Symmetric to
+ * MERGER_EXPECTED — every file in src/lib/removers/ must appear
+ * here.
+ */
+const REMOVER_EXPECTED = Object.freeze({
+  "claude-mcp": ["claude-mcp-entry"],
+  "cursor-mcp": ["cursor-mcp-entry"],
+  "vscode-mcp": ["vscode-mcp-entry", "vscode-mcp-input"],
+  "windsurf-mcp": ["windsurf-mcp-entry"],
+  "env-local": ["env-local-key"],
+  gitignore: ["gitignore-entries"],
+  // One remover file (settings.mjs), two descriptor ids — project-
+  // local and global variants go through the same walk with the
+  // settings remover's `{ global }` option.
+  settings: ["settings-session-hook", "settings-session-hook-global"],
+});
+
+/**
+ * Registry ids handled inline by uninstall.mjs's
+ * `removeDirectoryArtifact` (not by a dedicated remover module).
+ * These are the `kind: "directory"` descriptors in the registry.
+ */
+const DIRECTORY_ARTIFACT_IDS = Object.freeze([
+  "skills-dir-project",
+  "skills-dir-global",
+  "global-config-dir",
+]);
+
+/**
+ * Read an mjs directory and return an array of basenames without
+ * extension, excluding any hidden files or subdirectories.
+ */
+function listMjsBasenames(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith(".mjs"))
+    .map((d) => d.name.replace(/\.mjs$/, ""));
+}
+
+describe("artifact-registry: drift enforcement", () => {
+  it("every file in src/lib/mergers/ is declared in MERGER_EXPECTED", () => {
+    // Filesystem-first direction: a new merger with no expected-set
+    // entry fails here. This is the load-bearing check — it catches
+    // "engineer added a new write path without updating the catalog."
+    const found = listMjsBasenames(MERGERS_DIR);
+    for (const name of found) {
+      assert.ok(
+        MERGER_EXPECTED[name],
+        `merger ${name}.mjs has no entry in MERGER_EXPECTED. ` +
+          `Add it to src/test/lib/artifact-registry.test.mjs AND add ` +
+          `a matching remover + registry descriptor.`,
+      );
+    }
+  });
+
+  it("every entry in MERGER_EXPECTED has a corresponding mjs file", () => {
+    // Inverse: catches a typo or stale entry in MERGER_EXPECTED
+    // (e.g., someone removed a merger file but forgot to trim this
+    // table). Low-severity drift but still worth catching.
+    const found = new Set(listMjsBasenames(MERGERS_DIR));
+    for (const name of Object.keys(MERGER_EXPECTED)) {
+      assert.ok(
+        found.has(name),
+        `MERGER_EXPECTED names ${name}.mjs but the file does not exist at ${MERGERS_DIR}.`,
+      );
+    }
+  });
+
+  it("every file in src/lib/removers/ is declared in REMOVER_EXPECTED", () => {
+    const found = listMjsBasenames(REMOVERS_DIR);
+    for (const name of found) {
+      assert.ok(
+        REMOVER_EXPECTED[name],
+        `remover ${name}.mjs has no entry in REMOVER_EXPECTED. ` +
+          `Add it to src/test/lib/artifact-registry.test.mjs AND confirm ` +
+          `its target ids are in ARTIFACT_REGISTRY.`,
+      );
+    }
+  });
+
+  it("every entry in REMOVER_EXPECTED has a corresponding mjs file", () => {
+    const found = new Set(listMjsBasenames(REMOVERS_DIR));
+    for (const name of Object.keys(REMOVER_EXPECTED)) {
+      assert.ok(
+        found.has(name),
+        `REMOVER_EXPECTED names ${name}.mjs but the file does not exist at ${REMOVERS_DIR}.`,
+      );
+    }
+  });
+
+  it("every registry descriptor id has a remover or is an inline directory removal", () => {
+    // Registry-first direction: catches "descriptor added but no
+    // one implemented the removal."
+    const allImplementedIds = new Set([
+      ...Object.values(REMOVER_EXPECTED).flat(),
+      ...DIRECTORY_ARTIFACT_IDS,
+    ]);
+    for (const d of ARTIFACT_REGISTRY) {
+      assert.ok(
+        allImplementedIds.has(d.id),
+        `ARTIFACT_REGISTRY id "${d.id}" has no remover. Either add ` +
+          `it to REMOVER_EXPECTED (with a matching src/lib/removers/ ` +
+          `file) or to DIRECTORY_ARTIFACT_IDS if it's a whole-directory ` +
+          `removal handled inline by uninstall.mjs.`,
+      );
+    }
+  });
+
+  it("every REMOVER_EXPECTED id exists in ARTIFACT_REGISTRY", () => {
+    // Catches a typo in the expected-set that doesn't match a real
+    // descriptor.
+    const registryIds = new Set(ARTIFACT_REGISTRY.map((d) => d.id));
+    for (const [removerName, ids] of Object.entries(REMOVER_EXPECTED)) {
+      for (const id of ids) {
+        assert.ok(
+          registryIds.has(id),
+          `REMOVER_EXPECTED["${removerName}"] references id "${id}" ` +
+            `but ARTIFACT_REGISTRY has no descriptor with that id.`,
+        );
+      }
+    }
+  });
+
+  it("every MERGER_EXPECTED id has a matching descriptor AND a remover path", () => {
+    // Mutual consistency: a merger that installs an artifact must
+    // have both a registry descriptor AND a teardown path (direct
+    // remover or inline directory removal). Otherwise we're
+    // writing state the user can never clean up.
+    const registryIds = new Set(ARTIFACT_REGISTRY.map((d) => d.id));
+    const allImplementedIds = new Set([
+      ...Object.values(REMOVER_EXPECTED).flat(),
+      ...DIRECTORY_ARTIFACT_IDS,
+    ]);
+    for (const [mergerName, ids] of Object.entries(MERGER_EXPECTED)) {
+      for (const id of ids) {
+        assert.ok(
+          registryIds.has(id),
+          `MERGER_EXPECTED["${mergerName}"] references id "${id}" ` +
+            `but ARTIFACT_REGISTRY has no descriptor with that id.`,
+        );
+        assert.ok(
+          allImplementedIds.has(id),
+          `MERGER_EXPECTED["${mergerName}"] installs id "${id}" but ` +
+            `no remover is bound to it. A write with no teardown is ` +
+            `exactly the drift #885 exists to prevent.`,
+        );
+      }
+    }
+  });
+
+  it("every DIRECTORY_ARTIFACT_ID is a directory-kind descriptor in the registry", () => {
+    for (const id of DIRECTORY_ARTIFACT_IDS) {
+      const d = ARTIFACT_REGISTRY.find((x) => x.id === id);
+      assert.ok(d, `DIRECTORY_ARTIFACT_IDS references unknown id ${id}`);
+      assert.equal(
+        d.kind,
+        "directory",
+        `DIRECTORY_ARTIFACT_IDS contains non-directory descriptor ${id} (kind=${d.kind})`,
+      );
+    }
+  });
+
+  it("descriptor kind enum is limited to the known set", () => {
+    // Catches a descriptor that uses a `kind` the dispatch table
+    // doesn't understand — would produce a runtime "no remover
+    // bound" error at uninstall time rather than a clean test failure.
+    const VALID_KINDS = new Set([
+      "json-key",
+      "json-input",
+      "line",
+      "section",
+      "directory",
+    ]);
+    for (const d of ARTIFACT_REGISTRY) {
+      assert.ok(
+        VALID_KINDS.has(d.kind),
+        `descriptor ${d.id} has unknown kind "${d.kind}". Allowed: ` +
+          `${[...VALID_KINDS].join(", ")}`,
+      );
+    }
+  });
+});