skillrepo 4.8.0 → 4.8.2

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

@@ -13,6 +13,12 @@ import { tmpdir } from "node:os";
 
 import { runUpdate } from "../../commands/update.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import {
+  readLastSync,
+  writeLastSync,
+  FULL_RESYNC_FLOOR,
+  cliVersionBelowFloor,
+} from "../../lib/sync.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";
@@ -111,6 +117,43 @@ describe("runUpdate — happy path", () => {
   });
 });
 
+describe("runUpdate — summary printer (removed line)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("prints the removed line in the human summary when a tombstone deletes a skill", async () => {
+    // printSummary only emits `− N removed` when `s.removed > 0`. Every
+    // other human-mode test produces added/updated-only summaries, so the
+    // `if (s.removed > 0)` true branch was never taken. Sync a skill,
+    // then re-sync with it tombstoned so `removed` is non-zero and the
+    // line is rendered.
+    server.setLibraryResponse({
+      skills: [makeSkill("doomed")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "doomed")), "precondition: skill on disk");
+
+    stdout.clear();
+    server.resetLibraryInspection?.();
+    server.setLibraryResponse({
+      skills: [],
+      removals: [{ owner: "alice", name: "doomed", removedAt: "x" }],
+      syncedAt: "y",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+
+    const out = stdout.text();
+    assert.match(out, /Library sync complete/);
+    assert.match(out, /−\s*1 removed/, "the removed line must render when removed > 0");
+    assert.ok(
+      !existsSync(resolvePlacementDir("claudeProject", "doomed")),
+      "the tombstoned skill is gone from disk",
+    );
+  });
+});
+
 describe("runUpdate — credential resolution", () => {
   beforeEach(setup);
   afterEach(teardown);
@@ -335,6 +378,48 @@ describe("runUpdate — --session-hook contract", () => {
     );
     assert.equal(stdout.text(), "", "zero-delta 200 is silent");
   });
+
+  it("an UNEXPECTED positional arg is rejected, then caught into the exit-0 failure line", async () => {
+    // The session-hook `acceptPositional` callback accepts only
+    // --session-hook / --silent and returns false for anything else, so
+    // a stray bare positional (`extra`) makes resolveFlags throw
+    // "Unexpected"/"extra argument". Because that throw is INSIDE the
+    // session-hook try/catch, the contract holds: no rejection, and the
+    // one-line failure marker is emitted. Covers the acceptPositional
+    // `return false` branch in session-hook mode.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--session-hook", "stray-positional"],
+          { stdout },
+        ),
+      "an unexpected positional must be caught by the exit-0 contract, not thrown",
+    );
+    assert.match(stdout.text(), /\[SkillRepo\] Sync failed:/);
+  });
+
+  it("swallows a throwing stdout.write in the failure path (closed-pipe safety)", async () => {
+    // The failure branch wraps its `stdout.write` in try/catch so a
+    // closed pipe (the hook runner went away) can't turn a sync failure
+    // into an unhandled exception. Inject a stdout whose write throws and
+    // point at an unreachable server so the failure path runs. The call
+    // must still resolve without throwing. Covers the inner write catch.
+    const throwingStdout = {
+      write() {
+        throw new Error("EPIPE: write to closed hook pipe");
+      },
+      isTTY: false,
+    };
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", "http://127.0.0.1:1", "--session-hook"],
+          { stdout: throwingStdout },
+        ),
+      "a throwing stdout.write in the failure path must be swallowed",
+    );
+  });
 });
 
 // ── --silent mode (#1240) ─────────────────────────────────────────────
@@ -437,6 +522,22 @@ describe("runUpdate — --silent contract", () => {
     );
   });
 
