superacli 1.13.0 → 1.15.0

package/docs/server.md

@@ -1,130 +0,0 @@
-# Server
-
-The supercli server provides a web UI for managing custom commands, OpenAPI specs, MCP servers, plugins, and viewing execution history.
-
-## Commands
-
-Create and manage custom commands through the server UI at `/commands`. Commands are indexed as `namespace.resource.action` and sync to the CLI via `sc sync`.
-
-### Shell Adapter
-
-The shell adapter executes bash scripts with argument interpolation. Use `{{variable}}` syntax to reference command arguments:
-
-```json
-{
-  "script": "echo 'Hello {{name}}'",
-  "timeout_ms": 5000,
-  "unsafe": true
-}
-```
-
-Arguments defined in the command schema are interpolated before execution. For example, with an argument named `name`:
-
-- Command: `sc system test foo --name Pedro`
-- Interpolated script: `echo 'Hello Pedro'`
-
-**Important:** Shell adapter requires `adapterConfig.unsafe=true` for security policy reasons.
-
-### Other Adapters
-
-- **http**: Raw HTTP requests with customizable method, headers, and body
-- **openapi**: Auto-generates commands from OpenAPI specifications
-- **mcp**: Exposes MCP server tools as commands
-- **process**: Spawns external processes with arguments
-- **custom**: User-defined JavaScript functions
-
-## OpenAPI
-
-Manage OpenAPI specifications at `/specs`. Upload OpenAPI/Swagger JSON or YAML files to auto-generate command definitions for all endpoints.
-
-## MCP
-
-Manage Model Context Protocol server connections at `/mcp`. Connect to MCP servers via SSE or stdio to expose their tools as supercli commands.
-
-### MCP Transport Modes
-
-The supercli MCP adapter supports multiple transport modes:
-
-#### HTTP/SSE MCP
-- Use `adapterConfig.url` for HTTP-based MCP servers
-- Supercli MCP adapter automatically supports SSE streaming
-- Sends `Accept: text/event-stream, application/json` header
-- Parses SSE responses and returns accumulated results
-- Uses JSON-RPC 2.0 format for requests
-
-Example configuration:
-```json
-{
-  "adapterConfig": {
-    "url": "http://localhost:3002",
-    "tool": "get_deep_directory_tree"
-  }
-}
-```
-
-#### Stdio MCP with Daemon
-- Use `adapterConfig.server` + `adapterConfig.stateful: true` for stdio MCPs
-- Best for local stdio MCP servers
-- Routes through MCP daemon for stateful stdio handling
-- **Daemon runs on CLI side** (not server) - starts on-demand when first command is executed via CLI
-- Daemon runs as detached background process with Unix socket at `~/.supercli/mcp-daemon.sock`
-- Persists across command executions to maintain MCP server sessions
-- Manual control: `supercli mcp daemon start/stop/status`
-
-Example configuration:
-```json
-{
-  "adapterConfig": {
-    "server": "deep-directory-tree",
-    "tool": "tool_name",
-    "stateful": true,
-    "timeout_ms": 60000
-  }
-}
-```
-
-#### Stdio MCP Direct
-- Use `adapterConfig.command` for direct stdio calls
-- May have compatibility issues with different MCP implementations
-
-### Using mcp-proxy with Supercli
-
-The mcp-proxy tool transforms stdio MCPs into HTTP/SSE. Here's how to use it:
-
-1. Start mcp-proxy:
-```bash
-npx -y mcp-proxy --port 3002 -- npx -y @andredezzy/deep-directory-tree-mcp
-```
-
-2. Add MCP server to supercli:
-```bash
-supercli server mcp add '{"name":"deep-tree","url":"http://localhost:3002"}'
-```
-
-3. Create command:
-```bash
-supercli server commands add '{"namespace":"tree","resource":"deep","action":"list","adapter":"mcp","adapterConfig":{"url":"http://localhost:3002","tool":"get_deep_directory_tree"}}'
-```
-
-4. Sync and use:
-```bash
-supercli sync
-supercli tree deep list --path /some/dir --depth 3
-```
-
-**Note:** Use space syntax for arguments: `--path /dir` not `--path=/dir`
-
-### MCP Adapter Features
-
-- **Auto-detection**: Automatically detects SSE responses and falls back to JSON
-- **JSON-RPC Support**: Uses JSON-RPC 2.0 format for HTTP MCP calls
-- **SSE Parsing**: Parses Server-Sent Events and accumulates results
-- **Stream Flag**: Reserved for future streaming output support (`--stream`)
-
-## Plugins
-
-Manage server plugins at `/plugins`. Upload plugin ZIP files, enable/disable plugins, and view plugin manifests. Server plugins extend CLI capabilities with custom commands and harnesses.
-
-## Jobs
-
-View command execution history at `/jobs`. Tracks all command executions with timestamps, duration, status, and output for debugging and observability.

