skillrepo 3.0.0 → 3.1.0

package/src/lib/artifact-registry.mjs

@@ -0,0 +1,265 @@
+/**
+ * Single source of truth for every file and in-file entry `skillrepo init`
+ * writes to the user's filesystem (#885).
+ *
+ * The goal is drift prevention: any future command that writes a new
+ * artifact (a new MCP vendor, a new project-local config file, etc.)
+ * MUST add its descriptor to this registry in the same PR. The CI
+ * enforcement test at `src/test/lib/artifact-registry.test.mjs` walks
+ * the mergers/ and removers/ directories on the filesystem and fails
+ * loudly if a merger has no matching remover, or if the registry is
+ * missing a descriptor for an id that the test's expected-set covers.
+ *
+ * This file is DATA ONLY. No filesystem access, no dynamic behavior,
+ * no side effects — if you find yourself importing `fs` here you are
+ * writing in the wrong module. Actual removal logic lives in
+ * `src/lib/removers/*.mjs`; this module only catalogs WHAT gets
+ * removed, not HOW.
+ *
+ * Out of scope for v3.1.0 (see #885 section 3 Non-Goals):
+ *   - v2.0.0 artifacts (.claude/rules/skillrepo-*.md,
+ *     .claude/hooks/skillrepo-*). v3.0.0 is the minimum supported
+ *     version; users of earlier versions clean up manually.
+ *   - The <cwd>/skills/ fallback directory written for non-Claude-Code
+ *     vendors. Tracked in #876 until those IDEs publish their own
+ *     on-disk skill discovery conventions.
+ *
+ * The `settings-session-hook` descriptor is a forward-declaration: it
+ * names the SessionStart hook entry that #884 installs. The fingerprint
+ * string is exported below so #884's installer can import it and both
+ * modules stay in lockstep without a circular dependency.
+ */
+
+import {
+  claudeMcpJson,
+  cursorMcpJson,
+  vscodeMcpJson,
+  windsurfMcpJson,
+  envLocal,
+  gitignorePath,
+  claudeSkillsProjectRoot,
+  claudeSkillsGlobalRoot,
+} from "./paths.mjs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ── Fingerprint constants exported for cross-module consumption ───────
+
+/**
+ * `.gitignore` section header. Lines directly under this header, up to
+ * the next blank line or the end of file, are considered SkillRepo-owned
+ * and are removed by the gitignore remover. User-authored lines outside
+ * the section are never touched — this is the attribution mechanism.
+ *
+ * MUST stay in lockstep with `src/lib/mergers/gitignore.mjs`
+ * SECTION_HEADER. The artifact-registry CI test asserts both modules
+ * resolve the same header text.
+ */
+export const GITIGNORE_SECTION_HEADER =
+  "# SkillRepo CLI (added by `skillrepo init`)";
+
+/**
+ * Entries written under the gitignore section by init. The remover
+ * does not match individual entries — it removes every line between the
+ * header and the next blank line — but the expected set is exported so
+ * tests can verify the two lists stay in sync.
+ */
+export const GITIGNORE_REQUIRED_ENTRIES = Object.freeze([
+  ".env.local",
+  ".claude/skills/",
+  ".claude/settings.local.json",
+]);
+
+/**
+ * Environment variable name owned by the CLI in `.env.local`. Any line
+ * starting with `${ENV_LOCAL_KEY_NAME}=` is considered SkillRepo-owned.
+ * Exact prefix match (not substring) so a user-authored
+ * `# SKILLREPO_ACCESS_KEY is set via ...` comment line is never
+ * stripped.
+ */
+export const ENV_LOCAL_KEY_NAME = "SKILLREPO_ACCESS_KEY";
+
+/**
+ * VS Code input `id` owned by the CLI. Lives in the `inputs` array of
+ * `.vscode/mcp.json` alongside the server entry.
+ */
+export const VSCODE_INPUT_ID = "skillrepo-api-key";
+
+/**
+ * Substring that identifies a SessionStart hook command entry as
+ * SkillRepo-owned. The #884 installer writes a hook whose `command`
+ * field contains `skillrepo update --session-hook`; any entry whose
+ * command contains this substring is removed by the uninstall path.
+ *
+ * Exported so #884's installer can import and use the same constant —
+ * this is the module boundary that makes #884 depend on #885 rather
+ * than the other way around. The architect design (issue #884 section
+ * 5.3) notes the bidirectional-fingerprint requirement; centralizing
+ * it here enforces it at the language level.
+ */
+export const SESSION_HOOK_FINGERPRINT = "skillrepo update --session-hook";
+
+// ── Artifact descriptors ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} ArtifactDescriptor
+ * @property {string} id - Stable identifier. Shows up in --json output.
+ * @property {"project" | "global"} scope - Which teardown pass owns this.
+ * @property {"json-key" | "json-input" | "line" | "section" | "directory"} kind
+ *          How the remover deletes this artifact.
+ * @property {() => string} pathFn - Resolves the on-disk path (absolute).
+ * @property {string} displayPath - Human-readable path for output (e.g.
+ *          `~/.codeium/windsurf/mcp_config.json`). Never an absolute
+ *          path — those leak the user's home directory.
+ * @property {string[]} [jsonPath] - For json-key: property path to delete.
+ * @property {string} [inputId] - For json-input: the id field to match.
+ * @property {string} [linePrefix] - For line: lines starting with this
+ *          string are owned and removed.
+ * @property {string} [sectionHeader] - For section: the header line;
+ *          every line under it up to a blank-line sentinel is owned.
+ * @property {string} [commandFingerprint] - For the SessionStart hook
+ *          entry: `command` field contains this substring.
+ */
+
+/**
+ * The complete v3.1.0 artifact list. Frozen so callers can't mutate
+ * the catalog at runtime — if a future feature needs to conditionally
+ * include/exclude entries, do the filter at consumption time, not by
+ * editing the module.
+ *
+ * Order matters for display: the uninstall command's pre-removal
+ * summary renders in this order, so keep "scope grouped and cheapest
+ * operation first" within each scope for a predictable UX.
+ */
+export const ARTIFACT_REGISTRY = Object.freeze([
+  // ── Project scope ────────────────────────────────────────────────
+  Object.freeze({
+    id: "claude-mcp-entry",
+    scope: "project",
+    kind: "json-key",
+    pathFn: claudeMcpJson,
+    displayPath: ".mcp.json",
+    jsonPath: ["mcpServers", "skillrepo"],
+  }),
+  Object.freeze({
+    id: "cursor-mcp-entry",
+    scope: "project",
+    kind: "json-key",
+    pathFn: cursorMcpJson,
+    displayPath: ".cursor/mcp.json",
+    jsonPath: ["mcpServers", "skillrepo"],
+  }),
+  Object.freeze({
+    id: "vscode-mcp-entry",
+    scope: "project",
+    kind: "json-key",
+    pathFn: vscodeMcpJson,
+    displayPath: ".vscode/mcp.json",
+    jsonPath: ["servers", "skillrepo"],
+  }),
+  Object.freeze({
+    id: "vscode-mcp-input",
+    scope: "project",
+    kind: "json-input",
+    pathFn: vscodeMcpJson,
+    displayPath: ".vscode/mcp.json",
+    inputId: VSCODE_INPUT_ID,
+  }),
+  Object.freeze({
+    id: "env-local-key",
+    scope: "project",
+    kind: "line",
+    pathFn: envLocal,
+    displayPath: ".env.local",
+    linePrefix: `${ENV_LOCAL_KEY_NAME}=`,
+  }),
+  Object.freeze({
+    id: "gitignore-entries",
+    scope: "project",
+    kind: "section",
+    pathFn: gitignorePath,
+    displayPath: ".gitignore",
+    sectionHeader: GITIGNORE_SECTION_HEADER,
+  }),
+  Object.freeze({
+    id: "settings-session-hook",
+    scope: "project",
+    kind: "json-key",
+    pathFn: () => join(process.cwd(), ".claude", "settings.local.json"),
+    displayPath: ".claude/settings.local.json",
+    // Hook entries live in `hooks.SessionStart` as an array of
+    // objects. The remover filters the array by a predicate on the
+    // `command` field rather than by index, because array order is
+    // not load-bearing and user-authored hooks may precede or follow
+    // SkillRepo's entry.
+    commandFingerprint: SESSION_HOOK_FINGERPRINT,
+  }),
+  Object.freeze({
+    id: "skills-dir-project",
+    scope: "project",
+    kind: "directory",
+    pathFn: claudeSkillsProjectRoot,
+    displayPath: ".claude/skills/",
+  }),
+
+  // ── Global scope ─────────────────────────────────────────────────
+  Object.freeze({
+    id: "windsurf-mcp-entry",
+    scope: "global",
+    kind: "json-key",
+    pathFn: windsurfMcpJson,
+    displayPath: "~/.codeium/windsurf/mcp_config.json",
+    jsonPath: ["mcpServers", "skillrepo"],
+  }),
+  Object.freeze({
+    id: "skills-dir-global",
+    scope: "global",
+    kind: "directory",
+    pathFn: claudeSkillsGlobalRoot,
+    displayPath: "~/.claude/skills/",
+  }),
+  Object.freeze({
+    id: "global-config-dir",
+    scope: "global",
+    kind: "directory",
+    // `~/.claude/skillrepo/` — the parent dir of both config.json and
+    // .last-sync. Whole-directory removal is correct because both
+    // children are CLI-owned and there's no room for user content.
+    pathFn: () => join(homedir(), ".claude", "skillrepo"),
+    displayPath: "~/.claude/skillrepo/",
+  }),
+  Object.freeze({
+    // Global-scope counterpart to `settings-session-hook` above. Added
+    // in #884 alongside the session-sync feature: `skillrepo init
+    // --global` and `skillrepo session-sync enable --global` write the
+    // hook to the user-wide settings file, not the project-local one.
+    // Without this descriptor, `skillrepo uninstall --global` would
+    // miss the global hook — a real gap that `session-sync disable
+    // --global` could clean up but the project-scope uninstall could
+    // not. Mirrors the skills-dir-project / skills-dir-global pair.
+    id: "settings-session-hook-global",
+    scope: "global",
+    kind: "json-key",
+    pathFn: () => join(homedir(), ".claude", "settings.local.json"),
+    displayPath: "~/.claude/settings.local.json",
+    commandFingerprint: SESSION_HOOK_FINGERPRINT,
+  }),
+]);
+
+/**
+ * Convenience filter by scope. Used by the uninstall command to
+ * partition the registry for the "project only" vs "project + global"
+ * passes.
+ */
+export function artifactsByScope(scope) {
+  return ARTIFACT_REGISTRY.filter((a) => a.scope === scope);
+}
+
+/**
+ * Lookup by id. Returns `undefined` for unknown ids — callers should
+ * treat that as a programming error (registry lookup for an id that
+ * was never declared), not a user-visible failure.
+ */
+export function artifactById(id) {
+  return ARTIFACT_REGISTRY.find((a) => a.id === id);
+}

