superacli 1.0.0

package/.env.example

@@ -0,0 +1,14 @@
+# Storage Configuration
+# Set to "true" to use MongoDB, otherwise uses local JSON files
+SUPERCLI_USE_MONGO=false
+SUPERCLI_STORAGE_DIR=./supercli_storage
+
+# MongoDB connection (only used if SUPERCLI_USE_MONGO=true)
+MONGO_URL=mongodb://127.0.0.1:27017
+SUPERCLI_DB=supercli
+
+# Server port
+PORT=3000
+
+# CLI server URL (used by CLI runtime)
+SUPERCLI_SERVER=http://127.0.0.1:3000

package/README.md

@@ -0,0 +1,173 @@
+# SuperCLI
+
+Config-driven, AI-friendly CLI that dynamically generates commands from cloud configuration.
+
+## Architecture
+
+```
+         Web UI (EJS + Vue3 + DaisyUI)
+                    │
+                REST API
+                    │
+           NodeJS + MongoDB
+                    │
+              CLI Runtime
+                    │
+          ┌────────┼────────┐
+       OpenAPI    HTTP     MCP
+       Adapter   Adapter  Adapter
+```
+
+## Quick Start
+
+```bash
+# Quick usage (no install, local-only by default)
+npx supercli help
+npx supercli skills teach
+
+# Install
+npm install
+
+# Configure (copy and edit)
+cp .env.example .env
+
+# Start server (defaults to local JSON files, no MongoDB required!)
+npm start
+# Or alternatively, start via CLI:
+# supercli --server
+
+# Open Web UI
+open http://localhost:3000
+
+# CLI usage
+node cli/supercli.js help
+node cli/supercli.js commands
+node cli/supercli.js <namespace> <resource> <action> [--args]
+
+# Optional: sync commands from a remote SuperCLI server
+export SUPERCLI_SERVER=http://localhost:3000
+node cli/supercli.js sync
+```
+
+## CLI Usage
+
+```bash
+# Discovery
+supercli help                              # List namespaces
+supercli <namespace>                       # List resources
+supercli <namespace> <resource>            # List actions
+
+# Inspection
+supercli inspect <ns> <res> <act>          # Command details + schema
+supercli <ns> <res> <act> --schema         # Input/output schema
+
+# Execution
+supercli <ns> <res> <act> --arg value      # Execute command
+supercli <ns> <res> <act> --compact        # Token-optimized output
+
+# Plans (DAG)
+supercli plan <ns> <res> <act> [--args]    # Dry-run execution plan
+supercli execute <plan_id>                 # Execute stored plan
+
+# Skills (LLM bootstrap)
+supercli skills list --json                # Minimal skill metadata (name, description)
+supercli skills get <ns.res.act>           # Emit SKILL.md (default format)
+supercli skills teach                      # Emit starter meta-skill (default format)
+supercli skills get <ns.res.act> --show-dag
+
+# Natural Language (AI)
+export OPENAI_BASE_URL=https://api.openai.com/v1     # Enable local AI resolution
+supercli ask "list the posts and summarize them"         # Execute natural language queries
+
+# Config & Server
+supercli sync                              # Sync local cache from SUPERCLI_SERVER (when set)
+supercli config show                       # Show cache info
+supercli --server                          # Start the SuperCLI backend server directly
+
+# Local MCP registry (no server required)
+supercli mcp list
+supercli mcp add summarize-local --url http://127.0.0.1:8787
+supercli mcp remove summarize-local
+
+# Stdio MCP demo (no server required)
+node examples/mcp-stdio/install-demo.js
+supercli ai text summarize --text "Hello world" --json
+
+# Remote MCP SSE/HTTP demo
+node examples/mcp-sse/server.js
+node examples/mcp-sse/install-demo.js
+supercli ai text summarize_remote --text "Hello world" --json
+
+# Agent capability discovery
+supercli --help-json                       # Machine-readable capabilities
+```
+
+## Output Modes
+
+| Flag        | Output                                    |
+|-------------|-------------------------------------------|
+| (default)   | JSON if piped, human-readable if TTY      |
+| `--json`    | Structured JSON envelope                  |
+| `--human`   | Formatted tables and key-value output     |
+| `--compact` | Compressed JSON (shortened keys)          |
+
+## Output Envelope
+
+Every command returns a deterministic envelope:
+
+```json
+{
+  "version": "1.0",
+  "command": "namespace.resource.action",
+  "duration_ms": 42,
+  "data": { ... }
+}
+```
+
+## Exit Codes
+
+| Code    | Type                | Action                     |
+|---------|---------------------|----------------------------|
+| 0       | success             | Proceed                    |
+| 82      | validation_error    | Fix input                  |
+| 85      | invalid_argument    | Fix argument               |
+| 92      | resource_not_found  | Try different resource     |
+| 105     | integration_error   | Retry with backoff         |
+| 110     | internal_error      | Report bug                 |
+
+## API Endpoints
+
+| Method | Endpoint                      | Description              |
+|--------|-------------------------------|--------------------------|
+| GET    | `/api/config`                 | Full CLI config          |
+| GET    | `/api/tree`                   | List namespaces          |
+| GET    | `/api/tree/:ns`               | List resources           |
+| GET    | `/api/tree/:ns/:res`          | List actions             |
+| GET    | `/api/command/:ns/:res/:act`  | Full command spec        |
+| CRUD   | `/api/commands`               | Manage commands          |
+| CRUD   | `/api/specs`                  | Manage OpenAPI specs     |
+| CRUD   | `/api/mcp`                    | Manage MCP servers       |
+| CRUD   | `/api/plans`                  | Execution plans          |
+| GET    | `/api/jobs`                   | Execution history        |
+| GET    | `/api/jobs/stats`             | Aggregate stats          |
+
+## Adapters
+
+- **http** — Raw HTTP requests (method, url, headers)
+- **openapi** — Resolves operation from OpenAPI spec
+- **mcp** — Calls MCP server tools (supports both HTTP endpoints and local Stdio processes)
+
+## Tech Stack
+
+- NodeJS + Express
+- Pluggable KV Storage (Local JSON files by default, MongoDB optional)
+- EJS + Vue3 CDN + Tailwind CDN + DaisyUI CDN
+- Zero build tools
+
+## Contributors
+
+Contributions are welcome! If you have ideas for improvements, new adapters, or bug fixes, just send a Pull Request (PR) and I will review it.
+
+## License
+
+MIT

