superacli 1.0.0

package/cli/ask.js

@@ -0,0 +1,208 @@
+const { execute } = require("./executor");
+
+async function localLLMCompletion(query, config, baseUrl, model, apiKey) {
+  const namespaces = [...new Set(config.commands.map((c) => c.namespace))];
+  const allDefs = [];
+
+  for (const ns of namespaces) {
+    const resources = [
+      ...new Set(
+        config.commands
+          .filter((c) => c.namespace === ns)
+          .map((c) => c.resource),
+      ),
+    ];
+    for (const res of resources) {
+      const actions = config.commands
+        .filter((c) => c.namespace === ns && c.resource === res)
+        .map((c) => c.action);
+      for (const act of actions) {
+        const cmd = config.commands.find(
+          (c) => c.namespace === ns && c.resource === res && c.action === act,
+        );
+        if (!cmd) continue;
+        const argList = (cmd.args || [])
+          .map((a) => `--${a.name}${a.required ? " (required)" : ""}`)
+          .join(" ");
+        allDefs.push(
+          `- ${ns} ${res} ${act} ${argList} : ${cmd.description || "no desc"}`,
+        );
+      }
+    }
+  }
+
+  const systemPrompt = `You are an AI CLI assistant router.
+Available commands:
+${allDefs.join("\n")}
+
+The user wants to accomplish a goal. Map their goal into a sequence of CLI commands to run.
+Respond STRICTLY with a valid JSON array of steps. For example:
+[
+  { "command": "aws.instances.list", "args": { "region": "us-east-1" } },
+  { "command": "ai.summarize.text", "args": { "text": "{{step.0.data.summary}}" } }
+]
+Do not wrap it in markdown. Do not include any other text.`;
+
+  const r = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: query },
+      ],
+      temperature: 0,
+    }),
+  });
+
+  if (!r.ok) {
+    const txt = await r.text();
+    throw new Error(`Local LLM Error ${r.status}: ${txt}`);
+  }
+
+  const data = await r.json();
+  const content =
+    data.choices &&
+    data.choices[0] &&
+    data.choices[0].message &&
+    data.choices[0].message.content;
+  if (!content) throw new Error("Invalid response format from local LLM");
+
+  let jsonStr = content.trim();
+  if (jsonStr.startsWith("```json"))
+    jsonStr = jsonStr
+      .replace(/^```json/, "")
+      .replace(/```$/, "")
+      .trim();
+  else if (jsonStr.startsWith("```"))
+    jsonStr = jsonStr.replace(/^```/, "").replace(/```$/, "").trim();
+
+  const steps = JSON.parse(jsonStr);
+  if (!Array.isArray(steps)) throw new Error("LLM did not return a JSON array");
+  return steps;
+}
+
+async function remoteLLMCompletion(query, serverUrl) {
+  const r = await fetch(`${serverUrl}/api/ask`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query }),
+  });
+
+  if (!r.ok) {
+    const errorBody = await r.json().catch(() => ({}));
+    throw new Error(
+      `Server LLM completion failed: ${errorBody.error || r.statusText}`,
+    );
+  }
+
+  const data = await r.json();
+  return data.steps;
+}
+
+async function handleAskCommand({
+  positional,
+  config,
+  context,
+  humanMode,
+  output,
+  outputError,
+}) {
+  if (positional.length < 2) {
+    outputError({
+      code: 85,
+      type: "invalid_argument",
+      message: 'Usage: supercli ask "<your natural language query>"',
+      recoverable: false,
+    });
+    return;
+  }
+
+  const query = positional.slice(1).join(" ");
+  const hasLocalLLM = !!process.env.OPENAI_BASE_URL;
+  const hasServerLLM = context.server && config.features && config.features.ask;
+
+  if (!hasLocalLLM && !hasServerLLM) {
+    outputError({
+      code: 105,
+      type: "integration_error",
+      message:
+        "The 'ask' feature is not configured. Export OPENAI_BASE_URL locally or ensure the SUPERCLI_SERVER has it configured.",
+      recoverable: false,
+    });
+    return;
+  }
+
+  if (humanMode) {
+    console.log(
+      `\n  🤖 Thinking... (${hasLocalLLM ? "local" : "server"} resolution)`,
+    );
+  }
+
+  try {
+    let steps = [];
+    if (hasLocalLLM) {
+      steps = await localLLMCompletion(
+        query,
+        config,
+        process.env.OPENAI_BASE_URL,
+        process.env.OPENAI_MODEL || "gpt-3.5-turbo",
+        process.env.OPENAI_API_KEY || "dummy",
+      );
+    } else {
+      steps = await remoteLLMCompletion(query, context.server);
+    }
+
+    if (humanMode) {
+      console.log(`  📋 Plan:`);
+      steps.forEach((s, i) => {
+        const argStr = Object.entries(s.args || {})
+          .map(([k, v]) => `--${k}="${v}"`)
+          .join(" ");
+        console.log(`    ${i + 1}. ${s.command.replace(/\./g, " ")} ${argStr}`);
+      });
+      console.log(`\n  ▶ Executing...`);
+    }
+
+    // Map to a virtual workflow command and execute
+    const virtualCommand = {
+      namespace: "system",
+      resource: "ai",
+      action: "ask",
+      type: "workflow",
+      adapterConfig: { steps },
+    };
+
+    const start = Date.now();
+    const result = await execute(virtualCommand, {}, context);
+    const duration = Date.now() - start;
+
+    const envelope = {
+      version: "1.0",
+      command: "ask",
+      duration_ms: duration,
+      data: result,
+    };
+
+    if (!humanMode) {
+      output(envelope);
+    } else {
+      console.log(`\n  ✅ Success (${duration}ms)\n`);
+      console.log(JSON.stringify(envelope.data, null, 2));
+      console.log("");
+    }
+  } catch (err) {
+    outputError({
+      code: 105,
+      type: "integration_error",
+      message: err.message,
+      recoverable: true,
+    });
+  }
+}
+
+module.exports = { handleAskCommand };

