skillrepo 2.0.0 → 3.1.0

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

@@ -3,7 +3,7 @@
  * Uses Node built-ins only — no dependencies.
  */
 
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { homedir } from "node:os";
 
 const cwd = () => process.cwd();
@@ -11,19 +11,10 @@ const cwd = () => process.cwd();
 // Claude Code
 export const claudeMcpJson = () => join(cwd(), ".mcp.json");
 export const claudeDir = () => join(cwd(), ".claude");
-export const claudeSettingsLocal = () => join(cwd(), ".claude", "settings.local.json");
-export const claudeSkillrepoMd = () => join(cwd(), ".claude", "skillrepo.md");
-export const claudeSkillrepoIndex = () => join(cwd(), ".claude", "skillrepo-index.json");
-export const claudeSkillrepoConfig = () => join(cwd(), ".claude", "skillrepo-config.json");
 
 // Cursor
 export const cursorDir = () => join(cwd(), ".cursor");
 export const cursorMcpJson = () => join(cwd(), ".cursor", "mcp.json");
-export const cursorRulesDir = () => join(cwd(), ".cursor", "rules");
-export const cursorHooksDir = () => join(cwd(), ".cursor", "hooks");
-export const cursorSkillrepoMdc = () => join(cwd(), ".cursor", "rules", "skillrepo.mdc");
-export const cursorSkillrepoIndex = () => join(cwd(), ".cursor", "skillrepo-index.json");
-export const cursorHooksJson = () => join(cwd(), ".cursor", "hooks.json");
 
 // Windsurf (always global — no project-level config)
 export const windsurfDir = () => join(homedir(), ".codeium", "windsurf");
@@ -34,15 +25,74 @@ export const vscodeDir = () => join(cwd(), ".vscode");
 export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 
 // Global SkillRepo cache (shared across projects, lives in user home)
-export const globalSkillrepoDir = () => join(homedir(), ".claude", "skillrepo");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
-export const globalIndexPath = () => join(homedir(), ".claude", "skillrepo", "index.json");
-export const globalSkillsDir = () => join(homedir(), ".claude", "skillrepo", "skills");
 
-// Project-level rules directories (deterministic skill delivery)
-export const claudeRulesDir = () => join(cwd(), ".claude", "rules");
+// ── Skill placement targets (added in #646 / PR1) ─────────────────────
+//
+// Claude Code documents two skill discovery locations at
+// https://code.claude.com/docs/en/skills:
+//
+//   Personal: ~/.claude/skills/<name>/SKILL.md
+//   Project:  <cwd>/.claude/skills/<name>/SKILL.md
+//
+// The `name` segment must match the `name` field in the SKILL.md
+// frontmatter per the agentskills.io spec — the file-write pipeline
+// enforces this at write time.
+//
+// Other detected vendors (Cursor, Windsurf, VS Code Copilot) do not
+// currently document an on-disk skill discovery convention. For those
+// vendors, the file-write pipeline writes to a project-level fallback
+// at `<cwd>/skills/<name>/`, with an entry added to .gitignore on
+// first write so the user-specific skill set never leaks into the repo
+// history. See follow-up issue #876 for tracking when those IDEs
+// publish their own conventions.
+
+/** Claude Code project-local skill directory for a specific skill name. */
+export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", name);
+
+/** Claude Code personal/global skill directory for a specific skill name. */
+export const claudeSkillsGlobal = (name) => join(homedir(), ".claude", "skills", name);
+
+/** Project-local fallback skills root (used when --ide includes a vendor without a documented convention). */
+export const projectSkillsFallbackRoot = () => join(cwd(), "skills");
+
+/** Project-local fallback for a specific skill name. */
+export const projectSkillsFallback = (name) => join(cwd(), "skills", name);
+
+/** Parent directory of the project-local Claude Code skills (used by orphan cleanup). */
+export const claudeSkillsProjectRoot = () => join(cwd(), ".claude", "skills");
+
+/** Parent directory of the personal/global Claude Code skills (used by orphan cleanup). */
+export const claudeSkillsGlobalRoot = () => join(homedir(), ".claude", "skills");
+
+// ── Shared ────────────────────────────────────────────────────────────
 
-// Shared
 export const envLocal = () => join(cwd(), ".env.local");
-export const projectRoot = () => resolve(cwd());
+
+/**
+ * Project .gitignore — used by the file-write pipeline to ensure the
+ * 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/prompt.mjs

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

package/src/lib/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" };
+}

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 };
+}