package/cli/adapters/http.js

@@ -0,0 +1,72 @@
+// HTTP Adapter
+// Raw HTTP calls based on adapterConfig: method, url, headers, body
+
+async function execute(cmd, flags, context) {
+  const config = cmd.adapterConfig || {}
+  let url = config.url
+  let method = (config.method || "GET").toUpperCase()
+  const headers = { ...(config.headers || {}) }
+
+  if (!url) {
+    throw new Error("HTTP adapter requires 'url' in adapterConfig")
+  }
+
+  // Replace {param} placeholders in URL with flag values
+  for (const [k, v] of Object.entries(flags)) {
+    if (["human", "json", "compact"].includes(k)) continue
+    url = url.replace(`{${k}}`, encodeURIComponent(v))
+  }
+
+  // Build query string from flags for GET requests
+  if (method === "GET") {
+    const queryFlags = Object.entries(flags).filter(([k]) =>
+      !["human", "json", "compact"].includes(k) && !url.includes(encodeURIComponent(flags[k]))
+    )
+    if (queryFlags.length > 0 && !url.includes("?")) {
+      // Only add flags that weren't used as path params
+      const remaining = queryFlags.filter(([k]) => !config.url.includes(`{${k}}`))
+      if (remaining.length > 0) {
+        url += "?" + remaining.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&")
+      }
+    }
+  }
+
+  const fetchOpts = { method, headers }
+
+  // Build body for non-GET methods
+  if (["POST", "PUT", "PATCH"].includes(method)) {
+    if (config.body) {
+      fetchOpts.body = JSON.stringify(config.body)
+    } else {
+      const bodyObj = {}
+      for (const [k, v] of Object.entries(flags)) {
+        if (!["human", "json", "compact"].includes(k)) {
+          bodyObj[k] = v
+        }
+      }
+      if (Object.keys(bodyObj).length > 0) {
+        fetchOpts.body = JSON.stringify(bodyObj)
+        headers["Content-Type"] = "application/json"
+      }
+    }
+  }
+
+  const r = await fetch(url, fetchOpts)
+
+  if (!r.ok) {
+    const text = await r.text().catch(() => "")
+    throw Object.assign(new Error(`HTTP request failed: ${r.status} ${r.statusText} ${text}`), {
+      code: r.status >= 500 ? 105 : 92,
+      type: r.status >= 500 ? "integration_error" : "resource_not_found",
+      recoverable: r.status >= 500
+    })
+  }
+
+  const contentType = r.headers.get("content-type") || ""
+  if (contentType.includes("json")) {
+    return r.json()
+  }
+  return { raw: await r.text() }
+}
+
+module.exports = { execute }

package/cli/adapters/mcp.js