package/cli/config.js

@@ -0,0 +1,133 @@
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+const CACHE_DIR = path.join(os.homedir(), ".supercli")
+const CACHE_FILE = path.join(CACHE_DIR, "config.json")
+
+function ensureCacheDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true })
+  }
+}
+
+function readCache() {
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      const raw = fs.readFileSync(CACHE_FILE, "utf-8")
+      return JSON.parse(raw)
+    }
+  } catch (e) {
+    // Corrupted cache, ignore
+  }
+  return null
+}
+
+function writeCache(config) {
+  ensureCacheDir()
+  const data = {
+    ...config,
+    fetchedAt: Date.now()
+  }
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2))
+  return data
+}
+
+function ttlValid(cache) {
+  if (!cache || !cache.fetchedAt) return false
+  const ttl = (cache.ttl || 3600) * 1000
+  return (Date.now() - cache.fetchedAt) < ttl
+}
+
+async function fetchRemoteConfig(server) {
+  if (!server) throw new Error("SUPERCLI_SERVER is not configured")
+  const url = `${server}/api/config`
+  const r = await fetch(url)
+  if (!r.ok) throw new Error(`Failed to fetch config: ${r.status} ${r.statusText}`)
+  return r.json()
+}
+
+function emptyConfig() {
+  return {
+    version: "1",
+    ttl: 3600,
+    mcp_servers: [],
+    specs: [],
+    commands: []
+  }
+}
+
+async function loadConfig() {
+  const cache = readCache()
+  if (cache) return cache
+  return emptyConfig()
+}
+
+async function syncConfig(server) {
+  const config = await fetchRemoteConfig(server)
+
+  if (!Array.isArray(config.mcp_servers)) {
+    try {
+      const mcpRes = await fetch(`${server}/api/mcp?format=json`)
+      config.mcp_servers = mcpRes.ok ? await mcpRes.json() : []
+    } catch {
+      config.mcp_servers = []
+    }
+  }
+
+  if (!Array.isArray(config.specs)) {
+    try {
+      const specsRes = await fetch(`${server}/api/specs?format=json`)
+      config.specs = specsRes.ok ? await specsRes.json() : []
+    } catch {
+      config.specs = []
+    }
+  }
+
+  if (!Array.isArray(config.commands)) config.commands = []
+  return writeCache(config)
+}
+
+async function setMcpServer(name, url) {
+  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 }
+  if (idx >= 0) servers[idx] = next
+  else servers.push(next)
+  cfg.mcp_servers = servers.sort((a, b) => a.name.localeCompare(b.name))
+  return writeCache(cfg)
+}
+
+async function removeMcpServer(name) {
+  const cfg = readCache() || emptyConfig()
+  const servers = Array.isArray(cfg.mcp_servers) ? cfg.mcp_servers : []
+  const next = servers.filter(s => s && s.name !== name)
+  const removed = next.length !== servers.length
+  cfg.mcp_servers = next
+  writeCache(cfg)
+  return removed
+}
+
+async function listMcpServers() {
+  const cfg = await loadConfig()
+  return Array.isArray(cfg.mcp_servers) ? cfg.mcp_servers : []
+}
+
+async function showConfig() {
+  const cache = readCache()
+  if (!cache) {
+    return { cached: false, message: "No config cached. Set SUPERCLI_SERVER and run: supercli sync" }
+  }
+  return {
+    version: cache.version,
+    ttl: cache.ttl,
+    fetchedAt: new Date(cache.fetchedAt).toISOString(),
+    commands: cache.commands ? cache.commands.length : 0,
+    mcp_servers: cache.mcp_servers ? cache.mcp_servers.length : 0,
+    specs: cache.specs ? cache.specs.length : 0,
+    cacheFile: CACHE_FILE
+  }
+}
+
+module.exports = { loadConfig, syncConfig, showConfig, setMcpServer, removeMcpServer, listMcpServers }