package/src/lib/fs-utils.mjs

@@ -3,7 +3,16 @@
  * Creates directories as needed, handles errors cleanly.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, chmodSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  statSync,
+  chmodSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
 import { dirname } from "node:path";
 
 /**
@@ -50,3 +59,76 @@ export function writeExecutable(filePath, content) {
 export function pathExists(p) {
   return existsSync(p);
 }
+
+/**
+ * Atomic write via temp-file + rename. Matches the pattern in
+ * `config.mjs`: write to `<path>.tmp`, then `renameSync` into place
+ * so the destination is never observed in a half-written state, and
+ * unlink the temp file on rename failure so a partial credential
+ * value is never left behind on disk.
+ *
+ * Use this (not `writeFileSafe`) for any module that modifies a user
+ * config file containing credentials or shared state. The uninstall
+ * removers (#885) touch `.env.local`, `.mcp.json`, and
+ * `settings.local.json` — all three benefit from atomic writes, the
+ * first two because of the credential-leak risk, the third because
+ * Claude Code parses it on startup and a half-written JSON would
+ * break the user's session.
+ *
+ * Parent-directory semantics match `writeFileSafe`: created
+ * recursively if missing. Directory-as-file collision is rejected
+ * before the temp-file is written.
+ *
+ * @param {string} filePath - Absolute path to the final destination.
+ * @param {string} content - UTF-8 content to persist.
+ * @param {object} [options]
+ * @param {number} [options.mode] - chmod applied to the temp file
+ *        BEFORE rename so the destination never exists with looser
+ *        permissions than intended. Skipped on Windows.
+ */
+export function writeFileAtomic(filePath, content, { mode } = {}) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+    throw new Error(`${filePath} is a directory, expected a file`);
+  }
+
+  const tmpPath = `${filePath}.tmp`;
+  try {
+    writeFileSync(tmpPath, content, "utf-8");
+  } catch (err) {
+    // Re-throw with a clearer message but preserve the cause for
+    // --verbose. A temp-file write failure is almost always a
+    // permissions or disk-full issue; the original error surfaces it.
+    throw new Error(`Cannot write ${tmpPath}: ${err.message}`, { cause: err });
+  }
+
+  if (mode !== undefined && process.platform !== "win32") {
+    try {
+      chmodSync(tmpPath, mode);
+    } catch {
+      // Non-fatal — same rationale as config.mjs: chmod failure
+      // doesn't corrupt the file, the destination just has looser
+      // permissions than intended. Callers that care can stat the
+      // file after the write.
+    }
+  }
+
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    // Clean up the stale temp file so a partial credential value
+    // isn't left behind. Best-effort — if the unlink also fails,
+    // the original rename error is still what we surface.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* best-effort */
+    }
+    throw new Error(`Cannot install ${filePath}: ${err.message}`, {
+      cause: err,
+    });
+  }
+}

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

