skillrepo 3.0.0 → 3.1.1

package/src/lib/mergers/session-hook.mjs

@@ -0,0 +1,378 @@
+/**
+ * SessionStart hook installer for Claude Code (#884).
+ *
+ * The inverse partner of `src/lib/removers/settings.mjs` (#885). Both
+ * modules identify SkillRepo-owned hooks via the shared
+ * `SESSION_HOOK_FINGERPRINT` constant from `artifact-registry.mjs` —
+ * the single source of truth that keeps the installer's output and
+ * the remover's predicate in lockstep. The round-trip is verified by
+ * `src/test/mergers/session-hook.test.mjs`.
+ *
+ * ## What this installs
+ *
+ * A Claude Code SessionStart hook shaped as:
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [
+ *         {
+ *           "hooks": [
+ *             { "type": "command", "command": "/abs/path/skillrepo update --session-hook 2>&1 || true" }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * Claude Code invokes every hook in `hooks.SessionStart[*].hooks[*]`
+ * on session start. The command shape is load-bearing in three ways:
+ *
+ *   1. **Absolute path**: resolved at install time via `which skillrepo`.
+ *      Claude Code's hook runner does not load the user's interactive
+ *      shell profile, so relying on PATH would break for any user
+ *      whose global `skillrepo` isn't on the minimal shell PATH.
+ *
+ *   2. **`--session-hook` flag**: tells `update` to honor the
+ *      exit-0-on-all-errors contract. A sync failure must NEVER block
+ *      a session start — offline, server 500, revoked key, or any
+ *      other error → exit 0 with a single failure-message line.
+ *
+ *   3. **`|| true` shell backstop**: non-negotiable. If a bug in
+ *      `--session-hook` ever causes non-zero exit, the shell layer
+ *      still returns 0. Two layers of defense. Per handoff learning
+ *      #9 — cannot be removed in a future refactor.
+ *
+ * ## Why settings.local.json (not settings.json)
+ *
+ * Per-developer. Claude Code's `settings.local.json` is gitignored
+ * (v3.0.0 init adds it to the ignore section at step 3). A team-
+ * shared hook in `settings.json` would either silently no-op for
+ * developers without `skillrepo` installed, or (worse) error on
+ * every session for them. Local-scope avoids both.
+ *
+ * ## Idempotency
+ *
+ * Re-running `skillrepo init` or `skillrepo session-sync enable`
+ * should produce the same end state as the first run. The installer:
+ *   - writes fresh if no SkillRepo hook is present
+ *   - updates in place if the fingerprint matches but the absolute
+ *     path changed (e.g. user moved the binary)
+ *   - no-ops if the exact command is already present
+ * Non-SkillRepo hooks and unrelated groups are never touched.
+ *
+ * ## Atomic writes
+ *
+ * settings.local.json is parsed by Claude Code at session start. A
+ * half-written file would break every future session until manually
+ * fixed. `writeFileAtomic` (temp file + rename + unlink-on-failure)
+ * guarantees either the new content is fully in place or the old
+ * content is fully preserved.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { SESSION_HOOK_FINGERPRINT } from "../artifact-registry.mjs";
+import {
+  claudeSettingsLocal,
+  claudeSettingsLocalGlobal,
+} from "../paths.mjs";
+import { diskError, validationError } from "../errors.mjs";
+import { removeSettingsSessionHook } from "../removers/settings.mjs";
+import { isNpxInvocation } from "../cli-config.mjs";
+import { platformConventions } from "../platform.mjs";
+
+/**
+ * Build the hook command string for a given absolute path. Exported
+ * so tests can assert the exact bytes the installer writes.
+ *
+ * Shell shape is platform-specific — see `platform.mjs` for the full
+ * rationale. Summary:
+ *
+ *   - **POSIX** (macOS, Linux): `<path> update --session-hook 2>&1 || true`.
+ *     `|| true` catches any non-zero exit at the shell level; primary
+ *     defense is the `--session-hook` flag contract in the Node process.
+ *   - **Windows** (cmd.exe / PowerShell): `<path> update --session-hook 2>&1`.
+ *     `|| true` omitted because cmd.exe doesn't know the `true` builtin.
+ *     `--session-hook` contract is the only defense; consequences of
+ *     binary-vanished scenarios are slightly noisier in Claude Code's
+ *     session log but still non-blocking.
+ *
+ * The suffix is supplied by `platformConventions().hookShellSuffix` —
+ * this function doesn't know which OS it's targeting, it just
+ * concatenates the convention's suffix.
+ *
+ * @param {string} binaryPath - Absolute path to the `skillrepo` binary.
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Default: `os.platform()`.
+ * @returns {string} The full shell command string.
+ */
+export function buildHookCommand(binaryPath, { platform: platformOverride } = {}) {
+  if (typeof binaryPath !== "string" || binaryPath.length === 0) {
+    throw validationError(
+      "buildHookCommand: binaryPath must be a non-empty string.",
+    );
+  }
+  const conv = platformConventions({ platform: platformOverride });
+  return `${binaryPath} update --session-hook 2>&1${conv.hookShellSuffix}`;
+}
+
+/**
+ * Resolve the absolute path of the `skillrepo` binary via `which`.
+ * Returns null if resolution fails (e.g. user ran `npx skillrepo init`
+ * without a global install) — the caller should skip hook installation
+ * with a clear warning rather than fail init.
+ *
+ * @returns {string | null}
+ */
+export function resolveSkillrepoBinary({ platform: platformOverride } = {}) {
+  // npx-invocation guard. Returns null early before any OS-specific
+  // logic runs — npx detection is platform-neutral (argv and env
+  // checks only) so it doesn't need the conventions object.
+  if (isNpxInvocation()) {
+    return null;
+  }
+
+  // Platform-specific binary locator name comes from the single
+  // source of truth in platform.mjs. Adding a new locator for a
+  // new platform is one edit in platform.mjs, not a scattered
+  // search for `platform() === "win32"` conditionals. See
+  // platform.mjs for the full rationale.
+  const conv = platformConventions({ platform: platformOverride });
+
+  try {
+    // 3-second timeout — `which`/`where` typically return in
+    // milliseconds, but a PATH that includes a network filesystem
+    // or a shell alias that does I/O could hang indefinitely.
+    // Bounding the call ensures `skillrepo init` never stalls on
+    // binary resolution.
+    const raw = execFileSync(conv.binaryLocator, ["skillrepo"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+    // Windows `where` can return multiple matching paths (one per
+    // PATH entry containing the binary) on separate lines. Take
+    // only the first. `which` always returns a single path but the
+    // split is harmless there. This is the one line where the
+    // platform difference actually leaks through — all platforms
+    // receive potentially-multi-line output that we canonicalize
+    // the same way.
+    const result = raw.split(/\r?\n/)[0].trim();
+    if (!result) return null;
+    // Sanity: the resolved path must be absolute. A relative
+    // result would be meaningless at session-start time because
+    // the Claude Code hook runner's cwd is undefined. `isAbsolute`
+    // handles both POSIX (`/foo/bar`) and Windows (`C:\foo\bar`)
+    // path styles — it's Node's built-in cross-platform check,
+    // not a platform-conditional we need to own.
+    if (!isAbsolute(result)) return null;
+    return result;
+  } catch {
+    // Locator exits non-zero if the binary isn't on PATH, or throws
+    // ENOENT if the locator itself isn't available (e.g. a minimal
+    // container image without `which`, or a Windows system with
+    // `where.exe` missing which is effectively never — but still
+    // safe-handled). Either way: null → caller routes to the
+    // architect-specified "requires stable install" skip message.
+    return null;
+  }
+}
+
+/**
+ * Install (or update) the SkillRepo SessionStart hook. Creates the
+ * settings.local.json file if it doesn't exist.
+ *
+ * @param {object} [options]
+ * @param {string} [options.binaryPath] - Absolute path to `skillrepo`.
+ *        Default: resolved via `which skillrepo`. Passing explicitly
+ *        is used by tests to inject a deterministic path.
+ * @param {boolean} [options.global=false] - When true, installs to the
+ *        user-global `~/.claude/settings.local.json` instead of the
+ *        project-local file.
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Propagated to both `resolveSkillrepoBinary` and
+ *        `buildHookCommand` so a test can exercise the full
+ *        installer path under simulated Windows semantics on a
+ *        non-Windows host. Production callers leave this unset so
+ *        both helpers see the real `os.platform()`. This option is
+ *        the mechanism that closes the architect's round-3 HIGH
+ *        finding — without it, a Windows-shaped `binaryPath` passed
+ *        in the test still got a POSIX-shaped command back because
+ *        `buildHookCommand` read `os.platform()` directly.
+ * @returns {{
+ *   path: string;
+ *   action: "installed" | "updated" | "unchanged" | "skipped";
+ *   reason?: string;
+ *   command?: string;
+ * }}
+ *        `action`:
+ *          - `"installed"` — no prior SkillRepo hook, we added one
+ *          - `"updated"` — prior SkillRepo hook existed but the
+ *            command differed (e.g. binary path changed); replaced
+ *            in place
+ *          - `"unchanged"` — exact command already present; no-op
+ *          - `"skipped"` — prerequisite missing (no binary path, file
+ *            corrupt, etc.). `reason` carries the human message.
+ */
+export function mergeSessionHook({
+  binaryPath: binaryPathOpt,
+  global = false,
+  platform: platformOverride,
+} = {}) {
+  const filePath = global ? claudeSettingsLocalGlobal() : claudeSettingsLocal();
+  const displayPath = global
+    ? "~/.claude/settings.local.json"
+    : ".claude/settings.local.json";
+
+  const binaryPath =
+    binaryPathOpt ?? resolveSkillrepoBinary({ platform: platformOverride });
+  if (!binaryPath) {
+    // Two reasons binaryPath can be null:
+    //   1. `isNpxInvocation()` returned true — the user ran
+    //      `npx skillrepo ...`. The npx cache path is transient and
+    //      unsuitable for baking into a long-lived hook command.
+    //   2. `which skillrepo` returned nothing — no global install
+    //      exists at all.
+    // Both are the same problem from the hook's perspective: we
+    // can't produce a command that will still work later. The
+    // architect's #884 design specified the same warning text for
+    // both cases.
+    return {
+      path: displayPath,
+      action: "skipped",
+      reason:
+        "Session sync requires a stable `skillrepo` binary on PATH. " +
+        "Under `npx skillrepo ...` or without a global install, the " +
+        "hook would bind to a transient path that eventually breaks. " +
+        "Install globally with `npm install -g skillrepo` and re-run " +
+        "`skillrepo session-sync enable`.",
+    };
+  }
+
+  const desiredCommand = buildHookCommand(binaryPath, {
+    platform: platformOverride,
+  });
+
+  // Parse existing file (or start fresh). A corrupt-but-present file
+  // is a hard error: silently overwriting it would destroy any user-
+  // authored hooks we can't read.
+  let config = {};
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, "utf-8");
+    if (raw.trim().length > 0) {
+      try {
+        config = JSON.parse(raw);
+      } catch (err) {
+        throw diskError(
+          `Cannot parse ${displayPath}: ${err.message}. Fix or delete the file, then re-run.`,
+          { cause: err },
+        );
+      }
+      if (!config || typeof config !== "object" || Array.isArray(config)) {
+        throw diskError(
+          `${displayPath} must be a JSON object at the top level.`,
+        );
+      }
+    }
+  }
+
+  // Walk `hooks.SessionStart[i].hooks[j].command` looking for an
+  // existing SkillRepo entry (fingerprint-matched). This MUST mirror
+  // the remover's walk in src/lib/removers/settings.mjs — the shared
+  // SESSION_HOOK_FINGERPRINT import is the mechanism that keeps
+  // them in lockstep. The round-trip test in session-hook.test.mjs
+  // locks the contract in.
+  if (!config.hooks || typeof config.hooks !== "object") {
+    config.hooks = {};
+  }
+  if (!Array.isArray(config.hooks.SessionStart)) {
+    config.hooks.SessionStart = [];
+  }
+
+  let foundAction = null; // null → install fresh
+  for (const group of config.hooks.SessionStart) {
+    if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+      continue;
+    }
+    for (const inner of group.hooks) {
+      if (
+        inner &&
+        typeof inner === "object" &&
+        typeof inner.command === "string" &&
+        inner.command.includes(SESSION_HOOK_FINGERPRINT)
+      ) {
+        if (inner.command === desiredCommand) {
+          foundAction = "unchanged";
+        } else {
+          inner.command = desiredCommand;
+          // Also normalize the `type` field in case an older format
+          // was present (or the entry was hand-edited).
+          inner.type = "command";
+          foundAction = "updated";
+        }
+        break;
+      }
+    }
+    if (foundAction) break;
+  }
+
+  if (!foundAction) {
+    // Fresh install — append a new group with a single hook. We
+    // append (not prepend) so user-authored groups retain their
+    // relative order. Claude Code fires all groups in sequence.
+    config.hooks.SessionStart.push({
+      hooks: [{ type: "command", command: desiredCommand }],
+    });
+    foundAction = "installed";
+  }
+
+  if (foundAction === "unchanged") {
+    // No-op. Skip the write so we don't touch mtime for nothing.
+    return {
+      path: displayPath,
+      action: "unchanged",
+      command: desiredCommand,
+    };
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return {
+    path: displayPath,
+    action: foundAction,
+    command: desiredCommand,
+  };
+}
+
+/**
+ * Remove the SkillRepo SessionStart hook from settings.local.json.
+ *
+ * Thin adapter over `removeSettingsSessionHook` from
+ * `src/lib/removers/settings.mjs`. The consolidation to a single
+ * source of truth was the architect's round-1 priority tightening:
+ * before this PR, two separate implementations of the same walk
+ * existed (one here, one in settings.mjs) and they had already
+ * diverged in one observable behavior. Keeping both was a genuine
+ * maintenance hazard.
+ *
+ * This wrapper only forwards to the settings remover — it exists
+ * for the `session-sync disable` command to have a single import
+ * surface aligned with its installer counterpart (`mergeSessionHook`
+ * in this module). The actual logic lives in settings.mjs.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.global=false] - Forwarded to the
+ *        settings remover; operates on `~/.claude/settings.local.json`
+ *        when true.
+ * @returns {{
+ *   path: string;
+ *   action: "removed" | "would-remove" | "skipped" | "unchanged";
+ *   error?: string;
+ * }}
+ */
+export function removeSessionHook({ global = false } = {}) {
+  return removeSettingsSessionHook({ global });
+}

