skillrepo 2.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/cli-config.mjs

@@ -0,0 +1,230 @@
+/**
+ * Shared credential + flag resolution for command modules.
+ *
+ * Every command needs to:
+ *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
+ *   2. Fall back to ~/.claude/skillrepo/config.json
+ *   3. Fall back to SKILLREPO_ACCESS_KEY / SKILLREPO_URL env vars
+ *   4. Hard-error with an actionable hint pointing at `init` if no
+ *      key is configured
+ *
+ * Centralizing this here keeps the four command modules thin and
+ * means a future change to credential resolution (e.g., adding a
+ * keychain backend) is a single edit instead of four.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { globalConfigPath } from "./paths.mjs";
+import { authError, validationError } from "./errors.mjs";
+
+const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
+const VENDOR_ALIASES = { claude: "claudeCode" };
+
+/**
+ * @typedef {Object} ResolvedFlags
+ * @property {string} serverUrl
+ * @property {string} apiKey
+ * @property {boolean} global
+ * @property {string[]|null} vendors  - null = use the default
+ * @property {boolean} json
+ */
+
+/**
+ * Parse common flags from an argv slice. Returns a typed object with
+ * `serverUrl` and `apiKey` resolved per the priority order documented
+ * at the top of this file.
+ *
+ * Throws `validationError` for unknown flags (caller can intercept
+ * extra positional args before calling this).
+ *
+ * @param {string[]} argv - The argv slice the dispatcher passed to the command
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireAuth=true] - If false, skip the no-key error
+ *        (used by commands that may run without credentials, but PR2 has none)
+ * @param {boolean} [opts.skipConfig=false] - If true, DO NOT read from
+ *        ~/.claude/skillrepo/config.json as a fallback. Only flag values
+ *        and env vars are considered. Used by `init` so that its own
+ *        --force / stale-key flow can decide whether to consume cached
+ *        credentials — without this, resolveFlags would silently inject
+ *        the cached key before init's decision logic runs, making
+ *        --force a no-op.
+ * @param {(arg: string, i: number, argv: string[]) => boolean | number} [opts.acceptPositional]
+ *        Optional callback to consume positional args. Return:
+ *          - `false` (or any falsy non-zero) → arg rejected as unknown
+ *          - a positive integer N → consume N args (the current arg
+ *            plus the next N-1 if any)
+ *          - 0 is INVALID and treated the same as `false` — a
+ *            callback that "handles but consumes nothing" is a
+ *            contract violation and would loop forever
+ *          - any non-finite or negative number → invalid, treated as `false`
+ * @returns {ResolvedFlags}
+ */
+export function resolveFlags(argv, opts = {}) {
+  const flagState = {
+    global: false,
+    vendors: null,
+    json: false,
+    key: null,
+    serverUrl: null,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--global") {
+      flagState.global = true;
+    } else if (arg === "--ide" && argv[i + 1] !== undefined) {
+      flagState.vendors = parseVendorList(argv[++i]);
+    } else if (arg === "--json") {
+      flagState.json = true;
+    } else if ((arg === "--key" || arg === "-k") && argv[i + 1] !== undefined) {
+      flagState.key = argv[++i];
+    } else if ((arg === "--url" || arg === "-u") && argv[i + 1] !== undefined) {
+      flagState.serverUrl = argv[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      // Dispatcher should have intercepted this. Defensive no-op.
+      continue;
+    } else {
+      // Allow the caller to consume a positional arg before we treat
+      // it as unknown. This is how `get @owner/name` and
+      // `search <query>` slot in their main argument.
+      //
+      // Contract: callback returns a positive integer N (consume N
+      // args), `false`, or any falsy/zero/negative/non-integer value
+      // (reject the arg). Returning 0 is INVALID — it would mean
+      // "handled but consumed nothing", which would infinite-loop on
+      // the same arg. We reject zero defensively rather than trust
+      // every caller to read the JSDoc.
+      const consumed = opts.acceptPositional?.(arg, i, argv);
+      if (
+        typeof consumed === "number" &&
+        Number.isInteger(consumed) &&
+        consumed > 0
+      ) {
+        i += consumed - 1; // -1 because the for loop also increments
+      } else {
+        throw validationError(`Unknown argument: ${arg}`, {
+          hint: "Run the command with --help for valid options.",
+        });
+      }
+    }
+  }
+
+  // Resolve credentials in priority order
+  let serverUrl = flagState.serverUrl;
+  let apiKey = flagState.key;
+
+  // `skipConfig` suppresses the config-file fallback AND the eager
+  // default for serverUrl. `init` needs this because it owns the
+  // credential lifecycle: it reads the config file itself so
+  // `--force` and the stale-key re-prompt path can decide whether
+  // to use the cached credentials, and it needs to see `null`
+  // serverUrl (not the baked-in production URL) so its own
+  // "existingConfig.serverUrl → env → DEFAULT_URL" fallback chain
+  // takes effect. Without this, `init`'s `!serverUrl` branch was
+  // dead because resolveFlags would already have set it to
+  // https://skillrepo.dev.
+  if (opts.skipConfig) {
+    // Env var still applies — it's explicit config, not a cached
+    // credential. But the production URL default does NOT apply;
+    // the caller is expected to provide its own default.
+    if (!serverUrl) serverUrl = process.env.SKILLREPO_URL || null;
+    if (!apiKey) apiKey = process.env.SKILLREPO_ACCESS_KEY || null;
+  } else {
+    if (!serverUrl || !apiKey) {
+      const config = readGlobalConfig();
+      if (config) {
+        serverUrl = serverUrl || config.serverUrl;
+        apiKey = apiKey || config.apiKey;
+      }
+    }
+    if (!serverUrl) serverUrl = process.env.SKILLREPO_URL || "https://skillrepo.dev";
+    if (!apiKey) apiKey = process.env.SKILLREPO_ACCESS_KEY || null;
+  }
+
+  if (!apiKey && opts.requireAuth !== false) {
+    throw authError("No access key configured.", {
+      hint: "Run `skillrepo init` first, or pass --key sk_live_...",
+    });
+  }
+
+  return {
+    serverUrl,
+    apiKey,
+    global: flagState.global,
+    vendors: flagState.vendors,
+    json: flagState.json,
+  };
+}
+
+/**
+ * Compute the vendor list to pass to file-write / sync. Defaults to
+ * `["claudeCode"]` when neither `--ide` nor `--global` is provided —
+ * the v3.0.0 CLI deliberately does NOT silently fall back to
+ * `[claudeCode, cursor]` like v2.0.0 did. The user opts in.
+ */
+export function effectiveVendors(flags) {
+  if (flags.global) return undefined; // global mode ignores vendors
+  if (flags.vendors) return flags.vendors;
+  return ["claudeCode"];
+}
+
+// ── Internals ──────────────────────────────────────────────────────────
+
+function parseVendorList(raw) {
+  if (typeof raw !== "string") {
+    throw validationError(`--ide expects a comma-separated list, got: ${raw}`);
+  }
+
+  // First pass: collect tokens, normalize aliases, detect `all`.
+  const pieces = raw.split(",").map((p) => p.trim()).filter(Boolean);
+  const normalized = pieces.map((v) => VENDOR_ALIASES[v] ?? v);
+  const hasAll = normalized.includes("all");
+  const otherVendors = normalized.filter((v) => v !== "all");
+
+  // Defense against confusing input: `--ide cursor,all` is ambiguous
+  // — the user might think it means "cursor first, then everything"
+  // or "all minus duplicates". Both interpretations are wrong because
+  // `all` is the full set. Reject the combination so the user is
+  // forced to pick one.
+  if (hasAll && otherVendors.length > 0) {
+    throw validationError(
+      `--ide cannot mix "all" with other vendors: "${raw}"`,
+      { hint: "Use --ide all OR --ide claude,cursor,... — not both." },
+    );
+  }
+
+  if (hasAll) {
+    return ["claudeCode", "cursor", "windsurf", "vscode"];
+  }
+
+  if (normalized.length === 0) {
+    throw validationError("--ide list is empty.");
+  }
+
+  // Validate each vendor token
+  for (const resolved of normalized) {
+    if (!VALID_VENDORS.has(resolved)) {
+      // Find the original (un-aliased) form for the error message
+      const original = pieces[normalized.indexOf(resolved)];
+      throw validationError(`Unknown --ide vendor: "${original}"`, {
+        hint: "Use claudeCode (or 'claude'), cursor, windsurf, vscode, or 'all'.",
+      });
+    }
+  }
+
+  return normalized;
+}
+
+function readGlobalConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed && typeof parsed === "object") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}