package/docs/skills-catalog.md

@@ -1,133 +0,0 @@
-# Skill Documents Catalog
-
-SuperCLI can discover SKILL.md files from multiple local providers and expose them with stable `provider:id` identifiers.
-
-This catalog is for **skill documents** (agent instructions), not executable command capabilities. Executable capabilities are still discovered/executed via normal command routing (`supercli <namespace> <resource> <action>` and `supercli inspect ...`).
-
-## Provider Commands
-
-```bash
-supercli skills providers list --json
-supercli skills providers add --name mykb --type local_fs --roots /path/to/skills
-supercli skills providers show --name mykb --json
-supercli skills providers remove --name mykb --json
-```
-
-## Build Local Catalog
-
-```bash
-supercli skills sync --json
-```
-
-This scans enabled provider roots for `SKILL.md` files and rebuilds the local index.
-
-## Query Catalog Skill Documents
-
-```bash
-supercli skills list --catalog --json
-supercli skills search --query "planning" --json
-supercli skills get opencode:plan-changes
-```
-
-## Built-in MCP Usage Skill Document (Agent-Friendly)
-
-```bash
-supercli skills get mcp.servers.usage
-```
-
-This built-in skill document teaches non-human agents how to register, verify, and use MCP servers
-through SuperCLI, including a browser-use style `mcp-remote` SSE bridge pattern with
-runtime API-key passing.
-
-## Notes
-
-- IDs are always provider-qualified (`provider:id`) for future-proof disambiguation.
-- Current provider types include `local_fs`, `repo_fs`, and `remote_static`.
-- Existing capability-doc flow remains available (`skills list`, `skills get <ns.res.act>`, `skills teach`).
-
-## Remote Provider Example: agency-agents
-
-```bash
-supercli plugins install agency-agents --json
-supercli skills list --catalog --provider agency-agents --json
-supercli skills get agency-agents:engineering.engineering-frontend-developer
-```
-
-`agency-agents` maps skill documents one-to-one to upstream `.md` files in
-`msitarzewski/agency-agents`. If upstream paths change or files are removed,
-individual skill documents may stop resolving until reinstalled/refreshed.
-
-## Remote Provider Example: visual-explainer
-
-```bash
-supercli plugins install visual-explainer --json
-supercli skills list --catalog --provider visual-explainer --json
-supercli skills get visual-explainer:visual-explainer.skill
-```
-
-`visual-explainer` maps skill documents to normalized markdown files under
-`plugins/visual-explainer-normalized` in `javimosch/visual-explainer`.
-
-## Remote Provider Example: nullclaw
-
-```bash
-supercli plugins install nullclaw --json
-supercli skills list --catalog --provider nullclaw --json
-supercli skills get nullclaw:root.agents
-supercli skills get nullclaw:docs.en.commands
-```
-
-`nullclaw` indexes curated upstream markdown from `nullclaw/nullclaw` so agents can pull
-project overview, operator docs, security guidance, and implementation notes on demand.
-It also exposes the local `nullclaw` binary through wrapped commands and full passthrough.
-
-## Remote Provider Example: blogwatcher
-
-```bash
-supercli plugins install blogwatcher --json
-supercli skills list --catalog --provider blogwatcher --json
-supercli skills get blogwatcher:root.skill
-supercli skills get blogwatcher:root.readme
-```
-
-`blogwatcher` indexes the upstream `SKILL.md` and `README.md` from `Hyaxia/blogwatcher`
-so agents can learn the CLI workflow, storage model, and testing expectations on demand.
-It also exposes the local `blogwatcher` binary through wrapped commands and passthrough.
-
-## Remote Provider Example: xurl
-
-```bash
-supercli plugins install xurl --json
-supercli skills list --catalog --provider xurl --json
-supercli skills get xurl:root.skill
-supercli skills get xurl:root.readme
-```
-
-`xurl` indexes the upstream `SKILL.md` and `README.md` from `xdevplatform/xurl`
-so agents can learn safe X API workflows, auth constraints, and shortcut command patterns
-without reading local token storage. It also exposes curated read-only wrappers for the local
-`xurl` binary.
-
-## Remote Provider Example: clix
-
-```bash
-supercli plugins install clix --json
-supercli skills list --catalog --provider clix --json
-supercli skills get clix:root.skill
-supercli skills get clix:root.readme
-```
-
-`clix` indexes the upstream `SKILL.md` and `README.md` from `spideystreet/clix`
-so agents can learn safe cookie-auth X workflows, JSON usage, and agent-mode guidance.
-It also exposes curated read-only wrappers for the local `clix` binary.
-
-## Local Repo Skill Document Example: cline-non-interactive
-
-```bash
-supercli skills sync --json
-supercli skills list --catalog --provider repo --json
-supercli skills get repo:cline-non-interactive
-```
-
-`cline-non-interactive` is a repository-local skill document that teaches agents to prefer the wrapped
-`supercli cline task run` and `supercli cline task plan` commands for unattended Cline usage.

