skillrepo 2.0.0 → 3.1.0

package/src/commands/uninstall.mjs

@@ -0,0 +1,484 @@
+/**
+ * `skillrepo uninstall` (#885).
+ *
+ * Removes every SkillRepo artifact from the project (default) and
+ * optionally from user-global state (`--global`). Uses the shared
+ * `artifact-registry` catalog to drive per-descriptor removers; the
+ * registry is the single source of truth between init (which writes
+ * these files) and uninstall (which tears them down).
+ *
+ * Design guarantees (from issue #885):
+ *
+ *   - Surgical. Shared files (`.mcp.json`, `.gitignore`, `.env.local`,
+ *     `.claude/settings.local.json`) are parsed, SkillRepo-owned
+ *     entries are removed, and non-SkillRepo content is written back
+ *     unchanged. The file itself is never deleted.
+ *   - Offline. No server call is made. Uninstall works with a
+ *     revoked key, no network, or after the user deleted their
+ *     account — the user's local state is fully CLI-local.
+ *   - Idempotent. Running twice produces the same end state as
+ *     running once, with the second run reporting "Nothing to
+ *     remove" and exiting 0.
+ *   - Continue-with-errors. A single failing artifact does not
+ *     abort the operation; other artifacts are still processed.
+ *     The final exit code is 3 (EXIT_DISK) if any artifact failed,
+ *     0 otherwise.
+ *   - Interactive confirmation. The command prints a full list of
+ *     what will be removed BEFORE touching any file, then prompts.
+ *     `--yes` skips the prompt; `--dry-run` skips execution
+ *     entirely and just prints the preview.
+ *   - Stream injection. Every write goes through the injected
+ *     `io.stdout` / `io.stderr` streams — no `console.log`. Matches
+ *     the pattern every other command uses so tests can capture
+ *     output without monkey-patching process streams.
+ *
+ * Not in scope (explicit per the architect design):
+ *   - v2.0.0 artifacts (.claude/rules/skillrepo-*, hooks, etc.).
+ *     v3.0.0 is the minimum supported version; users of earlier
+ *     versions clean up manually.
+ *   - The `<cwd>/skills/` fallback directory (tracked in #876).
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+
+import {
+  ARTIFACT_REGISTRY,
+  artifactsByScope,
+} from "../lib/artifact-registry.mjs";
+import { removeGitignore } from "../lib/removers/gitignore.mjs";
+import { removeEnvLocal } from "../lib/removers/env-local.mjs";
+import { removeClaudeMcp } from "../lib/removers/claude-mcp.mjs";
+import { removeCursorMcp } from "../lib/removers/cursor-mcp.mjs";
+import { removeVscodeMcp } from "../lib/removers/vscode-mcp.mjs";
+import { removeWindsurfMcp } from "../lib/removers/windsurf-mcp.mjs";
+import { removeSettingsSessionHook } from "../lib/removers/settings.mjs";
+import { confirm } from "../lib/prompt.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { diskError } from "../lib/errors.mjs";
+
+// ── Descriptor → remover binding ──────────────────────────────────
+
+/**
+ * Per-descriptor dispatch table. The registry is a pure data module;
+ * the actual remover implementations live in `src/lib/removers/*.mjs`.
+ * This map is the single place where "descriptor id" meets "function
+ * that removes it." If a new descriptor is added to the registry
+ * without a matching entry here, the CI enforcement test at
+ * `src/test/lib/artifact-registry.test.mjs` fails.
+ *
+ * Directory artifacts (`skills-dir-project`, `skills-dir-global`,
+ * `global-config-dir`) are handled inline by `removeDirectoryArtifact`
+ * below rather than via separate modules — the removal is a single
+ * `rmSync({ recursive: true })` call with a basename assertion.
+ */
+const FILE_REMOVERS = Object.freeze({
+  "claude-mcp-entry": removeClaudeMcp,
+  "cursor-mcp-entry": removeCursorMcp,
+  "vscode-mcp-entry": removeVscodeMcp,
+  // vscode-mcp-input is handled by the same remover as vscode-mcp-entry
+  // (both live in one file; one call handles both in a single parse-
+  // mutate-write cycle). The registry still lists them as two
+  // descriptors for catalog completeness, but only one remover call
+  // is made.
+  "vscode-mcp-input": null,
+  "env-local-key": removeEnvLocal,
+  "gitignore-entries": removeGitignore,
+  "settings-session-hook": removeSettingsSessionHook,
+  // Global-scope variant added in #884: routes to the SAME remover
+  // but with `{ global: true }` so the pathFn resolves to
+  // ~/.claude/settings.local.json. The dryRun option is forwarded
+  // from the orchestrator's call site so preview + execute passes
+  // both work unchanged.
+  "settings-session-hook-global": (opts = {}) =>
+    removeSettingsSessionHook({ ...opts, global: true }),
+  "windsurf-mcp-entry": removeWindsurfMcp,
+  // Directory artifacts — handled inline.
+  "skills-dir-project": null,
+  "skills-dir-global": null,
+  "global-config-dir": null,
+});
+
+/**
+ * Inline remover for directory artifacts. Both the preview (dryRun)
+ * path and the execute path share this function. Preserves a strict
+ * basename assertion before any `rmSync` — if the path resolves to
+ * something other than `skills` / `skillrepo`, the removal is
+ * refused with a structured error rather than executing. This is
+ * defense in depth against a path-resolution bug or a future
+ * refactor that changes `claudeSkillsProjectRoot()` etc.
+ */
+function removeDirectoryArtifact(descriptor, { dryRun }) {
+  const path = descriptor.pathFn();
+  const displayPath = descriptor.displayPath;
+
+  if (!existsSync(path)) {
+    return { path: displayPath, action: "skipped" };
+  }
+
+  // Basename safety net on the RESOLVED path — following symlinks
+  // first. The earlier version only checked the path-string's last
+  // segment, which a `.claude/skills` symlink pointing at
+  // `/home/user/important-data/` would have bypassed: basename of
+  // the symlink was "skills" but `rmSync` would have walked the
+  // target. architect review round 1 flagged this as a defense-
+  // in-depth gap. `realpathSync` throws on dangling symlinks, so
+  // wrap it — if the target doesn't resolve, refuse rather than
+  // guessing.
+  let realPath;
+  try {
+    realPath = realpathSync(path);
+  } catch (err) {
+    return {
+      path: displayPath,
+      action: "skipped",
+      error: `Cannot resolve ${path}: ${err.message}. Refusing to rmSync a path that doesn't resolve.`,
+    };
+  }
+  const basename = realPath.split(/[\\/]/).filter(Boolean).pop();
+  if (basename !== "skills" && basename !== "skillrepo") {
+    return {
+      path: displayPath,
+      action: "skipped",
+      error: `Refusing to recursively remove ${path} (resolved to ${realPath}): basename "${basename}" is neither "skills" nor "skillrepo".`,
+    };
+  }
+
+  let childCount = 0;
+  try {
+    if (statSync(path).isDirectory()) {
+      childCount = readdirSync(path).length;
+    }
+  } catch {
+    // Stat failure is tolerable — we just lose the child-count detail.
+  }
+
+  if (dryRun) {
+    return {
+      path: displayPath,
+      action: "would-remove",
+      detail: childCount > 0 ? `${childCount} entries` : undefined,
+    };
+  }
+
+  rmSync(path, { recursive: true, force: true });
+
+  return {
+    path: displayPath,
+    action: "removed",
+    detail: childCount > 0 ? `${childCount} entries` : undefined,
+  };
+}
+
+// ── Command entry point ──────────────────────────────────────────
+
+/**
+ * Run uninstall.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ * @returns {Promise<void>}
+ */
+export async function runUninstall(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const { green, yellow, bold } = makeColors(stdout);
+
+  const { dryRun, yes, global, json } = parseUninstallFlags(argv);
+
+  // ── Scope filter ────────────────────────────────────────────────
+  // Project artifacts always included. Global artifacts only when
+  // `--global` is passed — a fresh-install-on-one-project uninstall
+  // should not nuke a multi-project user's shared credentials.
+  const descriptors = global
+    ? ARTIFACT_REGISTRY
+    : artifactsByScope("project");
+
+  // ── Scan phase (dry run every remover, collect preview) ────────
+  //
+  // Every descriptor runs with `dryRun: true` first so we can show
+  // the user a complete list before they confirm. The vscode-mcp-
+  // input descriptor is a catalog sibling of vscode-mcp-entry and
+  // shares a remover — running the remover twice would double-count,
+  // so we skip the second-descriptor entry.
+  const scanned = [];
+  for (const d of descriptors) {
+    if (d.id === "vscode-mcp-input") continue;
+    const result = runForDescriptor(d, { dryRun: true });
+    if (result.action === "would-remove" || result.error) {
+      scanned.push({ descriptor: d, result });
+    }
+  }
+
+  // ── Nothing to do ──────────────────────────────────────────────
+  if (scanned.length === 0) {
+    if (json) {
+      stdout.write(
+        JSON.stringify(
+          {
+            action: dryRun ? "dry-run" : "nothing-to-remove",
+            scope: global ? "global" : "project",
+            removed: [],
+            "would-remove": [],
+            errors: [],
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    } else {
+      stdout.write(
+        `\n  Nothing to remove. SkillRepo is not installed in this ${global ? "account" : "project"}.\n\n`,
+      );
+    }
+    return;
+  }
+
+  // ── Render preview ─────────────────────────────────────────────
+  if (!json) {
+    stdout.write(`\n  ${bold("SkillRepo Uninstall")}\n\n`);
+    stdout.write(
+      `  ${dryRun ? "Would remove" : "The following will be removed from " + (global ? "global state and " : "") + "this project"}:\n\n`,
+    );
+    for (const { descriptor, result } of scanned) {
+      stdout.write(renderPreviewLine(descriptor, result));
+    }
+    if (!global) {
+      stdout.write(
+        `\n  Nothing will be removed from global state (~/.claude/skillrepo/, Windsurf config).\n`,
+      );
+      stdout.write(`  Run with --global to also remove global state.\n`);
+    }
+    stdout.write("\n");
+  }
+
+  // ── Dry-run short-circuit ──────────────────────────────────────
+  if (dryRun) {
+    if (json) {
+      stdout.write(
+        JSON.stringify(
+          {
+            action: "dry-run",
+            scope: global ? "global" : "project",
+            "would-remove": scanned.map(({ descriptor, result }) => ({
+              id: descriptor.id,
+              path: result.path,
+              detail: result.detail,
+            })),
+            errors: scanned
+              .filter(({ result }) => result.error)
+              .map(({ descriptor, result }) => ({
+                id: descriptor.id,
+                path: result.path,
+                error: result.error,
+              })),
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    }
+    return;
+  }
+
+  // ── Prompt for confirmation (unless --yes or --json) ───────────
+  if (!yes && !json) {
+    const ok = await confirm("Proceed?", false);
+    if (!ok) {
+      stdout.write("  Cancelled. Nothing was removed.\n\n");
+      return;
+    }
+  }
+
+  // ── Execute phase ──────────────────────────────────────────────
+  const executed = [];
+  const errors = [];
+  for (const { descriptor } of scanned) {
+    try {
+      const result = runForDescriptor(descriptor, { dryRun: false });
+      executed.push({ descriptor, result });
+      if (result.error) {
+        errors.push({ descriptor, result });
+      }
+    } catch (err) {
+      // Re-thrown error (e.g., atomic-write rename failure). Continue
+      // with the rest; aggregate and report at the end.
+      const result = {
+        path: descriptor.displayPath,
+        action: "skipped",
+        error: err?.message ?? String(err),
+      };
+      executed.push({ descriptor, result });
+      errors.push({ descriptor, result });
+    }
+  }
+
+  // ── Render summary ─────────────────────────────────────────────
+  if (json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: errors.length === 0 ? "uninstalled" : "partially-uninstalled",
+          scope: global ? "global" : "project",
+          removed: executed
+            .filter(({ result }) => result.action === "removed")
+            .map(({ descriptor, result }) => ({
+              id: descriptor.id,
+              path: result.path,
+              detail: result.detail,
+            })),
+          errors: errors.map(({ descriptor, result }) => ({
+            id: descriptor.id,
+            path: result.path,
+            error: result.error,
+          })),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    for (const { result } of executed) {
+      if (result.action === "removed") {
+        stdout.write(`  ${green("✓")} ${result.path}`);
+        if (result.detail) stdout.write(` (${result.detail})`);
+        stdout.write("\n");
+      }
+    }
+    if (errors.length > 0) {
+      stderr.write(`\n  ${yellow("⚠")} Some artifacts could not be removed:\n`);
+      for (const { result } of errors) {
+        stderr.write(`    • ${result.path}: ${result.error}\n`);
+      }
+      stderr.write(
+        `  Fix the issues above and re-run \`skillrepo uninstall\`.\n\n`,
+      );
+    } else {
+      stdout.write(
+        `\n  SkillRepo has been removed from this ${global ? "account" : "project"}.\n`,
+      );
+      if (!global && !json) {
+        stdout.write(
+          `  Your access key at ~/.claude/skillrepo/config.json is still valid.\n`,
+        );
+      }
+      stdout.write(`  Run \`skillrepo init\` to re-initialize.\n\n`);
+    }
+  }
+
+  // Propagate the partial-failure exit code through the normal
+  // CliError mechanism. The dispatcher at bin/skillrepo.mjs catches
+  // any CliError and exits with its carried exit code, so throwing
+  // here (rather than calling process.exit directly) matches the
+  // pattern every other command uses AND keeps the test runner
+  // alive when uninstall is exercised from node:test.
+  if (errors.length > 0) {
+    throw diskError(
+      `Uninstall completed with ${errors.length} error${errors.length === 1 ? "" : "s"}. See output above for details.`,
+    );
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Dispatch a descriptor to its remover. Directory kinds go through
+ * the inline `removeDirectoryArtifact`; everything else goes through
+ * the `FILE_REMOVERS` table. Returns a `{ path, action, ... }`
+ * shape that the caller can consume uniformly.
+ */
+function runForDescriptor(descriptor, { dryRun }) {
+  if (descriptor.kind === "directory") {
+    return removeDirectoryArtifact(descriptor, { dryRun });
+  }
+  const fn = FILE_REMOVERS[descriptor.id];
+  if (!fn) {
+    // Only reachable for descriptors that share a remover with a
+    // sibling (e.g. vscode-mcp-input → handled via vscode-mcp-entry).
+    // Callers already skip those, so reaching here is a programming
+    // error — surface it loudly.
+    throw new Error(
+      `No remover bound to artifact descriptor "${descriptor.id}".`,
+    );
+  }
+  return fn({ dryRun });
+}
+
+function renderPreviewLine(descriptor, result) {
+  const prefix = result.error
+    ? "   [error] "
+    : descriptor.kind === "directory"
+      ? "   [dir]   "
+      : descriptor.kind === "line" || descriptor.kind === "section"
+        ? "   [lines] "
+        : "   [entry] ";
+  const detail = result.error
+    ? `→ ${result.error}`
+    : result.detail
+      ? `(${result.detail})`
+      : "";
+  return `${prefix}${result.path.padEnd(40)} ${detail}\n`;
+}
+
+function parseUninstallFlags(argv) {
+  let dryRun = false;
+  let yes = false;
+  // Reuse resolveFlags for the standard --global / --json / --ide /
+  // --key / --url shape. resolveFlags ignores unknown flags when an
+  // acceptPositional callback is provided that can consume them —
+  // the callback pattern matches init's own parsing.
+  const flags = resolveFlags(argv, {
+    requireAuth: false,
+    skipConfig: true,
+    acceptPositional(arg) {
+      if (arg === "--dry-run" || arg === "-n") {
+        dryRun = true;
+        return 1;
+      }
+      if (arg === "--yes" || arg === "-y") {
+        yes = true;
+        return 1;
+      }
+      return false;
+    },
+  });
+
+  // `global` and `json` live on flags via resolveFlags.
+  return {
+    dryRun,
+    yes,
+    global: Boolean(flags.global),
+    json: Boolean(flags.json),
+  };
+}
+
+// ── Color helpers (local — same pattern as init.mjs) ────────────
+//
+// The three color wrappers are constructed per-invocation inside
+// `runUninstall` via `makeColors(stdout)` below so they honor the
+// INJECTED stdout stream (not `process.stdout`). Under test the
+// capture stream is not a TTY, so ANSI codes never leak into
+// asserted output; under real use the user's TTY stream drives
+// color as expected. Matches `init.mjs`'s `makePrinter` pattern
+// exactly — the inconsistency was flagged by the code-reviewer.
+
+const GREEN = (s) => `\x1b[32m${s}\x1b[0m`;
+const YELLOW = (s) => `\x1b[33m${s}\x1b[0m`;
+const BOLD = (s) => `\x1b[1m${s}\x1b[0m`;
+
+function makeColors(stdout) {
+  const useColor = Boolean(stdout?.isTTY) && !process.env.NO_COLOR;
+  const paint = (color) => (s) => (useColor ? color(s) : s);
+  return {
+    green: paint(GREEN),
+    yellow: paint(YELLOW),
+    bold: paint(BOLD),
+  };
+}

package/src/commands/update.mjs

@@ -0,0 +1,184 @@
+/**
+ * `skillrepo update` (#675).
+ *
+ * Re-syncs the user's library against the registry by calling the
+ * shared `sync.mjs` engine. This is a thin command wrapper around
+ * `runSync` plus argument parsing and a printer.
+ *
+ * Flags (parsed by the shared `resolveFlags` helper):
+ *   --global         Write to ~/.claude/skills/ instead of project-local
+ *   --ide <list>     Comma-separated vendor list
+ *   --json           Print summary as JSON
+ *   --key <key>      Override config-file access key
+ *   --url <url>      Override config-file server URL
+ *
+ * v3.1.0 session-hook mode (#884):
+ *   --session-hook   Enforces the Claude Code SessionStart hook
+ *                    contract: EXIT 0 ON ALL ERRORS, silent on 304,
+ *                    one-line summary on changes, one-line failure
+ *                    message on error. See `runUpdate` JSDoc for the
+ *                    full contract. When this flag is absent, the
+ *                    command behaves as before (exit non-zero on
+ *                    network / auth / disk failures).
+ *
+ * Exit codes are inherited from sync.mjs / http.mjs error types,
+ * EXCEPT under `--session-hook` — see the flag's contract below.
+ */
+
+import { runSync } from "../lib/sync.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+
+/**
+ * Run `update`.
+ *
+ * NORMAL MODE (no `--session-hook`): throws CliError on any failure;
+ * the dispatcher formats and exits. This is the pre-v3.1.0 behavior.
+ *
+ * SESSION-HOOK MODE (`--session-hook`): invoked by the Claude Code
+ * SessionStart hook #884 installs. Enforces this contract:
+ *
+ *   - 304 Not Modified → exit 0, NO output.
+ *   - 200 with changes → exit 0, ONE line: `[SkillRepo] Library synced: N added, N updated, N removed.`
+ *   - Any failure → exit 0, ONE line: `[SkillRepo] Sync failed: <reason>.`
+ *
+ * The "exit 0 on all errors" contract is non-negotiable: a sync
+ * failure must NEVER block a Claude Code session start. Users on a
+ * plane, behind a corporate firewall, or with a rotated key must
+ * still be able to open Claude Code. The installer adds a `|| true`
+ * shell backstop for defense in depth, but this flag is the first
+ * line of defense — a buggy implementation that throws would be
+ * caught by `|| true`, but the visible failure-message line would
+ * be lost. Honoring the contract from inside this function ensures
+ * the user sees the reason.
+ *
+ * @param {string[]} argv
+ * @param {object} [io] - Optional injected streams for testability.
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runUpdate(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  // `stderr` is not used directly — the session-hook path pipes to
+  // BLACK_HOLE_STREAM and the normal path forwards `io` to runSync
+  // which reads `io.stderr` itself.
+
+  // ── Pre-pass: detect --session-hook BEFORE resolveFlags runs ─────
+  //
+  // resolveFlags can throw in three categories we must catch under
+  // session-hook mode:
+  //   - `authError` when no access key is configured (e.g., session
+  //     fires before `skillrepo init` has run — a real first-run
+  //     scenario, not synthetic)
+  //   - `validationError` on unknown flags
+  //   - `validationError` from parseVendorList on a malformed --ide
+  //
+  // All three happen INSIDE resolveFlags, before our try/catch block
+  // could see them if we called it after. The only robust answer is
+  // to detect --session-hook without invoking resolveFlags, then
+  // wrap resolveFlags + runSync together in the error handler.
+  //
+  // A simple argv scan is safe here: `--session-hook` has no value
+  // argument, so a plain `.includes` match can't misinterpret
+  // positional args. This DOES NOT accept variations like
+  // `--session-hook=true` or `-SH` — single canonical form only,
+  // matching what the installer writes.
+  const sessionHook = argv.includes("--session-hook");
+
+  if (sessionHook) {
+    // Session-hook mode: wrap EVERY error path in try/catch so a
+    // sync failure cannot block a Claude Code session start.
+    try {
+      const flags = resolveFlags(argv, {
+        acceptPositional(arg) {
+          // resolveFlags sees --session-hook as unknown unless we
+          // consume it here. Kept for the non-error path — the
+          // real "catch errors" logic is the outer try.
+          if (arg === "--session-hook") return 1;
+          return false;
+        },
+      });
+      const vendors = effectiveVendors(flags);
+
+      const summary = await runSync({
+        serverUrl: flags.serverUrl,
+        apiKey: flags.apiKey,
+        vendors,
+        global: flags.global,
+        io: { stdout: BLACK_HOLE_STREAM, stderr: BLACK_HOLE_STREAM },
+      });
+      const total = summary.added + summary.updated + summary.removed;
+      if (summary.notModified || total === 0) {
+        // 304 Not Modified OR 200 with zero deltas — silent by
+        // contract. Users should not see "Syncing..." on every
+        // session for no visible value.
+        return;
+      }
+      stdout.write(
+        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed.\n`,
+      );
+    } catch (err) {
+      // The one-line failure message is the user's primary signal
+      // that something's wrong. Do not surface a stack trace — the
+      // hook-runner's UI treats hook output as a system message and
+      // multi-line tracebacks clutter it.
+      //
+      // Defensive: `err?.message ?? String(err)` handles a non-Error
+      // throw (plain string, number, symbol) without crashing the
+      // interpolation. The `|| true` shell backstop remains as the
+      // absolute last line of defense.
+      const reason = err?.message ?? String(err);
+      try {
+        stdout.write(`[SkillRepo] Sync failed: ${reason}\n`);
+      } catch {
+        // Writing to a closed pipe etc. — the `|| true` wrapper
+        // will save the session. Nothing more to do here.
+      }
+    }
+    return;
+  }
+
+  // ── Normal mode: original behavior ───────────────────────────────
+  // Forward `io` to runSync so the non-fatal "failed to persist
+  // last-sync state" warning lands on the injected stderr stream
+  // when tests inject one.
+  const flags = resolveFlags(argv);
+  const vendors = effectiveVendors(flags);
+
+  const summary = await runSync({
+    serverUrl: flags.serverUrl,
+    apiKey: flags.apiKey,
+    vendors,
+    global: flags.global,
+    io,
+  });
+
+  if (flags.json) {
+    stdout.write(JSON.stringify(summary, null, 2) + "\n");
+    return;
+  }
+  printSummary(summary, stdout);
+}
+
+function printSummary(s, out) {
+  const total = s.added + s.updated + s.removed;
+  if (s.notModified || total === 0) {
+    out.write("  ✓ Library is up to date.\n");
+    return;
+  }
+  out.write("\n  Library sync complete:\n");
+  if (s.added > 0)   out.write(`    + ${s.added} added\n`);
+  if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
+  if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);
+  out.write("\n");
+}
+
+/**
+ * Black-hole writable stream used in session-hook mode to silence
+ * `runSync`'s internal warning prints. The command's own output
+ * (the success/failure one-liner) goes to the real stdout so the
+ * user sees it in the Claude Code session system message.
+ */
+const BLACK_HOLE_STREAM = {
+  write: () => true,
+  isTTY: false,
+};