package/cli/executor.js

@@ -0,0 +1,117 @@
+const path = require("path")
+
+// Adapter registry — lazy-loaded
+const ADAPTERS = {
+  openapi: () => require("./adapters/openapi"),
+  mcp: () => require("./adapters/mcp"),
+  http: () => require("./adapters/http")
+}
+
+async function execute(cmd, flags, context) {
+  // Workflow commands: execute steps sequentially
+  const steps = cmd.type === "workflow" ? (cmd.steps || (cmd.adapterConfig && cmd.adapterConfig.steps) || []) : null
+  if (cmd.type === "workflow" && steps && steps.length > 0) {
+    return executeWorkflow(cmd, flags, context, steps)
+  }
+
+  const adapterName = cmd.adapter
+
+  if (!ADAPTERS[adapterName]) {
+    try {
+      const custom = require(path.resolve("adapters", adapterName))
+      return custom.execute(cmd, flags, context)
+    } catch (e) {
+      throw Object.assign(new Error(`Unknown adapter: ${adapterName}`), {
+        code: 110,
+        type: "internal_error",
+        recoverable: false
+      })
+    }
+  }
+
+  const adapter = ADAPTERS[adapterName]()
+  return adapter.execute(cmd, flags, context)
+}
+
+async function executeWorkflow(workflow, flags, context, steps) {
+  const results = []
+  let prevOutput = null
+
+  for (const stepDef of steps) {
+    let stepCommandString = ""
+    let stepArgs = {}
+
+    if (typeof stepDef === "string") {
+      stepCommandString = stepDef
+    } else if (typeof stepDef === "object") {
+      stepCommandString = stepDef.command
+      stepArgs = stepDef.args || {}
+    }
+
+    let parts = stepCommandString.includes(".") ? stepCommandString.split(".") : stepCommandString.split(" ")
+    parts = parts.filter(p => !p.startsWith("-"))
+    if (parts.length < 3) {
+      throw Object.assign(new Error(`Invalid workflow step: ${stepCommandString}`), {
+        code: 85, type: "invalid_argument", recoverable: false
+      })
+    }
+    const [ns, resource, action] = parts
+
+    let stepCmd = null
+    if (context.config && Array.isArray(context.config.commands)) {
+      stepCmd = context.config.commands.find(c => c.namespace === ns && c.resource === resource && c.action === action)
+    }
+
+    if (!stepCmd) {
+      if (!context.server) {
+        throw Object.assign(new Error(`Workflow step command not found in local config and server is unavailable: ${stepCommandString}`), {
+          code: 92, type: "resource_not_found", recoverable: false
+        })
+      }
+      const r = await fetch(`${context.server}/api/command/${ns}/${resource}/${action}`)
+      if (!r.ok) {
+        throw Object.assign(new Error(`Workflow step command not found: ${stepCommandString}`), {
+          code: 92, type: "resource_not_found", recoverable: false
+        })
+      }
+      stepCmd = await r.json()
+    }
+
+    // Merge flags + explicit step args + previous output as context
+    const mergedFlags = { ...flags, ...stepArgs }
+    if (prevOutput && typeof prevOutput === "object") {
+      for (const [k, v] of Object.entries(prevOutput)) {
+        if (mergedFlags[k] === undefined && typeof v !== "object") {
+          mergedFlags[k] = v
+        }
+      }
+    }
+
+    // Note: Template replacement (e.g. "{{step.0.data.summary}}") handling should ideally be done here.
+    // For simplicity, doing a basic string replace for known vars on string arguments.
+    for (const [k, v] of Object.entries(mergedFlags)) {
+      if (typeof v === "string") {
+        mergedFlags[k] = v.replace(/\{\{args\.([^}]+)\}\}/g, (_, path) => flags[path] || "")
+        mergedFlags[k] = mergedFlags[k].replace(/\{\{step\.(\d+)\.([^}]+)\}\}/g, (_, idx, path) => {
+          const res = results[Number(idx)]
+          if (!res) return ""
+          // Simple dot path resolution for data...
+          let val = res
+          for (const p of path.split(".")) {
+            if (val && typeof val === "object") val = val[p]
+            else { val = ""; break; }
+          }
+          return val || ""
+        })
+      }
+    }
+
+    const result = await module.exports.execute(stepCmd, mergedFlags, context)
+    results.push({ step: stepCommandString, result })
+    prevOutput = result
+  }
+
+  return { workflow: workflow.namespace + "." + workflow.resource + "." + workflow.action, steps: results }
+}
+
+module.exports = { execute }

