skillrepo 3.0.0 → 3.1.1

package/src/lib/removers/env-local.mjs

@@ -0,0 +1,55 @@
+/**
+ * `.env.local` credential remover (#885).
+ *
+ * Strips every line whose prefix matches `SKILLREPO_ACCESS_KEY=`. Uses
+ * atomic write so a rename-mid-write crash cannot leave a partial
+ * credential value on disk.
+ *
+ * Prefix match (not substring) so the remover cannot inadvertently
+ * strip a user-authored comment or template line. The `.env.local`
+ * installer writes only the `KEY=value` shape, so "starts with
+ * SKILLREPO_ACCESS_KEY=" is exactly the set the installer produces.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { ENV_LOCAL_KEY_NAME } from "../artifact-registry.mjs";
+import { envLocal } from "../paths.mjs";
+
+/**
+ * Remove every `SKILLREPO_ACCESS_KEY=` line from `.env.local`.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - Preview-only mode; see
+ *        removeGitignore's JSDoc for rationale. Returns action
+ *        `"would-remove"` without touching the file.
+ *
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped"; removed: number }}
+ */
+export function removeEnvLocal({ dryRun = false } = {}) {
+  const filePath = envLocal();
+
+  if (!existsSync(filePath)) {
+    return { path: ".env.local", action: "skipped", removed: 0 };
+  }
+
+  const original = readFileSync(filePath, "utf-8");
+  const lineEnding = original.includes("\r\n") ? "\r\n" : "\n";
+  const lines = original.split(/\r?\n/);
+
+  const prefix = `${ENV_LOCAL_KEY_NAME}=`;
+  const survivors = lines.filter((l) => !l.startsWith(prefix));
+  const removed = lines.length - survivors.length;
+
+  if (removed === 0) {
+    return { path: ".env.local", action: "skipped", removed: 0 };
+  }
+
+  if (dryRun) {
+    return { path: ".env.local", action: "would-remove", removed };
+  }
+
+  writeFileAtomic(filePath, survivors.join(lineEnding));
+
+  return { path: ".env.local", action: "removed", removed };
+}

package/src/lib/removers/gitignore.mjs

