superacli 1.1.2 → 1.1.4

package/__tests__/xurl-plugin.test.js

@@ -0,0 +1,176 @@
+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")
+
+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('/SKILL.md')) { console.log('---\\nname: xurl\\ndescription: Test skill\\n---\\n# xurl Skill'); process.exit(0); }",
+    "if (url.endsWith('/README.md')) { console.log('# xurl\\n\\nTest readme.'); process.exit(0); }",
+    "console.error(`unsupported url: ${url}`);",
+    "process.exit(22);"
+  ].join("\n"), "utf-8")
+  fs.chmodSync(bin, 0o755)
+  return bin
+}
+
+function writeFakeXurlBinary(dir) {
+  const bin = path.join(dir, "xurl")
+  fs.writeFileSync(bin, [
+    "#!/usr/bin/env node",
+    "const args = process.argv.slice(2);",
+    "const emitJson = value => {",
+    "  const payload = JSON.stringify(value);",
+    "  if (process.env.NO_COLOR === '1') console.log(payload);",
+    "  else console.log(`\\u001b[32m${payload}\\u001b[0m`);",
+    "  process.exit(0);",
+    "};",
+    "if (args[0] === 'version') { console.log('xurl 1.0.3-test'); process.exit(0); }",
+    "if (args[0] === 'auth' && args[1] === 'status') { console.log('▸ my-app  [client_id: abc123…]'); process.exit(0); }",
+    "if (args[0] === 'auth' && args[1] === 'apps' && args[2] === 'list') { console.log('▸ my-app (client_id: abc123…)'); process.exit(0); }",
+    "if (args[0] === 'whoami') emitJson({ data: { id: '42', username: 'tester' } });",
+    "if (args[0] === 'user') emitJson({ data: { id: '84', username: args[1].replace(/^@/, '') } });",
+    "if (args[0] === 'read') emitJson({ data: { id: '123', text: 'hello world', ref: args[1] } });",
+    "if (args[0] === 'search') emitJson({ data: [{ id: '1', text: args[1] }] });",
+    "if (args[0] === 'timeline') emitJson({ data: [{ id: '2', text: 'timeline item' }] });",
+    "if (args[0] === 'mentions') emitJson({ data: [{ id: '3', text: 'mention item' }] });",
+    "if (args[0] === 'followers') emitJson({ data: [{ username: args.includes('--of') ? args[args.indexOf('--of') + 1] : 'alice' }] });",
+    "if (args[0] === 'following') emitJson({ data: [{ username: args.includes('--of') ? args[args.indexOf('--of') + 1] : 'bob' }] });",
+    "emitJson({ ok: true, args });"
+  ].join("\n"), "utf-8")
+  fs.chmodSync(bin, 0o755)
+  return bin
+}
+
+describe("xurl hybrid plugin", () => {
+  const fakeDir = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-xurl-"))
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-home-xurl-"))
+  writeFakeCurlBinary(fakeDir)
+  writeFakeXurlBinary(fakeDir)
+  const env = { ...process.env, PATH: `${fakeDir}:${process.env.PATH || ""}`, SUPERCLI_HOME: tempHome }
+  let removed = false
+
+  beforeAll(() => {
+    const install = runNoServer("plugins install ./plugins/xurl --on-conflict replace --json", { env })
+    expect(install.ok).toBe(true)
+  })
+
+  afterAll(() => {
+    if (!removed) runNoServer("plugins remove xurl --json", { env })
+    fs.rmSync(fakeDir, { recursive: true, force: true })
+    fs.rmSync(tempHome, { recursive: true, force: true })
+  })
+
+  test("indexes xurl skills provider", () => {
+    const provider = runNoServer("skills providers show --name xurl --json", { env })
+    expect(provider.ok).toBe(true)
+    expect(JSON.parse(provider.output).provider.name).toBe("xurl")
+
+    const list = runNoServer("skills list --catalog --provider xurl --json", { env })
+    expect(list.ok).toBe(true)
+    const listData = JSON.parse(list.output)
+    expect(listData.skills.some(skill => skill.id === "xurl:root.skill")).toBe(true)
+    expect(listData.skills.some(skill => skill.id === "xurl:root.readme")).toBe(true)
+  })
+
+  test("fetches indexed remote skill markdown", () => {
+    const skill = runNoServer("skills get xurl:root.skill", { env })
+    expect(skill.ok).toBe(true)
+    expect(skill.output).toContain("xurl Skill")
+  })
+
+  test("routes wrapped raw and parsed commands", () => {
+    const version = runNoServer("xurl cli version --json", { env })
+    expect(version.ok).toBe(true)
+    expect(JSON.parse(version.output).data.raw).toBe("xurl 1.0.3-test")
+
+    const status = runNoServer("xurl auth status --json", { env })
+    expect(status.ok).toBe(true)
+    expect(JSON.parse(status.output).data.raw).toContain("my-app")
+
+    const apps = runNoServer("xurl apps list --json", { env })
+    expect(apps.ok).toBe(true)
+    expect(JSON.parse(apps.output).data.raw).toContain("my-app")
+
+    const whoami = runNoServer("xurl account whoami --json", { env })
+    expect(whoami.ok).toBe(true)
+    expect(JSON.parse(whoami.output).data.data.username).toBe("tester")
+
+    const user = runNoServer("xurl users show --target @XDevelopers --json", { env })
+    expect(user.ok).toBe(true)
+    expect(JSON.parse(user.output).data.data.username).toBe("XDevelopers")
+
+    const read = runNoServer("xurl posts show --target 1234567890 --json", { env })
+    expect(read.ok).toBe(true)
+    expect(JSON.parse(read.output).data.data.ref).toBe("1234567890")
+
+    const search = runNoServer("xurl posts search --query \"from:XDevelopers\" --max-results 10 --json", { env })
+    expect(search.ok).toBe(true)
+    expect(JSON.parse(search.output).data.data[0].text).toBe("from:XDevelopers")
+  })
+
+  test("routes timeline mentions and social wrappers", () => {
+    const timeline = runNoServer("xurl timeline list --max-results 10 --json", { env })
+    expect(timeline.ok).toBe(true)
+    expect(JSON.parse(timeline.output).data.data[0].text).toBe("timeline item")
+
+    const mentions = runNoServer("xurl mentions list --max-results 10 --json", { env })
+    expect(mentions.ok).toBe(true)
+    expect(JSON.parse(mentions.output).data.data[0].text).toBe("mention item")
+
+    const followers = runNoServer("xurl social followers --of XDevelopers --max-results 20 --json", { env })
+    expect(followers.ok).toBe(true)
+    expect(JSON.parse(followers.output).data.data[0].username).toBe("XDevelopers")
+
+    const following = runNoServer("xurl social following --of XDevelopers --max-results 20 --json", { env })
+    expect(following.ok).toBe(true)
+    expect(JSON.parse(following.output).data.data[0].username).toBe("XDevelopers")
+  })
+
+  test("does not expose passthrough and reports dependencies as healthy", () => {
+    const manifest = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "plugins", "xurl", "plugin.json"), "utf-8"))
+    expect(manifest.commands.some(command => command.resource === "_" && command.action === "_")).toBe(false)
+
+    const doctor = runNoServer("plugins doctor xurl --json", { env })
+    expect(doctor.ok).toBe(true)
+    const doctorData = JSON.parse(doctor.output)
+    expect(doctorData.checks.some(c => c.type === "binary" && c.binary === "curl" && c.ok === true)).toBe(true)
+    expect(doctorData.checks.some(c => c.type === "binary" && c.binary === "xurl" && c.ok === true)).toBe(true)
+  })
+
+  test("removal cleans up the skills provider", () => {
+    const remove = runNoServer("plugins remove xurl --json", { env })
+    expect(remove.ok).toBe(true)
+    removed = true
+
+    const provider = runNoServer("skills providers show --name xurl --json", { env })
+    expect(provider.ok).toBe(false)
+  })
+})

