superacli 1.1.5 → 1.1.7

package/cli/config.js

@@ -1,7 +1,14 @@
 const fs = require("fs")
 const path = require("path")
 const os = require("os")
-const { getInstalledPluginCommands, listInstalledPlugins } = require("./plugins-store")
+const {
+  getEffectivePluginCommands,
+  listInstalledPlugins,
+  readServerPluginsLock,
+  writeServerPluginsLock,
+  SUPERCLI_PLUGINS_DIR,
+} = require("./plugins-store")
+const { spawnSync } = require("child_process")
 
 const CACHE_DIR = path.join(os.homedir(), ".supercli")
 const CACHE_FILE = path.join(CACHE_DIR, "config.json")
@@ -106,7 +113,7 @@ function emptyConfig() {
 async function loadConfig() {
   const cache = readCache()
   const base = cache || emptyConfig()
-  const pluginCommands = getInstalledPluginCommands()
+  const pluginCommands = getEffectivePluginCommands()
   const merged = {
     ...base,
     commands: [...(base.commands || []), ...pluginCommands]
@@ -114,6 +121,215 @@ async function loadConfig() {
   return merged
 }
 
+function safePluginName(name) {
+  return String(name || "").replace(/[^a-zA-Z0-9._-]/g, "-")
+}
+
+function safePluginVersion(version) {
+  const value = String(version || "0.0.0").replace(/[^a-zA-Z0-9._-]/g, "-")
+  return value || "0.0.0"
+}
+
+function resolveHooksPolicy(plugin, settings) {
+  const pluginPolicy = String(plugin.hooks_policy || "inherit")
+  if (pluginPolicy === "allow" || pluginPolicy === "deny") return pluginPolicy
+  return String(settings.default_hooks_policy || "deny")
+}
+
+function runServerPluginPostInstall(pluginDir, plugin, hookPolicy) {
+  const manifest = plugin.manifest || {}
+  if (!manifest.post_install || hookPolicy !== "allow") {
+    return { policy: hookPolicy, executed: false, reason: hookPolicy !== "allow" ? "policy_denied" : "hook_missing" }
+  }
+  if (manifest.post_install.runtime && manifest.post_install.runtime !== "node") {
+    return { policy: hookPolicy, executed: false, reason: "unsupported_runtime" }
+  }
+  const scriptRel = String(manifest.post_install.script || "")
+  if (!scriptRel) return { policy: hookPolicy, executed: false, reason: "hook_missing" }
+  const scriptPath = path.resolve(pluginDir, scriptRel)
+  const normalizedBase = path.resolve(pluginDir) + path.sep
+  if (!scriptPath.startsWith(normalizedBase) || !fs.existsSync(scriptPath)) {
+    return { policy: hookPolicy, executed: false, reason: "script_not_found" }
+  }
+  const timeoutMs = Number(manifest.post_install.timeout_ms)
+  const resolvedTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, 15000) : 15000
+  const result = spawnSync("node", [scriptPath], {
+    encoding: "utf-8",
+    timeout: resolvedTimeout,
+    env: {
+      ...process.env,
+      SUPERCLI_PLUGIN_NAME: plugin.name,
+      SUPERCLI_PLUGIN_DIR: pluginDir,
+    },
+  })
+  if (result.error) {
+    return { policy: hookPolicy, executed: true, ok: false, error: result.error.message }
+  }
+  if (result.status !== 0) {
+    return {
+      policy: hookPolicy,
+      executed: true,
+      ok: false,
+      error: (result.stderr || "").trim() || `exit ${result.status}`,
+    }
+  }
+  return { policy: hookPolicy, executed: true, ok: true }
+}
+
+function ensurePluginDir(rootDir, pluginName, pluginVersion) {
+  const dir = path.join(rootDir, safePluginName(pluginName), safePluginVersion(pluginVersion))
+  fs.mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+function extractZipToDir(archivePath, targetDir) {
+  const extract = spawnSync("unzip", ["-o", archivePath, "-d", targetDir], {
+    encoding: "utf-8",
+    timeout: 15000,
+  })
+  if (extract.error) {
+    const msg = extract.error.code === "ENOENT"
+      ? "'unzip' command is required for ZIP server plugins"
+      : extract.error.message
+    throw Object.assign(new Error(msg), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true,
+      suggestions: ["Install unzip and run: supercli sync"],
+    })
+  }
+  if (extract.status !== 0) {
+    throw Object.assign(new Error(`Failed to extract ZIP server plugin: ${(extract.stderr || "").trim() || `exit ${extract.status}`}`), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true,
+    })
+  }
+}
+
+async function syncServerPlugins(server) {
+  const lock = readServerPluginsLock()
+  const installed = lock.installed || {}
+
+  const r = await fetch(`${server}/api/plugins?format=json`)
+  if (r.status === 404) {
+    return {
+      total: 0,
+      enabled: 0,
+      updated: [],
+      unchanged: [],
+      removed: [],
+      shadowed_by_local: [],
+      hook_results: [],
+      skipped: true,
+      reason: "server_plugins_endpoint_missing",
+    }
+  }
+  if (!r.ok) {
+    throw new Error(`Failed to fetch server plugins: ${r.status} ${r.statusText}`)
+  }
+  const payload = await r.json()
+  const settings = payload.settings || { max_zip_mb: 10, default_hooks_policy: "deny" }
+  const allPlugins = Array.isArray(payload.plugins) ? payload.plugins : []
+  const enabledPlugins = allPlugins.filter(p => p && p.enabled !== false)
+
+  const pluginRoot = path.join(SUPERCLI_PLUGINS_DIR, "server")
+  fs.mkdirSync(pluginRoot, { recursive: true })
+
+  const localPlugins = listInstalledPlugins()
+  const localNames = new Set(localPlugins.map(p => p.name))
+  const nextInstalled = {}
+  const diagnostics = {
+    total: allPlugins.length,
+    enabled: enabledPlugins.length,
+    updated: [],
+    unchanged: [],
+    removed: [],
+    shadowed_by_local: [],
+    hook_results: [],
+  }
+
+  const expectedNames = new Set(enabledPlugins.map(p => p.name))
+  for (const [name, oldPlugin] of Object.entries(installed)) {
+    if (expectedNames.has(name)) continue
+    const oldPath = oldPlugin && oldPlugin.plugin_dir
+    if (oldPath && fs.existsSync(oldPath)) fs.rmSync(oldPath, { recursive: true, force: true })
+    diagnostics.removed.push(name)
+  }
+
+  for (const plugin of enabledPlugins) {
+    if (!plugin || !plugin.name) continue
+    if (localNames.has(plugin.name)) {
+      diagnostics.shadowed_by_local.push(plugin.name)
+      continue
+    }
+
+    const previous = installed[plugin.name]
+    const checksumUnchanged = previous && previous.checksum === plugin.checksum
+    if (checksumUnchanged) {
+      nextInstalled[plugin.name] = previous
+      diagnostics.unchanged.push(plugin.name)
+      continue
+    }
+
+    const pluginDir = ensurePluginDir(pluginRoot, plugin.name, plugin.version)
+    const manifest = plugin.manifest || null
+    if (!manifest || typeof manifest !== "object") {
+      throw Object.assign(new Error(`Server plugin '${plugin.name}' is missing manifest`), {
+        code: 105,
+        type: "integration_error",
+        recoverable: true,
+      })
+    }
+
+    fs.writeFileSync(path.join(pluginDir, "plugin.json"), JSON.stringify(manifest, null, 2))
+
+    if (plugin.source_type === "zip") {
+      const zipRes = await fetch(`${server}/api/plugins/${encodeURIComponent(plugin.name)}/archive`)
+      if (!zipRes.ok) {
+        throw Object.assign(new Error(`Failed to download ZIP for server plugin '${plugin.name}'`), {
+          code: 105,
+          type: "integration_error",
+          recoverable: true,
+        })
+      }
+      const bytes = Buffer.from(await zipRes.arrayBuffer())
+      const archivePath = path.join(pluginDir, "plugin.zip")
+      fs.writeFileSync(archivePath, bytes)
+      extractZipToDir(archivePath, pluginDir)
+    }
+
+    const hookPolicy = resolveHooksPolicy(plugin, settings)
+    const hookResult = runServerPluginPostInstall(pluginDir, { name: plugin.name, manifest }, hookPolicy)
+    diagnostics.hook_results.push({ plugin: plugin.name, ...hookResult })
+
+    nextInstalled[plugin.name] = {
+      name: plugin.name,
+      version: plugin.version,
+      description: plugin.description || "",
+      source: "server",
+      source_type: plugin.source_type,
+      checksum: plugin.checksum,
+      has_learn: plugin.has_learn === true,
+      tags: plugin.tags || [],
+      hooks_policy: plugin.hooks_policy || "inherit",
+      plugin_dir: pluginDir,
+      installed_at: new Date().toISOString(),
+      commands: Array.isArray(manifest.commands) ? manifest.commands.map(cmd => ({ ...cmd, plugin_name: plugin.name, plugin_dir: pluginDir })) : [],
+    }
+    diagnostics.updated.push(plugin.name)
+  }
+
+  writeServerPluginsLock({
+    version: 1,
+    fetched_at: new Date().toISOString(),
+    settings,
+    installed: nextInstalled,
+  })
+
+  return diagnostics
+}
+
 async function syncConfig(server) {
   const config = await fetchRemoteConfig(server)
 
@@ -136,7 +352,27 @@ async function syncConfig(server) {
   }
 
   if (!Array.isArray(config.commands)) config.commands = []
-  return writeCache(normalizeConfig(config))
+  let serverPlugins
+  try {
+    serverPlugins = await syncServerPlugins(server)
+  } catch (err) {
+    serverPlugins = {
+      total: 0,
+      enabled: 0,
+      updated: [],
+      unchanged: [],
+      removed: [],
+      shadowed_by_local: [],
+      hook_results: [],
+      skipped: true,
+      reason: err.message,
+    }
+  }
+  const written = writeCache(normalizeConfig(config))
+  return {
+    ...written,
+    server_plugins: serverPlugins,
+  }
 }
 
 async function setMcpServer(name, value) {
@@ -210,6 +446,7 @@ async function showConfig() {
     fetchedAt: new Date(cache.fetchedAt).toISOString(),
     commands: cache.commands ? cache.commands.length : 0,
     plugins: listInstalledPlugins().length,
+    server_plugins: Object.keys((readServerPluginsLock().installed || {})).length,
     mcp_servers: cache.mcp_servers ? cache.mcp_servers.length : 0,
     specs: cache.specs ? cache.specs.length : 0,
     cacheFile: CACHE_FILE

package/cli/discover.js

@@ -0,0 +1,157 @@
+const { listRegistryPlugins } = require("./plugins-registry")
+const { listInstalledPlugins, getPluginInstallGuidance } = require("./plugins-manager")
+
+const STOPWORDS = new Set([
+  "a", "an", "and", "as", "at", "be", "by", "do", "for", "from", "get", "how", "i", "in", "into",
+  "is", "it", "me", "of", "on", "or", "please", "that", "the", "this", "to", "use", "with"
+])
+
+const SYNONYMS = {
+  mail: "email",
+  mailbox: "email",
+  gmail: "email",
+  smtp: "email",
+  browse: "browser",
+  browsing: "browser",
+  browseruse: "browser-use",
+  web: "browser",
+  tweet: "twitter",
+  tweets: "twitter",
+  gcp: "google-cloud",
+  k8s: "kubernetes",
+}
+
+function tokenizeIntent(intent) {
+  const raw = String(intent || "").toLowerCase().replace(/[^a-z0-9\-\s]/g, " ")
+  const baseTokens = raw
+    .split(/\s+/)
+    .map(t => t.trim())
+    .filter(Boolean)
+    .filter(t => !STOPWORDS.has(t))
+
+  const expanded = []
+  for (const token of baseTokens) {
+    expanded.push(token)
+    if (SYNONYMS[token] && SYNONYMS[token] !== token) expanded.push(SYNONYMS[token])
+  }
+  return [...new Set(expanded)]
+}
+
+function countTokenHits(text, tokens) {
+  if (!text || tokens.length === 0) return []
+  const lower = String(text).toLowerCase()
+  return tokens.filter(t => lower.includes(t))
+}
+
+function scorePlugin(plugin, tokens, phrase, installedSet) {
+  const name = String(plugin.name || "")
+  const tags = Array.isArray(plugin.tags) ? plugin.tags.map(t => String(t)) : []
+  const description = String(plugin.description || "")
+
+  const nameHits = countTokenHits(name, tokens)
+  const tagHits = tags.flatMap(tag => countTokenHits(tag, tokens))
+  const descHits = countTokenHits(description, tokens)
+
+  const uniqueTagHits = [...new Set(tagHits)]
+  const uniqueDescHits = [...new Set(descHits)]
+  const baseScore = nameHits.length * 6 + uniqueTagHits.length * 5 + uniqueDescHits.length * 2
+  let score = baseScore
+
+  const phraseNormalized = String(phrase || "").trim().toLowerCase()
+  const phraseHit =
+    phraseNormalized.length > 2 &&
+    (`${name} ${description}`.toLowerCase().includes(phraseNormalized))
+
+  if (phraseHit) score += 4
+  if (installedSet.has(name)) score += 1
+  if (plugin.has_learn === true) score += 1
+
+  return {
+    plugin,
+    base_score: baseScore,
+    score,
+    matched_tokens: [...new Set([...nameHits, ...uniqueTagHits, ...uniqueDescHits])],
+    matched_fields: {
+      name: nameHits,
+      tags: uniqueTagHits,
+      description: uniqueDescHits,
+      phrase: phraseHit,
+    }
+  }
+}
+
+function discoverPluginsByIntent(intent, options = {}) {
+  const phrase = String(intent || "").trim()
+  if (!phrase) {
+    throw Object.assign(new Error("Missing --intent text"), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false,
+      suggestions: ["Run: supercli discover --intent \"send email\" --json"]
+    })
+  }
+
+  const limitRaw = options.limit
+  const limit = limitRaw === undefined || limitRaw === null ? 5 : Number(limitRaw)
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw Object.assign(new Error("Invalid --limit. Use a positive integer"), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false,
+    })
+  }
+
+  const tokens = tokenizeIntent(phrase)
+  const plugins = listRegistryPlugins()
+  const installedSet = new Set(listInstalledPlugins().map(p => p.name))
+
+  const ranked = plugins
+    .map(plugin => scorePlugin(plugin, tokens, phrase, installedSet))
+    .filter(item => item.base_score > 0 || item.matched_fields.phrase)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score
+      return a.plugin.name.localeCompare(b.plugin.name)
+    })
+
+  const top = ranked.slice(0, limit).map(item => {
+    const plugin = item.plugin
+    const guidance = getPluginInstallGuidance(plugin.name)
+    const installed = installedSet.has(plugin.name)
+    const nextSteps = []
+    if (plugin.has_learn === true) nextSteps.push(`supercli plugins learn ${plugin.name} --json`)
+    if (!installed) nextSteps.push(`supercli plugins install ${plugin.name}`)
+    if (guidance && Array.isArray(guidance.install_steps)) {
+      for (const cmd of guidance.install_steps.slice(0, 2)) {
+        if (installed && cmd.startsWith("supercli plugins install ")) continue
+        if (!nextSteps.includes(cmd)) nextSteps.push(cmd)
+      }
+    }
+
+    return {
+      name: plugin.name,
+      description: plugin.description,
+      tags: plugin.tags,
+      installed,
+      has_learn: plugin.has_learn === true,
+      source_type: (plugin.source && plugin.source.type) || "bundled",
+      score: item.score,
+      matched_tokens: item.matched_tokens,
+      matched_fields: item.matched_fields,
+      next_steps: nextSteps,
+    }
+  })
+
+  return {
+    intent: phrase,
+    tokens,
+    no_llm: true,
+    total_candidates: ranked.length,
+    returned: top.length,
+    plugins: top,
+  }
+}
+
+module.exports = {
+  tokenizeIntent,
+  discoverPluginsByIntent,
+}