@@ -0,0 +1,193 @@
+// MCP Adapter
+// Supports HTTP MCP endpoints and local stdio MCP commands.
+
+const { spawn } = require("child_process");
+
+async function callStdioTool(command, args, payload, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args || [], {
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: !Array.isArray(args) || args.length === 0,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(
+        Object.assign(
+          new Error(`MCP stdio call timed out after ${timeoutMs}ms`),
+          {
+            code: 105,
+            type: "integration_error",
+            recoverable: true,
+          },
+        ),
+      );
+    }, timeoutMs);
+
+    child.stdout.setEncoding("utf-8");
+    child.stderr.setEncoding("utf-8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(
+        Object.assign(
+          new Error(`Failed to start MCP stdio command: ${err.message}`),
+          {
+            code: 105,
+            type: "integration_error",
+            recoverable: true,
+          },
+        ),
+      );
+    });
+
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(
+          Object.assign(
+            new Error(
+              `MCP stdio command exited with code ${code}: ${stderr.trim()}`,
+            ),
+            {
+              code: 105,
+              type: "integration_error",
+              recoverable: true,
+            },
+          ),
+        );
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout.trim()));
+      } catch {
+        reject(
+          Object.assign(
+            new Error(`MCP stdio response is not valid JSON: ${stdout.trim()}`),
+            {
+              code: 105,
+              type: "integration_error",
+              recoverable: true,
+            },
+          ),
+        );
+      }
+    });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}
+
+async function resolveHttpServerUrl(config, context) {
+  if (config.url) return config.url;
+
+  if (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 (context.server) {
+    const r = await fetch(`${context.server}/api/mcp?format=json`);
+    if (!r.ok) {
+      throw Object.assign(
+        new Error(`Failed to fetch MCP servers list: ${r.status}`),
+        {
+          code: 105,
+          type: "integration_error",
+          recoverable: true,
+        },
+      );
+    }
+    const servers = await r.json();
+    const srv = servers.find((s) => s.name === config.server);
+    if (srv) return srv.url;
+  }
+
+  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`,
+    ),
+    {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false,
+    },
+  );
+}
+
+async function execute(cmd, flags, context) {
+  const config = cmd.adapterConfig || {};
+  const toolName = config.tool;
+  const hasHttpSource = !!(config.server || config.url);
+  const hasStdioSource = !!config.command;
+
+  if (!toolName || (!hasHttpSource && !hasStdioSource)) {
+    throw new Error(
+      "MCP adapter requires 'tool' and one of: 'server', 'url', or 'command' in adapterConfig",
+    );
+  }
+
+  const input = {};
+  for (const [k, v] of Object.entries(flags)) {
+    if (!["human", "json", "compact"].includes(k)) {
+      input[k] = v;
+    }
+  }
+
+  if (hasStdioSource) {
+    const commandArgs = Array.isArray(config.commandArgs)
+      ? config.commandArgs
+      : [];
+    const timeoutMs =
+      Number(config.timeout_ms) > 0 ? Number(config.timeout_ms) : 10000;
+    return callStdioTool(
+      config.command,
+      commandArgs,
+      { tool: toolName, input },
+      timeoutMs,
+    );
+  }
+
+  const resolvedUrl = await resolveHttpServerUrl(config, context);
+  const toolUrl = resolvedUrl.replace(/\/+$/, "");
+  const tr = await fetch(`${toolUrl}/tool`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ tool: toolName, input }),
+  });
+
+  if (!tr.ok) {
+    const text = await tr.text().catch(() => "");
+    throw Object.assign(
+      new Error(`MCP tool call failed: ${tr.status} ${text}`),
+      {
+        code: 105,
+        type: "integration_error",
+        recoverable: true,
+      },
+    );
+  }
+
+  return tr.json();
+}
+
+module.exports = { execute };

package/cli/adapters/openapi.js

@@ -0,0 +1,160 @@
+// OpenAPI Adapter
+// Fetches spec, resolves operation by operationId, builds URL, executes HTTP call
+
+const specCache = {};
+
+async function fetchSpec(specName, context) {
+  if (specCache[specName]) return specCache[specName];
+
+  const localSpecs =
+    context.config && Array.isArray(context.config.specs)
+      ? context.config.specs
+      : [];
+  const localSpec = localSpecs.find((s) => s && s.name === specName);
+  if (localSpec) {
+    const sr = await fetch(localSpec.url);
+    if (!sr.ok)
+      throw new Error(
+        `Failed to fetch OpenAPI spec from ${localSpec.url}: ${sr.status}`,
+      );
+    const specDoc = await sr.json();
+    specCache[specName] = { ...specDoc, _auth: localSpec.auth };
+    return specCache[specName];
+  }
+
+  if (!context.server) {
+    throw Object.assign(
+      new Error(
+        `OpenAPI spec '${specName}' not found in local config. Run supercli sync to load specs.`,
+      ),
+      {
+        code: 85,
+        type: "invalid_argument",
+        recoverable: false,
+      },
+    );
+  }
+
+  // Fetch spec URL from server
+  const r = await fetch(`${context.server}/api/specs?format=json`);
+  if (!r.ok) throw new Error(`Failed to fetch specs list: ${r.status}`);
+  const specs = await r.json();
+  const spec = specs.find((s) => s.name === specName);
+  if (!spec) throw new Error(`OpenAPI spec '${specName}' not found`);
+
+  // Fetch the actual OpenAPI spec
+  const sr = await fetch(spec.url);
+  if (!sr.ok)
+    throw new Error(
+      `Failed to fetch OpenAPI spec from ${spec.url}: ${sr.status}`,
+    );
+  const specDoc = await sr.json();
+  specCache[specName] = { ...specDoc, _auth: spec.auth };
+  return specCache[specName];
+}
+
+function findOperation(spec, operationId) {
+  const paths = spec.paths || {};
+  for (const [pathStr, methods] of Object.entries(paths)) {
+    for (const [method, op] of Object.entries(methods)) {
+      if (op.operationId === operationId) {
+        return { path: pathStr, method: method.toUpperCase(), operation: op };
+      }
+    }
+  }
+  throw new Error(`Operation '${operationId}' not found in spec`);
+}
+
+function buildUrl(baseUrl, pathStr, method, operation, flags) {
+  let url = pathStr;
+
+  // Replace path parameters
+  const pathParams = (operation.parameters || []).filter(
+    (p) => p.in === "path",
+  );
+  for (const p of pathParams) {
+    if (flags[p.name] !== undefined) {
+      url = url.replace(`{${p.name}}`, encodeURIComponent(flags[p.name]));
+    }
+  }
+
+  // Build query parameters
+  const queryParams = (operation.parameters || []).filter(
+    (p) => p.in === "query",
+  );
+  const query = [];
+  for (const p of queryParams) {
+    if (flags[p.name] !== undefined) {
+      query.push(
+        `${encodeURIComponent(p.name)}=${encodeURIComponent(flags[p.name])}`,
+      );
+    }
+  }
+
+  let fullUrl = baseUrl.replace(/\/+$/, "") + url;
+  if (query.length > 0) {
+    fullUrl += "?" + query.join("&");
+  }
+  return { url: fullUrl, method };
+}
+
+async function execute(cmd, flags, context) {
+  const config = cmd.adapterConfig || {};
+  const specName = config.spec;
+  const operationId = config.operationId;
+
+  if (!specName || !operationId) {
+    throw new Error(
+      "OpenAPI adapter requires 'spec' and 'operationId' in adapterConfig",
+    );
+  }
+
+  const spec = await fetchSpec(specName, context);
+  const { path: pathStr, method, operation } = findOperation(spec, operationId);
+
+  // Determine base URL from spec
+  const baseUrl =
+    (spec.servers && spec.servers[0] && spec.servers[0].url) || "";
+  const { url, method: httpMethod } = buildUrl(
+    baseUrl,
+    pathStr,
+    method,
+    operation,
+    flags,
+  );
+
+  const fetchOpts = { method: httpMethod, headers: {} };
+
+  // Handle request body for POST/PUT/PATCH
+  if (["POST", "PUT", "PATCH"].includes(httpMethod)) {
+    const bodyObj = {};
+    for (const [k, v] of Object.entries(flags)) {
+      if (!["human", "json", "compact"].includes(k)) {
+        bodyObj[k] = v;
+      }
+    }
+    fetchOpts.body = JSON.stringify(bodyObj);
+    fetchOpts.headers["Content-Type"] = "application/json";
+  }
+
+  const r = await fetch(url, fetchOpts);
+  if (!r.ok) {
+    const text = await r.text().catch(() => "");
+    throw Object.assign(
+      new Error(`API call failed: ${r.status} ${r.statusText} ${text}`),
+      {
+        code: r.status >= 500 ? 105 : 92,
+        type: r.status >= 500 ? "integration_error" : "resource_not_found",
+        recoverable: r.status >= 500,
+      },
+    );
+  }
+
+  const contentType = r.headers.get("content-type") || "";
+  if (contentType.includes("json")) {
+    return r.json();
+  }
+  return { raw: await r.text() };
+}
+
+module.exports = { execute };