package/cli/adapter-schema.js

@@ -69,6 +69,13 @@ function validateAdapterConfig(cmd) {
     if (!config.tool || typeof config.tool !== "string") throw asInvalid("MCP adapter requires adapterConfig.tool")
     const sources = [config.server, config.url, config.command].filter(Boolean)
     if (sources.length === 0) throw asInvalid("MCP adapter requires one source: adapterConfig.server, adapterConfig.url, or adapterConfig.command")
+    if (config.server !== undefined && typeof config.server !== "string") throw asInvalid("adapterConfig.server must be string")
+    if (config.url !== undefined && typeof config.url !== "string") throw asInvalid("adapterConfig.url must be string")
+    if (config.command !== undefined && typeof config.command !== "string") throw asInvalid("adapterConfig.command must be string")
+    if (config.args !== undefined && !Array.isArray(config.args)) throw asInvalid("adapterConfig.args must be an array")
+    if (config.commandArgs !== undefined && !Array.isArray(config.commandArgs)) throw asInvalid("adapterConfig.commandArgs must be an array")
+    if (config.headers !== undefined && (typeof config.headers !== "object" || Array.isArray(config.headers))) throw asInvalid("adapterConfig.headers must be object")
+    if (config.env !== undefined && (typeof config.env !== "object" || Array.isArray(config.env))) throw asInvalid("adapterConfig.env must be object")
     return
   }
 