package/cli/help-json.js

@@ -1,6 +1,7 @@
 function buildCapabilities(config, hasServer) {
   const commands = {
     help: { description: "List namespaces and commands" },
+    discover: { description: "Deterministic intent-to-plugin discovery", usage: "supercli discover --intent \"<task>\" [--limit <n>]" },
     config: { subcommands: ["show"] },
     plugins: { subcommands: ["list", "explore", "learn", "install", "remove", "show", "doctor"], description: "Manage local and remote command plugins" },
     mcp: { subcommands: ["list", "add", "tools", "call", "bind", "doctor", "remove"], description: "Manage local MCP server registry and invoke MCP tools" },
@@ -9,7 +10,7 @@ function buildCapabilities(config, hasServer) {
     plan: { description: "Create execution plan", usage: "supercli plan <ns> <res> <act> [--args]" },
     execute: { description: "Execute a stored plan", usage: "supercli execute <plan_id>" },
     skills: {
-      description: "Skill discovery and SKILL.md generation",
+      description: "Capability docs and SKILL.md catalog workflows",
       subcommands: ["list", "get", "teach", "sync", "search", "providers"]
     }
   }
@@ -20,6 +21,20 @@ function buildCapabilities(config, hasServer) {
     version: "1.0",
     name: "supercli",
     description: "Config-driven, AI-friendly dynamic CLI",
+    what_is_supercli: "A deterministic capability router that exposes namespace.resource.action commands, plugin-installed capabilities, MCP tool bindings, and SKILL.md-based skill docs.",
+    agent_onboarding: {
+      discovery_sequence: [
+        "supercli --json",
+        "supercli --help-json",
+        "supercli discover --intent \"<task>\" --json",
+        "supercli plugins learn <name> --json",
+        "supercli plugins install <name>",
+        "supercli commands --query <keyword> --limit 50 --json",
+        "supercli inspect <namespace> <resource> <action> --json"
+      ],
+      fallback_rule: "If a command is not found, use discover/plugins explore/plugins learn before retrying.",
+      no_llm_discovery: true
+    },
     commands,
     namespaces: [...new Set((config.commands || []).map(c => c.namespace))],
     total_commands: (config.commands || []).length,

package/cli/plugin-install-guidance.js

@@ -1,3 +1,8 @@
+const fs = require("fs")
+const path = require("path")
+const { readPluginsLock } = require("./plugins-store")
+const { getRegistryPlugin } = require("./plugins-registry")
+
 const PLUGIN_INSTALL_GUIDANCE = {
   beads: {
     plugin: "beads",
@@ -9,35 +14,9 @@ const PLUGIN_INSTALL_GUIDANCE = {
     ],
     note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
   },
-  gwc: {
-    plugin: "gwc",
-    binary: "gws",
-    check: "gws --version",
-    install_steps: [
-      "npm install -g @googleworkspace/cli",
-      "gws --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  commiat: {
-    plugin: "commiat",
-    binary: "commiat",
-    check: "commiat --version",
-    install_steps: [
-      "npm install -g commiat",
-      "commiat --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  docker: {
-    plugin: "docker",
-    binary: "docker",
-    check: "docker --version",
-    install_steps: [
-      "docker --version"
-    ],
-    note: "Install Docker Engine/Desktop using your OS package manager, then verify with docker --version."
-  },
+  gwc: { plugin: "gwc", binary: "gws", check: "gws --version", install_steps: ["npm install -g @googleworkspace/cli", "gws --version"], note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)." },
+  commiat: { plugin: "commiat", binary: "commiat", check: "commiat --version", install_steps: ["npm install -g commiat", "commiat --version"], note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)." },
+  docker: { plugin: "docker", binary: "docker", check: "docker --version", install_steps: ["docker --version"], note: "Install Docker Engine/Desktop using your OS package manager, then verify with docker --version." },
   stripe: {
     plugin: "stripe",
     binary: "stripe",
@@ -294,7 +273,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills get blogwatcher:root.skill",
       "supercli blogwatcher blogs list --json"
     ],
-    note: "This hybrid plugin indexes the upstream BlogWatcher README and SKILL documents into the skills catalog and exposes non-interactive wrappers for the local CLI. BlogWatcher stores data under ~/.blogwatcher, so use an isolated HOME when you want disposable test data."
+    note: "This hybrid plugin indexes the upstream BlogWatcher README and SKILL documents into the skill-doc catalog and exposes non-interactive wrappers for the local CLI. BlogWatcher stores data under ~/.blogwatcher, so use an isolated HOME when you want disposable test data."
   },
   himalaya: {
     plugin: "himalaya",
@@ -366,7 +345,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider monty --json",
       "supercli monty python run \"1 + 2\" --json"
     ],
-    note: "This hybrid plugin indexes the upstream Monty README and CLAUDE (skills) documents and provides a sandboxed Python execution environment. It manages its own @pydantic/monty dependency globally."
+    note: "This hybrid plugin indexes the upstream Monty README and CLAUDE skill documents and provides a sandboxed Python execution environment. It manages its own @pydantic/monty dependency globally."
   },
   cline: {
     plugin: "cline",
@@ -397,7 +376,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli nullclaw cli version --json",
       "supercli nullclaw system status --json"
     ],
-    note: "This hybrid plugin indexes remote NullClaw docs into the local skills catalog and exposes the local nullclaw binary through wrapped commands plus passthrough. curl is required for remote doc retrieval."
+    note: "This hybrid plugin indexes remote NullClaw docs into the local skill-doc catalog and exposes the local nullclaw binary through wrapped commands plus passthrough. curl is required for remote doc retrieval."
   },
   "agency-agents": {
     plugin: "agency-agents",
@@ -408,7 +387,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider agency-agents --json",
       "supercli skills get agency-agents:engineering.engineering-frontend-developer"
     ],
-    note: "Install indexes remote markdown skills from https://github.com/msitarzewski/agency-agents (best effort, upstream paths may change)."
+    note: "Install indexes remote markdown skill documents from https://github.com/msitarzewski/agency-agents (best effort, upstream paths may change)."
   },
   "visual-explainer": {
     plugin: "visual-explainer",
@@ -419,7 +398,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider visual-explainer --json",
       "supercli skills get visual-explainer:visual-explainer.skill"
     ],
-    note: "Install indexes normalized markdown skills from https://github.com/javimosch/visual-explainer (plugins/visual-explainer-normalized)."
+    note: "Install indexes normalized markdown skill documents from https://github.com/javimosch/visual-explainer (plugins/visual-explainer-normalized)."
   },
   resend: {
     plugin: "resend",
@@ -431,15 +410,91 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli resend login",
       "supercli resend cli doctor --json"
     ],
-    note: "This hybrid plugin indexes the upstream resend-cli README into the skills catalog and provides a wrapped interface for sending emails and checking environment health. It manages its own resend-cli dependency globally."
+    note: "This hybrid plugin indexes the upstream resend-cli README into the skill-doc catalog and provides a wrapped interface for sending emails and checking environment health. It manages its own resend-cli dependency globally."
+  },
+  "cocoindex-code": {
+    plugin: "cocoindex-code",
+    binary: "cocoindex-code",
+    check: "cocoindex-code --help",
+    install_steps: [
+      "pipx install cocoindex-code",
+      "cocoindex-code --help",
+      "supercli plugins install cocoindex-code",
+      "supercli cocoindex index build --json",
+      "supercli cocoindex code search --query \"where is auth middleware\" --limit 5 --json",
+      "supercli cocoindex mcp search --query \"where is auth middleware\" --limit 5 --json"
+    ],
+    note: "The plugin auto-registers local MCP server cocoindex-code, exposes fast direct search as cocoindex.code.search, and keeps cocoindex.mcp.search available for MCP-native flows. Use direct mcp call for advanced filters like languages/paths."
   }
 
 }
 
