skillrepo 2.0.0 → 3.0.0

package/src/lib/prompt.mjs

@@ -1,56 +1,23 @@
 /**
  * Interactive prompts using Node's built-in readline.
  * Zero dependencies. Supports TTY detection and NO_COLOR.
+ *
+ * v3.0.0 cleanup (PR4 cross-review): the old v2.0.0 print helpers
+ * (printHeader, printStep, printSuccess, printWarning, printError,
+ * printResult, printBlank) that wrote to `console.log` were removed.
+ * They wrote directly to `process.stdout` via `console.log`, bypassing
+ * the stream-injection pattern every v3.0.0 command uses for
+ * testability. `init.mjs` defines its own `makePrinter` helper that
+ * ties into the injected io.stdout/io.stderr streams; every other
+ * command uses the same pattern. This module now only exports the
+ * three interactive primitives (`promptText`, `promptSecret`,
+ * `confirm`) that still need direct stdin/stdout access.
  */
 
 import { createInterface } from "node:readline";
 
 const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
-
-// ── Colors ──────────────────────────────────────────────────────────────
-
-const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
-const yellow = (s) => (isTTY ? `\x1b[33m${s}\x1b[0m` : s);
-const red = (s) => (isTTY ? `\x1b[31m${s}\x1b[0m` : s);
 const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
-const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
-
-// ── Output helpers ──────────────────────────────────────────────────────
-
-export function printHeader(title) {
-  console.log("");
-  console.log(`  ${bold(title)}`);
-  console.log("");
-}
-
-export function printStep(n, total, message) {
-  console.log(`  ${dim(`Step ${n}/${total}:`)} ${message}`);
-}
-
-export function printSuccess(message) {
-  console.log(`  ${green("✓")} ${message}`);
-}
-
-export function printWarning(message) {
-  console.log(`  ${yellow("⚠")} ${message}`);
-}
-
-export function printError(message) {
-  console.error(`  ${red("✗")} ${message}`);
-}
-
-export function printResult(path, action) {
-  const label =
-    action === "created" ? green("created") :
-    action === "merged" ? yellow("merged") :
-    action === "updated" ? yellow("updated") :
-    dim("skipped");
-  console.log(`  ${path.padEnd(45)} ${label}`);
-}
-
-export function printBlank() {
-  console.log("");
-}
 
 // ── Prompts ─────────────────────────────────────────────────────────────
 

package/src/lib/sync.mjs

