skillrepo 3.2.0 → 4.1.0

package/src/lib/cli-config.mjs

@@ -2,7 +2,7 @@
  * Shared credential + flag resolution for command modules.
  *
  * Every command needs to:
- *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
+ *   1. Resolve `--key`/`--url`/`--agent`/`--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
@@ -20,17 +20,28 @@
 import { existsSync, readFileSync } from "node:fs";
 
 import { globalConfigPath } from "./paths.mjs";
+import {
+  AGENT_REGISTRY,
+  AGENTS_COHORT_KEYS,
+  getAgentByAlias,
+} from "./agent-registry.mjs";
 import { authError, validationError } from "./errors.mjs";
 
-const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
-const VENDOR_ALIASES = { claude: "claudeCode" };
+const ALL_VENDOR_KEYS = AGENT_REGISTRY.map((entry) => entry.key);
+
+// Sentinel returned by parseAgentList for `--agent none`. It is the
+// empty array literally — every consumer reads `flags.vendors.length`
+// to detect "no placement writes." Frozen so a downstream mutation
+// (e.g. `.push`) cannot turn one user's `none` into another's surprise.
+const NO_VENDORS = Object.freeze([]);
 
 /**
  * @typedef {Object} ResolvedFlags
  * @property {string} serverUrl
  * @property {string} apiKey
  * @property {boolean} global
- * @property {string[]|null} vendors  - null = use the default
+ * @property {string[]|null} vendors  - null = use the default;
+ *           empty array = `--agent none` (caller skips placement)
  * @property {boolean} json
  */
 
@@ -78,8 +89,22 @@ export function resolveFlags(argv, opts = {}) {
 
     if (arg === "--global") {
       flagState.global = true;
-    } else if (arg === "--ide" && argv[i + 1] !== undefined) {
-      flagState.vendors = parseVendorList(argv[++i]);
+    } else if (arg === "--agent") {
+      if (argv[i + 1] === undefined) {
+        throw validationError(
+          "Missing value for --agent. Pass a comma-separated list (e.g., --agent claude,agents).",
+        );
+      }
+      flagState.vendors = parseAgentList(argv[++i]);
+    } else if (arg === "--ide") {
+      throw validationError(
+        "--ide was renamed to --agent in v3.0.0.",
+        {
+          hint:
+            "Replace --ide with --agent (e.g., --agent claude). " +
+            "Run the command with --help for valid options.",
+        },
+      );
     } else if (arg === "--json") {
       flagState.json = true;
     } else if ((arg === "--key" || arg === "-k") && argv[i + 1] !== undefined) {
@@ -172,62 +197,139 @@ export function resolveFlags(argv, opts = {}) {
 }
 
 /**
- * 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.
+ * Compute the vendor list to pass to file-write / sync.
+ *
+ * Resolution order:
+ *   1. Explicit `--agent` (including the `--agent none` sentinel `[]`)
+ *      always wins. Both flags propagate together, so `--global
+ *      --agent windsurf` correctly resolves to `["windsurf"]` and
+ *      placementTargetsFor maps that to `windsurfGlobal`.
+ *   2. No `--agent` defaults to `["claudeCode"]`, regardless of
+ *      `--global`. The v3.0.0 CLI deliberately does NOT silently
+ *      fall back to `[claudeCode, cursor]` like v2.0.0 did.
+ *
+ * The empty-array `--agent none` sentinel is returned verbatim —
+ * callers detect "no placement" via `vendors.length === 0`. The
+ * default-fallback branch uses an explicit null/undefined check so
+ * the empty array survives.
  */
 export function effectiveVendors(flags) {
-  if (flags.global) return undefined; // global mode ignores vendors
-  if (flags.vendors) return flags.vendors;
-  return ["claudeCode"];
+  if (flags.vendors === null || flags.vendors === undefined) {
+    return ["claudeCode"];
+  }
+  return flags.vendors;
+}
+
+/**
+ * Reject `--agent none` for commands that have no meaningful behavior
+ * without a placement target. `init` and `update` accept `--agent none`
+ * (init still writes config + gitignore; update is a no-op). Every
+ * other write/read-write command (`add`, `get`, `remove`, `uninstall`)
+ * exists to put or remove specific skill files on disk — calling them
+ * with no targets is a user error, not a degenerate-but-valid case.
+ *
+ * Pass the resolved `vendors` array (the output of `effectiveVendors`).
+ * `undefined` (the `--global` case) is allowed because `--global`
+ * implies the Claude Code personal directory; only an empty array is
+ * rejected.
+ *
+ * @param {string[] | undefined} vendors
+ * @param {string} commandName - For the error message.
+ */
+export function requireVendorTargets(vendors, commandName) {
+  if (Array.isArray(vendors) && vendors.length === 0) {
+    throw validationError(
+      `--agent none has no effect on \`skillrepo ${commandName}\` ` +
+        `because the command writes or deletes specific skill files.`,
+      {
+        hint:
+          "Use --agent claude or --agent agents (or a specific vendor) to " +
+          "target a placement, or drop --agent to use the default.",
+      },
+    );
+  }
 }
 
 // ── Internals ──────────────────────────────────────────────────────────
 