@@ -0,0 +1,108 @@
+/**
+ * `.gitignore` section remover (#885).
+ *
+ * Surgical inverse of `mergers/gitignore.mjs`. Strips the SkillRepo
+ * section — the header line plus every non-blank line directly under
+ * it — while leaving every other line in the file unchanged.
+ *
+ * Attribution model: only lines inside the section are considered
+ * SkillRepo-owned. A user-authored `.env.local` line elsewhere in the
+ * file is preserved, even though it matches one of the strings the
+ * installer writes. This matters because `.env.local` is commonly
+ * gitignored for reasons unrelated to SkillRepo.
+ *
+ * Why a dedicated remover instead of inverting the merger by rewriting
+ * the file from parsed state: the merger only writes the section; it
+ * never touches the rest of the file. Mirroring that contract in the
+ * remover means we can guarantee "we only modify our section" at the
+ * syntactic level, which is stronger than any semantic-round-trip
+ * guarantee. The file keeps byte-for-byte fidelity outside the
+ * SkillRepo section.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { GITIGNORE_SECTION_HEADER } from "../artifact-registry.mjs";
+import { gitignorePath } from "../paths.mjs";
+
+/**
+ * Strip the SkillRepo section from .gitignore.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - When true, performs the
+ *        same detection logic but does not write. Returns action
+ *        `"would-remove"` instead of `"removed"` so callers can
+ *        distinguish a preview from an executed removal. The
+ *        uninstall command uses this to present a pre-execution
+ *        summary to the user before prompting for confirmation.
+ *
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped"; removed: number }}
+ */
+export function removeGitignore({ dryRun = false } = {}) {
+  const filePath = gitignorePath();
+
+  if (!existsSync(filePath)) {
+    return { path: ".gitignore", action: "skipped", removed: 0 };
+  }
+
+  const original = readFileSync(filePath, "utf-8");
+  // Preserve the original line ending so a file written with CRLF
+  // stays CRLF. `split(/\r?\n/)` discards the line-ending bytes, so
+  // we detect them explicitly and rebuild on that basis.
+  const lineEnding = original.includes("\r\n") ? "\r\n" : "\n";
+  const lines = original.split(/\r?\n/);
+
+  const headerIdx = lines.findIndex((l) => l === GITIGNORE_SECTION_HEADER);
+  if (headerIdx === -1) {
+    return { path: ".gitignore", action: "skipped", removed: 0 };
+  }
+
+  // Section boundary: from the header line, consume every following
+  // non-blank line until we hit the first blank line or EOF. This
+  // matches the installer's "header + N entries, separated from the
+  // rest by a blank line" shape.
+  let end = headerIdx + 1;
+  while (end < lines.length && lines[end] !== "") {
+    end += 1;
+  }
+
+  // Also consume the single trailing blank line that the installer
+  // emits after the section — if present. This prevents a stranded
+  // blank line where the section used to be. If the user had their
+  // own multi-blank separator around the section, only the single
+  // separator immediately after the section is eaten; extras survive.
+  if (end < lines.length && lines[end] === "") {
+    end += 1;
+  }
+
+  const removedLines = end - headerIdx;
+  // -1 on removedLines for the display: the "trailing blank line"
+  // isn't a meaningful count of SkillRepo entries. Only the header
+  // + entries count. But lines after the header that are blank were
+  // already excluded by the while-loop above, so `end - 1 -
+  // headerIdx` is header+entries. Subtract 1 more only if we
+  // consumed the trailing blank.
+  //
+  // Actually the simpler accounting: count the non-blank deleted
+  // lines. `end - headerIdx` includes at most one trailing blank;
+  // `Math.min(end, lines.length) - headerIdx - (<consumed-blank>
+  // ? 1 : 0)` gives the SkillRepo-line count.
+  const consumedTrailingBlank =
+    end > headerIdx + 1 && lines[end - 1] === "";
+  const reportedRemoved = removedLines - (consumedTrailingBlank ? 1 : 0);
+
+  if (dryRun) {
+    return {
+      path: ".gitignore",
+      action: "would-remove",
+      removed: reportedRemoved,
+    };
+  }
+
+  const survivors = [...lines.slice(0, headerIdx), ...lines.slice(end)];
+  const rebuilt = survivors.join(lineEnding);
+
+  writeFileAtomic(filePath, rebuilt);
+
+  return { path: ".gitignore", action: "removed", removed: reportedRemoved };
+}

package/src/lib/removers/settings.mjs