@@ -0,0 +1,305 @@
+/**
+ * Shared library sync engine (#675 partial — used by update/get/init).
+ *
+ * Wraps the http.mjs `getLibrary` call with:
+ *   • ETag-based conditional requests (skip work if nothing changed)
+ *   • Persistent last-sync state at ~/.claude/skillrepo/.last-sync
+ *   • Tombstone application via `removeSkillDir`
+ *   • Per-skill writes via `writeSkillDir`
+ *   • A summary suitable for both human and --json output
+ *
+ * Architectural notes:
+ *
+ *   • `update.mjs` is a thin wrapper around `runSync` plus a printer.
+ *   • PR3a's `add` does NOT use this — it does a single-skill GET +
+ *     direct write (avoids clock-skew on the `since` filter).
+ *   • PR3a's `remove` does NOT use this — it deletes locally directly
+ *     (avoids the ETag cache poisoning on tombstones, see #875).
+ *   • PR3b's `init` calls `runSync({ vendors, global })` after writing
+ *     the global config to perform the first pull.
+ *
+ * The state file format is JSON with an explicit `schemaVersion` so we
+ * can evolve it without breaking older CLIs catastrophically. Future
+ * versions should bump the schema when fields are added/removed.
+ *
+ * @typedef {Object} SyncSummary
+ * @property {number} added       - Skills newly written that were not on disk
+ * @property {number} updated     - Skills overwritten on disk
+ * @property {number} removed     - Tombstones applied
+ * @property {boolean} notModified - True if 304 short-circuit fired
+ * @property {string} syncedAt    - ISO timestamp from the server response
+ *
+ * @typedef {Object} SyncStateFile
+ * @property {number} schemaVersion
+ * @property {string|null} etag
+ * @property {string} syncedAt
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { getLibrary } from "./http.mjs";
+import { writeSkillDir, removeSkillDir, cleanupOrphans } from "./file-write.mjs";
+import {
+  globalLastSyncPath,
+  claudeSkillsProject,
+  claudeSkillsGlobal,
+  projectSkillsFallback,
+} from "./paths.mjs";
+import { diskError, validationError } from "./errors.mjs";
+
+/**
+ * Current schema version of the .last-sync file. Bump on any
+ * structural change. The reader treats unknown future versions as
+ * "ignore the cache and do a full sync" — forward-compat without
+ * crashing.
+ */
+export const LAST_SYNC_SCHEMA_VERSION = 1;
+
+/**
+ * Read the persisted last-sync state from ~/.claude/skillrepo/.last-sync.
+ * Returns null if the file doesn't exist, is malformed, or has a
+ * schema version we don't recognize.
+ *
+ * Intentionally lossy on parse failure — we can always do a full
+ * sync. We never crash the CLI on a corrupt cache file.
+ */
+export function readLastSync() {
+  const path = globalLastSyncPath();
+  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" ||
+    parsed.schemaVersion !== LAST_SYNC_SCHEMA_VERSION
+  ) {
+    return null;
+  }
+
+  return parsed;
+}
+
+/**
+ * Persist the last-sync state. Throws `diskError` on failure — the
+ * caller can decide whether to surface this as a warning or hard
+ * error. Most callers should treat a state-file write failure as
+ * non-fatal because the actual skill files were already written
+ * successfully.
+ */
+export function writeLastSync({ etag, syncedAt }) {
+  const path = globalLastSyncPath();
+  const dir = dirname(path);
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    throw diskError(`Cannot create ${dir}: ${err.message}`, { cause: err });
+  }
+  const body = {
+    schemaVersion: LAST_SYNC_SCHEMA_VERSION,
+    etag: etag ?? null,
+    syncedAt: syncedAt ?? new Date().toISOString(),
+  };
+  try {
+    writeFileSync(path, JSON.stringify(body, null, 2) + "\n", "utf-8");
+  } catch (err) {
+    throw diskError(`Cannot write ${path}: ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Run a library sync against the server.
+ *
+ * Strategy:
+ *   1. Clean up any orphan .tmp/.old directories from a crashed prior run
+ *   2. Read the last-sync state file
+ *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
+ *      cached ETag) AND `since` (always, for delta semantics)
+ *   4. Short-circuit on 304 — return `notModified: true`
+ *   5. For each skill in the response:
+ *      a. Write it via `writeSkillDir` — overwrites if changed
+ *      b. Skip writing skills with `filesIncomplete: true` (see comment)
+ *   6. For each tombstone in the response:
+ *      a. Call `removeSkillDir` — deletes from all configured targets
+ *   7. Persist the new ETag (if the response was complete) for the
+ *      next sync
+ *   8. Return the summary
+ *
+ * Error handling: any thrown error from the network or filesystem
+ * layer propagates unchanged. The caller (a command) decides how to
+ * present it. The state file is NOT updated on partial failure — a
+ * subsequent sync will retry with the previous ETag.
+ *
+ * @param {object} options
+ * @param {string} options.serverUrl
+ * @param {string} options.apiKey
+ * @param {string[]} [options.vendors] - Vendor keys; required unless `global`
+ * @param {boolean} [options.global]
+ * @param {object} [options.io] - Optional injected output streams. Defaults
+ *                  to process.stdout/stderr. The non-fatal warning emitted
+ *                  when `writeLastSync` fails uses io.stderr so tests that
+ *                  inject a capture stream don't lose that output.
+ * @param {NodeJS.WritableStream} [options.io.stderr=process.stderr]
+ * @returns {Promise<SyncSummary>}
+ */
+export async function runSync(options) {
+  const { serverUrl, apiKey, vendors, global, io } = options;
+  // Coalesce both `undefined` AND `null` to {}. Destructuring with
+  // `io = {}` only handles `undefined`, so an explicit `io: null`
+  // would otherwise blow up at the .stderr access below. Both
+  // round-2 reviewers caught this.
+  const resolvedIo = io ?? {};
+  const stderr = resolvedIo.stderr ?? process.stderr;
+
+  if (typeof serverUrl !== "string" || serverUrl.trim() === "") {
+    throw validationError("runSync: serverUrl is required");
+  }
+  if (typeof apiKey !== "string" || apiKey.trim() === "") {
+    throw validationError("runSync: apiKey is required");
+  }
+
+  // Step 1: clean orphans from prior crashes BEFORE doing any new writes
+  cleanupOrphans({ vendors, global });
+
+  // Step 2: read prior state
+  const lastSync = readLastSync();
+
+  // Step 3: fetch with conditional headers
+  const opts = {};
+  if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
+  if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
+
+  const result = await getLibrary(serverUrl, apiKey, opts);
+
+  // Step 4: 304 short-circuit
+  if (result.notModified) {
+    return {
+      added: 0,
+      updated: 0,
+      removed: 0,
+      notModified: true,
+      syncedAt: lastSync?.syncedAt ?? new Date().toISOString(),
+    };
+  }
+
+  // Step 5 + 6: apply skills + removals
+  const summary = {
+    added: 0,
+    updated: 0,
+    removed: 0,
+    notModified: false,
+    syncedAt: result.syncedAt,
+  };
+
+  // Apply removals FIRST so a re-add (skill removed then re-added with
+  // the same name) can't accidentally delete a freshly-written skill.
+  // The server's `removals` array is only populated on delta sync (when
+  // `since` was set), so on a full first-sync this loop is empty.
+  //
+  // We pass `tombstone.name` only (NOT `tombstone.owner`). The CLI
+  // places skills by name alone — `.claude/skills/<name>/` — not by
+  // `.claude/skills/<owner>/<name>/`. The server prevents two skills
+  // from different owners sharing the same `name` in one library, so
+  // this is safe today. If a future PR adds owner-namespaced
+  // directories, this loop must be updated to disambiguate.
+  // Note on error handling: any throw from `removeSkillDir` propagates
+  // out of this loop (no try/catch wrapper). That's intentional —
+  // partial tombstone application is dangerous because the user
+  // would have local files for skills that no longer belong in their
+  // library. Surface the first failure loudly so the user can fix
+  // the cause and re-run sync.
+  for (const tombstone of result.removals) {
+    const removeResult = removeSkillDir(tombstone.name, { vendors, global });
+    if (removeResult.removed.length > 0) {
+      summary.removed++;
+    }
+    // notFound: silently ignored. A tombstone for a skill that
+    // never existed on this machine (added on machine A, removed on
+    // machine A, this is machine B) is not an error.
+  }
+
+  // Apply skills. We don't have on-disk SHAs to compute "unchanged"
+  // efficiently — `unchanged` stays 0 unless a future enhancement
+  // adds disk-side hashing. For the user-facing summary, "added" vs
+  // "updated" is distinguished by whether the target directory
+  // already existed before the write.
+  //
+  // Skills with `filesIncomplete: true` are SKIPPED and the ETag
+  // is NOT persisted — the server returned a partial payload because
+  // one or more files failed to inline from blob storage. Writing
+  // a partial skill would leave the user with broken resource
+  // references (the SKILL.md body would point to files that don't
+  // exist on disk).
+  let anyIncomplete = false;
+  for (const skill of result.skills) {
+    if (skill.filesIncomplete) {
+      anyIncomplete = true;
+      continue;
+    }
+    const wasAlreadyOnDisk = isAnyTargetPresent(skill.name, { vendors, global });
+    writeSkillDir(skill, { vendors, global });
+    if (wasAlreadyOnDisk) {
+      summary.updated++;
+    } else {
+      summary.added++;
+    }
+  }
+
+  // Step 7: persist new ETag (only if the response was complete)
+  if (!anyIncomplete && result.etag) {
+    try {
+      writeLastSync({ etag: result.etag, syncedAt: result.syncedAt });
+    } catch (err) {
+      // Non-fatal — the skills are on disk, we just won't get the
+      // 304 short-circuit on the next run. Surface a warning via
+      // the injected stderr stream so tests can capture it.
+      stderr.write(
+        `  warning: failed to persist last-sync state (${err.message}). ` +
+          `Next sync will be a full fetch.\n`,
+      );
+    }
+  }
+
+  return summary;
+}
+
+// ── Internals ──────────────────────────────────────────────────────────
+
+/**
+ * Check whether ANY of the configured placement targets already
+ * contains a directory for the given skill name. Used to distinguish
+ * "added" from "updated" in the summary. Cheap — just an `existsSync`
+ * per target.
+ */
+function isAnyTargetPresent(skillName, options) {
+  if (options.global) {
+    return existsSync(claudeSkillsGlobal(skillName));
+  }
+  if (!Array.isArray(options.vendors) || options.vendors.length === 0) {
+    return false;
+  }
+  if (options.vendors.includes("claudeCode")) {
+    if (existsSync(claudeSkillsProject(skillName))) return true;
+  }
+  if (
+    options.vendors.includes("cursor") ||
+    options.vendors.includes("windsurf") ||
+    options.vendors.includes("vscode")
+  ) {
+    if (existsSync(projectSkillsFallback(skillName))) return true;
+  }
+  return false;
+}

package/src/test/commands/add.test.mjs

@@ -0,0 +1,285 @@
+/**
+ * Unit/integration tests for src/commands/add.mjs (PR3a of #646).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runAdd } from "../../commands/add.mjs";
+import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import { CliError, EXIT_VALIDATION, EXIT_AUTH, EXIT_SCOPE } 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(owner, name) {
+  return {
+    owner,
+    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-add-"));
+  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;
+
+  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("runAdd — happy path", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("adds a new skill to the library and writes files locally", async () => {
+    // Default server response is 201 added; register the skill for the
+    // follow-up GET /api/v1/skills/{owner}/{name}
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+
+    await runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper"], { stdout });
+
+    // POST body captured by mock server
+    const postBody = server.getLastPostBody();
+    assert.deepEqual(postBody, { owner: "alice", name: "pdf-helper" });
+
+    // Local files written
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+
+    // Human summary mentions "Added"
+    assert.match(stdout.text(), /Added @alice\/pdf-helper/);
+  });
+
+  it("idempotent: already-in-library re-fetches and writes (refresh semantics)", async () => {
+    // Configure the server to respond with 409 already_in_library
+    server.setAddResponse("alice", "pdf-helper", {
+      status: 409,
+      body: { error: "Skill is already in your library", code: "already_in_library" },
+    });
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+
+    await runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper"], { stdout });
+
+    // Local files still written (refresh semantics)
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+
+    // Summary mentions the refresh path
+    assert.match(stdout.text(), /already in your library — refreshed/);
+  });
+
+  it("--json outputs added status on fresh add", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runAdd(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json", "@alice/pdf-helper"],
+      { stdout },
+    );
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "added");
+    assert.equal(json.owner, "alice");
+    assert.equal(json.name, "pdf-helper");
+    assert.equal(json.filesWritten, 1);
+  });
+
+  it("--json outputs already-in-library status on refresh", async () => {
+    server.setAddResponse("alice", "pdf-helper", {
+      status: 409,
+      body: { code: "already_in_library" },
+    });
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+
+    await runAdd(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json", "@alice/pdf-helper"],
+      { stdout },
+    );
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "already-in-library");
+  });
+
+  it("--global writes to home dir", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runAdd(
+      ["--key", VALID_KEY, "--url", serverUrl, "--global", "@alice/pdf-helper"],
+      { stdout },
+    );
+    const dir = resolvePlacementDir("claudeGlobal", "pdf-helper");
+    assert.ok(existsSync(dir));
+    assert.ok(dir.startsWith(process.env.HOME));
+  });
+
+  it("--ide cursor writes to the project /skills/ fallback", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runAdd(
+      ["--key", VALID_KEY, "--url", serverUrl, "--ide", "cursor", "@alice/pdf-helper"],
+      { stdout },
+    );
+    const dir = resolvePlacementDir("projectFallback", "pdf-helper");
+    assert.ok(existsSync(dir));
+  });
+});
+
+describe("runAdd — error paths", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("rejects missing identifier", async () => {
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects malformed identifier", async () => {
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "not-an-identifier"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects extra positional after identifier", async () => {
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@a/b", "@c/d"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("404 not-found returns clean validation error", async () => {
+    server.setAddResponse("alice", "missing", {
+      status: 404,
+      body: { error: "Skill not found", code: "not_found" },
+    });
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/missing"], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /not found/i.test(err.message),
+    );
+  });
+
+  it("409 self-ownership rejects with clean error", async () => {
+    server.setAddResponse("alice", "my-skill", {
+      status: 409,
+      body: {
+        error: "Cannot add your own skill to your library",
+        code: "self_ownership",
+      },
+    });
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/my-skill"], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /your own skill/i.test(err.message),
+    );
+  });
+
+  it("403 plan-limit maps to validationError with billing hint", async () => {
+    server.setAddResponse("alice", "limit-test", {
+      status: 403,
+      body: {
+        error: "Your free plan allows up to 5 library skills.",
+        code: "plan_limit",
+      },
+    });
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/limit-test"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /plan/i.test(err.message),
+    );
+  });
+
+  it("403 scope-required maps to scopeError (exit 4)", async () => {
+    server.setAddResponse("alice", "scope-test", {
+      status: 403,
+      body: { error: "Insufficient scope", code: "scope_required" },
+    });
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/scope-test"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+    );
+  });
+
+  it("401 auth error exits 2", async () => {
+    server.setAddResponse("alice", "auth-test", {
+      status: 401,
+      body: { error: "Invalid access key" },
+    });
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/auth-test"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("server-returned wrong owner/name is rejected (defense in depth)", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("bob", "wrong"));
+    // POST succeeds with default 201, but the follow-up GET returns a
+    // mismatched skill.
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper"], { stdout }),
+      (err) => err instanceof CliError && /wrong skill/i.test(err.message),
+    );
+  });
+
+  it("filesIncomplete skill is rejected", async () => {
+    const incomplete = makeSkill("alice", "incomplete");
+    incomplete.filesIncomplete = true;
+    server.setSkillResponse("alice", "incomplete", incomplete);
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/incomplete"], { stdout }),
+      (err) => err instanceof CliError && /incomplete/i.test(err.message),
+    );
+  });
+
+  it("POST succeeds but follow-up GET returns 404 surfaces as validation error", async () => {
+    // Server-side inconsistency: add succeeded (default 201) but the
+    // GET returns 404. The add command surfaces this as a clear error
+    // pointing the user at `update` rather than silently writing nothing.
+    // NOTE: no skillResponse registered for "alice/ghost" → default 404
+    await assert.rejects(
+      () => runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/ghost"], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /added to your library but the fetch returned 404/i.test(err.message),
+    );
+  });
+});