skillrepo 3.0.0 → 3.1.1

package/src/lib/artifact-registry.mjs

@@ -0,0 +1,305 @@
+/**
+ * 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 ends with `<binary-path> update --session-hook ...`; any
+ * entry whose command contains ` update --session-hook` (with the
+ * leading space) is removed by the uninstall path.
+ *
+ * The leading space is a lightweight word boundary — it requires
+ * that `update` is preceded by whitespace (i.e. it's an argv token
+ * after the binary path), not a suffix of a longer identifier like
+ * `toolupdate` or `postupdate`. Without the space, a hypothetical
+ * binary at `/usr/local/bin/myapp-update` invoked with
+ * `--session-hook` as `/usr/local/bin/myapp-update --session-hook`
+ * would NOT match (because the substring would be `-update
+ * --session-hook`, not ` update --session-hook`), whereas a naive
+ * `update --session-hook` fingerprint would have.
+ *
+ * The leading space does NOT eliminate all false-positive classes.
+ * A command like `brew update --session-hook` DOES match the
+ * fingerprint — the space between `brew` and `update` is exactly
+ * what we key on. The primary protection against real-world false
+ * positives is the specificity of the two-token combination
+ * `update --session-hook` itself: `--session-hook` is not a
+ * conventional flag name used by tools other than SkillRepo, so the
+ * chance of a coincidental match is astronomically low. The test
+ * at `session-hook.test.mjs` "the fingerprint is specific enough
+ * that innocuous user hooks do NOT match it" enumerates plausible
+ * user-hook commands and confirms none trip the predicate.
+ *
+ * The fingerprint is also deliberately platform-neutral. Earlier
+ * versions matched the longer `skillrepo update --session-hook`
+ * substring, but that pattern silently fails to match Windows hook
+ * commands because npm installs the CLI as a `.cmd` shim — the
+ * absolute path on Windows ends `...\skillrepo.cmd`, which puts the
+ * `.cmd` extension between `skillrepo` and `update` in the command
+ * string. The shorter ` update --session-hook` substring is present
+ * on both:
+ *   POSIX:   `/usr/local/bin/skillrepo update --session-hook 2>&1 || true`
+ *   Windows: `C:\path\skillrepo.cmd update --session-hook 2>&1`
+ *
+ * Backward-compat: any v3.1.0 hook contains
+ * `skillrepo update --session-hook`, which is a strict superset of
+ * ` update --session-hook` (the space between `skillrepo` and `update`
+ * is the space we're matching). So upgrades still correctly identify
+ * and update the old entry in place.
+ *
+ * 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 = " 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/cli-config.mjs

@@ -1,6 +1,11 @@
 /**
  * Shared credential + flag resolution for command modules.
  *
+ * Also houses process-environment helpers that multiple command
+ * modules need — specifically `isNpxInvocation()` which several
+ * surfaces use to decide whether the user has a stable global
+ * install or is running a transient npx download.
+ *
  * Every command needs to:
  *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
  *   2. Fall back to ~/.claude/skillrepo/config.json
@@ -21,6 +26,70 @@ import { authError, validationError } from "./errors.mjs";
 const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
 const VENDOR_ALIASES = { claude: "claudeCode" };
 
+/**
+ * True when the current process was launched via `npx skillrepo ...`
+ * rather than from a stable global install.
+ *
+ * Why this matters:
+ *
+ *   - `npx skillrepo init` downloads the package into `~/.npm/_npx/<hash>/`
+ *     and exposes its `.bin/skillrepo` on PATH for the subprocess only.
+ *     `execFileSync("which", ["skillrepo"])` DOES find that path, but it
+ *     is a transient cache location. npm eviction, a version bump, or
+ *     `npm cache clean` later invalidates the absolute path, so any
+ *     on-disk reference to it (e.g. a SessionStart hook command baked
+ *     in at install time) silently breaks.
+ *
+ *   - The architect design for #884 explicitly specified that npx
+ *     users should skip the session-sync step with a "requires a global
+ *     install" warning. The `which`-based resolver in
+ *     `mergers/session-hook.mjs` alone is too permissive — it finds the
+ *     npx cache path and treats it as stable. This helper closes that
+ *     gap by detecting npx unambiguously.
+ *
+ *   - `init`'s "Next steps" output also needs to know: under npx, the
+ *     right hint is `npx skillrepo list` (or "install globally first"),
+ *     not bare `skillrepo list` (which would fail for the user).
+ *
+ * Detection uses two signals, either one sufficient:
+ *
+ *   1. `process.argv[1]` contains `/_npx/` (or Windows `\_npx\`) —
+ *      the primary signal. npx-launched scripts literally live inside
+ *      `~/.npm/_npx/<hash>/node_modules/.bin/...` so the executable
+ *      path itself names the cache directory. Highest reliability,
+ *      no false-positive surface.
+ *
+ *   2. `process.env._` ends with `/npx` (or `\npx` on Windows) —
+ *      legacy fallback for shells that set `_` to the launched
+ *      command. Defensive against shim layouts where argv[1] has
+ *      been symlinked through a path that doesn't contain `_npx`.
+ *
+ * Why NOT `process.env.npm_command === "exec"`: this signal was
+ * considered but rejected in v3.1.1 review. `npm_command=exec` is
+ * also set when a stable-install user runs `skillrepo init` from a
+ * `package.json` lifecycle script (e.g. `"postinstall": "skillrepo
+ * init --yes"`) or invokes `npm exec skillrepo ...` directly. In
+ * those cases the user has a real global install and should NOT
+ * have session-sync skipped or see `npx skillrepo` in Next Steps.
+ * The argv[1] signal already catches real npx invocations
+ * unambiguously; adding npm_command trades a minor coverage gain
+ * (shim layouts) for a false-positive surface that affects real
+ * users. See v3.1.1 PR review cycle for the full discussion.
+ *
+ * @returns {boolean}
+ */
+export function isNpxInvocation() {
+  const execPath = process.argv[1] ?? "";
+  if (execPath.includes("/_npx/") || execPath.includes("\\_npx\\")) {
+    return true;
+  }
+  const underscore = process.env._ ?? "";
+  if (underscore.endsWith("/npx") || underscore.endsWith("\\npx")) {
+    return true;
+  }
+  return false;
+}
+
 /**
  * @typedef {Object} ResolvedFlags
  * @property {string} serverUrl
@@ -85,6 +154,15 @@ export function resolveFlags(argv, opts = {}) {
     } else if (arg === "--help" || arg === "-h") {
       // Dispatcher should have intercepted this. Defensive no-op.
       continue;
+    } else if (arg === "--verbose") {
+      // Global flag set by the dispatcher into SKILLREPO_VERBOSE=1
+      // so http.mjs's retry logger can honor it. It's a first-class
+      // flag, not an unknown arg — accept it silently in every
+      // command that passes through resolveFlags. Before this
+      // branch existed, any command that consumed argv via
+      // resolveFlags rejected `--verbose` with "Unknown argument",
+      // breaking the flag documented in the top-level --help.
+      continue;
     } else {
       // Allow the caller to consume a positional arg before we treat
       // it as unknown. This is how `get @owner/name` and

package/src/lib/config.mjs

@@ -43,10 +43,10 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
-import { platform } from "node:os";
 
 import { globalConfigPath } from "./paths.mjs";
 import { diskError, validationError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Current schema version. Bump this on any structural change.
@@ -187,8 +187,11 @@ export function writeConfig(config) {
 
   // chmod the temp file before renaming so the destination never
   // exists with world-readable perms (which would be a brief
-  // credential leak window on a shared system).
-  if (platform() !== "win32") {
+  // credential leak window on a shared system). Windows callers
+  // route through platformConventions().supportsPosixPermissions —
+  // see platform.mjs for why we skip chmod there instead of pretend-
+  // applying it.
+  if (platformConventions().supportsPosixPermissions) {
     try {
       chmodSync(tmpPath, 0o600);
     } catch {

package/src/lib/file-write.mjs

@@ -50,7 +50,6 @@ import {
   statSync,
 } from "node:fs";
 import { dirname, join, isAbsolute, relative } from "node:path";
-import { platform } from "node:os";
 
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
@@ -63,6 +62,7 @@ import {
   gitignorePath,
 } from "./paths.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 // ── Constants (mirror the server-side validators in src/lib/skills/) ────
 
@@ -562,8 +562,13 @@ function writeSkillToDir(skill, targetDir) {
     }
   }
 
-  // 2 + 3 + 4: rename dance (POSIX atomic on same filesystem; best-effort on Windows)
-  if (platform() === "win32") {
+  // 2 + 3 + 4: rename dance. POSIX is atomic on the same filesystem;
+  // Windows has to do remove-then-rename because renameSync fails on
+  // existing directory targets. The split is named via
+  // platformConventions().supportsAtomicDirectoryRename so the intent
+  // reads as a capability check, not a platform check. See
+  // platform.mjs for the rationale.
+  if (!platformConventions().supportsAtomicDirectoryRename) {
     // Windows: rename fails on existing destinations and locked files,
     // so we fall back to remove-then-rename. There is a window where
     // the live target is gone but the rename has not yet completed.

package/src/lib/fs-utils.mjs

@@ -3,8 +3,18 @@
  * 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";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Read a file as UTF-8, returning null if it doesn't exist.
@@ -36,17 +46,88 @@ export function writeFileSafe(filePath, content) {
 }
 
 /**
- * Write a file and mark it executable (0o755).
- * Used for the Cursor session hook which is invoked directly via shebang.
+ * Check if a path exists (file or directory).
  */
-export function writeExecutable(filePath, content) {
-  writeFileSafe(filePath, content);
-  chmodSync(filePath, 0o755);
+export function pathExists(p) {
+  return existsSync(p);
 }
 
 /**
- * Check if a path exists (file or directory).
+ * 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 pathExists(p) {
-  return existsSync(p);
+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 && platformConventions().supportsPosixPermissions) {
+    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.
+    }
+  }
+  // On Windows we deliberately skip chmod entirely. Node lets the call
+  // succeed on Windows but the mode bits don't map to anything the
+  // ACL layer enforces, so a "success" return would mislead the caller
+  // into thinking the credential file is access-restricted when it
+  // isn't. Windows users needing per-user protection should rely on
+  // %APPDATA%'s inherited ACLs (which default to the current user) or
+  // apply DACL restrictions at the OS level — outside this CLI's scope.
+
+  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,
+    });
+  }
 }