superacli 1.1.4 → 1.1.6

package/cli/mcp-stdio-jsonrpc.js

@@ -0,0 +1,246 @@
+const { spawn } = require("child_process");
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string");
+}
+
+function shouldUseStdioJsonRpc(config = {}) {
+  if (config.mcp_protocol === "jsonrpc") return true;
+  const args = [
+    ...asStringArray(config.args),
+    ...asStringArray(config.commandArgs),
+  ];
+  return args.includes("mcp-remote");
+}
+
+function detectWireMode(config = {}) {
+  if (config.mcp_wire === "jsonl") return "jsonl";
+  if (config.mcp_wire === "lsp") return "lsp";
+  const args = [
+    ...asStringArray(config.args),
+    ...asStringArray(config.commandArgs),
+  ];
+  if (args.includes("mcp-remote")) return "jsonl";
+  return "lsp";
+}
+
+function parseBufferMessages(state, chunk, onMessage) {
+  const nextChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf-8");
+  state.buffer = Buffer.concat([state.buffer, nextChunk]);
+
+  while (state.buffer.length > 0) {
+    const headerEnd = state.buffer.indexOf("\r\n\r\n");
+    if (headerEnd >= 0) {
+      const headerText = state.buffer.slice(0, headerEnd).toString("utf-8");
+      const match = headerText.match(/Content-Length:\s*(\d+)/i);
+      if (match) {
+        const length = Number(match[1]);
+        const total = headerEnd + 4 + length;
+        if (state.buffer.length < total) return;
+        const body = state.buffer.slice(headerEnd + 4, total).toString("utf-8");
+        state.buffer = state.buffer.slice(total);
+        try {
+          onMessage(JSON.parse(body));
+        } catch {
+          // ignore parse errors for malformed messages
+        }
+        continue;
+      }
+    }
+
+    const newline = state.buffer.indexOf("\n");
+    if (newline < 0) return;
+    const line = state.buffer.slice(0, newline).toString("utf-8").trim();
+    state.buffer = state.buffer.slice(newline + 1);
+    if (!line) continue;
+    try {
+      onMessage(JSON.parse(line));
+    } catch {
+      // ignore non-json lines
+    }
+  }
+}
+
+function buildRpcError(error, fallback) {
+  const msg =
+    (error && typeof error.message === "string" && error.message) ||
+    fallback ||
+    "MCP JSON-RPC error";
+  return Object.assign(new Error(msg), {
+    code: 105,
+    type: "integration_error",
+    recoverable: true,
+  });
+}
+
+function runJsonRpcSession(options) {
+  const {
+    command,
+    args,
+    env,
+    timeoutMs,
+    operation,
+    tool,
+    input,
+    protocolVersion = "2025-06-18",
+    wireMode = "lsp",
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args || [], {
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: !Array.isArray(args) || args.length === 0,
+      env: env && typeof env === "object" ? { ...process.env, ...env } : process.env,
+    });
+
+    const state = {
+      buffer: Buffer.alloc(0),
+      settled: false,
+      nextId: 1,
+      pending: new Map(),
+      stderr: "",
+    };
+
+    function settleError(err) {
+      if (state.settled) return;
+      state.settled = true;
+      clearTimeout(timer);
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // ignore kill errors
+      }
+      reject(err);
+    }
+
+    function settleOk(value) {
+      if (state.settled) return;
+      state.settled = true;
+      clearTimeout(timer);
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // ignore kill errors
+      }
+      resolve(value);
+    }
+
+    function frame(obj) {
+      const body = JSON.stringify(obj);
+      if (wireMode === "jsonl") return `${body}\n`;
+      return `Content-Length: ${Buffer.byteLength(body, "utf-8")}\r\n\r\n${body}`;
+    }
+
+    function sendRequest(method, params) {
+      return new Promise((res, rej) => {
+        const id = state.nextId++;
+        state.pending.set(id, { res, rej });
+        child.stdin.write(
+          frame({ jsonrpc: "2.0", id, method, params: params || {} }),
+        );
+      });
+    }
+
+    function sendNotification(method, params) {
+      child.stdin.write(
+        frame({ jsonrpc: "2.0", method, params: params || {} }),
+      );
+    }
+
+    const timer = setTimeout(() => {
+      settleError(buildRpcError(null, `MCP stdio JSON-RPC timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.stderr.on("data", (chunk) => {
+      state.stderr += chunk.toString();
+    });
+
+    child.stdout.on("data", (chunk) => {
+      parseBufferMessages(state, chunk, (msg) => {
+        if (!msg || typeof msg !== "object") return;
+        if (msg.id === undefined || msg.id === null) return;
+        const pending = state.pending.get(msg.id);
+        if (!pending) return;
+        state.pending.delete(msg.id);
+        if (msg.error) {
+          pending.rej(buildRpcError(msg.error, `MCP JSON-RPC error: ${msg.error.message || "unknown"}`));
+          return;
+        }
+        pending.res(msg.result);
+      });
+    });
+
+    child.on("error", (err) => {
+      settleError(buildRpcError(err, `Failed to start MCP stdio command: ${err.message}`));
+    });
+
+    child.on("close", (code) => {
+      if (state.settled) return;
+      if (code === 0) {
+        settleError(
+          buildRpcError(
+            null,
+            "MCP stdio JSON-RPC session ended before operation completed",
+          ),
+        );
+        return;
+      }
+      settleError(
+        buildRpcError(
+          null,
+          `MCP stdio command exited with code ${code}: ${state.stderr.trim()}`,
+        ),
+      );
+    });
+
+    (async () => {
+      try {
+        await sendRequest("initialize", {
+          protocolVersion,
+          capabilities: {},
+          clientInfo: { name: "supercli", version: "1.0.0" },
+        });
+        sendNotification("notifications/initialized", {});
+
+        if (operation === "list_tools") {
+          const result = await sendRequest("tools/list", {});
+          const tools = result && Array.isArray(result.tools) ? result.tools : [];
+          settleOk({ tools });
+          return;
+        }
+
+        const result = await sendRequest("tools/call", {
+          name: tool,
+          arguments: input || {},
+        });
+        settleOk(result);
+      } catch (err) {
+        settleError(buildRpcError(err, err.message));
+      }
+    })();
+  });
+}
+
+async function stdioListToolsJsonRpc(options) {
+  return runJsonRpcSession({
+    ...options,
+    operation: "list_tools",
+    wireMode: options.wireMode || detectWireMode(options),
+  });
+}
+
+async function stdioCallToolJsonRpc(options) {
+  return runJsonRpcSession({
+    ...options,
+    operation: "call_tool",
+    wireMode: options.wireMode || detectWireMode(options),
+  });
+}
+
+module.exports = {
+  shouldUseStdioJsonRpc,
+  detectWireMode,
+  stdioListToolsJsonRpc,
+  stdioCallToolJsonRpc,
+};

package/cli/plugin-install-guidance.js

@@ -356,6 +356,18 @@ const PLUGIN_INSTALL_GUIDANCE = {
     ],
     note: "This hybrid plugin indexes upstream clix docs and exposes curated read-only wrappers. Use upstream clix directly for cookie login, account switching, posting, deleting, likes, retweets, and bookmark mutations."
   },
+  monty: {
+    plugin: "monty",
+    binary: "node",
+    check: "supercli monty cli version --json",
+    install_steps: [
+      "supercli plugins install monty",
+      "supercli monty cli setup",
+      "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."
+  },
   cline: {
     plugin: "cline",
     binary: "cline",
@@ -408,7 +420,20 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "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)."
+  },
+  resend: {
+    plugin: "resend",
+    binary: "resend",
+    check: "resend doctor --json",
+    install_steps: [
+      "supercli plugins install resend",
+      "supercli resend cli setup",
+      "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."
   }
+
 }
 
 function getPluginInstallGuidance(name) {

package/cli/plugins-command.js

@@ -9,11 +9,26 @@ const {
 } = require("./plugins-manager")
 const { listRegistryPlugins } = require("./plugins-registry")
 const { loadConfig } = require("./config")
+const { getPluginLearn } = require("./plugins-learn")
 
 async function handlePluginsCommand(options) {
   const { positional, flags, humanMode, output, outputHumanTable, outputError } = options
   const subcommand = positional[1]
 
+  function parseBooleanFlag(name, value) {
+    if (value === undefined) return null
+    const raw = String(value).trim().toLowerCase()
+    if (raw === "true") return true
+    if (raw === "false") return false
+    outputError({
+      code: 85,
+      type: "invalid_argument",
+      message: `Invalid --${name}. Use true or false`,
+      recoverable: false
+    })
+    return null
+  }
+
   if (subcommand === "list") {
     const plugins = listInstalledPlugins().map(p => ({
       name: p.name,
@@ -70,18 +85,65 @@ async function handlePluginsCommand(options) {
       .map(t => t.trim())
       .filter(Boolean)
     const name = flags.name ? String(flags.name).trim() : ""
-    const plugins = listRegistryPlugins({ name, tags }).map(p => ({
+    const hasLearnFilter = parseBooleanFlag("has-learn", flags["has-learn"])
+    if (flags["has-learn"] !== undefined && hasLearnFilter === null) return true
+
+    const installedFilter = parseBooleanFlag("installed", flags.installed)
+    if (flags.installed !== undefined && installedFilter === null) return true
+
+    const sourceFilter = flags.source ? String(flags.source).trim().toLowerCase() : null
+    if (sourceFilter && !["bundled", "git"].includes(sourceFilter)) {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: "Invalid --source. Use bundled or git",
+        recoverable: false
+      })
+      return true
+    }
+
+    const limit = flags.limit === undefined ? null : Number(flags.limit)
+    if (flags.limit !== undefined && (!Number.isFinite(limit) || limit <= 0 || !Number.isInteger(limit))) {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: "Invalid --limit. Use a positive integer",
+        recoverable: false
+      })
+      return true
+    }
+
+    const installedSet = new Set(listInstalledPlugins().map(p => p.name))
+
+    let plugins = listRegistryPlugins({ name, tags }).map(p => ({
       name: p.name,
       description: p.description,
       tags: p.tags,
+      has_learn: p.has_learn === true,
+      installed: installedSet.has(p.name),
       source_type: (p.source && p.source.type) || "bundled",
       source_repo: p.source && p.source.repo ? p.source.repo : ""
     }))
 
+    if (hasLearnFilter !== null) {
+      plugins = plugins.filter(p => p.has_learn === hasLearnFilter)
+    }
+    if (installedFilter !== null) {
+      plugins = plugins.filter(p => p.installed === installedFilter)
+    }
+    if (sourceFilter) {
+      plugins = plugins.filter(p => p.source_type === sourceFilter)
+    }
+
+    const total = plugins.length
+    if (limit !== null) plugins = plugins.slice(0, limit)
+
     if (humanMode) {
       console.log("\n  ⚡ Plugin Registry\n")
       outputHumanTable(plugins, [
         { key: "name", label: "Name" },
+        { key: "installed", label: "Installed" },
+        { key: "has_learn", label: "Learn" },
         { key: "source_type", label: "Source" },
         { key: "tags", label: "Tags" },
         { key: "description", label: "Description" }
@@ -90,9 +152,15 @@ async function handlePluginsCommand(options) {
     } else {
       output({
         plugins,
+        total,
+        returned: plugins.length,
         filters: {
           name: name || null,
-          tags
+          tags,
+          has_learn: hasLearnFilter,
+          installed: installedFilter,
+          source: sourceFilter,
+          limit: limit === null ? null : limit
         }
       })
     }
@@ -131,7 +199,22 @@ async function handlePluginsCommand(options) {
     return true
   }
 
-  outputError({ code: 85, type: "invalid_argument", message: "Unknown plugins subcommand. Use: list, explore, install, remove, show, doctor", recoverable: false })
+  if (subcommand === "learn") {
+    const name = positional[2]
+    if (!name) {
+      outputError({ code: 85, type: "invalid_argument", message: "Usage: dcli plugins learn <name>", recoverable: false })
+      return true
+    }
+    const info = getPluginLearn(name)
+    if (humanMode) {
+      console.log(info.learn_markdown)
+    } else {
+      output(info)
+    }
+    return true
+  }
+
+  outputError({ code: 85, type: "invalid_argument", message: "Unknown plugins subcommand. Use: list, explore, install, remove, show, doctor, learn", recoverable: false })
   return true
 }
 

package/cli/plugins-learn.js

@@ -0,0 +1,177 @@
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+const { spawnSync } = require("child_process")
+const { getPlugin } = require("./plugins-manager")
+const { getRegistryPlugin } = require("./plugins-registry")
+
+function invalid(message) {
+  return Object.assign(new Error(message), {
+    code: 85,
+    type: "invalid_argument",
+    recoverable: false,
+  })
+}
+
+function notFound(message, suggestions = []) {
+  return Object.assign(new Error(message), {
+    code: 92,
+    type: "resource_not_found",
+    recoverable: false,
+    suggestions,
+  })
+}
+
+function integration(message, suggestions = []) {
+  return Object.assign(new Error(message), {
+    code: 105,
+    type: "integration_error",
+    recoverable: true,
+    suggestions,
+  })
+}
+
+function parseManifest(manifestPath) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf-8"))
+  } catch (err) {
+    throw invalid(`Invalid plugin manifest at ${manifestPath}: ${err.message}`)
+  }
+}
+
+function resolveBundledManifestPath(pluginName) {
+  return path.resolve(__dirname, "..", "plugins", pluginName, "plugin.json")
+}
+
+function resolveLearnMarkdown(manifest, manifestPath) {
+  const learn = manifest.learn
+  if (!learn) {
+    throw notFound(`Plugin '${manifest.name}' does not define learn content`, [
+      "Use: supercli plugins show <name>",
+      "Use: supercli plugins explore --name <name>",
+    ])
+  }
+
+  if (typeof learn === "string") return learn
+
+  if (!learn || typeof learn !== "object" || Array.isArray(learn)) {
+    throw invalid("Invalid plugin learn definition: expected string or object")
+  }
+
+  if (learn.text && learn.file) {
+    throw invalid("Invalid plugin learn definition: use either learn.text or learn.file")
+  }
+
+  if (typeof learn.text === "string") return learn.text
+
+  if (typeof learn.file === "string") {
+    const base = path.dirname(manifestPath)
+    const filePath = path.resolve(base, learn.file)
+    const normalizedBase = path.resolve(base) + path.sep
+    if (!filePath.startsWith(normalizedBase)) {
+      throw invalid(`Invalid learn.file path '${learn.file}'`)
+    }
+    if (!fs.existsSync(filePath)) {
+      throw notFound(`Learn file not found: ${learn.file}`)
+    }
+    return fs.readFileSync(filePath, "utf-8")
+  }
+
+  throw invalid("Invalid plugin learn definition: expected learn.text or learn.file")
+}
+
+function loadManifestFromGit(repo, ref, manifestPath) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "supercli-plugin-learn-"))
+  try {
+    const args = ["clone", "--depth", "1"]
+    if (ref) args.push("--branch", String(ref), "--single-branch")
+    args.push(repo, tmpDir)
+    const clone = spawnSync("git", args, { encoding: "utf-8", timeout: 15000 })
+    if (clone.error) {
+      throw integration(`Failed to clone plugin repo '${repo}': ${clone.error.message}`, ["Check internet connectivity"])
+    }
+    if (clone.status !== 0) {
+      throw integration(`Failed to clone plugin repo '${repo}': ${(clone.stderr || "").trim() || `exit ${clone.status}`}`)
+    }
+
+    const rel = manifestPath || "plugin.json"
+    const full = path.resolve(tmpDir, rel)
+    const normalized = path.resolve(tmpDir) + path.sep
+    if (!full.startsWith(normalized)) {
+      throw invalid(`Invalid manifest path '${rel}'`)
+    }
+    if (!fs.existsSync(full)) {
+      throw notFound(`Plugin manifest not found in repo: ${rel}`)
+    }
+    return { manifest: parseManifest(full), manifestPath: full }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+function resolveManifestFromInstalled(installed) {
+  const source = installed && installed.resolved_from
+  if (!source || typeof source !== "object") return null
+
+  if ((source.type === "path" || source.type === "registry") && source.manifest_path) {
+    if (!fs.existsSync(source.manifest_path)) return null
+    return {
+      manifest: parseManifest(source.manifest_path),
+      manifestPath: source.manifest_path,
+      source: source.type,
+    }
+  }
+
+  if (source.type === "git" && source.repo) {
+    const loaded = loadManifestFromGit(source.repo, source.ref, source.manifest_path)
+    return { ...loaded, source: "git" }
+  }
+
+  return null
+}
+
+function resolveManifestFromRegistry(name) {
+  const entry = getRegistryPlugin(name)
+  if (!entry) return null
+
+  const source = entry.source || {}
+  if ((source.type || "bundled") === "git") {
+    const loaded = loadManifestFromGit(source.repo, source.ref, source.manifest_path)
+    return { ...loaded, source: "registry-git" }
+  }
+
+  const manifestPath = source.manifest_path
+    ? path.resolve(__dirname, "..", source.manifest_path)
+    : resolveBundledManifestPath(name)
+  if (!fs.existsSync(manifestPath)) {
+    throw notFound(`Plugin manifest not found for '${name}'`)
+  }
+  return {
+    manifest: parseManifest(manifestPath),
+    manifestPath,
+    source: "registry-bundled",
+  }
+}
+
+function getPluginLearn(pluginName) {
+  const installed = getPlugin(pluginName)
+  const installedLoaded = installed ? resolveManifestFromInstalled(installed) : null
+  const loaded = installedLoaded || resolveManifestFromRegistry(pluginName)
+
+  if (!loaded) {
+    throw notFound(`Plugin '${pluginName}' not found`, ["Run: supercli plugins explore"])
+  }
+
+  const markdown = resolveLearnMarkdown(loaded.manifest, loaded.manifestPath)
+  return {
+    plugin: loaded.manifest.name || pluginName,
+    installed: !!installed,
+    source: loaded.source,
+    learn_markdown: markdown,
+  }
+}
+
+module.exports = {
+  getPluginLearn,
+  resolveLearnMarkdown,
+}

package/cli/plugins-manager.js

@@ -464,11 +464,14 @@ function installPlugin(ref, options = {}) {
     const existingKeysForSamePlugin = new Set((existing && existing.commands ? existing.commands : []).map(commandKey))
     const conflicts = []
     const installedCommands = []
+    const pluginDir = path.dirname(loaded.manifestPath)
 
     for (const cmd of manifest.commands) {
       const key = commandKey(cmd)
       const owner = ownerByKey[key]
       if ((!existingByKey[key] && !owner) || existingKeysForSamePlugin.has(key)) {
+        cmd.plugin_name = manifest.name
+        cmd.plugin_dir = pluginDir
         installedCommands.push(cmd)
         continue
       }

package/cli/plugins-registry.js

@@ -35,7 +35,8 @@ function normalizePlugin(entry) {
     name: entry.name,
     description: entry.description || "",
     tags: Array.isArray(entry.tags) ? entry.tags.map(t => String(t)) : [],
-    source: entry.source && typeof entry.source === "object" ? entry.source : {}
+    source: entry.source && typeof entry.source === "object" ? entry.source : {},
+    has_learn: entry.has_learn === true
   }
 }