package/cli/adapters/mcp.js

@@ -3,11 +3,63 @@
 
 const { spawn } = require("child_process");
 
-async function callStdioTool(command, args, payload, timeoutMs) {
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+}
+
+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;
+  }
+  return out;
+}
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string");
+}
+
+function mergeMcpConfig(cmdConfig, serverEntry) {
+  const mergedHeaders = {
+    ...asStringMap(serverEntry && serverEntry.headers),
+    ...asStringMap(cmdConfig.headers),
+  };
+  const mergedEnv = {
+    ...asStringMap(serverEntry && serverEntry.env),
+    ...asStringMap(cmdConfig.env),
+  };
+  const mergedArgs = [
+    ...asStringArray(serverEntry && serverEntry.args),
+    ...asStringArray(serverEntry && serverEntry.commandArgs),
+    ...asStringArray(cmdConfig.args),
+    ...asStringArray(cmdConfig.commandArgs),
+  ];
+
+  return {
+    tool: cmdConfig.tool,
+    server: cmdConfig.server,
+    url: cmdConfig.url || (serverEntry && serverEntry.url),
+    command: cmdConfig.command || (serverEntry && serverEntry.command),
+    timeout_ms:
+      cmdConfig.timeout_ms !== undefined
+        ? cmdConfig.timeout_ms
+        : serverEntry && serverEntry.timeout_ms,
+    headers: mergedHeaders,
+    env: mergedEnv,
+    args: mergedArgs,
+  };
+}
+
+async function callStdioTool(command, args, payload, timeoutMs, env) {
   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,
     });
 
     let stdout = "";
@@ -95,17 +147,15 @@ async function callStdioTool(command, args, payload, timeoutMs) {
   });
 }
 