-function parseVendorList(raw) {
+/**
+ * Parse the raw `--agent <list>` argument into a deduplicated array
+ * of canonical vendor keys, OR the empty array sentinel for `none`.
+ *
+ * Token semantics (each comma-separated token):
+ *
+ *   - `none`  → empty array (no placement writes). Must be the only
+ *               token — mixing with any other token is rejected.
+ *   - `claude` → `["claudeCode"]` (the Claude Code target shortcut).
+ *   - `agents` → every cohort vendor whose project writes land in
+ *                `.agents/skills/`, derived from the registry.
+ *   - canonical key (e.g., `claudeCode`, `cursor`) → that key.
+ *   - alias declared on a registry entry (e.g., `claude-code`,
+ *     `vscode`) → its canonical key.
+ *   - anything else → validation error.
+ *
+ * `all` is NOT a valid token — use `claude,agents` for full coverage.
+ */
+function parseAgentList(raw) {
   if (typeof raw !== "string") {
-    throw validationError(`--ide expects a comma-separated list, got: ${raw}`);
+    throw validationError(`--agent 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 (pieces.length === 0) {
+    throw validationError("--agent list is empty.", {
+      hint: "Pass one or more of: claude, agents, none, or a vendor name.",
+    });
   }
 
-  if (hasAll) {
-    return ["claudeCode", "cursor", "windsurf", "vscode"];
+  // `none` is mutually exclusive with every other token. Mixing
+  // `--agent claude,none` is ambiguous — does the user want Claude
+  // or no placement? Reject so they pick one.
+  if (pieces.includes("none")) {
+    if (pieces.length > 1) {
+      throw validationError(
+        `--agent cannot mix "none" with other tokens: "${raw}"`,
+        { hint: "Pass --agent none alone, or list specific targets without none." },
+      );
+    }
+    return NO_VENDORS;
   }
 
-  if (normalized.length === 0) {
-    throw validationError("--ide list is empty.");
+  const expanded = [];
+  for (const token of pieces) {
+    if (token === "claude") {
+      expanded.push("claudeCode");
+      continue;
+    }
+    if (token === "agents") {
+      for (const key of AGENTS_COHORT_KEYS) {
+        expanded.push(key);
+      }
+      continue;
+    }
+    const canonical = getAgentByAlias(token);
+    if (canonical !== null) {
+      expanded.push(canonical);
+      continue;
+    }
+    throw validationError(`Unknown --agent target: "${token}"`, {
+      hint:
+        "Use one of: claude, agents, none, or a canonical vendor key " +
+        `(${ALL_VENDOR_KEYS.join(", ")}).`,
+    });
   }
 
-  // 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'.",
-      });
+  // Dedupe while preserving first-seen order — matters for tests and
+  // for downstream consumers that iterate the array deterministically.
+  const seen = new Set();
+  const result = [];
+  for (const key of expanded) {
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(key);
     }
   }
-
-  return normalized;
+  return result;
 }
 
 function readGlobalConfig() {

package/src/lib/detect-agents.mjs

@@ -0,0 +1,112 @@
+/**
+ * Multi-signal agent detection (#1236, Phase 3 of #876).
+ *
+ * Replaces the single-signal `detect-ides.mjs` module. Detection is
+ * registry-driven: every probe is described as a `DetectionSignal` on
+ * the corresponding `AGENT_REGISTRY` entry, and this module just
+ * iterates the registry and runs the platform-correct probe for each
+ * signal type. Adding a new signal is a registry edit, no change here.
+ *
+ * Three signal types:
+ *
+ *   - `env`     — `process.env[value]` is truthy. Indicates an active
+ *                 agent session (the agent itself sets the var in the
+ *                 shells it spawns).
+ *   - `home`    — `~/<value>` exists on disk. Indicates the agent has
+ *                 been installed for this user (most agents create the
+ *                 directory on first run).
+ *   - `project` — `<cwd>/<value>` exists on disk. Indicates the agent
+ *                 is configured for this repo (dotdir / dotfile).
+ *
+ * For each agent, `detected` is the OR of all signal probes. The first
+ * signal that fires (priority order: env > home > project) becomes the
+ * human-readable `reason`. Reasons are formatted to match the picker UX:
+ *
+ *   - env signal:     `"CLAUDECODE=1"`
+ *   - home signal:    `"~/.claude/"` or `"~/.codeium/windsurf/"`
+ *   - project signal: `".claude/"` or `".github/skills/"`
+ *   - none:           `null` (the picker translates this to
+ *                     `"(no signal — opt in if you use one)"`)
+ *
+ * Cross-platform: paths use `node:path.join(homedir(), …)` and
+ * `join(process.cwd(), …)`. On Windows, `homedir()` reads
+ * `USERPROFILE`; the test sandbox helper sets both HOME and USERPROFILE
+ * so probes are sandbox-isolated on every platform.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { AGENT_REGISTRY } from "./agent-registry.mjs";
+
+/**
+ * @typedef {Object} AgentDetection
+ * @property {string} key                 - Canonical agent key.
+ * @property {string} displayName         - Brand name (used in picker hints).
+ * @property {boolean} detected           - True if any signal fired.
+ * @property {string|null} reason         - Short human-readable label of the
+ *           first signal that fired, or `null` when nothing fired.
+ */
+
+/**
+ * Probe one detection signal against the live process state and disk.
+ *
+ * Pure helper. Returns the formatted reason string when the signal
+ * fires, or `null` when it does not.
+ *
+ * @param {import("./agent-registry.mjs").DetectionSignal} signal
+ * @returns {string | null}
+ */
+function probeSignal(signal) {
+  if (signal.type === "env") {
+    const raw = process.env[signal.value];
+    if (raw === undefined || raw === "") return null;
+    // Env vars in shell environments are always strings. Truthy
+    // values include "1", "true", "yes", etc — Cline's documented
+    // value is the literal string "true". We accept any non-empty
+    // value rather than a stricter truthy-string match because the
+    // signal's purpose is "the agent set this var on me" and any
+    // value the agent chose to set qualifies.
+    return `${signal.value}=${raw}`;
+  }
+  if (signal.type === "home") {
+    const path = join(homedir(), signal.value);
+    if (!existsSync(path)) return null;
+    return `~/${signal.value}/`;
+  }
+  if (signal.type === "project") {
+    const path = join(process.cwd(), signal.value);
+    if (!existsSync(path)) return null;
+    return `${signal.value}/`;
+  }
+  // Unknown type — defensive guard. Callers should never see this
+  // because the registry's frozen entries are typed.
+  return null;
+}
+
+/**
+ * Detect every agent in the registry against the current process and
+ * working directory. Returns one `AgentDetection` per registry entry,
+ * in registry order (Claude Code first, then the cohort).
+ *
+ * @returns {AgentDetection[]}
+ */
+export function detectAgents() {
+  return AGENT_REGISTRY.map((entry) => {
+    let reason = null;
+    for (const signal of entry.detectionSignals) {
+      const fired = probeSignal(signal);
+      if (fired !== null) {
+        reason = fired;
+        break;
+      }
+    }
+    return {
+      key: entry.key,
+      displayName: entry.displayName,
+      detected: reason !== null,
+      reason,
+    };
+  });
+}