@@ -0,0 +1,298 @@
+/**
+ * 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 { 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";
+
+/**
+ * Build the hook command string for a given absolute path. Exported
+ * so tests can assert the exact bytes the installer writes.
+ *
+ * @param {string} binaryPath - Absolute path to the `skillrepo` binary.
+ * @returns {string} The full shell command string.
+ */
+export function buildHookCommand(binaryPath) {
+  if (typeof binaryPath !== "string" || binaryPath.length === 0) {
+    throw validationError(
+      "buildHookCommand: binaryPath must be a non-empty string.",
+    );
+  }
+  return `${binaryPath} update --session-hook 2>&1 || true`;
+}
+
+/**
+ * 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() {
+  try {
+    // 3-second timeout — `which` typically returns in milliseconds,
+    // but a PATH that includes a network filesystem or a `which`
+    // alias that does I/O could hang indefinitely. Bounding the
+    // call ensures `skillrepo init` never stalls on binary
+    // resolution. Per code-reviewer round-1 LOW finding.
+    const result = execFileSync("which", ["skillrepo"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    }).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.
+    if (!result.startsWith("/")) return null;
+    return result;
+  } catch {
+    // `which` exits non-zero if the binary isn't found. Treat as
+    // "no global install, skip session-sync" — caller handles.
+    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.
+ * @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,
+} = {}) {
+  const filePath = global ? claudeSettingsLocalGlobal() : claudeSettingsLocal();
+  const displayPath = global
+    ? "~/.claude/settings.local.json"
+    : ".claude/settings.local.json";
+
+  const binaryPath = binaryPathOpt ?? resolveSkillrepoBinary();
+  if (!binaryPath) {
+    return {
+      path: displayPath,
+      action: "skipped",
+      reason:
+        "Could not resolve a stable path for `skillrepo`. Session sync requires a global install. Run `npm install -g skillrepo` and re-run `skillrepo session-sync enable`.",
+    };
+  }
+
+  const desiredCommand = buildHookCommand(binaryPath);
+
+  // 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");