-async function resolveHttpServerUrl(config, context) {
-  if (config.url) return config.url;
-
-  if (context.config && Array.isArray(context.config.mcp_servers)) {
+async function resolveServerEntry(config, context) {
+  if (config.server && context.config && Array.isArray(context.config.mcp_servers)) {
     const local = context.config.mcp_servers.find(
       (s) => s && s.name === config.server,
     );
-    if (local) return local.url;
+    if (local) return local;
   }
 
-  if (context.server) {
+  if (config.server && context.server) {
     const r = await fetch(`${context.server}/api/mcp?format=json`);
     if (!r.ok) {
       throw Object.assign(
@@ -118,10 +168,12 @@ async function resolveHttpServerUrl(config, context) {
       );
     }
     const servers = await r.json();
-    const srv = servers.find((s) => s.name === config.server);
-    if (srv) return srv.url;
+    const srv = servers.find((s) => s && s.name === config.server);
+    if (srv) return srv;
   }
 
+  if (config.url || config.command) return {};
+
   throw Object.assign(
     new Error(
       `MCP server '${config.server}' not found in local config. Add one with: supercli mcp add ${config.server} --url <mcp_url> or run supercli sync`,
@@ -135,17 +187,23 @@ async function resolveHttpServerUrl(config, context) {
 }
 
 async function execute(cmd, flags, context) {
-  const config = cmd.adapterConfig || {};
-  const toolName = config.tool;
-  const hasHttpSource = !!(config.server || config.url);
-  const hasStdioSource = !!config.command;
+  const cmdConfig = cmd.adapterConfig || {};
+  const toolName = cmdConfig.tool;
+  const hasDeclaredSource = !!(cmdConfig.server || cmdConfig.url || cmdConfig.command);
 
-  if (!toolName || (!hasHttpSource && !hasStdioSource)) {
+  if (!toolName || !hasDeclaredSource) {
     throw new Error(
       "MCP adapter requires 'tool' and one of: 'server', 'url', or 'command' in adapterConfig",
     );
   }
 
+  const serverEntry = cmdConfig.server
+    ? await resolveServerEntry(cmdConfig, context)
+    : {};
+  const config = mergeMcpConfig(cmdConfig, serverEntry);
+  const hasStdioSource = !!config.command;
+  const hasHttpSource = !!config.url;
+
   const input = {};
   for (const [k, v] of Object.entries(flags)) {
     if (!["human", "json", "compact"].includes(k)) {
@@ -154,9 +212,7 @@ async function execute(cmd, flags, context) {
   }
 
   if (hasStdioSource) {
-    const commandArgs = Array.isArray(config.commandArgs)
-      ? config.commandArgs
-      : [];
+    const commandArgs = Array.isArray(config.args) ? config.args : [];
     const timeoutMs =
       Number(config.timeout_ms) > 0 ? Number(config.timeout_ms) : 10000;
     return callStdioTool(
@@ -164,14 +220,20 @@ async function execute(cmd, flags, context) {
       commandArgs,
       { tool: toolName, input },
       timeoutMs,
+      config.env,
+    );
+  }
+
+  if (!hasHttpSource) {
+    throw new Error(
+      "MCP adapter could not resolve a source. Define adapterConfig.url/command or configure the named server with url/command.",
     );
   }
 
-  const resolvedUrl = await resolveHttpServerUrl(config, context);
-  const toolUrl = resolvedUrl.replace(/\/+$/, "");
+  const toolUrl = config.url.replace(/\/+$/, "");
   const tr = await fetch(`${toolUrl}/tool`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...(config.headers || {}) },
     body: JSON.stringify({ tool: toolName, input }),
   });
 

package/cli/config.js

@@ -16,7 +16,8 @@ function readCache() {
   try {
     if (fs.existsSync(CACHE_FILE)) {
       const raw = fs.readFileSync(CACHE_FILE, "utf-8")
-      return JSON.parse(raw)
+      const parsed = JSON.parse(raw)
+      return normalizeConfig(parsed)
     }
   } catch (e) {
     // Corrupted cache, ignore
@@ -24,10 +25,60 @@ function readCache() {
   return null
 }
 
+function normalizeMcpServerEntry(name, entry) {
+  if (!name || typeof name !== "string") return null
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null
+  const out = { name }
+  if (typeof entry.url === "string") out.url = entry.url
+  if (typeof entry.command === "string") out.command = entry.command
+  if (Array.isArray(entry.args)) out.args = entry.args.filter(v => typeof v === "string")
+  if (Array.isArray(entry.commandArgs)) out.commandArgs = entry.commandArgs.filter(v => typeof v === "string")
+  if (entry.headers && typeof entry.headers === "object" && !Array.isArray(entry.headers)) {
+    out.headers = Object.fromEntries(Object.entries(entry.headers).filter(([k, v]) => typeof k === "string" && typeof v === "string"))
+  }
+  if (entry.env && typeof entry.env === "object" && !Array.isArray(entry.env)) {
+    out.env = Object.fromEntries(Object.entries(entry.env).filter(([k, v]) => typeof k === "string" && typeof v === "string"))
+  }
+  if (typeof entry.timeout_ms === "number" && entry.timeout_ms > 0) out.timeout_ms = entry.timeout_ms
+  return out
+}
+
+function normalizeMcpServers(config) {
+  const out = []
+  const byName = new Map()
+
+  if (config && config.mcpServers && typeof config.mcpServers === "object" && !Array.isArray(config.mcpServers)) {
+    for (const [name, value] of Object.entries(config.mcpServers)) {
+      const normalized = normalizeMcpServerEntry(name, value)
+      if (normalized) byName.set(name, normalized)
+    }
+  }
+
+  if (Array.isArray(config && config.mcp_servers)) {
+    for (const entry of config.mcp_servers) {
+      if (!entry || typeof entry !== "object") continue
+      const normalized = normalizeMcpServerEntry(entry.name, entry)
+      if (normalized) byName.set(normalized.name, normalized)
+    }
+  }
+
+  for (const value of byName.values()) out.push(value)
+  out.sort((a, b) => a.name.localeCompare(b.name))
+  return out
+}
+
+function normalizeConfig(config) {
+  const base = config && typeof config === "object" ? { ...config } : emptyConfig()
+  base.mcp_servers = normalizeMcpServers(base)
+  if (!Array.isArray(base.specs)) base.specs = []
+  if (!Array.isArray(base.commands)) base.commands = []
+  return base
+}
+
 function writeCache(config) {
   ensureCacheDir()
   const data = {
-    ...config,
+    ...normalizeConfig(config),
     fetchedAt: Date.now()
   }
   fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2))
@@ -85,19 +136,25 @@ async function syncConfig(server) {
   }
 
   if (!Array.isArray(config.commands)) config.commands = []
-  return writeCache(config)
+  return writeCache(normalizeConfig(config))
 }
 
-async function setMcpServer(name, url) {
+async function setMcpServer(name, value) {
   const cfg = readCache() || emptyConfig()
   const servers = Array.isArray(cfg.mcp_servers) ? cfg.mcp_servers.slice() : []
   const idx = servers.findIndex(s => s && s.name === name)
-  const next = { name, url }
+  const incoming = typeof value === "string" ? { url: value } : (value && typeof value === "object" ? value : {})
+  const next = normalizeMcpServerEntry(name, { name, ...incoming })
+  if (!next) {
+    throw Object.assign(new Error("Invalid MCP server definition"), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
   if (idx >= 0) servers[idx] = next
   else servers.push(next)
-  cfg.mcp_servers = servers
-    .filter(s => s && typeof s.name === "string")
-    .sort((a, b) => a.name.localeCompare(b.name))
+  cfg.mcp_servers = normalizeMcpServers({ mcp_servers: servers })
   return writeCache(cfg)
 }
 

package/cli/mcp-local.js

@@ -10,8 +10,25 @@ async function handleMcpRegistryCommand(options) {
     removeMcpServer,
     listMcpServers,
   } = options;
+  const cliFlags = flags || {};
 
   const subcommand = positional[1];
+
+  function parseJsonFlag(name, raw) {
+    if (raw === undefined) return undefined;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: `Invalid JSON for --${name}`,
+        recoverable: false,
+      });
+      return null;
+    }
+  }
+
   if (subcommand === "list") {
     const servers = await listMcpServers();
     if (humanMode) {
@@ -29,17 +46,46 @@ async function handleMcpRegistryCommand(options) {
 
   if (subcommand === "add") {
     const name = positional[2];
-    const url = flags.url;
-    if (!name || !url) {
+    const url = cliFlags.url;
+    const command = cliFlags.command;
+
+    if (!name || (!url && !command)) {
       outputError({
         code: 85,
         type: "invalid_argument",
-        message: "Usage: supercli mcp add <name> --url <mcp_url>",
+        message:
+          "Usage: supercli mcp add <name> (--url <mcp_url> | --command <binary>) [--args-json '[]'] [--headers-json '{}'] [--env-json '{}'] [--timeout-ms <ms>]",
         recoverable: false,
       });
       return true;
     }
-    await setMcpServer(name, url);
+
+    const args = parseJsonFlag("args-json", cliFlags["args-json"]);
+    if (args === null) return true;
+    const headers = parseJsonFlag("headers-json", cliFlags["headers-json"]);
+    if (headers === null) return true;
+    const env = parseJsonFlag("env-json", cliFlags["env-json"]);
+    if (env === null) return true;
+    const timeoutMs =
+      cliFlags["timeout-ms"] !== undefined ? Number(cliFlags["timeout-ms"]) : undefined;
+    if (cliFlags["timeout-ms"] !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: "--timeout-ms must be a positive number",
+        recoverable: false,
+      });
+      return true;
+    }
+
+    await setMcpServer(name, {
+      url,
+      command,
+      args,
+      headers,
+      env,
+      timeout_ms: timeoutMs,
+    });
     output({ ok: true, message: `MCP server '${name}' saved locally` });
     return true;
   }

package/cli/plugin-install-guidance.js

@@ -256,6 +256,106 @@ const PLUGIN_INSTALL_GUIDANCE = {
     ],
     note: "Install cargo-nextest with prebuilt binaries or cargo. Most commands are intended for Rust workspaces, but version and help commands work anywhere."
   },
+  mysql: {
+    plugin: "mysql",
+    binary: "mysql",
+    check: "mysql --version",
+    install_steps: [
+      "mysql --version",
+      "supercli plugins install mysql",
+      "supercli mysql cli version --json",
+      "supercli mysql query execute --execute \"select 1\" --host 127.0.0.1 --user root --database mysql --json"
+    ],
+    note: "Install the MySQL client with your platform package manager. The wrapped query command is tuned for batch output and works best when connection settings come from flags or standard MySQL environment variables like MYSQL_HOST, MYSQL_USER, MYSQL_DATABASE, and MYSQL_PWD."
+  },
+  mongosh: {
+    plugin: "mongosh",
+    binary: "mongosh",
+    check: "mongosh --version",
+    install_steps: [
+      "mongosh --version",
+      "supercli plugins install mongosh",
+      "supercli mongosh cli version --json",
+      "supercli mongosh server ping --host 127.0.0.1 --port 27017 --json",
+      "supercli mongosh eval run --javascript \"db.adminCommand({ ping: 1 })\" --json"
+    ],
+    note: "This plugin targets the current mongosh shell rather than the legacy mongo shell. Wrapped commands prefer relaxed JSON output for automation, while raw passthrough remains available for connection-string-based flows."
+  },
+  blogwatcher: {
+    plugin: "blogwatcher",
+    binary: "blogwatcher",
+    check: "blogwatcher --version",
+    install_steps: [
+      "brew install Hyaxia/tap/blogwatcher",
+      "go install github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest",
+      "blogwatcher --version",
+      "supercli plugins install blogwatcher",
+      "supercli skills list --catalog --provider blogwatcher --json",
+      "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."
+  },
+  himalaya: {
+    plugin: "himalaya",
+    binary: "himalaya",
+    check: "himalaya --version",
+    install_steps: [
+      "brew install himalaya",
+      "cargo install himalaya --locked",
+      "himalaya --version",
+      "supercli plugins install himalaya",
+      "supercli himalaya account list --json",
+      "supercli himalaya folder list --account personal --json",
+      "supercli himalaya envelope list --account personal --folder INBOX --page 1 --json"
+    ],
+    note: "Prefer the wrapped read-only commands for automation. Himalaya itself uses --output json rather than --json, and interactive or write-side flows like account configure, message send, and mailbox mutation are intentionally left out of wrapped v1."
+  },
+  wacli: {
+    plugin: "wacli",
+    binary: "wacli",
+    check: "wacli --version",
+    install_steps: [
+      "brew install steipete/tap/wacli",
+      "go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli",
+      "wacli --version",
+      "supercli plugins install wacli",
+      "supercli wacli doctor run --json",
+      "supercli wacli auth status --json",
+      "supercli wacli chats list --store ~/.wacli --json"
+    ],
+    note: "This plugin intentionally wraps only read-only diagnostics and local-store inspection commands. Use the upstream wacli CLI directly for QR auth, sync loops, sending messages, media download, and group/contact mutations."
+  },
+  xurl: {
+    plugin: "xurl",
+    binary: "xurl",
+    check: "xurl version",
+    install_steps: [
+      "brew install --cask xdevplatform/tap/xurl",
+      "npm install -g @xdevplatform/xurl",
+      "go install github.com/xdevplatform/xurl@latest",
+      "xurl version",
+      "supercli plugins install xurl",
+      "supercli skills list --catalog --provider xurl --json",
+      "supercli xurl auth status --json",
+      "supercli xurl account whoami --json"
+    ],
+    note: "This hybrid plugin indexes upstream xurl docs and exposes a curated set of read-only wrappers. Use the upstream xurl CLI directly for auth setup, posting, likes, follows, raw requests, streams, webhooks, and any command that can mutate X state."
+  },
+  clix: {
+    plugin: "clix",
+    binary: "clix",
+    check: "clix auth status --json",
+    install_steps: [
+      "uv pip install clix0",
+      "clix auth",
+      "supercli plugins install clix",
+      "supercli skills list --catalog --provider clix --json",
+      "supercli clix auth status --json",
+      "supercli clix timeline list --count 10 --json"
+    ],
+    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."
+  },
   cline: {
     plugin: "cline",
     binary: "cline",