superacli 1.0.1 → 1.1.2

package/cli/supercli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-require("dotenv").config();
+require("dotenv").config({ quiet: true });
 const {
   loadConfig,
   syncConfig,
@@ -12,6 +12,7 @@ const {
 const { execute } = require("./executor");
 const { buildCapabilities } = require("./help-json");
 const { handleMcpRegistryCommand } = require("./mcp-local");
+const { handlePluginsCommand } = require("./plugins-command");
 const {
   buildLocalPlan,
   annotateServerPlan,
@@ -19,6 +20,7 @@ const {
 } = require("./plan-runtime");
 const { handleAskCommand } = require("./ask");
 const { handleSkillsCommand } = require("./skills");
+const { findNamespacePassthrough } = require("./namespace-passthrough");
 
 const SERVER = process.env.SUPERCLI_SERVER;
 const hasServer = !!SERVER;
@@ -57,6 +59,7 @@ const RESERVED_FLAGS = [
   "no-color",
   "show-dag",
   "format",
+  "on-conflict",
 ];
 
 function compactKeys(obj) {
@@ -97,6 +100,18 @@ function output(data) {
   console.log(str);
 }
 
+function makeStreamEmitter(commandName) {
+  if (humanMode) return null
+  return (event) => {
+    output({
+      version: "1.0",
+      command: commandName,
+      stream: true,
+      data: event,
+    })
+  }
+}
+
 function outputHumanTable(rows, columns) {
   if (!humanMode) return false;
   if (!rows || rows.length === 0) {
@@ -126,9 +141,12 @@ function outputHumanTable(rows, columns) {
 }
 
 function outputError(error) {
+  const numericCode = Number.isInteger(error.code)
+    ? error.code
+    : Number.parseInt(error.code, 10) || 110;
   const envelope = {
     error: {
-      code: error.code || 110,
+      code: numericCode,
       type: error.type || "internal_error",
       message: error.message,
       recoverable: error.recoverable || false,
@@ -169,6 +187,59 @@ function userFlags() {
   return f;
 }
 
+function renderTopLevelHelp(config) {
+  const namespaces = [...new Set(config.commands.map((c) => c.namespace))];
+  if (humanMode) {
+    console.log("\n  ⚡ SuperCLI\n");
+    console.log("  Namespaces:\n");
+    namespaces.forEach((ns) => {
+      const resources = [
+        ...new Set(
+          config.commands.filter((c) => c.namespace === ns).map((c) => c.resource),
+        ),
+      ];
+      console.log(`    ${ns}`);
+      resources.forEach((r) => {
+        const actions = config.commands
+          .filter((c) => c.namespace === ns && c.resource === r)
+          .map((c) => c.action);
+        console.log(`      └─ ${r}: ${actions.join(", ")}`);
+      });
+    });
+    console.log("\n  Usage: supercli <namespace> <resource> <action> [--args]");
+    if (hasServer) console.log("  Sync: supercli sync");
+    console.log(
+      "  Plugins: supercli plugins explore | supercli plugins install <name|path> | supercli plugins install --git <repo>",
+    );
+    console.log(
+      "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp remove <name>",
+    );
+    console.log(
+      "  Skills: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
+    );
+    if (config.features?.ask || process.env.OPENAI_BASE_URL) {
+      console.log('  AI: supercli ask "<your natural language query>"');
+    }
+    console.log("  Server: supercli --server");
+    console.log(
+      "  Flags: --json | --human | --compact | --schema | --help-json | --server\n",
+    );
+    return;
+  }
+
+  output({
+    version: "1.0",
+    namespaces: namespaces.map((ns) => ({
+      name: ns,
+      resources: [...new Set(config.commands.filter((c) => c.namespace === ns).map((c) => c.resource))]
+        .map((r) => ({
+          name: r,
+          actions: config.commands.filter((c) => c.namespace === ns && c.resource === r).map((c) => c.action),
+        })),
+    })),
+  });
+}
+
 async function readStdin() {
   // Only read stdin if data is actually being piped
   if (process.stdin.isTTY) return null;
@@ -227,65 +298,29 @@ async function main() {
       return;
     }
 
-    if (positional.length === 0 || positional[0] === "help") {
-      const config = await loadConfig(SERVER);
-      const namespaces = [...new Set(config.commands.map((c) => c.namespace))];
-      if (humanMode) {
-        console.log("\n  ⚡ SuperCLI\n");
-        console.log("  Namespaces:\n");
-        namespaces.forEach((ns) => {
-          const resources = [
-            ...new Set(
-              config.commands
-                .filter((c) => c.namespace === ns)
-                .map((c) => c.resource),
-            ),
-          ];
-          console.log(`    ${ns}`);
-          resources.forEach((r) => {
-            const actions = config.commands
-              .filter((c) => c.namespace === ns && c.resource === r)
-              .map((c) => c.action);
-            console.log(`      └─ ${r}: ${actions.join(", ")}`);
-          });
-        });
-        console.log(
-          "\n  Usage: supercli <namespace> <resource> <action> [--args]",
-        );
-        if (hasServer) console.log("  Sync: supercli sync");
-        console.log(
-          "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp remove <name>",
-        );
-        console.log(
-          "  Skills: supercli skills list | supercli skills get <ns.res.act> | supercli skills teach",
-        );
-        if (config.features?.ask || process.env.OPENAI_BASE_URL) {
-          console.log('  AI: supercli ask "<your natural language query>"');
-        }
-        console.log("  Server: supercli --server");
-        console.log(
-          "  Flags: --json | --human | --compact | --schema | --help-json | --server\n",
-        );
-      } else {
+    if (positional.length === 0) {
+      if (!humanMode) {
         output({
           version: "1.0",
-          namespaces: namespaces.map((ns) => ({
-            name: ns,
-            resources: [
-              ...new Set(
-                config.commands
-                  .filter((c) => c.namespace === ns)
-                  .map((c) => c.resource),
-              ),
-            ].map((r) => ({
-              name: r,
-              actions: config.commands
-                .filter((c) => c.namespace === ns && c.resource === r)
-                .map((c) => c.action),
-            })),
-          })),
+          mode: "agent_bootstrap",
+          goal: "Use skills for command-safe execution",
+          next: [
+            "supercli skills teach --format skill.md",
+            "supercli skills list --json",
+            "supercli skills get <namespace.resource.action> --format skill.md"
+          ],
+          note: "Use skills teach first, then fetch only the skill you need."
         });
+        return;
       }
+      const config = await loadConfig(SERVER);
+      renderTopLevelHelp(config);
+      return;
+    }
+
+    if (positional[0] === "help") {
+      const config = await loadConfig(SERVER);
+      renderTopLevelHelp(config);
       return;
     }
 
@@ -339,6 +374,18 @@ async function main() {
       return;
     }
 
+    if (positional[0] === "plugins") {
+      await handlePluginsCommand({
+        positional,
+        flags,
+        humanMode,
+        output,
+        outputHumanTable,
+        outputError,
+      });
+      return;
+    }
+
     if (positional[0] === "skills") {
       const config = await loadConfig(SERVER);
       handleSkillsCommand({
@@ -528,6 +575,45 @@ async function main() {
       return;
     }
 
+    {
+      const config = await loadConfig(SERVER);
+      const passthrough = findNamespacePassthrough(config, positional, rawArgs);
+      if (passthrough) {
+        const start = Date.now();
+        const result = await execute(
+          passthrough.command,
+          {
+            __rawArgs: passthrough.passthroughArgs,
+            __passthroughInteractive: humanMode && isTTY,
+          },
+          {
+            server: SERVER || "",
+            config,
+            onStreamEvent: passthrough.command.adapterConfig && passthrough.command.adapterConfig.stream === "jsonl"
+              ? makeStreamEmitter(`${passthrough.namespace}.passthrough`)
+              : null,
+          },
+        );
+        const duration = Date.now() - start;
+        const envelope = {
+          version: "1.0",
+          command: `${passthrough.namespace}.passthrough`,
+          duration_ms: duration,
+          data: result,
+        };
+
+        if (humanMode && result && typeof result === "object" && result.passthrough === true) {
+          return;
+        }
+        if (humanMode && result && typeof result === "object" && typeof result.raw === "string") {
+          console.log(result.raw);
+        } else {
+          output(envelope);
+        }
+        return;
+      }
+    }
+
     if (positional.length === 1) {
       const config = await loadConfig(SERVER);
       const cmds = config.commands.filter((c) => c.namespace === positional[0]);
@@ -642,7 +728,13 @@ async function main() {
     }
 
     const start = Date.now();
-    const result = await execute(cmd, uFlags, { server: SERVER || "", config });
+    const result = await execute(cmd, uFlags, {
+      server: SERVER || "",
+      config,
+      onStreamEvent: cmd.adapterConfig && cmd.adapterConfig.stream === "jsonl"
+        ? makeStreamEmitter(`${namespace}.${resource}.${action}`)
+        : null,
+    });
     const duration = Date.now() - start;
 
     const envelope = {

package/docs/docs.html

@@ -0,0 +1,224 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>supercli Documentation</title>
+    <script src="https://cdn.tailwindcss.com?plugins=typography"></script>
+    <script>
+      tailwind.config = {
+        theme: {
+          extend: {
+            fontFamily: {
+              sans: ['Inter', 'system-ui', 'sans-serif'],
+              display: ['Space Grotesk', 'sans-serif']
+            },
+            colors: {
+              brand: {
+                100: '#E0F2FE',
+                200: '#BAE6FD',
+                400: '#38BDF8',
+                500: '#0891B2'
+              }
+            }
+          }
+        }
+      };
+    </script>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600&family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/daisyui@4.7.2/dist/full.min.css" />
+    <style>
+      body {
+        font-family: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        background-color: #020617;
+        color: #e2e8f0;
+      }
+      .sidebar-link {
+        transition: background-color 0.2s ease, color 0.2s ease;
+      }
+    </style>
+  </head>
+  <body class="bg-slate-950">
+    <div class="flex min-h-screen">
+      <aside id="sidebar" class="w-72 flex-shrink-0 border-r border-slate-800 bg-slate-950/80 backdrop-blur hidden lg:block">
+        <div class="p-6 space-y-8">
+          <div>
+            <p class="text-xs uppercase tracking-[0.4em] text-brand-400">Docs</p>
+            <h1 class="text-2xl font-display font-semibold mt-3 text-white">supercli</h1>
+            <p class="text-sm text-slate-400">Universal Skill Router</p>
+          </div>
+          <nav class="space-y-4">
+            <div>
+              <p class="text-xs uppercase tracking-widest text-slate-500 mb-2">Overview</p>
+              <ul class="space-y-2 text-sm">
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#getting-started">Getting Started</a></li>
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#skill-layer">Skill Layer Basics</a></li>
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#skill-sources">Skill Sources</a></li>
+              </ul>
+            </div>
+            <div>
+              <p class="text-xs uppercase tracking-widest text-slate-500 mb-2">Runtime</p>
+              <ul class="space-y-2 text-sm">
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#architecture">Architecture</a></li>
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#cli-usage">CLI Usage</a></li>
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#plugins">Plugins & Harnesses</a></li>
+              </ul>
+            </div>
+            <div>
+              <p class="text-xs uppercase tracking-widest text-slate-500 mb-2">Vision</p>
+              <ul class="space-y-2 text-sm">
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#skill-vision">Skill Mesh Vision</a></li>
+                <li><a class="sidebar-link block rounded-lg px-3 py-2 hover:bg-brand-500/10 hover:text-brand-100" href="#resources">Resources</a></li>
+              </ul>
+            </div>
+          </nav>
+        </div>
+      </aside>
+
+      <div class="flex-1 flex flex-col">
+        <header class="border-b border-slate-800 px-6 py-4 flex items-center justify-between">
+          <button id="mobileToggle" class="lg:hidden btn btn-sm btn-outline border-brand-400 text-brand-100" type="button">Menu</button>
+          <div>
+            <p class="text-xs uppercase tracking-[0.4em] text-brand-400">Documentation</p>
+            <h1 class="text-2xl font-display font-semibold text-white">supercli Knowledge Base</h1>
+          </div>
+        </header>
+
+        <main class="flex-1 overflow-y-auto">
+          <section class="border-b border-slate-900 bg-slate-900/60 px-6 py-6">
+            <div class="max-w-4xl">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Quick filter</p>
+              <input id="filterInput" type="text" placeholder="Search anything (e.g. OpenAPI, plugins, plans)" class="mt-3 w-full rounded-2xl bg-slate-950/70 border border-slate-700 px-4 py-3 text-slate-100 placeholder:text-slate-500 focus:border-brand-400 focus:outline-none" />
+            </div>
+          </section>
+
+          <div class="max-w-4xl px-6 py-10 space-y-10">
+            <article class="doc-section space-y-4" id="getting-started" data-keywords="install npm start quick start env">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Start here</p>
+              <h2 class="text-3xl font-display font-semibold">Getting Started</h2>
+              <p class="text-slate-300">Run `npx supercli help` for instant usage, install dependencies with `npm install`, copy `.env.example`, and start the local server via `npm start` or `supercli --server`. The web UI (EJS + Vue + Tailwind) is reachable at `http://localhost:3000`. Refer to the repository README for additional context.</p>
+            </article>
+
+            <article class="doc-section space-y-4" id="skill-layer" data-keywords="skill layer discovery routing execution mesh">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Concept</p>
+              <h2 class="text-3xl font-display font-semibold">Skill Layer Basics</h2>
+              <p class="text-slate-300">Every capability becomes a skill, whether it originates from CLI commands, OpenAPI endpoints, MCP tools, workflows, or HTTP requests. supercli indexes names like `namespace.resource.action`, exposes schemas, and lets agents discover, inspect, and execute consistently.</p>
+              <pre class="bg-slate-900 border border-slate-800 rounded-2xl p-4 text-sm"><code>supercli skills list
+supercli skills search "database"
+supercli skills get beads.issue.create</code></pre>
+            </article>
+
+            <article class="doc-section space-y-4" id="skill-sources" data-keywords="bundled adapters openapi http mcp workflows plugins">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Sources</p>
+              <h2 class="text-3xl font-display font-semibold">Skill Sources</h2>
+              <ul class="list-disc list-inside text-slate-300 space-y-2">
+                <li><strong>Bundled Harnesses</strong> – beads, gwc, commiat ship with the CLI.</li>
+                <li><strong>Built-in Adapters</strong> – OpenAPI specs, raw HTTP, and MCP servers become skills automatically.</li>
+                <li><strong>Plugins</strong> – Install docker, gh, aws, kubectl, terraform harnesses via `supercli plugins install`.</li>
+                <li><strong>AI Plans / Workflows</strong> – Natural language `ask` and `plan` commands create DAGs of skills.</li>
+              </ul>
+            </article>
+
+            <article class="doc-section space-y-4" id="architecture" data-keywords="router discovery layer adapters harness diagram">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Runtime</p>
+              <h2 class="text-3xl font-display font-semibold">Architecture</h2>
+              <p class="text-slate-300">Agents route requests through the skill discovery layer, which maps namespaces to harnesses/adapters. Execution envelopes guarantee deterministic JSON responses and exit codes.</p>
+              <pre class="bg-slate-900 border border-slate-800 rounded-2xl p-4 text-sm"><code>Agents/Humans → supercli runtime → Skill Router → Harness / Adapter → Tool</code></pre>
+            </article>
+
+            <article class="doc-section space-y-4" id="cli-usage" data-keywords="cli usage beads gwc docker plan ask plugins config">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Interface</p>
+              <h2 class="text-3xl font-display font-semibold">CLI Usage</h2>
+              <div class="space-y-3">
+                <pre class="bg-slate-900 border border-slate-800 rounded-2xl p-4 text-sm"><code>supercli &lt;harness&gt;                # list skills
+supercli beads issue list --json
+supercli skills search --harness beads "task"
+supercli ask "deploy staging"
+supercli plugins explore --tags git,ai</code></pre>
+                <p class="text-slate-300">`--json`, `--human`, and `--compact` control output, while exit codes communicate validation, resource, or integration errors.</p>
+              </div>
+            </article>
+
+            <article class="doc-section space-y-4" id="plugins" data-keywords="plugin harness guide manifest commiat docker install">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Extension</p>
+              <h2 class="text-3xl font-display font-semibold">Plugins & Harnesses</h2>
+              <p class="text-slate-300">Wrap any CLI with a `plugin.json` manifest that defines commands, schemas, dependency checks, and passthrough rules. Install from the registry, Git repos, or local paths.</p>
+              <p class="text-slate-400 text-sm">Need more? Check `docs/plugin-harness-guide.md` in the repository for step-by-step authoring details.</p>
+            </article>
+
+            <article class="doc-section space-y-4" id="skill-vision" data-keywords="skill mesh registry graph governance dag api telemetry">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Vision</p>
+              <h2 class="text-3xl font-display font-semibold">Skill Mesh Direction</h2>
+              <p class="text-slate-300">The platform is evolving toward a mesh that handles discovery, routing, execution, composition, and governance. Key areas under exploration include a unified skill registry, graph-native discovery, mesh-wide policy, DAG orchestration, agent endpoints, composition tooling, telemetry, and richer plugin UX.</p>
+            </article>
+
+            <article class="doc-section space-y-4" id="resources" data-keywords="readme docs skills catalog supported harnesses">
+              <p class="text-sm uppercase tracking-widest text-brand-200">Resources</p>
+              <h2 class="text-3xl font-display font-semibold">More Documentation</h2>
+              <ul class="list-disc list-inside text-slate-300 space-y-2">
+                <li>README.md (repository root)</li>
+                <li>docs/skills-catalog.md</li>
+                <li>docs/supported-harnesses.md</li>
+                <li>docs/features/skills.md</li>
+              </ul>
+            </article>
+          </div>
+        </main>
+      </div>
+    </div>
+
+    <div id="mobileDrawer" class="fixed inset-0 bg-black/60 hidden z-40 lg:hidden">
+      <div class="w-72 bg-slate-950 h-full border-r border-slate-800 p-6 overflow-y-auto">
+        <div class="flex items-center justify-between mb-6">
+          <h2 class="text-white text-xl font-display">Navigate</h2>
+          <button id="drawerClose" class="btn btn-sm btn-ghost">Close</button>
+        </div>
+        <div id="drawerNav" class="space-y-6 text-sm">
+          <!-- Populated from sidebar -->
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const filterInput = document.getElementById('filterInput');
+      const sections = document.querySelectorAll('.doc-section');
+
+      filterInput.addEventListener('input', (event) => {
+        const query = event.target.value.trim().toLowerCase();
+        sections.forEach((section) => {
+          const text = section.textContent.toLowerCase();
+          const keywords = section.dataset.keywords || '';
+          const match = text.includes(query) || keywords.includes(query);
+          section.style.display = match ? 'block' : 'none';
+        });
+      });
+
+      const sidebar = document.getElementById('sidebar');
+      const mobileDrawer = document.getElementById('mobileDrawer');
+      const drawerNav = document.getElementById('drawerNav');
+      const mobileToggle = document.getElementById('mobileToggle');
+      const drawerClose = document.getElementById('drawerClose');
+
+      const cloneSidebarNav = () => {
+        if (!sidebar) return;
+        drawerNav.innerHTML = sidebar.querySelector('nav').innerHTML;
+      };
+      cloneSidebarNav();
+
+      const openDrawer = () => {
+        mobileDrawer.classList.remove('hidden');
+      };
+      const closeDrawer = () => {
+        mobileDrawer.classList.add('hidden');
+      };
+
+      mobileToggle.addEventListener('click', openDrawer);
+      drawerClose.addEventListener('click', closeDrawer);
+      mobileDrawer.addEventListener('click', (event) => {
+        if (event.target === mobileDrawer) closeDrawer();
+      });
+    </script>
+  </body>
+</html>

package/docs/feature-gaps.md

@@ -0,0 +1,16 @@
+# Feature Gaps
+
+Comparison of the current release versus the broader skill-mesh vision from the latest brainstorming notes.
+
+| Feature name | Description | Why it matters |
+| --- | --- | --- |
+| Unified skill registry service | Dedicated registry service that persists skill metadata, ownership, and lifecycle events outside the CLI runtime. | Enables organization-wide discovery, policy management, and sharing without relying on a single CLI process or local cache. |
+| Skill graph traversal API | Graph-native search endpoints ("related skills", capability clustering, semantic tags). | Agents can explore neighboring skills, infer dependencies, and auto-complete workflows instead of executing isolated commands. |
+| Mesh-wide governance & policy | Central rules for authentication, rate limits, approvals, and auditing across every harness/adapter. | Provides enterprise-grade controls so teams can safely expose sensitive CLIs/APIs without bespoke wrappers. |
+| Execution DAG orchestration | First-class scheduler for multi-skill plans with retries, checkpoints, and observability hooks. | Bridges `plan/execute` concepts with reliable automation, turning plans into production-grade workflows. |
+| Agent-facing HTTP interface | Stable HTTP/WebSocket endpoints that mirror CLI capabilities for direct agent/automation consumption. | Lets agents integrate via simple API calls rather than shelling out to the CLI, unlocking server-side agents and SaaS integrations. |
+| Skill composition toolkit | Declarative way to package multiple skills into composites or workflows that publish as new skills. | Encourages reuse, accelerates plugin development, and aligns with the "skill mesh" abstraction where every composite is also a skill. |
+| Telemetry & lineage for skills | Built-in tracing, metrics, and history for each skill invocation and plan. | Makes it possible to reason about reliability, enforce governance, and debug agent runs across heterogeneous tools. |
+| Plugin certification & discovery UX | Registry UX for tagging, ranking, and validating community plugins directly in `supercli plugins explore`. | Reduces trust friction for third-party harnesses and makes the discovery narrative match the README’s emphasis on skills-first exploration. |
+
+These gaps represent future-facing opportunities rather than committed roadmap items; they document the delta between today’s shipping features and the aspirational skill-mesh direction.