+  it("rejects an UNEXPECTED positional arg under --silent (propagates, not silent-swallowed)", async () => {
+    // The silent-mode `acceptPositional` callback accepts ONLY --silent
+    // and returns false for anything else. A stray positional therefore
+    // makes resolveFlags throw a validationError, which — unlike
+    // session-hook mode — is NOT caught: silent mode propagates real exit
+    // codes. Covers the silent-mode acceptPositional `return false` branch.
+    await assert.rejects(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--silent", "stray-positional"],
+          { stdout },
+        ),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
   it("--silent + --session-hook simultaneously: session-hook wins (defensive precedence) (#1239 QA)", async () => {
     // INTENT: defensive precedence test. The two flags have different
     // exit-code contracts: --session-hook is exit-0-on-everything
@@ -471,3 +572,120 @@ describe("runUpdate — --silent contract", () => {
     );
   });
 });
+
+// ── #1911 membership heal — through the `update` COMMAND ──────────────
+//
+// The engine-level heal is locked in sync.test.mjs. But #1911 escaped
+// because the engine and the command layer were tested separately: a
+// stuck client runs `skillrepo update` (or the SessionStart hook runs it
+// for them), and what matters to the user is that the missing skill
+// actually lands on DISK via that command — not just that runSync would
+// have fetched it. These tests drive the heal through runUpdate end to
+// end (normal mode AND the --session-hook black-hole) and assert the
+// delivery a 304 would have silently skipped.
+function placedSkillMd(name) {
+  return join(resolvePlacementDir("claudeProject", name), "SKILL.md");
+}
+
+describe("runUpdate — #1911 membership heal lands the skill on disk", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("a pre-fix .last-sync forces a full re-fetch that delivers a skill a 304 would have skipped", async () => {
+    // 1) First sync: library = [alpha]. alpha lands; .last-sync stamped
+    //    with the CURRENT (>= floor) version and etag v1.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+    assert.ok(existsSync(placedSkillMd("alpha")), "precondition: alpha on disk after first sync");
+
+    // 2) Simulate the stuck pre-fix client: a NEW skill (beta) is now in
+    //    the library, but the etag is UNCHANGED (the #1911 bug — the
+    //    client cached an etag that still 304s), and .last-sync was
+    //    written by a pre-fix CLI (4.7.0). A normal conditional sync
+    //    would send If-None-Match v1 → 304 → beta NEVER delivered.
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    const prior = readLastSync();
+    writeLastSync({
+      etag: prior.etag,
+      syncedAt: prior.syncedAt,
+      skills: prior.skills,
+      cliVersion: "4.7.0",
+    });
+    assert.ok(!existsSync(placedSkillMd("beta")), "precondition: beta NOT yet on disk");
+    server.resetLibraryInspection();
+    stdout.clear();
+
+    // 3) `skillrepo update` heals: drops BOTH conditional headers, full
+    //    fetch, beta lands on disk. This is the delivery #1911 dropped.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+    assert.equal(server.getLastLibraryIfNoneMatch(), null, "heal must NOT send If-None-Match");
+    assert.equal(server.getLastLibrarySince(), null, "heal must NOT send since");
+    assert.ok(
+      existsSync(placedSkillMd("beta")),
+      "the skill a 304 would have skipped MUST land on disk via `update`",
+    );
+    assert.match(stdout.text(), /added/, "user sees a non-empty sync summary");
+
+    // 4) The heal re-stamped the running version → the next `update`
+    //    resumes normal delta (sends the conditional, gets a 304).
+    assert.equal(
+      cliVersionBelowFloor(readLastSync().cliVersion, FULL_RESYNC_FLOOR),
+      false,
+      "heal must restamp cliVersion at/above the floor so it heals only once",
+    );
+    server.resetLibraryInspection();
+    stdout.clear();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      '"v1"',
+      "post-heal `update` resumes delta (sends the conditional)",
+    );
+    assert.match(stdout.text(), /up to date/, "post-heal steady state is a normal 304");
+  });
+
+  it("the heal also delivers under --session-hook (the SessionStart path) without throwing", async () => {
+    // The SessionStart hook runs `skillrepo update --session-hook`. A
+    // stuck active user is MORE exposed (the hook runs every session, so
+    // `since` is always recent). The heal must still land the missing
+    // skill, the command must not throw (exit-0 contract), and the user
+    // gets the one-line summary.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude", "--session-hook"], { stdout });
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    const prior = readLastSync();
+    writeLastSync({ etag: prior.etag, syncedAt: prior.syncedAt, skills: prior.skills, cliVersion: "4.7.0" });
+    server.resetLibraryInspection();
+    stdout.clear();
+
+    await assert.doesNotReject(() =>
+      runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude", "--session-hook"], { stdout }),
+    );
+    assert.equal(server.getLastLibraryIfNoneMatch(), null, "session-hook heal drops If-None-Match");
+    assert.ok(existsSync(placedSkillMd("beta")), "session-hook heal lands the missing skill on disk");
+    assert.match(
+      stdout.text(),
+      /^\[SkillRepo\] Library synced: \d+ added, \d+ updated, \d+ removed\.\n$/,
+      "session-hook emits exactly one summary line after a healing sync",
+    );
+  });
+});

