skillrepo 3.2.0 → 4.1.0

package/src/commands/list.mjs

@@ -14,7 +14,7 @@
  *   --json           Pipe-friendly JSON output
  *   --key/--url      Override credentials
  *
- * No --global / --ide flags — `list` is a library-state inspector,
+ * No --global / --agent flags — `list` is a library-state inspector,
  * not a writer.
  */
 

package/src/commands/remove.mjs

@@ -32,13 +32,17 @@
  *   - 403 scope → scopeError (via http.mjs) with write-key hint
  *   - 401 → authError
  *
- * Flags: --global / --ide / --json / --key / --url
+ * Flags: --global / --agent / --json / --key / --url
  * Positional: <@owner/name>
  */
 
 import { removeSkillFromLibrary } from "../lib/http.mjs";
 import { removeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -75,6 +79,10 @@ export async function runRemove(argv, io = {}) {
 
   const { owner, name } = parseIdentifier(identifier);
   const vendors = effectiveVendors(flags);
+  // `remove` deletes specific files from disk — `--agent none` means
+  // "no targets to delete from", which is a no-op the user almost
+  // certainly didn't intend. Reject early.
+  requireVendorTargets(vendors, "remove");
 
   // Pre-flight: clean any .old/ orphans from a prior crashed write.
   // `remove` isn't writing new files, but it IS deleting, and the

package/src/commands/uninstall.mjs

@@ -58,6 +58,7 @@ import { removeCursorMcp } from "../lib/removers/cursor-mcp.mjs";
 import { removeVscodeMcp } from "../lib/removers/vscode-mcp.mjs";
 import { removeWindsurfMcp } from "../lib/removers/windsurf-mcp.mjs";
 import { removeSettingsSessionHook } from "../lib/removers/settings.mjs";
+import { removeAgentHookArtifact } from "../lib/removers/agent-hooks.mjs";
 import { confirm } from "../lib/prompt.mjs";
 import { resolveFlags } from "../lib/cli-config.mjs";
 import { diskError } from "../lib/errors.mjs";
@@ -398,6 +399,14 @@ function runForDescriptor(descriptor, { dryRun }) {
   if (descriptor.kind === "directory") {
     return removeDirectoryArtifact(descriptor, { dryRun });
   }
+  // Cohort SessionStart-hook descriptors (#1240) dispatch by `kind`
+  // rather than by id: every `kind: "agent-hook"` descriptor goes to
+  // the same batch remover, which uses the descriptor's `vendorKey`
+  // to route to the per-shape merger. Adding a new cohort vendor =
+  // one registry entry + one descriptor; this dispatch never changes.
+  if (descriptor.kind === "agent-hook") {
+    return removeAgentHookArtifact(descriptor, { dryRun });
+  }
   const fn = FILE_REMOVERS[descriptor.id];
   if (!fn) {
     // Only reachable for descriptors that share a remover with a
@@ -418,7 +427,9 @@ function renderPreviewLine(descriptor, result) {
       ? "   [dir]   "
       : descriptor.kind === "line" || descriptor.kind === "section"
         ? "   [lines] "
-        : "   [entry] ";
+        : descriptor.kind === "agent-hook"
+          ? "   [hook]  "
+          : "   [entry] ";
   const detail = result.error
     ? `→ ${result.error}`
     : result.detail
@@ -430,7 +441,7 @@ function renderPreviewLine(descriptor, result) {
 function parseUninstallFlags(argv) {
   let dryRun = false;
   let yes = false;
-  // Reuse resolveFlags for the standard --global / --json / --ide /
+  // Reuse resolveFlags for the standard --global / --json / --agent /
   // --key / --url shape. resolveFlags ignores unknown flags when an
   // acceptPositional callback is provided that can consume them —
   // the callback pattern matches init's own parsing.

package/src/commands/update.mjs

@@ -7,7 +7,7 @@
  *
  * Flags (parsed by the shared `resolveFlags` helper):
  *   --global         Write to ~/.claude/skills/ instead of project-local
- *   --ide <list>     Comma-separated vendor list
+ *   --agent <list>   Comma-separated agent target list
  *   --json           Print summary as JSON
  *   --key <key>      Override config-file access key
  *   --url <url>      Override config-file server URL
@@ -21,12 +21,32 @@
  *                    command behaves as before (exit non-zero on
  *                    network / auth / disk failures).
  *
+ * v4.1.0 silent mode (#1240):
+ *   --silent         Suppress stdout: write `{}` on success, propagate
+ *                    failures (non-zero exit) with the error on stderr.
+ *                    Used by the per-agent SessionStart hooks (Cursor,
+ *                    Gemini CLI, Codex CLI, VS Code + Copilot) the
+ *                    cohort installer writes via `npx --yes skillrepo
+ *                    update --silent`. Gemini CLI specifically requires
+ *                    hook stdout to be valid JSON; the empty `{}`
+ *                    satisfies that. Distinct from `--session-hook` —
+ *                    `--silent` does NOT suppress error exit codes,
+ *                    because none of the cohort agents block session
+ *                    start on non-zero hook exits the way Claude Code
+ *                    does. If primary-source evidence later shows a
+ *                    cohort vendor DOES block, give that vendor its
+ *                    own contract flag rather than widening this one.
+ *
  * Exit codes are inherited from sync.mjs / http.mjs error types,
  * EXCEPT under `--session-hook` — see the flag's contract below.
  */
 
 import { runSync } from "../lib/sync.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 
 /**
  * Run `update`.
@@ -58,31 +78,41 @@ import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
  */
 export async function runUpdate(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
-  // `stderr` is not used directly — the session-hook path pipes to
-  // BLACK_HOLE_STREAM and the normal path forwards `io` to runSync
-  // which reads `io.stderr` itself.
+  const stderr = io.stderr ?? process.stderr;
 
-  // ── Pre-pass: detect --session-hook BEFORE resolveFlags runs ─────
+  // ── Pre-pass: detect --session-hook / --silent BEFORE resolveFlags runs ─
   //
-  // resolveFlags can throw in three categories we must catch under
-  // session-hook mode:
+  // resolveFlags can throw in three categories the wrapping mode must
+  // catch:
   //   - `authError` when no access key is configured (e.g., session
   //     fires before `skillrepo init` has run — a real first-run
   //     scenario, not synthetic)
   //   - `validationError` on unknown flags
-  //   - `validationError` from parseVendorList on a malformed --ide
+  //   - `validationError` from parseAgentList on a malformed --agent
   //
   // All three happen INSIDE resolveFlags, before our try/catch block
   // could see them if we called it after. The only robust answer is
-  // to detect --session-hook without invoking resolveFlags, then
-  // wrap resolveFlags + runSync together in the error handler.
+  // to detect the mode flags without invoking resolveFlags, then wrap
+  // resolveFlags + runSync together in the error handler.
   //
-  // A simple argv scan is safe here: `--session-hook` has no value
-  // argument, so a plain `.includes` match can't misinterpret
-  // positional args. This DOES NOT accept variations like
-  // `--session-hook=true` or `-SH` — single canonical form only,
-  // matching what the installer writes.
+  // A simple argv scan is safe here: neither flag takes a value, so a
+  // plain `.includes` match can't misinterpret positional args. This
+  // DOES NOT accept variations like `--session-hook=true` or `-S` —
+  // single canonical form only, matching what the installers write.
   const sessionHook = argv.includes("--session-hook");
+  const silent = argv.includes("--silent");
+
+  // Precedence: when both flags appear in argv, `--session-hook`
+  // wins because the order of the branches below dispatches it
+  // first. The session-hook path's `acceptPositional` accepts both
+  // flags so it doesn't reject `--silent` as unknown. The silent
+  // path only accepts `--silent` (different exit-code contract).
+  // Don't reorder these branches without coordinating with the two
+  // hook-installer paths in `commands/init-cohort-hooks.mjs` and
+  // `mergers/session-hook.mjs`. Practical exposure: zero — neither
+  // installer writes a hook command containing both flags. The
+  // precedence is defensive against a future code path or a manual
+  // user edit, not an active scenario.
 
   if (sessionHook) {
     // Session-hook mode: wrap EVERY error path in try/catch so a
@@ -90,14 +120,24 @@ export async function runUpdate(argv, io = {}) {
     try {
       const flags = resolveFlags(argv, {
         acceptPositional(arg) {
-          // resolveFlags sees --session-hook as unknown unless we
-          // consume it here. Kept for the non-error path — the
-          // real "catch errors" logic is the outer try.
+          // resolveFlags sees these as unknown unless we consume them
+          // here. Both flags are accepted because a future caller may
+          // combine them (defense — installers should pick one); the
+          // outer mode dispatch above already chose `session-hook` if
+          // present, so accepting `--silent` here is a no-op tolerance.
           if (arg === "--session-hook") return 1;
+          if (arg === "--silent") return 1;
           return false;
         },
       });
       const vendors = effectiveVendors(flags);
+      // `--agent none` makes `update` a no-op — the user opted out of
+      // placement, so there's nowhere to write the synced library.
+      // Reject in session-hook mode too: the contract is "exit 0 on
+      // any error", but the requireVendorTargets throw is a typed
+      // validation error and the outer try/catch maps it to the
+      // documented one-line failure message.
+      requireVendorTargets(vendors, "update");
 
       const summary = await runSync({
         serverUrl: flags.serverUrl,
@@ -137,12 +177,65 @@ export async function runUpdate(argv, io = {}) {
     return;
   }
 
+  // ── Silent mode (#1240): cohort SessionStart hook contract ──────
+  //
+  // Used by Cursor / Gemini CLI / Codex CLI / VS Code + Copilot. Their
+  // SessionStart hook config invokes `npx --yes skillrepo update
+  // --silent`. Contract:
+  //
+  //   - stdout produces ONE valid-JSON line on success: `{}`. Gemini
+  //     CLI specifically requires hook stdout to be JSON; the empty
+  //     object is the minimal valid value that injects no model
+  //     context. Other vendors tolerate it.
+  //   - On failure, stdout writes nothing extra; the typed error
+  //     propagates through the dispatcher's catch which writes to
+  //     stderr and exits with the appropriate code. We do NOT write
+  //     `{}` on failure — partial JSON output alongside an error
+  //     message on stderr would mislead a hook runner that treats
+  //     stdout as model context.
+  //   - All sync progress lines (the "failed to persist last-sync
+  //     state" warning from sync.mjs, etc.) are routed to a black-hole
+  //     stdout so they cannot leak into the JSON expectation.
+  //
+  // Distinct from `--session-hook`. That mode is Claude-Code-specific
+  // and contracts "EXIT 0 ON ALL ERRORS" because Claude Code's hook
+  // runner blocks session start on non-zero exits. The cohort vendors
+  // handled here have no documented session-blocking behavior, so a
+  // failure should surface as a real exit code — the user can then
+  // investigate via `skillrepo update` directly.
+  if (silent) {
+    const flags = resolveFlags(argv, {
+      acceptPositional(arg) {
+        if (arg === "--silent") return 1;
+        return false;
+      },
+    });
+    const vendors = effectiveVendors(flags);
+    requireVendorTargets(vendors, "update");
+
+    await runSync({
+      serverUrl: flags.serverUrl,
+      apiKey: flags.apiKey,
+      vendors,
+      global: flags.global,
+      // sync.mjs surfaces non-fatal warnings (e.g. failed to persist
+      // last-sync state) via stderr; preserve that channel so a real
+      // operator running `update --silent` from a terminal can still
+      // see them. Stdout is the contract-bearing stream and stays
+      // black-hole until we emit `{}` ourselves.
+      io: { stdout: BLACK_HOLE_STREAM, stderr },
+    });
+    stdout.write("{}\n");
+    return;
+  }
+
   // ── Normal mode: original behavior ───────────────────────────────
   // Forward `io` to runSync so the non-fatal "failed to persist
   // last-sync state" warning lands on the injected stderr stream
   // when tests inject one.
   const flags = resolveFlags(argv);
   const vendors = effectiveVendors(flags);
+  requireVendorTargets(vendors, "update");
 
   const summary = await runSync({
     serverUrl: flags.serverUrl,

package/src/lib/agent-hook-merge.mjs

@@ -0,0 +1,203 @@
+/**
+ * Cohort SessionStart-hook fan-out (#1240).
+ *
+ * Public API:
+ *
+ *   - `installAgentHookFor(vendorKey)` → install or refresh the hook
+ *     for one vendor.
+ *   - `uninstallAgentHookFor(vendorKey, options)` → strip the hook
+ *     from one vendor.
+ *   - `installAgentHooksForVendors({ vendors, io? })` → fan-out
+ *     wrapper that runs `installAgentHookFor` for each vendor and
+ *     aggregates results, mirroring `mcp-merge.mjs` for the cohort
+ *     session-hook flow.
+ *
+ * The dispatcher's job is to translate a registry vendorKey into the
+ * correct per-shape merger call. The merger choice is data-driven via
+ * `agent-registry.mjs`'s `agentHook.shape` field — adding a new shape
+ * is a registry edit + a new merger module + a new switch arm here.
+ *
+ * ## Why fan-out instead of a single `installAll()`
+ *
+ * The init flow only installs hooks for vendors the picker selected,
+ * not every vendor in the registry. A bare `installAll()` would
+ * install Cursor's hook for a user who picked only Gemini. The
+ * fan-out wrapper accepts the explicit vendor list so the call site
+ * (init step 6) decides scope.
+ *
+ * Per-vendor failures are NOT fatal to the fan-out: one broken hook
+ * config doesn't abort init. The result array reports each vendor's
+ * outcome so the caller can summarize and surface failures
+ * individually. Mirrors `mergeMcpForVendors`'s same-error contract.
+ */
+
+import { getAgentByKey } from "./agent-registry.mjs";
+import {
+  mergeClaudeShapeAgentHook,
+  unmergeClaudeShapeAgentHook,
+} from "./mergers/agent-hook-claude-shape.mjs";
+import {
+  mergeCursorShapeAgentHook,
+  unmergeCursorShapeAgentHook,
+} from "./mergers/agent-hook-cursor-shape.mjs";
+import { validationError } from "./errors.mjs";
+
+/**
+ * @typedef {Object} AgentHookInstallResult
+ * @property {string} vendorKey
+ * @property {string} displayName
+ * @property {string} path - User-facing path (e.g. `~/.cursor/hooks.json`).
+ * @property {"installed" | "updated" | "unchanged" | "failed"} action
+ * @property {string} [reason] - Present when action is "failed".
+ */
+
+/**
+ * @typedef {Object} AgentHookUninstallResult
+ * @property {string} vendorKey
+ * @property {string} displayName
+ * @property {string} path
+ * @property {"removed" | "would-remove" | "skipped" | "unchanged" | "failed"} action
+ * @property {string} [error] - Present when action is "skipped" due to
+ *           a parse error, or when action is "failed".
+ */
+
+/**
+ * Install the cohort SessionStart hook for one vendor. Throws
+ * `validationError` for unknown vendors or vendors whose `agentHook`
+ * is null (Claude Code, Windsurf, Cline). The dispatcher does NOT
+ * silently no-op on null: a caller asking to install a hook for a
+ * vendor with no spec is a programming error, and a silent no-op
+ * would mask it.
+ *
+ * @param {string} vendorKey
+ * @returns {{ path: string; action: "installed" | "updated" | "unchanged"; command: string }}
+ */
+export function installAgentHookFor(vendorKey) {
+  const entry = requireRegistryEntryWithHook(vendorKey, "install");
+  switch (entry.agentHook.shape) {
+    case "claude-shape":
+      return mergeClaudeShapeAgentHook({ vendorKey });
+    case "cursor-shape":
+      return mergeCursorShapeAgentHook({ vendorKey });
+    default:
+      // The agent-registry typedef caps `shape` to the known set;
+      // hitting this branch means a registry author added a new shape
+      // value without wiring a merger. Surface the gap loudly.
+      throw validationError(
+        `Unknown agentHook.shape "${entry.agentHook.shape}" for vendor "${vendorKey}". Wire a merger in agent-hook-merge.mjs.`,
+      );
+  }
+}
+
+/**
+ * Uninstall the cohort SessionStart hook for one vendor. See
+ * `installAgentHookFor` for the validation contract.
+ *
+ * @param {string} vendorKey
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped" | "unchanged"; error?: string }}
+ */
+export function uninstallAgentHookFor(vendorKey, { dryRun = false } = {}) {
+  const entry = requireRegistryEntryWithHook(vendorKey, "uninstall");
+  switch (entry.agentHook.shape) {
+    case "claude-shape":
+      return unmergeClaudeShapeAgentHook({ vendorKey, dryRun });
+    case "cursor-shape":
+      return unmergeCursorShapeAgentHook({ vendorKey, dryRun });
+    default:
+      throw validationError(
+        `Unknown agentHook.shape "${entry.agentHook.shape}" for vendor "${vendorKey}". Wire a remover in agent-hook-merge.mjs.`,
+      );
+  }
+}
+
+/**
+ * Fan-out installer for an explicit list of vendor keys. Used by init
+ * step 6's cohort sibling. Vendors without an `agentHook` spec
+ * (Claude Code, Windsurf, Cline) are silently skipped — they're a
+ * deliberate registry classification, not a caller error. Truly
+ * unknown vendor keys are NOT silently skipped: they surface as
+ * `action: "failed"` so a typo in `--agent` doesn't hide.
+ *
+ * @param {object} options
+ * @param {string[]} options.vendors - Canonical vendor keys.
+ * @returns {AgentHookInstallResult[]}
+ */
+export function installAgentHooksForVendors({ vendors }) {
+  if (!Array.isArray(vendors)) {
+    throw validationError(
+      "installAgentHooksForVendors: vendors must be an array of canonical agent keys.",
+    );
+  }
+
+  // Dedupe to avoid running the merger twice on a caller that built a
+  // vendor list with a duplicate (e.g. a future `--agent agents,gemini`
+  // expansion). Set preserves first-seen order.
+  const uniqueVendors = Array.from(new Set(vendors));
+  const results = [];
+
+  for (const vendorKey of uniqueVendors) {
+    const entry = getAgentByKey(vendorKey);
+    if (!entry) {
+      // Unknown key. Don't silently skip — that hides typos. Surface
+      // as a failure with a clear reason.
+      results.push({
+        vendorKey,
+        displayName: vendorKey,
+        path: "(unknown)",
+        action: "failed",
+        reason: `Unknown agent key: ${vendorKey}`,
+      });
+      continue;
+    }
+    if (!entry.agentHook) {
+      // Deliberate skip: Claude Code uses the legacy session-hook;
+      // Windsurf and Cline are deferred per the agent-registry
+      // docstring. Skipping silently is correct.
+      continue;
+    }
+
+    try {
+      const r = installAgentHookFor(vendorKey);
+      results.push({
+        vendorKey,
+        displayName: entry.displayName,
+        path: r.path,
+        action: r.action,
+      });
+    } catch (err) {
+      results.push({
+        vendorKey,
+        displayName: entry.displayName,
+        path: entry.agentHook.displayPath,
+        action: "failed",
+        reason: err?.message ?? String(err),
+      });
+    }
+  }
+
+  return results;
+}
+
+// ── Internals ─────────────────────────────────────────────────────
+
+function requireRegistryEntryWithHook(vendorKey, verb) {
+  const entry = getAgentByKey(vendorKey);
+  if (!entry) {
+    throw validationError(
+      `Cannot ${verb} cohort hook for unknown agent: ${vendorKey}.`,
+    );
+  }
+  if (!entry.agentHook) {
+    throw validationError(
+      `Cannot ${verb} cohort hook for "${vendorKey}" — no agentHook spec.`,
+      {
+        hint:
+          "Claude Code uses the legacy session-hook (mergers/session-hook.mjs); " +
+          "Windsurf and Cline are deferred (#1239 epic).",
+      },
+    );
+  }
+  return entry;
+}