package/src/lib/paths.mjs

@@ -75,3 +75,24 @@ export const envLocal = () => join(cwd(), ".env.local");
  * project /skills/ fallback directory is gitignored on first write.
  */
 export const gitignorePath = () => join(cwd(), ".gitignore");
+
+// ── Claude Code settings ──────────────────────────────────────────────
+//
+// settings.local.json is the per-developer, per-project Claude Code
+// settings file. It's gitignored (the init flow adds it to .gitignore
+// at step 3), so the SessionStart hook added by #884 lives there
+// rather than in settings.json — that keeps each developer's sync
+// behavior independent even when they share a repo. Claude Code
+// applies both settings.json (checked in) and settings.local.json
+// (gitignored) with local taking precedence.
+//
+// The global variant at ~/.claude/settings.local.json is the user-
+// wide equivalent, used when init runs with --global.
+
+/** Project-local Claude Code settings file (per-developer, gitignored). */
+export const claudeSettingsLocal = () =>
+  join(cwd(), ".claude", "settings.local.json");
+
+/** User-wide Claude Code settings file. Used by `init --global`. */
+export const claudeSettingsLocalGlobal = () =>
+  join(homedir(), ".claude", "settings.local.json");

package/src/lib/platform.mjs

@@ -0,0 +1,124 @@
+/**
+ * Platform conventions — single source of truth for OS-specific
+ * differences the CLI has to honor.
+ *
+ * The CLI runs on POSIX systems (macOS, Linux) and Windows. Most
+ * code paths are platform-neutral via Node built-ins (path.join,
+ * os.homedir, fs.rmSync, etc.) — but a handful of surfaces have
+ * real platform differences that can't be abstracted away at the
+ * Node level:
+ *
+ *   1. **Binary-locator command**. POSIX provides `which`; Windows
+ *      provides `where.exe`. `execFileSync` doesn't spawn a shell,
+ *      so the literal name must exist on disk.
+ *
+ *   2. **Hook shell backstop suffix**. The SessionStart hook command
+ *      relies on a shell-level fallback (`|| true`) to guarantee
+ *      exit 0 even if the binary vanishes. POSIX shells support it;
+ *      cmd.exe doesn't know the `true` builtin and would emit a
+ *      confusing error. The `--session-hook` flag's exit-0 contract
+ *      inside the Node process is the primary defense regardless of
+ *      platform; the shell backstop is belt-and-suspenders that we
+ *      lose on Windows.
+ *
+ *   3. **POSIX file permissions**. `chmodSync(0o600)` silently
+ *      succeeds on Windows but doesn't produce the intended effect —
+ *      Windows's ACL model doesn't map to the Unix mode bits. Any
+ *      call meant to restrict permissions on credential files must
+ *      be guarded so Windows users aren't misled into thinking their
+ *      files are access-controlled when they aren't.
+ *
+ *   4. **Atomic directory replacement semantics**. POSIX's
+ *      `renameSync` over an existing directory is atomic on the same
+ *      filesystem — the swap is instantaneous from the perspective
+ *      of any concurrent reader. Windows fails with EEXIST/EPERM if
+ *      the target exists; the replacement must be done as a
+ *      remove-then-rename sequence with a small window where the
+ *      target is missing. Callers that write skills have to know
+ *      which strategy applies so they can surface a meaningful
+ *      recovery hint if the Windows path fails mid-sequence.
+ *
+ * This module exposes a single `platformConventions()` function that
+ * returns a frozen object with every platform-specific value the
+ * CLI needs. New platform-specific surfaces should be added here
+ * rather than spreading ad-hoc `platform() === "win32"` checks
+ * across the codebase. This is a convention, not an enforced rule —
+ * it's documentation plus a consumer pattern, not a linter.
+ *
+ * The `platform` parameter is an optional override for tests —
+ * production callers let it default to `os.platform()`.
+ */
+
+import { platform as osPlatform } from "node:os";
+
+/**
+ * @typedef {Object} PlatformConventions
+ * @property {"posix" | "windows"} family - High-level family name.
+ * @property {string} binaryLocator - Command used to resolve a
+ *           binary's absolute path from PATH. `"which"` on POSIX,
+ *           `"where"` on Windows.
+ * @property {string} hookShellSuffix - Suffix appended to hook
+ *           commands to guarantee exit 0 at the shell level. `" || true"`
+ *           on POSIX (appended to the base command), empty string on
+ *           Windows (the `--session-hook` flag's exit-0 contract is
+ *           the only defense).
+ * @property {boolean} supportsPosixPermissions - True when
+ *           `chmodSync(mode)` produces the intended POSIX mode-bit
+ *           effect. False on Windows, where the call nominally
+ *           succeeds but doesn't restrict ACLs the way a 0600 bit
+ *           would on Unix. Callers use this to skip chmod on
+ *           Windows rather than leave misleading "perms applied"
+ *           success paths that don't actually restrict access.
+ * @property {boolean} supportsAtomicDirectoryRename - True when
+ *           `renameSync` over an existing directory is atomic.
+ *           POSIX: true. Windows: false — callers must implement
+ *           remove-then-rename, accepting the small non-atomic
+ *           window where the target doesn't exist. The Windows
+ *           code path MUST produce a recoverable failure state if
+ *           the rename step fails (i.e. leave the `.tmp/` dir on
+ *           disk so the user can rename it manually).
+ */
+
+const POSIX = Object.freeze({
+  family: "posix",
+  binaryLocator: "which",
+  hookShellSuffix: " || true",
+  supportsPosixPermissions: true,
+  supportsAtomicDirectoryRename: true,
+});
+
+const WINDOWS = Object.freeze({
+  family: "windows",
+  binaryLocator: "where",
+  hookShellSuffix: "",
+  supportsPosixPermissions: false,
+  supportsAtomicDirectoryRename: false,
+});
+
+/**
+ * Return the platform-specific convention set for the current
+ * platform, or an override.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Production callers should let this default to the real
+ *        runtime platform.
+ * @returns {PlatformConventions}
+ */
+export function platformConventions({ platform: platformOverride } = {}) {
+  const plat = platformOverride ?? osPlatform();
+  return plat === "win32" ? WINDOWS : POSIX;
+}
+
+/**
+ * True if the current (or overridden) platform is Windows.
+ * Convenience wrapper — prefer `platformConventions().family ===
+ * "windows"` in call sites that already hold a conventions object.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform]
+ * @returns {boolean}
+ */
+export function isWindows({ platform: platformOverride } = {}) {
+  return platformConventions({ platform: platformOverride }).family === "windows";
+}

