@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/lib/clients/claude-code.mjs

@@ -1,3 +1,7 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import { askYesNo } from "../prompt.mjs";
 import {
   getClaudeCodeSettingsPath,
@@ -8,17 +12,36 @@ import {
   removeKeys,
   writeJsonFile,
 } from "../config.mjs";
-import { detectClaude, detectExistingMeko } from "../detect.mjs";
-import { redactKey, run } from "./common.mjs";
+import { detectClaude, detectExistingMeko, getClaudeCodeConfigPath } from "../detect.mjs";
+import {
+  redactKey,
+  resolveHooksRoot,
+  run,
+  shellQuote,
+  writeInstallerMarker,
+} from "./common.mjs";
 
 const CLAUDE_INSTALL_URL =
   "https://docs.anthropic.com/en/docs/claude-code/getting-started";
 
-// Hook scripts produced by earlier installer versions that may have had inline
-// MEKO_MCP_URL=... / MEKO_API_KEY=... env assignments baked into the command
-// string. Used by stripLiteralUrlFromHooks to recognize and clean them up.
+// Filenames of the Meko-owned hook scripts. The meko-agent-skills plugin
+// registers these at runtime via ${CLAUDE_PLUGIN_ROOT} (skills/hooks/hooks.json),
+// so any entry still present in ~/.claude/settings.json that references one of
+// these filenames is stale — either a pre-plugin absolute-path install that
+// accumulated across install locations (issue #60), or a legacy env-prefixed
+// command rewritten from MEKO-20. pruneMekoHookEntries uses this list to
+// identify and remove those stale entries.
 const MEKO_HOOK_SCRIPTS = ["session-start.sh", "pre-compact.sh", "session-end.sh"];
 
+// Qualified `plugin@marketplace` form. CLI 2.1.x's `plugin update` and
+// `plugin uninstall` require this exact shape — the bare name fails with
+// `Plugin "meko-agent-skills" not found` even when the plugin is installed
+// (issues #59 / #63). `plugin install` fuzzy-resolves the bare name but we
+// keep the shape consistent so every call site agrees. The marketplace happens
+// to share the plugin's name (see extraKnownMarketplaces in settings.json).
+const MEKO_PLUGIN_REF = "meko-agent-skills@meko-agent-skills";
+const MEKO_MARKETPLACE_NAME = "meko-agent-skills";
+
 // Meko MCP tools to union into `permissions.allow` so Claude Code resolves
 // them without the deferred-tools ToolSearch round-trip (issue #5). The set
 // is intentionally tight — only tools the agent calls proactively per
@@ -41,11 +64,24 @@ const MEKO_ALWAYS_AVAILABLE_TOOLS = [
 ];
 
 /**
- * @param {{ getSettingsPath?: () => string }} [options]
+ * @param {{
+ *   getSettingsPath?: () => string,
+ *   getConfigPath?: () => string,
+ *   getMekoCaptureDir?: () => string,
+ *   runCommand?: (cmd: string) => string,
+ * }} [options]
  * @returns {object}
  */
 export function createClaudeCodeAdapter(options = {}) {
   const resolveSettingsPath = options.getSettingsPath ?? getClaudeCodeSettingsPath;
+  const resolveConfigPath = options.getConfigPath ?? getClaudeCodeConfigPath;
+  const resolveMekoCaptureDir =
+    options.getMekoCaptureDir ??
+    (() => join(homedir(), ".claude", "meko-capture"));
+  // DI hook: tests substitute a fake shell so installSkills() branching
+  // (probe -> update vs install, fallback on old CLIs) is verifiable
+  // without invoking a real `claude` binary.
+  const runCommand = options.runCommand ?? run;
 
   return {
     id: "claude-code",
@@ -68,11 +104,11 @@ export function createClaudeCodeAdapter(options = {}) {
     isInstalled() {
       return detectClaude().found;
     },
-    detectExisting(name) {
-      return detectExistingMeko(name);
+    detectExisting(name, { scope = "user", projectRoot } = {}) {
+      return detectExistingMeko(name, { scope, projectRoot });
     },
-    removeRegistration(name) {
-      run(`claude mcp remove ${name}`);
+    removeRegistration(name, { scope = "user" } = {}) {
+      runCommand(`claude mcp remove --scope ${shellQuote(scope)} ${shellQuote(name)}`);
     },
     registerServer({ name, url, scope, apiKey, dryRun, verbose, log }) {
       const cmd = this.buildRegisterCommand({ name, url, scope, apiKey });
@@ -87,18 +123,21 @@ export function createClaudeCodeAdapter(options = {}) {
       }
     },
     buildRegisterCommand({ name, url, scope, apiKey }) {
-      let cmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
+      let cmd =
+        `claude mcp add --transport http --scope ${shellQuote(scope)} ` +
+        `${shellQuote(name)} ${shellQuote(url)}`;
       if (apiKey) {
-        cmd += ` -H "Authorization: Bearer ${apiKey}"`;
+        cmd += ` --header ${shellQuote(`Authorization: Bearer ${apiKey}`)}`;
       }
       return cmd;
     },
     buildRegisterDisplayCommand({ name, url, scope, apiKey }) {
-      let displayCmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
-      if (apiKey) {
-        displayCmd += ` -H "Authorization: Bearer ${redactKey(apiKey)}"`;
-      }
-      return displayCmd;
+      return this.buildRegisterCommand({
+        name,
+        url,
+        scope,
+        apiKey: apiKey ? redactKey(apiKey) : null,
+      });
     },
     runRegisterCommand(cmd) {
       return run(cmd);
@@ -129,7 +168,34 @@ export function createClaudeCodeAdapter(options = {}) {
 
       mergeSettings(settingsPath, envPatch);
       mergeAllowList(settingsPath, "permissions.allow", MEKO_ALWAYS_AVAILABLE_TOOLS);
-      const migrated = stripLiteralUrlFromHooks(settingsPath);
+      const pruned = pruneMekoHookEntries(settingsPath);
+      if (pruned) {
+        // The prune removed at least one stale Meko hook entry. On the common
+        // path these were frozen capture.js copies from prior install roots
+        // (issue #60). On the edge case where Cursor claude-compat installed
+        // from a DIFFERENT root than this Claude Code install, those Cursor
+        // entries are indistinguishable from stale Claude Code entries and
+        // were also removed — warn the user so they can re-run the Cursor
+        // installer if they notice Cursor hooks missing.
+        log.warn(
+          "Removed stale Meko hook entries from settings.json. If you use Cursor claude-compat from a different install path, re-run the Cursor installer to restore its hooks.",
+        );
+      }
+
+      // Drop an installer-version marker in the meko-capture watermark dir so
+      // future installer runs can tell which version last touched this
+      // machine. This is purely for diagnostics / future upgrade logic —
+      // capture.js itself ignores the marker.
+      const mekoCaptureDir = resolveMekoCaptureDir();
+      try {
+        mkdirSync(mekoCaptureDir, { recursive: true });
+        writeInstallerMarker(mekoCaptureDir);
+      } catch (err) {
+        if (verbose) {
+          log.dim(`  Could not write meko-capture marker: ${err.message}`);
+        }
+      }
+
       if (verbose) {
         log.dim(`  Updated ${settingsPath}`);
         log.dim(`    MEKO_MCP_URL = ${url}`);
@@ -139,9 +205,6 @@ export function createClaudeCodeAdapter(options = {}) {
         log.dim(
           `    permissions.allow += ${MEKO_ALWAYS_AVAILABLE_TOOLS.length} Meko tools`,
         );
-        if (migrated) {
-          log.dim("    Migrated stale hook command literals to env-based form.");
-        }
       }
     },
     installSkills({ scope, dryRun, verbose, log }) {
@@ -152,17 +215,28 @@ export function createClaudeCodeAdapter(options = {}) {
       // succeeds today.
       const marketplaceCmd =
         `claude plugin marketplace add yugabyte/meko-mcp-server --scope ${scope}`;
-      const pluginCmd = `claude plugin install meko-agent-skills --scope ${scope}`;
+      // `claude plugin list` dropped --scope in CLI 2.1.x; it prints all
+      // scopes. The match-by-token regex used below is scope-agnostic by
+      // design — `plugin update` failing with "not found" on a
+      // different-scope install is handled in the fallback chain.
+      const listCmd = `claude plugin list`;
+      // Qualified `plugin@marketplace` form — see MEKO_PLUGIN_REF comment
+      // at the top of this file.
+      const installCmd = `claude plugin install ${MEKO_PLUGIN_REF} --scope ${scope}`;
+      const updateCmd = `claude plugin update ${MEKO_PLUGIN_REF} --scope ${scope}`;
+      const uninstallCmd = `claude plugin uninstall ${MEKO_PLUGIN_REF} --scope ${scope}`;
 
       if (dryRun) {
         log.dim(`  Would run: ${marketplaceCmd}`);
-        log.dim(`  Would run: ${pluginCmd}`);
+        log.dim(`  Would run: ${listCmd}`);
+        log.dim(`  Would run: ${updateCmd} (if already installed)`);
+        log.dim(`  Would run: ${installCmd} (if not yet installed)`);
         return { marketplace: "dry-run", skills: "dry-run" };
       }
 
       let marketplaceStatus = "ok";
       try {
-        const output = run(marketplaceCmd);
+        const output = runCommand(marketplaceCmd);
         if (verbose && output) log.dim(`  ${output}`);
       } catch (err) {
         const msg = err.stderr || err.message || "";
@@ -175,27 +249,130 @@ export function createClaudeCodeAdapter(options = {}) {
         }
       }
 
-      let skillStatus = "ok";
+      // Probe for an existing install so we can call `plugin update` instead
+      // of `plugin install` (the latter no-ops on newer Claude CLIs when the
+      // plugin is already present — which means users running
+      // `npx @yugabytedb/meko-mcp@latest` never pull updated skill content).
+      let alreadyInstalled = false;
       try {
-        const output = run(pluginCmd);
-        if (verbose && output) log.dim(`  ${output}`);
+        const listOutput = runCommand(listCmd);
+        if (verbose && listOutput) log.dim(`  ${listOutput}`);
+        // Match only when "meko-agent-skills" appears as a standalone token.
+        // Leading anchor (^|\s) prevents false positives on substrings like
+        // `not-meko-agent-skills`. Trailing anchor accepts whitespace, EOL,
+        // or `@` — CLI 2.1.x formats plugins as `name@marketplace`, so the
+        // plugin appears as `meko-agent-skills@meko-agent-skills` in the
+        // probe output. `\b` is too loose because `-` counts as a word
+        // boundary, so `\bmeko-agent-skills\b` would match inside
+        // `not-meko-agent-skills`.
+        //
+        // This is deliberately scope-agnostic — `plugin list` prints all
+        // scopes. If the plugin exists at a scope other than the one we're
+        // installing into, `plugin update --scope ${scope}` will fail with
+        // "Plugin not found" and the `not found` branch in the update
+        // catch-block below falls through to `plugin install`.
+        alreadyInstalled = /(^|\s)meko-agent-skills(\s|@|$)/m.test(listOutput);
       } catch (err) {
+        // If the probe fails we fall through to `plugin install`, which is
+        // the original behavior — safer than assuming a state we can't see.
         const msg = err.stderr || err.message || "";
-        if (msg.includes("already") || msg.includes("installed")) {
-          skillStatus = "already";
-        } else {
-          skillStatus = "error";
-          log.warn("Skills plugin install skipped (non-critical).");
-          log.dim(msg.trim());
+        if (verbose) log.dim(`  plugin list probe failed: ${msg.trim()}`);
+      }
+
+      let skillStatus = "ok";
+      if (alreadyInstalled) {
+        try {
+          const output = runCommand(updateCmd);
+          if (verbose && output) log.dim(`  ${output}`);
+          log.dim("  Updated meko-agent-skills plugin");
+        } catch (err) {
+          const msg = err.stderr || err.message || "";
+          // Older Claude CLIs don't know `plugin update`. The exact wording
+          // varies (`unknown command`, `unrecognized option`, `invalid`,
+          // `command not found`) so we match a family of signals and fall
+          // back to uninstall + install, which achieves the same refresh.
+          if (
+            msg.includes("unknown command") ||
+            msg.includes("unrecognized") ||
+            msg.includes("invalid command") ||
+            msg.includes("command not found") ||
+            msg.includes("Unknown subcommand")
+          ) {
+            log.warn("  claude plugin update not supported — falling back to uninstall + install");
+            try {
+              const unOutput = runCommand(uninstallCmd);
+              if (verbose && unOutput) log.dim(`  ${unOutput}`);
+            } catch (unErr) {
+              if (verbose) {
+                const unMsg = unErr.stderr || unErr.message || "";
+                log.dim(`  plugin uninstall (fallback) failed: ${unMsg.trim()}`);
+              }
+            }
+            try {
+              const inOutput = runCommand(installCmd);
+              if (verbose && inOutput) log.dim(`  ${inOutput}`);
+              log.dim("  Installed meko-agent-skills plugin");
+            } catch (inErr) {
+              const inMsg = inErr.stderr || inErr.message || "";
+              skillStatus = "error";
+              log.warn("Skills plugin install skipped (non-critical).");
+              log.dim(inMsg.trim());
+            }
+          } else if (msg.includes("not found")) {
+            // `plugin list` matched the plugin at some scope, but
+            // `plugin update --scope ${scope}` can't see it — the install
+            // lives at a different scope. Fall through to `plugin install`
+            // at the requested scope, which is what the user actually
+            // asked for. (Also covers rare probe false-positives where
+            // the regex matched but the plugin isn't really installed
+            // anywhere visible to update.)
+            log.dim(`  plugin update reports not found at scope ${scope} — installing instead`);
+            try {
+              const inOutput = runCommand(installCmd);
+              if (verbose && inOutput) log.dim(`  ${inOutput}`);
+              log.dim("  Installed meko-agent-skills plugin");
+            } catch (inErr) {
+              const inMsg = inErr.stderr || inErr.message || "";
+              if (inMsg.includes("already") || inMsg.includes("installed")) {
+                skillStatus = "already";
+              } else {
+                skillStatus = "error";
+                log.warn("Skills plugin install skipped (non-critical).");
+                log.dim(inMsg.trim());
+              }
+            }
+          } else {
+            skillStatus = "error";
+            log.warn("Skills plugin update skipped (non-critical).");
+            log.dim(msg.trim());
+          }
+        }
+      } else {
+        try {
+          const output = runCommand(installCmd);
+          if (verbose && output) log.dim(`  ${output}`);
+          log.dim("  Installed meko-agent-skills plugin");
+        } catch (err) {
+          const msg = err.stderr || err.message || "";
+          if (msg.includes("already") || msg.includes("installed")) {
+            skillStatus = "already";
+          } else {
+            skillStatus = "error";
+            log.warn("Skills plugin install skipped (non-critical).");
+            log.dim(msg.trim());
+          }
         }
       }
 
       return { marketplace: marketplaceStatus, skills: skillStatus };
     },
-    uninstall({ name, settingsPath }) {
+    uninstall({ name, scope = "user", settingsPath }) {
       const results = [];
       try {
-        run(`claude mcp remove ${name}`);
+        // Route through runCommand (DI) so unit tests that stub the shell
+        // don't accidentally invoke the real `claude mcp remove` against
+        // the developer's or CI runner's own config.
+        runCommand(`claude mcp remove ${name}`);
         results.push({ key: "mcp", ok: true, message: `MCP server "${name}" removed.` });
       } catch {
         results.push({ key: "mcp", ok: false, message: `MCP server "${name}" was not registered (nothing to remove).` });
@@ -210,67 +387,200 @@ export function createClaudeCodeAdapter(options = {}) {
       }
 
       try {
-        run("claude plugin uninstall meko-agent-skills");
+        pruneMekoHookEntries(settingsPath);
+        results.push({ key: "hooks", ok: true, message: "Stale Meko hook entries pruned from settings." });
+      } catch (err) {
+        results.push({ key: "hooks", ok: false, message: `Could not prune Meko hook entries: ${err.message}` });
+      }
+
+      try {
+        // Qualified plugin@marketplace form — CLI 2.1.x rejects the bare
+        // name (issue #63). Before: `catch` swallowed every failure as
+        // "not installed", so a CLI shape mismatch reported success while
+        // the plugin stayed registered. Distinguish real "not installed"
+        // from other errors by inspecting stderr (case-insensitive, since
+        // wording varies across CLI versions).
+        //
+        // Scope must match the installSkills() call site — a project-scope
+        // install is invisible to a user-scope uninstall on CLI 2.1.x, so
+        // without --scope the plugin stays registered after `--uninstall`.
+        runCommand(`claude plugin uninstall ${MEKO_PLUGIN_REF} --scope ${scope}`);
         results.push({ key: "skills", ok: true, message: "Skills plugin removed." });
-      } catch {
-        results.push({ key: "skills", ok: false, message: "Skills plugin was not installed (nothing to remove)." });
+      } catch (err) {
+        const msg = err.stderr || err.message || "";
+        const lower = msg.toLowerCase();
+        if (lower.includes("not found") || lower.includes("not installed")) {
+          results.push({ key: "skills", ok: false, message: "Skills plugin was not installed (nothing to remove)." });
+        } else {
+          results.push({ key: "skills", ok: false, message: `Skills plugin uninstall failed: ${msg.trim()}` });
+        }
       }
 
       try {
-        run("claude plugin marketplace remove meko-agent-skills");
+        runCommand(`claude plugin marketplace remove ${MEKO_MARKETPLACE_NAME}`);
         results.push({ key: "marketplace", ok: true, message: "Plugin marketplace entry removed." });
-      } catch {
-        results.push({ key: "marketplace", ok: false, message: "Plugin marketplace entry was not registered (nothing to remove)." });
+      } catch (err) {
+        // Mirror the skills-uninstall treatment: a legitimate "never
+        // registered" state is different from a CLI shape mismatch or a
+        // missing binary. Without this, a broken CLI contract looks
+        // identical to success.
+        const msg = err.stderr || err.message || "";
+        const lower = msg.toLowerCase();
+        if (lower.includes("not found") || lower.includes("not registered") || lower.includes("not installed")) {
+          results.push({ key: "marketplace", ok: false, message: "Plugin marketplace entry was not registered (nothing to remove)." });
+        } else {
+          results.push({ key: "marketplace", ok: false, message: `Plugin marketplace remove failed: ${msg.trim()}` });
+        }
       }
 
       return results;
     },
-    async validateConfig({ serverName }) {
+    async validateConfig({ serverName, scope = "user", projectRoot, url, apiKey }) {
+      const configPath = resolveConfigPath();
+      let cfg;
       try {
-        const output = run("claude mcp list");
-        const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
-        const found = lines.some((line) => line.split(":")[0].trim() === serverName);
-        if (found) return { ok: true, message: `Server "${serverName}" is registered.` };
+        cfg = readJsonFile(configPath);
+      } catch (err) {
+        return { ok: false, message: `Could not read ${configPath}: ${err.message}` };
+      }
+      const entry =
+        scope === "project"
+          ? cfg?.projects?.[projectRoot]?.mcpServers?.[serverName]
+          : cfg?.mcpServers?.[serverName];
+
+      if (!entry) {
+        return { ok: false, message: `Server "${serverName}" not found in ${configPath}.` };
+      }
+
+      if (url && entry.url !== url) {
         return {
           ok: false,
-          message: `Server "${serverName}" not found in \`claude mcp list\` output. Run the installer again or add it manually.`,
+          message: `Server "${serverName}" in ${configPath} still points at ${entry.url ?? "<missing url>"}.`,
         };
-      } catch (err) {
-        return { ok: false, message: `Failed to run \`claude mcp list\`: ${err.message}` };
       }
+
+      const authHeader = getHeader(entry.headers, "Authorization");
+      if (apiKey) {
+        const expected = `Bearer ${apiKey}`;
+        if (authHeader !== expected) {
+          return {
+            ok: false,
+            message: `Server "${serverName}" in ${configPath} does not contain the current Authorization header.`,
+          };
+        }
+      } else if (authHeader) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${configPath} still contains an Authorization header.`,
+        };
+      }
+
+      return { ok: true, message: `Server "${serverName}" is registered in ${configPath}.` };
     },
   };
 }
 
-// Rewrites `MEKO_MCP_URL='...' [MEKO_API_KEY='...'] bash "<script>"` hook command
-// strings to `bash "<script>"`, for the three meko hook scripts. Earlier installer
-// versions (cursor.mjs buildScriptCommand) literalized URL+key into the command,
-// which silently shadowed the env block at runtime — see MEKO-20. Runs on every
-// Claude Code install as a one-time migration. Returns true if anything changed.
-export function stripLiteralUrlFromHooks(settingsPath) {
+/**
+ * Remove stale Meko hook entries from a Claude Code settings.json —
+ * keeping any entry that points at the CURRENT install's hooks root.
+ *
+ * The meko-agent-skills plugin registers hooks at runtime via
+ * ${CLAUDE_PLUGIN_ROOT} (skills/hooks/hooks.json), so a Meko entry in
+ * settings.json.hooks.* pointing at SOME OTHER install path is a
+ * pre-plugin absolute-path entry left over from a prior install location
+ * (issue #60) or a legacy env-prefixed command (MEKO-20). Those fire
+ * frozen copies of capture.js on every session event and throw against
+ * the current contract.
+ *
+ * Cursor's claude-compat mode (cursor.mjs installClaudeCompatHooks)
+ * shares this file on scope=user and writes entries in exactly the same
+ * shape as stale Claude Code entries — both are absolute-path
+ * `bash "<hooks-handlers-root>/<script>"` commands. There's no
+ * schema-safe signal in the command string that distinguishes the two,
+ * so prune uses the current install root as a best-effort exemption:
+ *
+ * GUARANTEE (narrow): a Cursor claude-compat entry SURVIVES when its
+ * command references the SAME resolveHooksRoot() this Claude Code
+ * install resolved to. Cursor installed from the same path (e.g. both
+ * via homebrew, or both from the same repo clone) will keep its hooks.
+ *
+ * KNOWN TRADE-OFF (issue #60 comment thread): a Cursor claude-compat
+ * entry written from a DIFFERENT install root (e.g. Cursor installed
+ * from the repo clone, Claude Code installed from npx cache) WILL be
+ * pruned — it's indistinguishable from the stale-Claude-Code entries
+ * that issue #60 is about. Callers should warn the user, and users
+ * recover by re-running the Cursor installer.
+ *
+ * Match rule for pruning: command is a string that contains BOTH
+ * `hooks-handlers/` AND one of MEKO_HOOK_SCRIPTS, AND the command does
+ * NOT contain the current install's hooks root path. The `hooks-handlers/`
+ * fence keeps unrelated user scripts that happen to share a filename
+ * (e.g. their own `session-start.sh`) from being pruned.
+ *
+ * Prunes empty group.hooks arrays, empty groups, empty event arrays, and
+ * deletes cfg.hooks entirely when it ends up empty — so an untouched file
+ * stays byte-identical. Only writes when something actually changed.
+ *
+ * @param {string} settingsPath
+ * @returns {boolean} true iff the file was rewritten
+ */
+export function pruneMekoHookEntries(settingsPath) {
   const cfg = readJsonFile(settingsPath);
   if (!cfg?.hooks || typeof cfg.hooks !== "object") return false;
 
+  const currentHooksRoot = resolveHooksRoot();
+
+  const isStaleMekoHookCommand = (cmd) =>
+    typeof cmd === "string"
+    && cmd.includes("hooks-handlers/")
+    && MEKO_HOOK_SCRIPTS.some((s) => cmd.includes(s))
+    && !cmd.includes(currentHooksRoot);
+
+  // Only cascade empty-array cleanup on events where we actually removed a
+  // Meko entry — otherwise a user's pre-existing empty hook array unrelated
+  // to Meko (e.g. { hooks: { Notification: [] } }) would get silently
+  // collapsed and trigger a file rewrite, breaking the "untouched file
+  // stays byte-identical" guarantee.
   let changed = false;
-  for (const eventArr of Object.values(cfg.hooks)) {
+  for (const event of Object.keys(cfg.hooks)) {
+    const eventArr = cfg.hooks[event];
     if (!Array.isArray(eventArr)) continue;
+
+    let eventChanged = false;
     for (const group of eventArr) {
       if (!Array.isArray(group?.hooks)) continue;
-      for (const h of group.hooks) {
-        if (typeof h?.command !== "string") continue;
-        if (!MEKO_HOOK_SCRIPTS.some((s) => h.command.includes(s))) continue;
-        const rewritten = h.command.replace(
-          /^\s*(?:MEKO_\w+=(?:'[^']*'|"[^"]*"|\S+)\s+)+/,
-          "",
-        );
-        if (rewritten !== h.command) {
-          h.command = rewritten;
-          changed = true;
-        }
-      }
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((h) => !isStaleMekoHookCommand(h?.command));
+      if (group.hooks.length !== before) eventChanged = true;
+    }
+    if (!eventChanged) continue;
+
+    const prunedEventArr = eventArr.filter(
+      (group) => Array.isArray(group?.hooks) && group.hooks.length > 0,
+    );
+    if (prunedEventArr.length !== eventArr.length) {
+      cfg.hooks[event] = prunedEventArr;
+    }
+
+    if (cfg.hooks[event].length === 0) {
+      delete cfg.hooks[event];
     }
+    changed = true;
+  }
+
+  if (changed && Object.keys(cfg.hooks).length === 0) {
+    delete cfg.hooks;
   }
 
   if (changed) writeJsonFile(settingsPath, cfg);
   return changed;
 }
+
+function getHeader(headers, name) {
+  if (!headers || typeof headers !== "object") return undefined;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === wanted) return value;
+  }
+  return undefined;
+}

package/lib/clients/claude-desktop.mjs

@@ -8,7 +8,14 @@ import {
   readJsonFile,
   removeKeys,
 } from "../config.mjs";
-import { getRepoRoot, run } from "./common.mjs";
+import {
+  getAssetRoot,
+  getInstallerVersion,
+  markerIsStale,
+  readInstallerMarker,
+  run,
+  writeInstallerMarker,
+} from "./common.mjs";
 
 /**
  * Claude Desktop adapter.
@@ -32,13 +39,16 @@ import { getRepoRoot, run } from "./common.mjs";
  * mcp-remote) with no space around the colon after the header name —
  * some clients mis-parse space-containing `--header` args.
  *
- * installSkills() runs skills/scripts/package-desktop-skill.sh to build the
- * .skill bundle and prints import instructions. Desktop has no programmatic
- * skill install API — the user drags the .skill into the app.
+ * installSkills() runs scripts/package-desktop-skill.sh under the resolved
+ * asset root to build the .skill bundle and prints import instructions.
+ * Desktop has no programmatic skill install API — the user drags the .skill
+ * into the app. The asset root is `installer/assets/` for packaged installs
+ * (npx) and `<repo>/skills/` for source checkouts; both layouts share the
+ * same shape so the script can be invoked the same way.
  */
 export function createClaudeDesktopAdapter(options = {}) {
   const configPathResolver = options.getConfigPath ?? getClaudeDesktopConfigPath;
-  const repoRootResolver = options.getRepoRoot ?? getRepoRoot;
+  const assetRootResolver = options.getAssetRoot ?? getAssetRoot;
   const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
   const npxProber = options.probeNpx ?? defaultProbeNpx;
 
@@ -119,13 +129,20 @@ export function createClaudeDesktopAdapter(options = {}) {
       }
     },
     installSkills({ dryRun, log }) {
-      const repoRoot = repoRootResolver();
-      const script = join(repoRoot, "skills", "scripts", "package-desktop-skill.sh");
-      const output = join(repoRoot, "skills", "meko-mcp-tools-desktop.skill");
+      const assetRoot = assetRootResolver();
+      const script = join(assetRoot, "scripts", "package-desktop-skill.sh");
+      const output = join(assetRoot, "meko-mcp-tools-desktop.skill");
+      // The .skill output is a ZIP file, so we can't drop a marker inside it.
+      // Stamp the marker in the parent dir instead — it signals which
+      // installer version produced the bundle sitting alongside it, so a
+      // re-run can tell whether the existing .skill is stale.
+      const markerDir = dirname(output);
+      const currentVersion = getInstallerVersion();
 
       if (dryRun) {
         log.dim(`  Would run: bash ${script}`);
         log.dim(`  Would produce: ${output}`);
+        log.dim(`  Would write .meko-installer marker (version=${currentVersion}) in ${markerDir}`);
         return { marketplace: "skipped", skills: "dry-run", output };
       }
 
@@ -137,6 +154,17 @@ export function createClaudeDesktopAdapter(options = {}) {
         return { marketplace: "skipped", skills: "script-missing" };
       }
 
+      // If a previous build's marker is stale, warn visibly — the user has to
+      // re-drag the .skill into Claude Desktop's Extensions panel; we can't do
+      // that step for them. Keep rebuilding either way.
+      const existingMarker = readInstallerMarker(markerDir);
+      if (existsSync(output) && existingMarker && markerIsStale(markerDir, currentVersion)) {
+        log.warn(
+          `Claude Desktop .skill bundle was produced by installer ${existingMarker.version}. ` +
+            `Rebuilding — you will need to re-drag it into Claude Desktop > Settings > Extensions.`,
+        );
+      }
+
       try {
         packageRunner(script);
       } catch (err) {
@@ -149,6 +177,15 @@ export function createClaudeDesktopAdapter(options = {}) {
         return { marketplace: "skipped", skills: "error" };
       }
 
+      // Stamp the marker after a successful build so the next run knows what
+      // version the sibling .skill was produced by.
+      try {
+        writeInstallerMarker(markerDir);
+      } catch (err) {
+        // Marker is best-effort — a failure here doesn't invalidate the build.
+        log.warn(`Could not write .skill installer marker: ${err.message}`);
+      }
+
       log.info(`Built Meko skill bundle: ${output}`);
       log.info(
         "Install it in Claude Desktop: Settings > Extensions > Import skill, " +