package/enhance-descriptions.ts

@@ -1,155 +0,0 @@
-#!/usr/bin/env bun
-import { readFileSync, writeFileSync } from "fs";
-import * as readline from "readline";
-
-interface Plugin {
-  name: string;
-  description: string;
-  tags: string[];
-  source: string;
-  installSteps: string[];
-}
-
-// AI suggestions based on name and tags
-function suggestDescription(plugin: Plugin): string {
-  const { name, tags, source } = plugin;
-  const tagStr = tags.slice(0, 3).join(", ");
-
-  // Pattern-based suggestions
-  const patterns: Record<string, (name: string) => string> = {
-    // Languages/Runtimes
-    "python": () => `Python — interpreted programming language with extensive libraries`,
-    "rust": () => `Rust — systems programming language emphasizing safety and performance`,
-    "go": () => `Go — compiled language designed for simplicity and concurrency`,
-    "javascript": () => `JavaScript — versatile language for web and server development`,
-    "bash": () => `Bash — POSIX shell interpreter and command language`,
-    "zsh": () => `Zsh — advanced shell with scripting capabilities`,
-
-    // Development Tools
-    "git": () => `Git — distributed version control system for code management`,
-    "docker": () => `Docker — containerization platform for application deployment`,
-    "kubernetes": () => `Kubernetes — container orchestration for scalable deployments`,
-
-    // Data Tools
-    "database": () => `Database tool for querying and managing data`,
-    "sql": () => `SQL query tool for relational database operations`,
-
-    // Productivity
-    "task": () => `Task management tool for organizing work and projects`,
-    "note": () => `Note-taking application for capturing and organizing information`,
-  };
-
-  // Try to match tags
-  for (const tag of tags) {
-    if (patterns[tag]) {
-      return patterns[tag](name);
-    }
-  }
-
-  // Fallback: Use tags to construct description
-  if (tags.length > 0) {
-    return `${name} — ${tags[0]} tool for ${tags.slice(1, 3).join(" and ")}`;
-  }
-
-  return `${name} — command-line tool with features and capabilities`;
-}
-
-async function createInterface() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-}
-
-async function askQuestion(rl: readline.Interface, question: string): Promise<string> {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      resolve(answer.trim());
-    });
-  });
-}
-
-async function main() {
-  console.log("📝 Plugin Description Enhancer");
-  console.log("=============================\n");
-
-  // Load plugins
-  const plugins: Plugin[] = JSON.parse(readFileSync("marketing/plugins-dump.json", "utf-8"));
-  const shortDesc = plugins.filter((p) => (p.description || "").length < 30);
-
-  console.log(`Found ${shortDesc.length} plugins with short descriptions (< 30 chars)\n`);
-
-  if (shortDesc.length === 0) {
-    console.log("✓ All plugins have adequate descriptions!");
-    process.exit(0);
-  }
-
-  const rl = await createInterface();
-
-  let enhanced = 0;
-  let skipped = 0;
-  const updates: Map<string, string> = new Map();
-
-  for (let i = 0; i < shortDesc.length; i++) {
-    const plugin = shortDesc[i];
-    const suggestion = suggestDescription(plugin);
-
-    console.log(`\n[${i + 1}/${shortDesc.length}] ${plugin.name}`);
-    console.log(`Tags: ${plugin.tags.join(", ")}`);
-    console.log(`Source: ${plugin.source}`);
-    console.log(`Current: "${plugin.description}" (${plugin.description.length} chars)`);
-    console.log(`Suggested: "${suggestion}" (${suggestion.length} chars)`);
-
-    const response = await askQuestion(rl, "\n(a)ccept / (e)dit / (s)kip / (q)uit? ");
-
-    if (response.toLowerCase() === "q") {
-      console.log("\nStopping enhancement...");
-      break;
-    }
-
-    if (response.toLowerCase() === "s") {
-      skipped++;
-      continue;
-    }
-
-    if (response.toLowerCase() === "a") {
-      updates.set(plugin.name, suggestion);
-      enhanced++;
-      console.log("✓ Accepted");
-    } else if (response.toLowerCase() === "e") {
-      const custom = await askQuestion(rl, "Enter new description: ");
-      if (custom.length >= 30) {
-        updates.set(plugin.name, custom);
-        enhanced++;
-        console.log("✓ Custom description saved");
-      } else {
-        console.log("⚠ Description too short (< 30 chars), skipped");
-        skipped++;
-      }
-    }
-  }
-
-  // Apply updates
-  if (updates.size > 0) {
-    console.log(`\n✅ Applying ${updates.size} description updates...`);
-
-    for (const plugin of plugins) {
-      if (updates.has(plugin.name)) {
-        plugin.description = updates.get(plugin.name)!;
-      }
-    }
-
-    writeFileSync("marketing/plugins-dump.json", JSON.stringify(plugins, null, 2));
-    console.log("✓ plugins-dump.json updated");
-  }
-
-  console.log(`\n📊 Summary`);
-  console.log(`==========`);
-  console.log(`Enhanced: ${enhanced}`);
-  console.log(`Skipped: ${skipped}`);
-  console.log(`Remaining: ${shortDesc.length - enhanced - skipped}`);
-
-  rl.close();
-}
-
-main().catch(console.error);