package/src/lib/removers/claude-mcp.mjs

@@ -0,0 +1,67 @@
+/**
+ * Claude Code `.mcp.json` remover (#885).
+ *
+ * Surgical inverse of `mergers/claude-mcp.mjs`: parse the JSON,
+ * delete `mcpServers.skillrepo` if present, write back. Any other
+ * `mcpServers.*` entries (vendor configs the user added manually or
+ * via another tool) are preserved verbatim.
+ *
+ * A file that doesn't exist is skipped. A file with unparseable
+ * JSON is reported as an error but does not throw from the remover
+ * — the uninstall command aggregates errors per artifact and
+ * surfaces them at the end. The user would need to fix or delete
+ * the file manually before re-running uninstall for this artifact.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { claudeMcpJson } from "../paths.mjs";
+
+/**
+ * Delete `mcpServers.skillrepo` from `.mcp.json`.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - Preview-only mode; returns
+ *        `"would-remove"` without touching the file.
+ *
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped"; error?: string }}
+ */
+export function removeClaudeMcp({ dryRun = false } = {}) {
+  const filePath = claudeMcpJson();
+
+  if (!existsSync(filePath)) {
+    return { path: ".mcp.json", action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: ".mcp.json",
+      action: "skipped",
+      error: `Cannot parse .mcp.json: ${err.message}. Fix or delete the file and re-run uninstall.`,
+    };
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    !config.mcpServers ||
+    typeof config.mcpServers !== "object" ||
+    !("skillrepo" in config.mcpServers)
+  ) {
+    return { path: ".mcp.json", action: "skipped" };
+  }
+
+  if (dryRun) {
+    return { path: ".mcp.json", action: "would-remove" };
+  }
+
+  delete config.mcpServers.skillrepo;
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return { path: ".mcp.json", action: "removed" };
+}