@@ -0,0 +1,183 @@
+/**
+ * `.claude/settings.local.json` SessionStart-hook remover (#885 + #884).
+ *
+ * SINGLE SOURCE OF TRUTH for removing the SkillRepo SessionStart hook.
+ * Both `skillrepo uninstall` (#885) and `skillrepo session-sync disable`
+ * (#884) route through this one function — the architect round-1
+ * review flagged the earlier dual-implementation design as a
+ * maintenance hazard. Consolidating here eliminates the drift surface.
+ *
+ * The fingerprint lives in `artifact-registry.mjs` and is imported by
+ * both this remover and the #884 installer (`mergers/session-hook.mjs`)
+ * — single source of truth for the match predicate, enforced at the
+ * language level.
+ *
+ * Settings-file shape (per Claude Code docs):
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [
+ *         { "hooks": [ { "type": "command", "command": "..." } ] },
+ *         ...
+ *       ]
+ *     }
+ *   }
+ *
+ * The outer array holds "hook groups"; each group has its own
+ * `hooks` array containing individual commands. #884 writes a
+ * single group with a single command. The remover walks both
+ * levels and drops any INNER hook that matches the fingerprint; if
+ * a group's inner array becomes empty, the whole group is dropped.
+ * This keeps unrelated groups intact even if one of them happens
+ * to be adjacent in the file.
+ *
+ * ## Action values
+ *
+ * Normalized to distinguish three semantic cases:
+ *
+ *   - `"skipped"` — the file does NOT exist (or unparseable). The
+ *     operation couldn't run.
+ *   - `"unchanged"` — the file exists (including zero-byte) AND is
+ *     parseable AND has no SkillRepo hook to remove. The operation
+ *     ran; there was nothing to do.
+ *   - `"would-remove"` — dryRun=true and a SkillRepo hook is present.
+ *   - `"removed"` — a SkillRepo hook was stripped.
+ *
+ * This is the semantic fix architect round-1 review flagged: earlier
+ * versions returned `"skipped"` both for "file missing" AND "file
+ * exists but no hook", conflating two distinct states. CI scripts
+ * that want to verify "session sync is definitely disabled" can now
+ * treat `"skipped" | "unchanged" | "removed"` as success and `error`
+ * as failure, cleanly.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { SESSION_HOOK_FINGERPRINT } from "../artifact-registry.mjs";
+import {
+  claudeSettingsLocal,
+  claudeSettingsLocalGlobal,
+} from "../paths.mjs";
+
+/**
+ * Strip the SkillRepo SessionStart hook from settings.local.json.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - Preview-only mode.
+ * @param {boolean} [options.global=false] - Operate on the user-wide
+ *        `~/.claude/settings.local.json` instead of project-local.
+ *
+ * @returns {{
+ *   path: string;
+ *   action: "removed" | "would-remove" | "skipped" | "unchanged";
+ *   error?: string;
+ * }}
+ */
+export function removeSettingsSessionHook({
+  dryRun = false,
+  global = false,
+} = {}) {
+  const filePath = global ? claudeSettingsLocalGlobal() : claudeSettingsLocal();
+  const displayPath = global
+    ? "~/.claude/settings.local.json"
+    : ".claude/settings.local.json";
+
+  if (!existsSync(filePath)) {
+    return { path: displayPath, action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+
+  // Empty-file guard — a zero-byte or whitespace-only settings.local.json
+  // is a valid state (some tools create the file as a touch-target).
+  // Treating it as unparseable would produce a misleading "Cannot parse"
+  // error for what is genuinely an empty file. Code-reviewer round-1
+  // flagged this for `removeSessionHook`; fixing at the single source
+  // of truth closes it everywhere.
+  if (raw.trim().length === 0) {
+    return { path: displayPath, action: "unchanged" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: displayPath,
+      action: "skipped",
+      error: `Cannot parse ${displayPath}: ${err.message}. Fix or delete the file and re-run.`,
+    };
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    !config.hooks ||
+    typeof config.hooks !== "object" ||
+    !Array.isArray(config.hooks.SessionStart)
+  ) {
+    // File is parseable but has no hooks section — nothing to do.
+    // This is the "unchanged" semantic, not "skipped": the operation
+    // ran successfully, there just wasn't anything to remove.
+    return { path: displayPath, action: "unchanged" };
+  }
+
+  const originalSessionStart = config.hooks.SessionStart;
+  let anyRemoved = false;
+
+  const newSessionStart = originalSessionStart
+    .map((group) => {
+      if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+        // Unknown group shape — leave it alone. The installer only
+        // writes a specific shape; anything else is user-authored
+        // and the remover must not mutate it.
+        return group;
+      }
+      const beforeCount = group.hooks.length;
+      const survivingHooks = group.hooks.filter((h) => {
+        if (!h || typeof h !== "object" || typeof h.command !== "string") {
+          return true;
+        }
+        const matches = h.command.includes(SESSION_HOOK_FINGERPRINT);
+        if (matches) {
+          anyRemoved = true;
+          return false;
+        }
+        return true;
+      });
+      if (survivingHooks.length !== beforeCount && survivingHooks.length === 0) {
+        // The whole group was ours — drop it. Returning `null`
+        // flags the group for removal in the subsequent filter.
+        return null;
+      }
+      if (survivingHooks.length !== beforeCount) {
+        return { ...group, hooks: survivingHooks };
+      }
+      return group;
+    })
+    .filter((g) => g !== null);
+
+  if (!anyRemoved) {
+    return { path: displayPath, action: "unchanged" };
+  }
+
+  if (dryRun) {
+    return { path: displayPath, action: "would-remove" };
+  }
+
+  // Clean up empty containers so the file doesn't accumulate dead
+  // structure: empty SessionStart array → remove the key; empty
+  // hooks object → remove the key. Leaves a minimally-clean file.
+  if (newSessionStart.length === 0) {
+    delete config.hooks.SessionStart;
+  } else {
+    config.hooks.SessionStart = newSessionStart;
+  }
+  if (Object.keys(config.hooks).length === 0) {
+    delete config.hooks;
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return { path: displayPath, action: "removed" };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * VS Code `.vscode/mcp.json` remover (#885).
+ *
+ * Two-artifact file: the installer writes both a server entry
+ * (`servers.skillrepo`) and an input entry (an element of the
+ * `inputs` array with `id === "skillrepo-api-key"`). This remover
+ * tears down BOTH in a single read-mutate-write cycle so the file
+ * is never observed with only one half of the SkillRepo footprint.
+ *
+ * Note: VS Code uses `servers` (not `mcpServers` like Claude/Cursor)
+ * and separates credential prompting into the `inputs` array — that's
+ * why this remover's shape differs from the other three.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { VSCODE_INPUT_ID } from "../artifact-registry.mjs";
+import { vscodeMcpJson } from "../paths.mjs";
+
+/**
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ *
+ * @returns {{
+ *   path: string;
+ *   action: "removed" | "would-remove" | "skipped";
+ *   removed?: string[];
+ *   error?: string;
+ * }}
+ */
+export function removeVscodeMcp({ dryRun = false } = {}) {
+  const filePath = vscodeMcpJson();
+
+  if (!existsSync(filePath)) {
+    return { path: ".vscode/mcp.json", action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: ".vscode/mcp.json",
+      action: "skipped",
+      error: `Cannot parse .vscode/mcp.json: ${err.message}. Fix or delete the file and re-run uninstall.`,
+    };
+  }
+
+  if (!config || typeof config !== "object") {
+    return { path: ".vscode/mcp.json", action: "skipped" };
+  }
+
+  const removed = [];
+
+  // Server entry
+  if (
+    config.servers &&
+    typeof config.servers === "object" &&
+    "skillrepo" in config.servers
+  ) {
+    delete config.servers.skillrepo;
+    removed.push("servers.skillrepo");
+  }
+
+  // Input entry — filter the inputs array by id. Other input entries
+  // (user-authored prompts for other extensions) survive untouched.
+  if (Array.isArray(config.inputs)) {
+    const before = config.inputs.length;
+    config.inputs = config.inputs.filter((i) => i?.id !== VSCODE_INPUT_ID);
+    if (config.inputs.length !== before) {
+      removed.push(`inputs[${VSCODE_INPUT_ID}]`);
+    }
+  }
+
+  if (removed.length === 0) {
+    return { path: ".vscode/mcp.json", action: "skipped" };
+  }
+
+  if (dryRun) {
+    return { path: ".vscode/mcp.json", action: "would-remove", removed };
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return { path: ".vscode/mcp.json", action: "removed", removed };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Windsurf `~/.codeium/windsurf/mcp_config.json` remover (#885).
+ *
+ * Windsurf is always global-scope — unlike Claude/Cursor/VS Code,
+ * Windsurf has no project-level config. This remover is only
+ * invoked when uninstall runs with `--global`.
+ *
+ * Same schema as claude-mcp / cursor-mcp (surgical delete of
+ * `mcpServers.skillrepo`), but the server entry uses `serverUrl`
+ * instead of `url` so a future feature that validates the shape of
+ * what we're removing would diverge here. Kept separate for
+ * symmetry and testability.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import { windsurfMcpJson } from "../paths.mjs";
+
+const DISPLAY_PATH = "~/.codeium/windsurf/mcp_config.json";
+
+/**
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ *
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped"; error?: string }}
+ */
+export function removeWindsurfMcp({ dryRun = false } = {}) {
+  const filePath = windsurfMcpJson();
+
+  if (!existsSync(filePath)) {
+    return { path: DISPLAY_PATH, action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: DISPLAY_PATH,
+      action: "skipped",
+      error: `Cannot parse ${DISPLAY_PATH}: ${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: DISPLAY_PATH, action: "skipped" };
+  }
+
+  if (dryRun) {
+    return { path: DISPLAY_PATH, action: "would-remove" };
+  }
+
+  delete config.mcpServers.skillrepo;
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return { path: DISPLAY_PATH, action: "removed" };
+}

package/src/lib/sync.mjs

@@ -27,6 +27,22 @@
  * @property {number} updated     - Skills overwritten on disk
  * @property {number} removed     - Tombstones applied
  * @property {boolean} notModified - True if 304 short-circuit fired
+ * @property {boolean | null} fullSync - True if this was a full (non-delta)
+ *                                   sync — i.e. no prior `.last-sync` state
+ *                                   existed so no `since` was sent. False if
+ *                                   this was a delta sync. `null` only ever
+ *                                   appears in SYNTHESIZED failure summaries
+ *                                   (e.g. `init.mjs` when runSync threw) to
+ *                                   mark the state as genuinely unknown —
+ *                                   consumers should never see `null` from
+ *                                   runSync itself. A full sync returning
+ *                                   zero skills genuinely means "empty
+ *                                   library"; a delta sync returning zero
+ *                                   means "nothing changed since last sync".
+ *                                   Consumers must distinguish these to
+ *                                   render accurate user messages (see
+ *                                   init.mjs step 7).
+ * @property {string} [syncedAt]
  * @property {string} syncedAt    - ISO timestamp from the server response
  *
  * @typedef {Object} SyncStateFile
@@ -182,6 +198,14 @@ export async function runSync(options) {
   if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
   if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
 
+  // Track whether this is a full or delta sync BEFORE the network
+  // call, for the returned summary's `fullSync` field. A "full" sync
+  // is one where no `since` was sent — which is exactly when no
+  // prior last-sync state existed. The distinction matters to
+  // consumers (init.mjs) that need to tell "empty library" from
+  // "nothing changed since last sync" in the zero-counters case.
+  const fullSync = !lastSync?.syncedAt;
+
   const result = await getLibrary(serverUrl, apiKey, opts);
 
   // Step 4: 304 short-circuit
@@ -191,6 +215,7 @@ export async function runSync(options) {
       updated: 0,
       removed: 0,
       notModified: true,
+      fullSync,
       syncedAt: lastSync?.syncedAt ?? new Date().toISOString(),
     };
   }
@@ -201,6 +226,7 @@ export async function runSync(options) {
     updated: 0,
     removed: 0,
     notModified: false,
+    fullSync,
     syncedAt: result.syncedAt,
   };
 

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

@@ -13,12 +13,18 @@ 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";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let server;
 let serverUrl;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 const VALID_KEY = "sk_live_test";
 
@@ -46,9 +52,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
 
   server = createMockServer({});
@@ -61,7 +67,7 @@ async function setup() {
 async function teardown() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }

package/src/test/commands/get.test.mjs

@@ -13,12 +13,18 @@ import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let server;
 let serverUrl;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 const VALID_KEY = "sk_live_test";
 
@@ -53,9 +59,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
   delete process.env.SKILLREPO_URL;
 
@@ -69,7 +75,7 @@ async function setup() {
 async function teardown() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }