superacli 1.1.4 → 1.1.6

package/__tests__/plugins-command.test.js

@@ -10,10 +10,12 @@ const {
 } = require("../cli/plugins-manager")
 const { listRegistryPlugins } = require("../cli/plugins-registry")
 const { loadConfig } = require("../cli/config")
+const { getPluginLearn } = require("../cli/plugins-learn")
 
 jest.mock("../cli/plugins-manager")
 jest.mock("../cli/plugins-registry")
 jest.mock("../cli/config")
+jest.mock("../cli/plugins-learn")
 
 describe("plugins-command", () => {
   let mockOutput
@@ -108,8 +110,9 @@ describe("plugins-command", () => {
   })
 
   test("explore subcommand", async () => {
-    const mockReg = [{ name: "p1", tags: ["t1"] }]
+    const mockReg = [{ name: "p1", tags: ["t1"], has_learn: true }]
     listRegistryPlugins.mockReturnValue(mockReg)
+    listInstalledPlugins.mockReturnValue([{ name: "p1" }])
 
     await handlePluginsCommand({
       positional: ["plugins", "explore"],
@@ -125,6 +128,64 @@ describe("plugins-command", () => {
     expect(mockOutput).toHaveBeenCalledWith(expect.objectContaining({
       plugins: expect.any(Array)
     }))
+    expect(mockOutput.mock.calls[0][0].plugins[0].has_learn).toBe(true)
+    expect(mockOutput.mock.calls[0][0].plugins[0].installed).toBe(true)
+  })
+
+  test("explore supports has-learn/source/installed/limit filters", async () => {
+    listInstalledPlugins.mockReturnValue([{ name: "p2" }])
+    listRegistryPlugins.mockReturnValue([
+      { name: "p1", tags: ["x"], has_learn: true, source: { type: "bundled" } },
+      { name: "p2", tags: ["x"], has_learn: true, source: { type: "bundled" } },
+      { name: "p3", tags: ["x"], has_learn: false, source: { type: "git" } },
+    ])
+
+    await handlePluginsCommand({
+      positional: ["plugins", "explore"],
+      flags: { "has-learn": "true", source: "bundled", installed: "false", limit: "1" },
+      humanMode: false,
+      output: mockOutput,
+      outputError: mockOutputError,
+    })
+
+    const out = mockOutput.mock.calls[0][0]
+    expect(out.total).toBe(1)
+    expect(out.returned).toBe(1)
+    expect(out.plugins[0].name).toBe("p1")
+    expect(out.filters).toEqual(expect.objectContaining({
+      has_learn: true,
+      source: "bundled",
+      installed: false,
+      limit: 1,
+    }))
+    expect(mockOutputError).not.toHaveBeenCalled()
+  })
+
+  test("explore rejects invalid has-learn", async () => {
+    await handlePluginsCommand({
+      positional: ["plugins", "explore"],
+      flags: { "has-learn": "maybe" },
+      outputError: mockOutputError,
+    })
+    expect(mockOutputError).toHaveBeenCalledWith(expect.objectContaining({ code: 85 }))
+  })
+
+  test("explore rejects invalid source", async () => {
+    await handlePluginsCommand({
+      positional: ["plugins", "explore"],
+      flags: { source: "svn" },
+      outputError: mockOutputError,
+    })
+    expect(mockOutputError).toHaveBeenCalledWith(expect.objectContaining({ code: 85 }))
+  })
+
+  test("explore rejects invalid limit", async () => {
+    await handlePluginsCommand({
+      positional: ["plugins", "explore"],
+      flags: { limit: "0" },
+      outputError: mockOutputError,
+    })
+    expect(mockOutputError).toHaveBeenCalledWith(expect.objectContaining({ code: 85 }))
   })
 
   test("explore subcommand in human mode", async () => {
@@ -208,6 +269,36 @@ describe("plugins-command", () => {
     expect(doctorAllPlugins).toHaveBeenCalled()
   })
 
+  test("learn subcommand success json", async () => {
+    getPluginLearn.mockReturnValue({ plugin: "browser-use", installed: false, source: "registry-bundled", learn_markdown: "# Learn" })
+    await handlePluginsCommand({
+      positional: ["plugins", "learn", "browser-use"],
+      humanMode: false,
+      output: mockOutput,
+    })
+    expect(getPluginLearn).toHaveBeenCalledWith("browser-use")
+    expect(mockOutput).toHaveBeenCalledWith(expect.objectContaining({ plugin: "browser-use" }))
+  })
+
+  test("learn subcommand success human", async () => {
+    getPluginLearn.mockReturnValue({ plugin: "browser-use", installed: false, source: "registry-bundled", learn_markdown: "# Learn" })
+    await handlePluginsCommand({
+      positional: ["plugins", "learn", "browser-use"],
+      humanMode: true,
+      output: mockOutput,
+    })
+    expect(consoleSpy).toHaveBeenCalledWith("# Learn")
+    expect(mockOutput).not.toHaveBeenCalled()
+  })
+
+  test("learn subcommand validation error", async () => {
+    await handlePluginsCommand({
+      positional: ["plugins", "learn"],
+      outputError: mockOutputError,
+    })
+    expect(mockOutputError).toHaveBeenCalledWith(expect.objectContaining({ code: 85 }))
+  })
+
   test("unknown subcommand", async () => {
     await handlePluginsCommand({
       positional: ["plugins", "unknown"],

package/__tests__/plugins-learn.test.js

@@ -0,0 +1,62 @@
+const fs = require("fs")
+const { spawnSync } = require("child_process")
+const { getPlugin } = require("../cli/plugins-manager")
+const { getRegistryPlugin } = require("../cli/plugins-registry")
+const { getPluginLearn, resolveLearnMarkdown } = require("../cli/plugins-learn")
+
+jest.mock("fs")
+jest.mock("child_process")
+jest.mock("../cli/plugins-manager")
+jest.mock("../cli/plugins-registry")
+
+describe("plugins-learn", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    spawnSync.mockReturnValue({ status: 0, stdout: "" })
+    getPlugin.mockReturnValue(null)
+    getRegistryPlugin.mockReturnValue(null)
+  })
+
+  test("loads learn markdown from registry bundled file", () => {
+    getRegistryPlugin.mockReturnValue({
+      name: "browser-use",
+      source: { type: "bundled", manifest_path: "plugins/browser-use/plugin.json" },
+    })
+
+    fs.existsSync.mockImplementation((p) => String(p).includes("plugin.json") || String(p).includes("SKILL.md"))
+    fs.readFileSync.mockImplementation((p) => {
+      if (String(p).includes("plugin.json")) {
+        return JSON.stringify({ name: "browser-use", learn: { file: "skills/quickstart/SKILL.md" } })
+      }
+      return "# Browser Use Learn"
+    })
+
+    const out = getPluginLearn("browser-use")
+    expect(out.plugin).toBe("browser-use")
+    expect(out.installed).toBe(false)
+    expect(out.learn_markdown).toContain("Browser Use Learn")
+  })
+
+  test("prefers installed plugin source when available", () => {
+    getPlugin.mockReturnValue({
+      name: "browser-use",
+      resolved_from: { type: "path", manifest_path: "/tmp/browser-use/plugin.json" },
+    })
+
+    fs.existsSync.mockImplementation((p) => String(p).includes("plugin.json") || String(p).includes("learn.md"))
+    fs.readFileSync.mockImplementation((p) => {
+      if (String(p).includes("plugin.json")) {
+        return JSON.stringify({ name: "browser-use", learn: { file: "learn.md" } })
+      }
+      return "# Installed Learn"
+    })
+
+    const out = getPluginLearn("browser-use")
+    expect(out.installed).toBe(true)
+    expect(out.learn_markdown).toContain("Installed Learn")
+  })
+
+  test("resolveLearnMarkdown rejects invalid learn object", () => {
+    expect(() => resolveLearnMarkdown({ name: "x", learn: { file: "a.md", text: "b" } }, "/tmp/plugin.json")).toThrow(/either learn.text or learn.file/)
+  })
+})

package/__tests__/plugins-registry.test.js

@@ -44,7 +44,7 @@ describe("plugins-registry", () => {
   describe("listRegistryPlugins", () => {
     const mockRegistry = {
       plugins: [
-        { name: "p1", description: "desc1", tags: ["t1", "t2"], source: { type: "git" } },
+        { name: "p1", description: "desc1", tags: ["t1", "t2"], source: { type: "git" }, has_learn: true },
         { name: "p2", description: "other", tags: ["t2"] }
       ]
     }
@@ -58,6 +58,8 @@ describe("plugins-registry", () => {
       const list = listRegistryPlugins()
       expect(list).toHaveLength(2)
       expect(list[0]).toMatchObject({ name: "p1", tags: ["t1", "t2"] })
+      expect(list[0].has_learn).toBe(true)
+      expect(list[1].has_learn).toBe(false)
       expect(list[1].source).toEqual({}) // normalized
     })
 

package/__tests__/resend-plugin.test.js

@@ -0,0 +1,122 @@
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { execSync } = require("child_process")
+
+const CLI = path.join(__dirname, "..", "cli", "supercli.js")
+const nodeDir = path.dirname(process.execPath)
+
+function runNoServer(args, options = {}) {
+  try {
+    const env = { ...process.env }
+    delete env.SUPERCLI_SERVER
+    const out = execSync(`node ${CLI} ${args}`, {
+      encoding: "utf-8",
+      timeout: 15000,
+      env: { ...env, ...(options.env || {}) }
+    })
+    return { ok: true, output: out.trim(), code: 0 }
+  } catch (err) {
+    return {
+      ok: false,
+      output: (err.stdout || "").trim(),
+      stderr: (err.stderr || "").trim(),
+      code: err.status
+    }
+  }
+}
+
+function writeFakeCurlBinary(dir) {
+  const bin = path.join(dir, "curl")
+  fs.writeFileSync(bin, [
+    "#!/usr/bin/env node",
+    "const args = process.argv.slice(2);",
+    "const url = args[args.length - 1] || '';",
+    "if (args.includes('--version')) { console.log('curl 8.0.0-test'); process.exit(0); }",
+    "if (url.endsWith('/README.md')) { console.log('# Resend CLI\\n\\nTest readme.'); process.exit(0); }",
+    "process.exit(22);"
+  ].join("\n"), "utf-8")
+  fs.chmodSync(bin, 0o755)
+  return bin
+}
+
+describe("resend hybrid plugin", () => {
+  const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-resend-bin-"))
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-home-resend-"))
+  const fakeUserHome = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-user-home-resend-"))
+  writeFakeCurlBinary(fakeBinDir)
+  
+  const env = {
+    ...process.env,
+    PATH: `${fakeBinDir}:${process.env.PATH || ""}`,
+    SUPERCLI_HOME: tempHome,
+    HOME: fakeUserHome
+  }
+  let removed = false
+
+  beforeAll(() => {
+    // Install the plugin
+    const install = runNoServer("plugins install ./plugins/resend --on-conflict replace --json", { env })
+    if (!install.ok) {
+        console.error("Install failed:", install.output, install.stderr)
+    }
+    expect(install.ok).toBe(true)
+  })
+
+  afterAll(() => {
+    if (!removed) runNoServer("plugins remove resend --json", { env })
+    fs.rmSync(fakeBinDir, { recursive: true, force: true })
+    fs.rmSync(tempHome, { recursive: true, force: true })
+    fs.rmSync(fakeUserHome, { recursive: true, force: true })
+  })
+
+  test("indexes resend skills provider", () => {
+    const list = runNoServer("skills list --catalog --provider resend --json", { env })
+    expect(list.ok).toBe(true)
+    const listData = JSON.parse(list.output)
+    expect(listData.skills.some(skill => skill.id === "resend:root.readme")).toBe(true)
+  })
+
+  test("fetches indexed remote skill markdown", () => {
+    const skill = runNoServer("skills get resend:root.readme", { env })
+    expect(skill.ok).toBe(true)
+    expect(skill.output).toContain("Resend CLI")
+  })
+
+  test("fails with helpful message when resend binary is missing", () => {
+    // Ensure 'resend' is not found, but keep 'node' available
+    const r = runNoServer("resend cli doctor --json", { 
+        env: { ...env, PATH: `${fakeBinDir}:${nodeDir}` } 
+    })
+    expect(r.ok).toBe(false)
+    const data = JSON.parse(r.output || r.stderr)
+    expect(data.error.message).toContain("Missing dependency 'resend'")
+    expect(data.error.message).toContain("Please run 'dcli resend cli setup'")
+  })
+
+  test("exposes expanded structured commands", () => {
+    const help = runNoServer("help resend --json", { env })
+    expect(help.ok).toBe(true)
+    const data = JSON.parse(help.output)
+    
+    const resendNamespace = data.namespaces.find(n => n.name === "resend")
+    expect(resendNamespace).toBeDefined()
+
+    const resources = new Set(resendNamespace.resources.map(r => r.name))
+    
+    expect(resources.has("domains")).toBe(true)
+    expect(resources.has("api-keys")).toBe(true)
+    expect(resources.has("webhooks")).toBe(true)
+    expect(resources.has("contacts")).toBe(true)
+    expect(resources.has("auth")).toBe(true)
+  })
+
+  test("doctor reports node and npm dependencies as healthy", () => {
+    const r = runNoServer("plugins doctor resend --json", { env })
+    expect(r.ok).toBe(true)
+    const data = JSON.parse(r.output)
+    expect(data.ok).toBe(true)
+    expect(data.checks.some(c => c.binary === "node" && c.ok === true)).toBe(true)
+    expect(data.checks.some(c => c.binary === "npm" && c.ok === true)).toBe(true)
+  })
+})

package/__tests__/skills.test.js

@@ -103,6 +103,10 @@ describe("skills", () => {
     const md = buildMcpServersUsageSkillMarkdown({ showDag: true })
     expect(md).toContain("skill_name: \"mcp_servers_usage\"")
     expect(md).toContain("supercli mcp add browser-use --command npx")
+    expect(md).toContain("supercli mcp tools --mcp-server browser-use --json")
+    expect(md).toContain("supercli mcp call --mcp-server browser-use --tool <tool_name>")
+    expect(md).toContain("supercli mcp bind --mcp-server browser-use --tool <tool_name>")
+    expect(md).toContain("supercli mcp doctor --mcp-server browser-use --json")
     expect(md).toContain("X-Browser-Use-API-Key")
     expect(md).toContain("dag:")
   })

package/cli/adapter-schema.js

@@ -36,8 +36,9 @@ function validateCommonConfig(adapterName, config) {
     if (typeof config.timeout_ms !== "number" || Number.isNaN(config.timeout_ms) || config.timeout_ms <= 0) {
       throw asInvalid("adapterConfig.timeout_ms must be a positive number")
     }
-    if (config.timeout_ms > 15000) {
-      throw asInvalid("adapterConfig.timeout_ms cannot exceed 15000ms")
+    const maxTimeoutMs = ["mcp", "process", "shell"].includes(adapterName) ? 180000 : 15000
+    if (config.timeout_ms > maxTimeoutMs) {
+      throw asInvalid(`adapterConfig.timeout_ms cannot exceed ${maxTimeoutMs}ms`)
     }
   }
 

package/cli/adapters/mcp.js

@@ -2,6 +2,10 @@
 // Supports HTTP MCP endpoints and local stdio MCP commands.
 
 const { spawn } = require("child_process");
+const {
+  shouldUseStdioJsonRpc,
+  stdioCallToolJsonRpc,
+} = require("../mcp-stdio-jsonrpc");
 
 function asObject(value) {
   return value && typeof value === "object" && !Array.isArray(value)
@@ -9,18 +13,23 @@ function asObject(value) {
     : {};
 }
 
+function interpolateEnvPlaceholders(text) {
+  if (typeof text !== "string") return text;
+  return text.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => process.env[name] || "");
+}
+
 function asStringMap(value) {
   const obj = asObject(value);
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
-    if (typeof k === "string" && typeof v === "string") out[k] = v;
+    if (typeof k === "string" && typeof v === "string") out[k] = interpolateEnvPlaceholders(v);
   }
   return out;
 }
 
 function asStringArray(value) {
   if (!Array.isArray(value)) return [];
-  return value.filter((v) => typeof v === "string");
+  return value.filter((v) => typeof v === "string").map((v) => interpolateEnvPlaceholders(v));
 }
 
 function mergeMcpConfig(cmdConfig, serverEntry) {
@@ -42,7 +51,7 @@ function mergeMcpConfig(cmdConfig, serverEntry) {
   return {
     tool: cmdConfig.tool,
     server: cmdConfig.server,
-    url: cmdConfig.url || (serverEntry && serverEntry.url),
+    url: interpolateEnvPlaceholders(cmdConfig.url || (serverEntry && serverEntry.url)),
     command: cmdConfig.command || (serverEntry && serverEntry.command),
     timeout_ms:
       cmdConfig.timeout_ms !== undefined
@@ -215,6 +224,16 @@ async function execute(cmd, flags, context) {
     const commandArgs = Array.isArray(config.args) ? config.args : [];
     const timeoutMs =
       Number(config.timeout_ms) > 0 ? Number(config.timeout_ms) : 10000;
+    if (shouldUseStdioJsonRpc(config)) {
+      return stdioCallToolJsonRpc({
+        command: config.command,
+        args: commandArgs,
+        timeoutMs,
+        env: config.env,
+        tool: toolName,
+        input,
+      });
+    }
     return callStdioTool(
       config.command,
       commandArgs,

package/cli/adapters/process.js

@@ -111,8 +111,12 @@ async function execute(cmd, flags, context = {}) {
   const timeoutMs = Number(cfg.timeout_ms) > 0 ? Number(cfg.timeout_ms) : 15000
   const flagsBeforePositionals = cfg.flagsBeforePositionals === true || binary === "docker"
   const passthroughInteractive = passthroughMode && flags.__passthroughInteractive === true
-  const cwd = typeof cfg.cwd === "string" ? cfg.cwd : undefined
-  const env = (cfg.env && typeof cfg.env === "object") ? { ...process.env, ...cfg.env } : process.env
+  const defaultCwd = cmd.plugin_dir || undefined
+  const cwd = typeof cfg.cwd === "string" ? cfg.cwd : defaultCwd
+  const pluginEnv = {}
+  if (cmd.plugin_dir) pluginEnv.SUPERCLI_PLUGIN_DIR = cmd.plugin_dir
+  if (cmd.plugin_name) pluginEnv.SUPERCLI_PLUGIN_NAME = cmd.plugin_name
+  const env = (cfg.env && typeof cfg.env === "object") ? { ...process.env, ...cfg.env, ...pluginEnv } : { ...process.env, ...pluginEnv }
   const streamMode = cfg.stream || null
   const onStreamEvent = typeof context.onStreamEvent === "function" ? context.onStreamEvent : null
 
@@ -215,11 +219,34 @@ async function execute(cmd, flags, context = {}) {
       settled = true
       clearTimeout(timer)
       if (code !== 0) {
-        reject(Object.assign(new Error(`Process adapter failed (${binary} ${args.join(" ")}): ${err.trim()}`), {
-          code: 105,
-          type: "integration_error",
-          recoverable: true
-        }))
+        const errorText = err.trim()
+        let parsedError = null
+        try {
+          const possibleJson = errorText.match(/\{.*\}/s)
+          if (possibleJson) {
+            parsedError = JSON.parse(possibleJson[0])
+          }
+        } catch {
+          // ignore
+        }
+
+        const baseMsg = `Process adapter failed (${binary} ${args.join(" ")})`
+        const finalMsg = parsedError && parsedError.error && parsedError.error.message
+          ? parsedError.error.message
+          : (parsedError && parsedError.message ? parsedError.message : errorText || baseMsg)
+
+        const errorObj = Object.assign(new Error(finalMsg), {
+          code: (parsedError && parsedError.error && parsedError.error.code) || (parsedError && parsedError.code) || 105,
+          type: (parsedError && parsedError.error && parsedError.error.type) || (parsedError && parsedError.type) || "integration_error",
+          recoverable: (parsedError && parsedError.error && typeof parsedError.error.recoverable === "boolean") 
+            ? parsedError.error.recoverable 
+            : ((parsedError && typeof parsedError.recoverable === "boolean") ? parsedError.recoverable : true),
+          suggestions: (parsedError && parsedError.error && Array.isArray(parsedError.error.suggestions))
+            ? parsedError.error.suggestions
+            : (Array.isArray(parsedError && parsedError.suggestions) ? parsedError.suggestions : [])
+        })
+
+        reject(errorObj)
         return
       }
 

package/cli/config.js

@@ -173,6 +173,32 @@ async function listMcpServers() {
   return Array.isArray(cfg.mcp_servers) ? cfg.mcp_servers : []
 }
 
+async function upsertCommand(commandDef) {
+  const cfg = readCache() || emptyConfig()
+  const commands = Array.isArray(cfg.commands) ? cfg.commands.slice() : []
+  const idx = commands.findIndex(c =>
+    c &&
+    c.namespace === commandDef.namespace &&
+    c.resource === commandDef.resource &&
+    c.action === commandDef.action,
+  )
+  if (idx >= 0) commands[idx] = commandDef
+  else commands.push(commandDef)
+  cfg.commands = commands
+  writeCache(cfg)
+  return commandDef
+}
+
+async function removeCommandsByNamespace(namespace) {
+  const cfg = readCache() || emptyConfig()
+  const commands = Array.isArray(cfg.commands) ? cfg.commands : []
+  const next = commands.filter(c => !(c && c.namespace === namespace))
+  const removed = commands.length - next.length
+  cfg.commands = next
+  writeCache(cfg)
+  return removed
+}
+
 async function showConfig() {
   const cache = readCache()
   if (!cache) {
@@ -190,4 +216,4 @@ async function showConfig() {
   }
 }
 
-module.exports = { loadConfig, syncConfig, showConfig, setMcpServer, removeMcpServer, listMcpServers }
+module.exports = { loadConfig, syncConfig, showConfig, setMcpServer, removeMcpServer, listMcpServers, upsertCommand, removeCommandsByNamespace }

package/cli/help-json.js

@@ -2,8 +2,8 @@ function buildCapabilities(config, hasServer) {
   const commands = {
     help: { description: "List namespaces and commands" },
     config: { subcommands: ["show"] },
-    plugins: { subcommands: ["list", "explore", "install", "remove", "show", "doctor"], description: "Manage local and remote command plugins" },
-    mcp: { subcommands: ["list", "add", "remove"], description: "Manage local MCP server registry" },
+    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" },
     commands: { description: "List all commands" },
     inspect: { description: "Inspect command details", usage: "supercli inspect <ns> <res> <act>" },
     plan: { description: "Create execution plan", usage: "supercli plan <ns> <res> <act> [--args]" },

package/cli/mcp-diagnostics.js

@@ -0,0 +1,152 @@
+const { spawnSync } = require("child_process");
+const {
+  shouldUseStdioJsonRpc,
+  stdioListToolsJsonRpc,
+} = require("./mcp-stdio-jsonrpc");
+
+function interpolateEnvPlaceholders(text) {
+  if (typeof text !== "string") return text;
+  return text.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => process.env[name] || "");
+}
+
+function interpolateStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((v) => typeof v === "string")
+    .map((v) => interpolateEnvPlaceholders(v));
+}
+
+function interpolateStringMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof k === "string" && typeof v === "string") out[k] = interpolateEnvPlaceholders(v);
+  }
+  return out;
+}
+
+function commandBinary(command) {
+  const text = String(command || "").trim();
+  if (!text) return "";
+  const first = text.split(/\s+/)[0];
+  return first || "";
+}
+
+function checkCommandAvailable(command) {
+  const bin = commandBinary(command);
+  if (!bin) {
+    return { ok: false, message: "Missing command" };
+  }
+  const probe = spawnSync("sh", ["-lc", `command -v ${bin}`], {
+    encoding: "utf-8",
+    timeout: 5000,
+  });
+  if (probe.error || probe.status !== 0) {
+    return { ok: false, message: `Command '${bin}' not found in PATH` };
+  }
+  return { ok: true, message: `Command '${bin}' is available` };
+}
+
+async function diagnoseMcpServer(server, options = {}) {
+  const discoverTools = options.discoverTools;
+  const transport = server.command ? "stdio" : server.url ? "http" : "unknown";
+  const checks = [];
+  const issues = [];
+
+  checks.push({
+    id: "source",
+    ok: !!(server.url || server.command),
+    message: server.url || server.command
+      ? "Server has a callable source"
+      : "Server is missing both url and command",
+  });
+
+  if (server.command) {
+    const c = checkCommandAvailable(server.command);
+    checks.push({ id: "command", ok: c.ok, message: c.message });
+    if (!c.ok) issues.push(c.message);
+
+    const args = interpolateStringArray(
+      Array.isArray(server.args)
+        ? server.args
+        : Array.isArray(server.commandArgs)
+          ? server.commandArgs
+          : [],
+    );
+    const usesNpx = commandBinary(server.command) === "npx";
+    const usesMcpRemote = args.includes("mcp-remote");
+    const hasYesFlag = args.includes("-y") || args.includes("--yes");
+    if (usesNpx && usesMcpRemote && !hasYesFlag) {
+      const note = "npx mcp-remote may hang in non-interactive mode without -y/--yes";
+      checks.push({ id: "npx_yes_flag", ok: false, message: note });
+      issues.push(`${note}; add '-y' before 'mcp-remote' in args.`);
+    }
+  }
+
+  let tools = [];
+  const detail = [];
+
+  if (server.command && shouldUseStdioJsonRpc(server)) {
+    try {
+      const rpc = await stdioListToolsJsonRpc({
+        command: server.command,
+        args: interpolateStringArray(
+          Array.isArray(server.args)
+            ? server.args
+            : Array.isArray(server.commandArgs)
+              ? server.commandArgs
+              : [],
+        ),
+        env: interpolateStringMap(server.env),
+        timeoutMs:
+          Number(server.timeout_ms) > 0
+            ? Math.min(Number(server.timeout_ms), 15000)
+            : 15000,
+      });
+      tools = Array.isArray(rpc && rpc.tools) ? rpc.tools : [];
+      detail.push("JSON-RPC stdio handshake completed");
+    } catch (err) {
+      const msg = `JSON-RPC discovery failed: ${err.message}`;
+      issues.push(msg);
+      detail.push(msg);
+    }
+  }
+
+  if (typeof discoverTools === "function" && (server.url || server.command)) {
+    try {
+      if (tools.length === 0) tools = await discoverTools(server);
+    } catch (err) {
+      issues.push(`Tool discovery error: ${err.message}`);
+    }
+  }
+
+  checks.push({
+    id: "tools",
+    ok: tools.length > 0,
+    message:
+      tools.length > 0
+        ? `Discovered ${tools.length} tool(s)`
+        : "No tools discovered (tool listing may be unsupported or requires auth)",
+  });
+  if (tools.length === 0) {
+    issues.push("No tools discovered; verify auth, endpoint, and list-tools support.");
+  }
+
+  const status = checks.every((c) => c.ok)
+    ? "healthy"
+    : checks.some((c) => c.ok)
+      ? "degraded"
+      : "unhealthy";
+
+  return {
+    server: server.name,
+    status,
+    transport,
+    checks,
+    tools,
+    issues,
+    detail,
+  };
+}
+
+module.exports = { diagnoseMcpServer, checkCommandAvailable, commandBinary };