package/src/lib/removers/cursor-mcp.mjs

@@ -0,0 +1,60 @@
+/**
+ * Cursor `.cursor/mcp.json` remover (#885).
+ *
+ * Identical shape to the Claude Code remover — Cursor uses the same
+ * `mcpServers.<key>` schema, only the path and env-var interpolation
+ * syntax differ. Kept as a separate module so each path has its own
+ * testable unit and so future divergence (Cursor adding a new
+ * config field, for instance) can land in this file without
+ * touching the Claude remover.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { cursorMcpJson } from "../paths.mjs";
+
+/**
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ *
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped"; error?: string }}
+ */
+export function removeCursorMcp({ dryRun = false } = {}) {
+  const filePath = cursorMcpJson();
+
+  if (!existsSync(filePath)) {
+    return { path: ".cursor/mcp.json", action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: ".cursor/mcp.json",
+      action: "skipped",
+      error: `Cannot parse .cursor/mcp.json: ${err.message}. Fix or delete the file and re-run uninstall.`,
+    };
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    !config.mcpServers ||
+    typeof config.mcpServers !== "object" ||
+    !("skillrepo" in config.mcpServers)
+  ) {
+    return { path: ".cursor/mcp.json", action: "skipped" };
+  }
+
+  if (dryRun) {
+    return { path: ".cursor/mcp.json", action: "would-remove" };
+  }
+
+  delete config.mcpServers.skillrepo;
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return { path: ".cursor/mcp.json", action: "removed" };
+}