package/cli/help-json.js

@@ -0,0 +1,46 @@
+function buildCapabilities(config, hasServer) {
+  const commands = {
+    help: { description: "List namespaces and commands" },
+    config: { subcommands: ["show"] },
+    mcp: { subcommands: ["list", "add", "remove"], description: "Manage local MCP server registry" },
+    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]" },
+    execute: { description: "Execute a stored plan", usage: "supercli execute <plan_id>" },
+    skills: {
+      description: "Skill discovery and SKILL.md generation",
+      subcommands: ["list", "get", "teach"]
+    }
+  }
+  if (hasServer) commands.sync = { description: "Sync local config from SUPERCLI_SERVER" }
+  if (config.features?.ask || process.env.OPENAI_BASE_URL) commands.ask = { description: "Execute natural language queries", usage: "supercli ask \"<query>\"" }
+
+  return {
+    version: "1.0",
+    name: "supercli",
+    description: "Config-driven, AI-friendly dynamic CLI",
+    commands,
+    namespaces: [...new Set((config.commands || []).map(c => c.namespace))],
+    total_commands: (config.commands || []).length,
+    output_formats: ["json", "human", "compact"],
+    flags: {
+      "--json": "Force JSON output",
+      "--human": "Force human-readable output",
+      "--compact": "Compressed JSON for token optimization",
+      "--schema": "Show input/output schema for a command",
+      "--help-json": "Machine-readable capability discovery",
+      "--show-dag": "Include execution DAG in output",
+      "--format": "Output format for selected commands"
+    },
+    exit_codes: {
+      "0": "success",
+      "82": "validation_error",
+      "85": "invalid_argument",
+      "92": "resource_not_found",
+      "105": "integration_error",
+      "110": "internal_error"
+    }
+  }
+}
+
+module.exports = { buildCapabilities }

package/cli/mcp-local.js

@@ -0,0 +1,72 @@
+async function handleMcpRegistryCommand(options) {
+  const {
+    positional,
+    flags,
+    humanMode,
+    output,
+    outputHumanTable,
+    outputError,
+    setMcpServer,
+    removeMcpServer,
+    listMcpServers,
+  } = options;
+
+  const subcommand = positional[1];
+  if (subcommand === "list") {
+    const servers = await listMcpServers();
+    if (humanMode) {
+      console.log("\n  ⚡ Local MCP Servers\n");
+      outputHumanTable(servers, [
+        { key: "name", label: "Name" },
+        { key: "url", label: "URL" },
+      ]);
+      console.log("");
+    } else {
+      output({ mcp_servers: servers });
+    }
+    return true;
+  }
+
+  if (subcommand === "add") {
+    const name = positional[2];
+    const url = flags.url;
+    if (!name || !url) {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: "Usage: supercli mcp add <name> --url <mcp_url>",
+        recoverable: false,
+      });
+      return true;
+    }
+    await setMcpServer(name, url);
+    output({ ok: true, message: `MCP server '${name}' saved locally` });
+    return true;
+  }
+
+  if (subcommand === "remove") {
+    const name = positional[2];
+    if (!name) {
+      outputError({
+        code: 85,
+        type: "invalid_argument",
+        message: "Usage: supercli mcp remove <name>",
+        recoverable: false,
+      });
+      return true;
+    }
+    const removed = await removeMcpServer(name);
+    output({ ok: true, removed });
+    return true;
+  }
+
+  outputError({
+    code: 85,
+    type: "invalid_argument",
+    message: "Unknown mcp subcommand. Use: list, add, remove",
+    recoverable: false,
+  });
+  return true;
+}
+
+module.exports = { handleMcpRegistryCommand };