package/examples/mcp-sse/install-demo.js

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const os = require("os");
-const path = require("path");
-
-const CACHE_DIR = path.join(os.homedir(), ".supercli");
-const CACHE_FILE = path.join(CACHE_DIR, "config.json");
-const MCP_NAME = "summarize-sse";
-const MCP_URL = process.env.MCP_SSE_URL || "http://127.0.0.1:8787";
-
-function ensureDir(dir) {
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-}
-
-function readConfig() {
-  if (!fs.existsSync(CACHE_FILE)) {
-    return {
-      version: "1",
-      ttl: 3600,
-      mcp_servers: [],
-      specs: [],
-      commands: [],
-    };
-  }
-  try {
-    return JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
-  } catch {
-    return {
-      version: "1",
-      ttl: 3600,
-      mcp_servers: [],
-      specs: [],
-      commands: [],
-    };
-  }
-}
-
-function upsertBy(arr, predicate, value) {
-  const idx = arr.findIndex(predicate);
-  if (idx >= 0) arr[idx] = value;
-  else arr.push(value);
-}
-
-function main() {
-  ensureDir(CACHE_DIR);
-  const config = readConfig();
-  if (!Array.isArray(config.commands)) config.commands = [];
-  if (!Array.isArray(config.mcp_servers)) config.mcp_servers = [];
-  if (!Array.isArray(config.specs)) config.specs = [];
-
-  upsertBy(config.mcp_servers, (s) => s && s.name === MCP_NAME, {
-    name: MCP_NAME,
-    url: MCP_URL,
-  });
-
-  upsertBy(
-    config.commands,
-    (c) =>
-      c &&
-      c.namespace === "ai" &&
-      c.resource === "text" &&
-      c.action === "summarize_remote",
-    {
-      _id: "command:ai.text.summarize_remote",
-      namespace: "ai",
-      resource: "text",
-      action: "summarize_remote",
-      description: "Mock summarize via remote MCP SSE/HTTP server",
-      adapter: "mcp",
-      adapterConfig: {
-        server: MCP_NAME,
-        tool: "summarize",
-      },
-      args: [{ name: "text", type: "string", required: true }],
-    },
-  );
-
-  config.fetchedAt = Date.now();
-  fs.writeFileSync(CACHE_FILE, JSON.stringify(config, null, 2));
-  process.stdout.write(
-    `Installed remote demo command ai.text.summarize_remote and MCP '${MCP_NAME}' in ${CACHE_FILE}\n`,
-  );
-}
-
-main();