+function normalizeInstallGuidance(guidance, pluginName) {
+  if (!guidance || typeof guidance !== "object" || Array.isArray(guidance)) return null
+  const normalized = {
+    plugin: typeof guidance.plugin === "string" && guidance.plugin ? guidance.plugin : String(pluginName || ""),
+    binary: typeof guidance.binary === "string" ? guidance.binary : "",
+    check: typeof guidance.check === "string" ? guidance.check : "",
+    install_steps: Array.isArray(guidance.install_steps) ? guidance.install_steps.map(step => String(step)).filter(Boolean) : [],
+    note: typeof guidance.note === "string" ? guidance.note : "",
+  }
+  if (!normalized.plugin) return null
+  return (!normalized.binary && !normalized.check && normalized.install_steps.length === 0 && !normalized.note) ? null : normalized
+}
+
+function readManifestGuidance(manifestPath, pluginName) {
+  if (!manifestPath || !fs.existsSync(manifestPath)) return null
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"))
+    return normalizeInstallGuidance(parsed.install_guidance, pluginName || parsed.name)
+  } catch {
+    return null
+  }
+}
+
+function findInstalledPlugin(name) {
+  const lower = String(name || "").toLowerCase().trim()
+  if (!lower) return null
+  const lock = readPluginsLock()
+  return Object.values(lock.installed || {}).find(p => String(p && p.name || "").toLowerCase() === lower) || null
+}
+
+function resolveRegistryManifestPath(entry) {
+  if (!entry || !entry.source || typeof entry.source !== "object") return null
+  const manifestPath = entry.source.manifest_path
+  if (!manifestPath || typeof manifestPath !== "string") return null
+  if (path.isAbsolute(manifestPath)) return manifestPath
+  return path.resolve(__dirname, "..", manifestPath)
+}
+
 function getPluginInstallGuidance(name) {
-  return PLUGIN_INSTALL_GUIDANCE[name] || null
+  const lower = String(name || "").toLowerCase().trim()
+  if (!lower) return null
+
+  const installed = findInstalledPlugin(lower)
+  if (installed) {
+    const stored = normalizeInstallGuidance(installed.install_guidance, installed.name)
+    if (stored) return stored
+    const resolved = installed.resolved_from && installed.resolved_from.manifest_path ? readManifestGuidance(installed.resolved_from.manifest_path, installed.name) : null
+    if (resolved) return resolved
+  }
+
+  const registryEntry = getRegistryPlugin(lower)
+  if (registryEntry) {
+    const inline = normalizeInstallGuidance(registryEntry.install_guidance, registryEntry.name)
+    if (inline) return inline
+    const fromManifest = readManifestGuidance(resolveRegistryManifestPath(registryEntry), registryEntry.name)
+    if (fromManifest) return fromManifest
+  }
+
+  const bundledManifest = path.resolve(__dirname, "..", "plugins", lower, "plugin.json")
+  const bundled = readManifestGuidance(bundledManifest, lower)
+  if (bundled) return bundled
+
+  return PLUGIN_INSTALL_GUIDANCE[lower] || null
 }
 
 module.exports = {
-  getPluginInstallGuidance
+  getPluginInstallGuidance,
+  normalizeInstallGuidance,
 }

package/cli/plugins-manager.js

@@ -15,6 +15,7 @@ const BUNDLED_PLUGINS = {
   beads: path.resolve(__dirname, "..", "plugins", "beads", "plugin.json"),
   gwc: path.resolve(__dirname, "..", "plugins", "gwc", "plugin.json"),
   docker: path.resolve(__dirname, "..", "plugins", "docker", "plugin.json"),
+  squirrelscan: path.resolve(__dirname, "..", "plugins", "squirrelscan", "plugin.json"),
   "agency-agents": path.resolve(__dirname, "..", "plugins", "agency-agents", "plugin.json"),
   "visual-explainer": path.resolve(__dirname, "..", "plugins", "visual-explainer", "plugin.json")
 }