package/cli/plan-runtime.js

@@ -0,0 +1,32 @@
+const { createPlan } = require("./planner")
+
+function buildLocalPlan(cmd, args) {
+  return {
+    ...createPlan(cmd, args),
+    persisted: false,
+    execution_mode: "local"
+  }
+}
+
+function annotateServerPlan(plan) {
+  return {
+    ...plan,
+    persisted: true,
+    execution_mode: "server"
+  }
+}
+
+function outputHumanPlan(plan) {
+  console.log(`\n  ⚡ Execution Plan: ${plan.plan_id}\n`)
+  console.log(`  Command: ${plan.command}`)
+  console.log(`  Risk:    ${plan.risk_level}`)
+  console.log(`  Side effects: ${plan.side_effects ? "yes" : "no"}`)
+  console.log(`  Persisted: ${plan.persisted ? "yes" : "no"}`)
+  console.log("\n  Steps:")
+  plan.steps.forEach((s, i) => console.log(`    ${i + 1}. [${s.type}] ${s.description || s.method || ""} ${s.url || ""}`))
+  if (plan.persisted) console.log(`\n  Execute: supercli execute ${plan.plan_id}`)
+  else console.log("\n  Execute: local plan preview only (set SUPERCLI_SERVER for persisted execute)")
+  console.log("")
+}
+
+module.exports = { buildLocalPlan, annotateServerPlan, outputHumanPlan }

package/cli/planner.js

@@ -0,0 +1,67 @@
+const crypto = require("crypto")
+
+function generatePlanId() {
+  return "plan_" + crypto.randomBytes(6).toString("hex")
+}
+
+function createPlan(cmd, args) {
+  const steps = []
+
+  // Step 1: Resolve command
+  steps.push({
+    step: 1,
+    type: "resolve_command",
+    description: "Resolve command definition from config cache"
+  })
+
+  // Step 2: Validate args
+  steps.push({
+    step: 2,
+    type: "validate_args",
+    description: "Validate input arguments against schema"
+  })
+
+  // Step 3: Adapter request
+  const adapterStep = { step: 3, type: "adapter_request", adapter: cmd.adapter }
+  if (cmd.adapter === "openapi") {
+    adapterStep.method = (cmd.adapterConfig && cmd.adapterConfig.method) || "GET"
+    adapterStep.operationId = cmd.adapterConfig && cmd.adapterConfig.operationId
+    adapterStep.description = `Call OpenAPI operation: ${adapterStep.operationId}`
+  } else if (cmd.adapter === "http") {
+    adapterStep.method = (cmd.adapterConfig && cmd.adapterConfig.method) || "GET"
+    adapterStep.url = cmd.adapterConfig && cmd.adapterConfig.url
+    adapterStep.description = `HTTP ${adapterStep.method} ${adapterStep.url || "(dynamic)"}`
+  } else if (cmd.adapter === "mcp") {
+    adapterStep.tool = cmd.adapterConfig && cmd.adapterConfig.tool
+    adapterStep.description = `Call MCP tool: ${adapterStep.tool}`
+  } else {
+    adapterStep.description = `Execute via ${cmd.adapter} adapter`
+  }
+  steps.push(adapterStep)
+
+  // Step 4: Transform output
+  steps.push({
+    step: 4,
+    type: "transform_output",
+    description: "Normalize response into structured output envelope"
+  })
+
+  // Determine side effects and risk
+  const isMutation = !!(cmd.mutation)
+  const riskLevel = cmd.risk_level || (isMutation ? "medium" : "safe")
+
+  return {
+    plan_id: generatePlanId(),
+    command: `${cmd.namespace}.${cmd.resource}.${cmd.action}`,
+    args,
+    steps,
+    side_effects: isMutation,
+    risk_level: riskLevel,
+    estimated_duration_ms: cmd.adapter === "http" || cmd.adapter === "openapi" ? 200 : 100,
+    status: "planned",
+    created_at: new Date().toISOString(),
+    expires_at: new Date(Date.now() + 5 * 60 * 1000).toISOString()
+  }
+}
+
+module.exports = { createPlan }