package/src/test/dispatcher.test.mjs

@@ -71,7 +71,7 @@ describe("dispatcher — top-level help", () => {
     assert.equal(r.status, 0);
     assert.match(r.stdout, /SkillRepo CLI/);
     // All 7 commands listed
-    for (const cmd of ["init", "update", "get", "add", "push", "remove", "list", "search"]) {
+    for (const cmd of ["init", "update", "get", "add", "push", "publish", "unpublish", "remove", "list", "search", "uninstall", "session-sync"]) {
       assert.match(r.stdout, new RegExp(`\\b${cmd}\\b`), `expected to see "${cmd}" in help`);
     }
   });
@@ -123,7 +123,7 @@ describe("dispatcher — 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", "push", "remove", "list", "search"]) {
+  for (const cmd of ["init", "update", "get", "add", "push", "publish", "unpublish", "remove", "list", "search", "uninstall", "session-sync"]) {
     it(`\`skillrepo ${cmd} --help\` prints command-specific help`, async () => {
       const r = await runCli([cmd, "--help"]);
       assert.equal(r.status, 0);
@@ -221,6 +221,107 @@ describe("dispatcher — implemented commands route to their modules", () => {
   });
 });
 
+describe("dispatcher — publish/unpublish/uninstall/session-sync route to their modules", () => {
+  // These four were never covered by the routing loop above. They are
+  // real registered commands users hit; prove the dispatcher routes
+  // each to a real implementation (not a stub, not an unknown-command).
+  it("`skillrepo publish` is wired (not a stub / unknown command)", async () => {
+    const r = await runCli(["publish", "@alice/x"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.doesNotMatch(r.stderr, /Unknown command/);
+    assert.ok([1, 2, 5].includes(r.status), `expected 1/2/5, got ${r.status}`);
+  });
+
+  it("`skillrepo unpublish` is wired (not a stub / unknown command)", async () => {
+    const r = await runCli(["unpublish", "@alice/x"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.doesNotMatch(r.stderr, /Unknown command/);
+    assert.ok([1, 2, 5].includes(r.status), `expected 1/2/5, got ${r.status}`);
+  });
+
+  it("`skillrepo uninstall --dry-run` is wired (not a stub / unknown command)", async () => {
+    // --dry-run needs no credentials — it inspects local state only, so
+    // it exits 0 with nothing to remove. Either way it must not be a stub.
+    const r = await runCli(["uninstall", "--dry-run"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.doesNotMatch(r.stderr, /Unknown command/);
+    assert.ok([0, 1, 2, 5].includes(r.status), `expected 0/1/2/5, got ${r.status}`);
+  });
+
+  it("`skillrepo session-sync` (no subcommand) is wired and validation-errors, not a stub", async () => {
+    const r = await runCli(["session-sync"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.doesNotMatch(r.stderr, /Unknown command/);
+    assert.match(r.stderr, /subcommand/);
+    assert.equal(r.status, 5);
+  });
+});
+
+describe("dispatcher — error rendering (--verbose stack + hint line)", () => {
+  // The dispatcher's catch block renders the message, an optional dim
+  // hint line, and — only under --verbose — the error's stack trace
+  // (plus a `Caused by:` chain when err.cause has a stack). None of this
+  // was covered; a regression could silently drop stacks operators rely
+  // on, or leak stacks by default.
+  it("renders a CliError's hint line on a thrown error", async () => {
+    // No key configured → authError carries a hint pointing at `init`.
+    const r = await runCli(["get", "@alice/x"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.match(r.stderr, /Error:/);
+    assert.match(r.stderr, /skillrepo init/, "the CliError hint line must render");
+  });
+
+  it("prints a stack trace under --verbose", async () => {
+    const r = await runCli(["get", "@alice/x", "--verbose"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.match(r.stderr, /Error:/);
+    assert.match(r.stderr, /\n\s+at\s/, "--verbose must print the error stack (frames like `    at ...`)");
+  });
+
+  it("does NOT print a stack trace without --verbose", async () => {
+    const r = await runCli(["get", "@alice/x"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(
+      r.stderr,
+      /\n\s+at\s/,
+      "stacks must be suppressed unless --verbose is passed",
+    );
+  });
+
+  it("renders the `Caused by:` chain under --verbose when err.cause has a stack", async () => {
+    // The authError path (no key) carries a hint but NO cause, so it
+    // never reaches the `err.cause.stack` branch. To exercise it we
+    // need a CliError whose `.cause` is a real Error with a stack.
+    // `getSkill` builds exactly that: a network failure wraps the
+    // underlying fetch TypeError as `networkError(..., { cause: err })`
+    // (src/lib/http.mjs safeFetch). Pointing SKILLREPO_URL at a refused
+    // port (127.0.0.1:1) with a key configured (so auth passes and the
+    // fetch is attempted) produces that wrapped error deterministically.
+    const r = await runCli(["get", "@alice/x", "--verbose"], {
+      env: {
+        HOME: "/tmp/no-skillrepo-config",
+        // Non-empty key so auth passes and the command reaches the
+        // network call (the base env zeroes SKILLREPO_ACCESS_KEY).
+        SKILLREPO_ACCESS_KEY: "sk_test_dummy",
+        // Refused connection → networkError wrapping a fetch TypeError.
+        SKILLREPO_URL: "http://127.0.0.1:1",
+        // Keep retry backoff bounded so the subprocess stays fast.
+        SKILLREPO_TIMEOUT_MS: "800",
+      },
+    });
+    assert.equal(r.status, 1, "a network failure exits EXIT_NETWORK (1)");
+    // The top-level stack (line 296) AND the cause chain (298-299).
+    assert.match(r.stderr, /\n\s+at\s/, "--verbose prints the top-level stack");
+    assert.match(
+      r.stderr,
+      /Caused by:/,
+      "the underlying fetch error's stack must render under --verbose",
+    );
+    assert.match(
+      r.stderr,
+      /TypeError: fetch failed/,
+      "the cause's own stack header must appear in the chain",
+    );
+  });
+});
+
 describe("dispatcher — init still works (PR1 keeps existing init untouched)", () => {
   it("`skillrepo init --help` prints init help", async () => {
     const r = await runCli(["init", "--help"]);

package/src/test/e2e/advertised-surface.test.mjs

@@ -0,0 +1,207 @@
+/**
+ * Advertised-surface contract test.
+ *
+ * Invariant under test: **every flag the CLI advertises in its own
+ * `--help` output must actually be accepted by the command.** If the
+ * dispatcher's usage string promises `--foo` but the command rejects it
+ * as "Unknown argument" / "Unexpected extra argument", that is a defect
+ * — the CLI is lying to the user about its surface.
+ *
+ * This is the regression guard for the class of bug where help text and
+ * command behavior drift apart (e.g. `push` advertising `--version` /
+ * `--changelog` long after those flags were removed from `push.mjs`).
+ * It deliberately derives the flag list from the LIVE `--help` output
+ * rather than a hardcoded table, so a future edit to a usage string is
+ * automatically held to the same contract.
+ *
+ * Mechanism: spawn the real binary (same approach as dispatcher.test.mjs).
+ *   1. `skillrepo <cmd> --help` → parse the Usage line → flag list.
+ *   2. For each advertised flag, spawn `skillrepo <cmd> <dummy positional>
+ *      <flag> [dummy value]` and assert stderr does NOT contain
+ *      "Unknown argument: <flag>" or "Unexpected extra argument: <flag>".
+ *
+ * The command still fails for OTHER reasons (no credentials, no server,
+ * missing SKILL.md, etc.) — we only assert the failure is not a
+ * flag-rejection naming the advertised flag. A flag that parses cleanly
+ * proceeds past `resolveFlags` to the network/validation layer, which is
+ * exactly what we want to confirm.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// This file lives at src/test/e2e/ — three levels below packages/cli/.
+const CLI_BIN = resolve(__dirname, "../../../bin/skillrepo.mjs");
+
+// Every command the dispatcher registers. Hardcoded because the command
+// SET is stable and the registry is not importable (bin/skillrepo.mjs
+// self-invokes main() on import). The FLAG set per command is derived
+// live from --help below — that's the part that drifts.
+const COMMANDS = [
+  "init",
+  "update",
+  "get",
+  "add",
+  "push",
+  "publish",
+  "unpublish",
+  "remove",
+  "list",
+  "search",
+  "uninstall",
+  "session-sync",
+];
+
+// Dummy positional arguments per command so a leading required positional
+// (`<@owner/name>`, `<path>`, `<query>`, `<enable|disable>`) doesn't swallow
+// the flag we're probing. These are stable; the flags are not.
+const POSITIONALS = {
+  init: [],
+  update: [],
+  get: ["@acme/widget"],
+  add: ["@acme/widget"],
+  push: ["."],
+  publish: ["@acme/widget"],
+  unpublish: ["@acme/widget"],
+  remove: ["@acme/widget"],
+  list: [],
+  search: ["query"],
+  uninstall: [],
+  "session-sync": ["enable"],
+};
+
+// Env that makes every command fail FAST at a layer AFTER flag parsing:
+// no key in env, an empty HOME so no global config is read, an
+// unroutable default URL, and a short timeout.
+const NO_HOME = join(tmpdir(), "advertised-surface-no-home");
+const SPAWN_ENV = {
+  ...process.env,
+  NO_COLOR: "1",
+  HOME: NO_HOME,
+  USERPROFILE: NO_HOME,
+  SKILLREPO_ACCESS_KEY: "",
+  SKILLREPO_URL: "http://127.0.0.1:9",
+  SKILLREPO_TIMEOUT_MS: "1500",
+};
+
+/**
+ * Run the binary synchronously, capturing stdout/stderr/status whether
+ * it exits 0 or not. execFileSync throws on non-zero exit; the thrown
+ * error carries `.stdout`/`.stderr`/`.status`.
+ */
+function runSync(args) {
+  try {
+    const stdout = execFileSync(process.execPath, [CLI_BIN, ...args], {
+      encoding: "utf-8",
+      timeout: 10_000,
+      env: SPAWN_ENV,
+    });
+    return { stdout: stdout ?? "", stderr: "", status: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout?.toString?.() ?? "",
+      stderr: err.stderr?.toString?.() ?? "",
+      status: typeof err.status === "number" ? err.status : 1,
+    };
+  }
+}
+
+/**
+ * Extract the advertised flag list for a command from its `--help`.
+ * Returns `{ flags: [{ flag, takesValue }] }` on success or
+ * `{ error: string }` if the Usage line can't be located — an
+ * unparseable help block is itself a contract failure, surfaced as a
+ * failing test rather than a collection-time crash.
+ */
+function advertisedFlags(cmd) {
+  const { stdout } = runSync([cmd, "--help"]);
+  const lines = stdout.split("\n");
+  const usageIdx = lines.findIndex((l) => /^\s*Usage:/.test(l));
+  if (usageIdx < 0) {
+    return { error: `\`skillrepo ${cmd} --help\` printed no "Usage:" section. stdout:\n${stdout}` };
+  }
+  // The usage string is the next non-blank line after "Usage:".
+  const usageLine = lines.slice(usageIdx + 1).find((l) => l.trim().length > 0);
+  if (!usageLine) {
+    return { error: `\`skillrepo ${cmd} --help\` Usage: section was empty` };
+  }
+
+  const tokens = usageLine.trim().split(/\s+/);
+  const flags = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const m = tokens[i].match(/(--[a-z][a-z-]*)/);
+    if (!m) continue;
+    const flag = m[1];
+    // A `<...>` placeholder as the next token marks a value flag, e.g.
+    // `[--key <key>]` → tokens `[--key` then `<key>]`.
+    const next = tokens[i + 1] ?? "";
+    const takesValue = /^<.*>\]?$/.test(next);
+    flags.push({ flag, takesValue });
+  }
+  return { flags };
+}
+
+// Resolve the advertised surface for every command up front. A spawn or
+// parse failure is captured as `{ error }` so it becomes a failing test
+// below instead of aborting the whole test file at collection time.
+const SURFACE = COMMANDS.map((cmd) => ({ cmd, ...advertisedFlags(cmd) }));
+
+/** A throwaway value appropriate to the flag, so value flags get one. */
+function dummyValueFor(flag) {
+  switch (flag) {
+    case "--url":
+      return "http://127.0.0.1:9";
+    case "--agent":
+      return "claude";
+    case "--limit":
+      return "5";
+    case "--key":
+      return "sk_live_dummy";
+    default:
+      return "x";
+  }
+}
+
+describe("advertised surface — every documented flag is accepted by its command", () => {
+  for (const { cmd, flags, error } of SURFACE) {
+    // Sanity: a command with a usage string should advertise at least one
+    // flag (every command exposes at least --json). If parsing failed or
+    // found none, the parser (or the help format) regressed.
+    it(`\`skillrepo ${cmd} --help\` advertises a parseable flag set`, () => {
+      assert.ok(!error, error);
+      assert.ok(
+        flags.length > 0,
+        `parsed zero flags from \`skillrepo ${cmd} --help\` — help format changed?`,
+      );
+    });
+
+    for (const { flag, takesValue } of flags ?? []) {
+      it(`\`skillrepo ${cmd}\` accepts advertised flag ${flag}`, () => {
+        const args = [
+          cmd,
+          ...POSITIONALS[cmd],
+          flag,
+          ...(takesValue ? [dummyValueFor(flag)] : []),
+        ];
+        const { stderr } = runSync(args);
+        assert.ok(
+          !stderr.includes(`Unknown argument: ${flag}`),
+          `\`skillrepo ${cmd}\` advertises ${flag} in --help but rejected it ` +
+            `as an unknown argument. stderr:\n${stderr}`,
+        );
+        assert.ok(
+          !stderr.includes(`Unexpected extra argument: ${flag}`),
+          `\`skillrepo ${cmd}\` advertises ${flag} in --help but rejected it ` +
+            `as an unexpected extra argument (the flag name is not wired into ` +
+            `the command's parser). stderr:\n${stderr}`,
+        );
+      });
+    }
+  }
+});

package/src/test/e2e/cli-commands.test.mjs

@@ -363,7 +363,7 @@ describe("CLI E2E — read commands", () => {
     assert.match(r.stderr, /write-scoped key|scope/);
   });
 
-  it("add with 403 plan_limit exits 5 with billing hint", async () => {
+  it("add with 403 plan_limit exits 5 (validation, server message shown)", async () => {
     server.setAddResponseForAny({
       status: 403,
       body: { error: "Your free plan allows up to 5 library skills.", code: "plan_limit" },