package/examples/mcp-sse/server.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-const http = require("http")
-
-const PORT = Number(process.env.MCP_SSE_PORT || 8787)
-const clients = new Set()
-
-function summarize(text) {
-  const normalized = String(text || "").trim().replace(/\s+/g, " ")
-  if (!normalized) return ""
-  const words = normalized.split(" ")
-  if (words.length <= 12) return normalized
-  return words.slice(0, 12).join(" ") + " ..."
-}
-
-function broadcast(event, data) {
-  const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
-  for (const res of clients) {
-    res.write(payload)
-  }
-}
-
-const server = http.createServer((req, res) => {
-  if (req.method === "GET" && req.url === "/events") {
-    res.writeHead(200, {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive"
-    })
-    res.write("event: ready\ndata: {\"ok\":true}\n\n")
-    clients.add(res)
-    req.on("close", () => clients.delete(res))
-    return
-  }
-
-  if (req.method === "POST" && req.url === "/tool") {
-    let raw = ""
-    req.setEncoding("utf-8")
-    req.on("data", chunk => { raw += chunk })
-    req.on("end", () => {
-      let payload
-      try {
-        payload = JSON.parse(raw || "{}")
-      } catch {
-        res.writeHead(400, { "Content-Type": "application/json" })
-        res.end(JSON.stringify({ error: "Invalid JSON body" }))
-        return
-      }
-
-      const tool = payload.tool
-      const input = payload.input || {}
-      if (tool !== "summarize") {
-        res.writeHead(404, { "Content-Type": "application/json" })
-        res.end(JSON.stringify({ error: `Unknown tool: ${tool}` }))
-        return
-      }
-
-      broadcast("tool_called", { tool, input })
-      const result = summarize(input.text)
-      const out = {
-        tool,
-        mode: "sse-http",
-        result,
-        words_in: String(input.text || "").trim() ? String(input.text).trim().split(/\s+/).length : 0,
-        words_out: result ? result.split(/\s+/).length : 0
-      }
-      broadcast("tool_done", out)
-      res.writeHead(200, { "Content-Type": "application/json" })
-      res.end(JSON.stringify(out))
-    })
-    return
-  }
-
-  res.writeHead(404, { "Content-Type": "application/json" })
-  res.end(JSON.stringify({ error: "Not found" }))
-})
-
-server.listen(PORT, "127.0.0.1", () => {
-  console.log(`MCP SSE demo server listening on http://127.0.0.1:${PORT}`)
-  console.log("Endpoints: POST /tool, GET /events")
-})

package/examples/mcp-stdio/install-demo.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const os = require("os");
-const path = require("path");
-
-const CACHE_DIR = path.join(os.homedir(), ".supercli");
-const CACHE_FILE = path.join(CACHE_DIR, "config.json");
-const ROOT = path.resolve(__dirname, "..", "..");
-const SERVER_SCRIPT = path.join(ROOT, "examples", "mcp-stdio", "server.js");
-
-function ensureDir(dir) {
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-}
-
-function readConfig() {
-  if (!fs.existsSync(CACHE_FILE)) {
-    return {
-      version: "1",
-      ttl: 3600,
-      mcp_servers: [],
-      specs: [],
-      commands: [],
-    };
-  }
-  try {
-    return JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
-  } catch {
-    return {
-      version: "1",
-      ttl: 3600,
-      mcp_servers: [],
-      specs: [],
-      commands: [],
-    };
-  }
-}
-
-function upsertCommand(config, command) {
-  const idx = config.commands.findIndex(
-    (c) =>
-      c.namespace === command.namespace &&
-      c.resource === command.resource &&
-      c.action === command.action,
-  );
-  if (idx >= 0) config.commands[idx] = command;
-  else config.commands.push(command);
-}
-
-function main() {
-  ensureDir(CACHE_DIR);
-  const config = readConfig();
-  if (!Array.isArray(config.commands)) config.commands = [];
-  if (!Array.isArray(config.mcp_servers)) config.mcp_servers = [];
-  if (!Array.isArray(config.specs)) config.specs = [];
-
-  upsertCommand(config, {
-    _id: "command:ai.text.summarize",
-    namespace: "ai",
-    resource: "text",
-    action: "summarize",
-    description: "Mock summarize using local stdio MCP server",
-    adapter: "mcp",
-    adapterConfig: {
-      tool: "summarize",
-      command: `node ${SERVER_SCRIPT}`,
-    },
-    args: [{ name: "text", type: "string", required: true }],
-  });
-
-  config.fetchedAt = Date.now();
-  fs.writeFileSync(CACHE_FILE, JSON.stringify(config, null, 2));
-  process.stdout.write(
-    `Installed demo command ai.text.summarize in ${CACHE_FILE}\n`,
-  );
-}
-
-main();