superacli 1.1.6 → 1.1.8

package/docs/server-plugins-usage-guide.md

@@ -0,0 +1,182 @@
+# Server Plugins Usage Guide
+
+This guide covers manual testing of server plugins in SUPERCLI, including JSON and ZIP plugin flows.
+
+## Prerequisites
+
+- A running server instance (example: `PORT=3001 sc --server`)
+- CLI shell with:
+
+```bash
+export SUPERCLI_SERVER=http://localhost:3001
+```
+
+## 1) Verify Server Plugin Endpoints
+
+```bash
+curl -s "$SUPERCLI_SERVER/api/plugins?format=json" | jq
+curl -s "$SUPERCLI_SERVER/api/plugins/settings" | jq
+```
+
+Expected: JSON response with `plugins` and `settings`.
+
+## 2) Create a JSON Server Plugin
+
+Create a simple shell command plugin:
+
+```bash
+curl -s -X POST "$SUPERCLI_SERVER/api/plugins" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source_type": "json",
+    "name": "server-demo-json",
+    "version": "0.1.0",
+    "description": "Server JSON plugin demo",
+    "enabled": true,
+    "hooks_policy": "inherit",
+    "manifest": {
+      "name": "server-demo-json",
+      "version": "0.1.0",
+      "commands": [
+        {
+          "namespace": "demo",
+          "resource": "fs",
+          "action": "list",
+          "description": "List files via server plugin",
+          "adapter": "shell",
+          "adapterConfig": {
+            "unsafe": true,
+            "script": "ls -lrt",
+            "parseJson": false,
+            "timeout_ms": 5000
+          },
+          "args": []
+        }
+      ]
+    }
+  }' | jq
+```
+
+## 3) Sync and Execute JSON Plugin Command
+
+```bash
+sc sync --json | jq
+sc commands --namespace demo --json | jq
+sc demo fs list --json | jq
+```
+
+Expected:
+
+- `sync` includes `server_plugins` diagnostics.
+- `demo fs list` appears in commands.
+- execution returns shell output in `data.raw`.
+
+## 4) Test Enable/Disable Server Plugin
+
+Disable:
+
+```bash
+curl -s -X PATCH "$SUPERCLI_SERVER/api/plugins/server-demo-json" \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled": false}' | jq
+```
+
+Re-sync and verify command removal:
+
+```bash
+sc sync --json | jq
+sc commands --namespace demo --json | jq
+```
+
+Re-enable:
+
+```bash
+curl -s -X PATCH "$SUPERCLI_SERVER/api/plugins/server-demo-json" \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled": true}' | jq
+sc sync --json | jq
+```
+
+## 5) Upload a ZIP Server Plugin (multipart)
+
+Create a minimal ZIP payload:
+
+```bash
+mkdir -p /tmp/server-demo-zip
+cat > /tmp/server-demo-zip/plugin.json <<'EOF'
+{
+  "name": "server-demo-zip",
+  "version": "0.1.0",
+  "commands": [
+    {
+      "namespace": "zipdemo",
+      "resource": "tool",
+      "action": "ping",
+      "description": "ZIP plugin ping",
+      "adapter": "shell",
+      "adapterConfig": {
+        "unsafe": true,
+        "script": "printf ping",
+        "parseJson": false,
+        "timeout_ms": 3000
+      },
+      "args": []
+    }
+  ]
+}
+EOF
+(cd /tmp/server-demo-zip && zip -r /tmp/server-demo-zip.zip .)
+```
+
+Upload as multipart form:
+
+```bash
+curl -s -X POST "$SUPERCLI_SERVER/api/plugins/upload" \
+  -F "name=server-demo-zip" \
+  -F "version=0.1.0" \
+  -F "description=ZIP plugin demo" \
+  -F "enabled=true" \
+  -F "hooks_policy=inherit" \
+  -F "manifest={\"name\":\"server-demo-zip\",\"version\":\"0.1.0\",\"commands\":[]}" \
+  -F "archive=@/tmp/server-demo-zip.zip;type=application/zip" | jq
+```
+
+Then sync and verify:
+
+```bash
+sc sync --json | jq
+sc commands --namespace zipdemo --json | jq
+```
+
+## 6) Validate Local-Over-Server Precedence
+
+Install/create a local plugin with the same plugin name as a server plugin.
+After `sc sync`, verify server plugin is shadowed:
+
+```bash
+sc sync --json | jq '.server_plugins.shadowed_by_local'
+```
+
+Expected: plugin name appears in `shadowed_by_local`, and local plugin commands remain active.
+
+## 7) Update Server Plugin Settings
+
+```bash
+curl -s -X PUT "$SUPERCLI_SERVER/api/plugins/settings" \
+  -H 'Content-Type: application/json' \
+  -d '{"max_zip_mb": 10, "default_hooks_policy": "deny"}' | jq
+```
+
+## 8) Cleanup
+
+```bash
+curl -s -X DELETE "$SUPERCLI_SERVER/api/plugins/server-demo-json" | jq
+curl -s -X DELETE "$SUPERCLI_SERVER/api/plugins/server-demo-zip" | jq
+sc sync --json | jq
+```
+
+## Troubleshooting
+
+- If ZIP upload fails with size errors, check `max_zip_mb` in `/api/plugins/settings`.
+- If ZIP sync fails on client extraction, ensure `unzip` is installed.
+- If commands do not appear after server updates, run `sc sync` again and inspect `server_plugins` diagnostics.

package/docs/skills-catalog.md

@@ -1,7 +1,9 @@
-# Skills Catalog
+# 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
@@ -19,7 +21,7 @@ supercli skills sync --json
 
 This scans enabled provider roots for `SKILL.md` files and rebuilds the local index.
 
-## Query Catalog Skills
+## Query Catalog Skill Documents
 
 ```bash
 supercli skills list --catalog --json
@@ -27,13 +29,13 @@ supercli skills search --query "planning" --json
 supercli skills get opencode:plan-changes
 ```
 
-## Built-in MCP Usage Skill (Agent-Friendly)
+## Built-in MCP Usage Skill Document (Agent-Friendly)
 
 ```bash
 supercli skills get mcp.servers.usage
 ```
 
-This built-in skill teaches non-human agents how to register, verify, and use MCP servers
+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.
 
@@ -41,7 +43,7 @@ runtime API-key passing.
 
 - IDs are always provider-qualified (`provider:id`) for future-proof disambiguation.
 - Current provider types include `local_fs`, `repo_fs`, and `remote_static`.
-- Existing command-skill flow remains available (`skills list`, `skills get <ns.res.act>`, `skills teach`).
+- Existing capability-doc flow remains available (`skills list`, `skills get <ns.res.act>`, `skills teach`).
 
 ## Remote Provider Example: agency-agents
 
@@ -51,9 +53,9 @@ supercli skills list --catalog --provider agency-agents --json
 supercli skills get agency-agents:engineering.engineering-frontend-developer
 ```
 
-`agency-agents` maps skills one-to-one to upstream `.md` files in
+`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 skills may stop resolving until reinstalled/refreshed.
+individual skill documents may stop resolving until reinstalled/refreshed.
 
 ## Remote Provider Example: visual-explainer
 
@@ -63,7 +65,7 @@ supercli skills list --catalog --provider visual-explainer --json
 supercli skills get visual-explainer:visual-explainer.skill
 ```
 
-`visual-explainer` maps skills to normalized markdown files under
+`visual-explainer` maps skill documents to normalized markdown files under
 `plugins/visual-explainer-normalized` in `javimosch/visual-explainer`.
 
 ## Remote Provider Example: nullclaw
@@ -119,7 +121,7 @@ supercli skills get clix:root.readme
 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 Example: cline-non-interactive
+## Local Repo Skill Document Example: cline-non-interactive
 
 ```bash
 supercli skills sync --json
@@ -127,5 +129,5 @@ supercli skills list --catalog --provider repo --json
 supercli skills get repo:cline-non-interactive
 ```
 
-`cline-non-interactive` is a repository-local skill that teaches agents to prefer the wrapped
+`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/index.html

@@ -0,0 +1,384 @@
+<!doctype html>
+<html lang="en" class="bg-slate-950">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>supercli — Universal Skill Router</title>
+    <script src="https://cdn.tailwindcss.com?plugins=typography"></script>
+    <script>
+      tailwind.config = {
+        theme: {
+          extend: {
+            fontFamily: {
+              display: ["Space Grotesk", "sans-serif"],
+              body: ["Inter", "sans-serif"],
+            },
+            colors: {
+              brand: {
+                50: "#ECF8FF",
+                200: "#A5D8FF",
+                400: "#38BDF8",
+                500: "#0891B2",
+                900: "#0F172A",
+              },
+            },
+          },
+        },
+      };
+    </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@400;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:
+          radial-gradient(
+            circle at top,
+            rgba(8, 145, 178, 0.24),
+            rgba(15, 23, 42, 0.95)
+          ),
+          #020617;
+      }
+      .hero-grid {
+        background: linear-gradient(
+          135deg,
+          rgba(56, 189, 248, 0.08),
+          rgba(8, 145, 178, 0.08)
+        );
+        border: 1px solid rgba(56, 189, 248, 0.3);
+      }
+    </style>
+  </head>
+  <body class="text-slate-100">
+    <header class="max-w-6xl mx-auto px-6 py-12 md:py-16">
+      <div class="flex flex-col gap-6 text-center">
+        <div
+          class="inline-flex items-center justify-center gap-2 text-xs uppercase tracking-[0.3em] text-brand-200"
+        >
+          <span class="h-px w-8 bg-brand-200/60"></span>
+          Universal Skill Router
+          <span class="h-px w-8 bg-brand-200/60"></span>
+        </div>
+        <h1
+          class="text-4xl md:text-5xl font-display font-semibold leading-tight"
+        >
+          supercli — unify every CLI, API, and MCP tool as discoverable skills.
+        </h1>
+         <p class="text-lg md:text-xl text-slate-300 max-w-3xl mx-auto">
+           Build a universal skill layer for your agents. supercli automatically
+           exposes CLIs, OpenAPI endpoints, MCP servers, HTTP integrations, and
+           workflows as structured skills so agents can discover, search, and
+           execute capabilities through one interface.
+         </p>
+         <p class="text-sm md:text-base text-slate-400 max-w-3xl mx-auto">
+           Get started with <code>supercli help</code> or see all options with <code>supercli --help</code>
+         </p>
+        <div class="flex flex-wrap justify-center gap-4">
+          <a
+            class="btn btn-primary px-6"
+            href="./docs/index.html#getting-started"
+            >Start Building</a
+          >
+          <a
+            class="btn btn-outline border-brand-400/50 text-brand-200 px-6"
+            href="./docs/index.html"
+            >Explore the Docs</a
+          >
+          <a
+            class="btn btn-ghost text-slate-300 px-6"
+            href="https://github.com/javimosch/supercli"
+            target="_blank"
+            rel="noreferrer"
+            >GitHub Repo</a
+          >
+        </div>
+      </div>
+    </header>
+
+    <main class="max-w-6xl mx-auto px-6 pb-20 space-y-20">
+      <section class="grid gap-6 md:grid-cols-2 hero-grid rounded-3xl p-8">
+        <div class="space-y-4">
+          <p class="text-sm uppercase tracking-widest text-brand-200">
+            Skill Discovery Layer
+          </p>
+          <h2 class="text-3xl font-display font-semibold">
+            Agents query a single skill graph.
+          </h2>
+          <p class="text-slate-300">
+            supercli caches schemas, inputs, outputs, and rules for every
+            harness. Agents explore skills via search, inspect action metadata,
+            and trust consistent envelopes and exit codes.
+          </p>
+        </div>
+        <div class="space-y-3">
+          <div class="card bg-slate-900/60 border border-slate-700">
+            <div class="card-body">
+              <p class="text-xs uppercase tracking-widest text-brand-200">
+                Example
+              </p>
+              <pre
+                class="text-sm bg-slate-950/70 p-4 rounded-xl overflow-x-auto"
+              ><code>supercli skills search "database"
+supercli skills get beads.issue.create
+supercli plan beads issue create --title "Task"</code></pre>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section class="space-y-10">
+        <div class="space-y-3">
+          <p class="text-sm uppercase tracking-widest text-brand-200">
+            Skill Sources
+          </p>
+          <h2 class="text-3xl font-display font-semibold">
+            Every tool becomes a skill.
+          </h2>
+          <p class="text-slate-300 max-w-3xl">
+            supercli ingests multiple ecosystems so the router stays agnostic to
+            execution details.
+          </p>
+        </div>
+        <div class="grid gap-5 md:grid-cols-3">
+          <article
+            class="p-6 rounded-2xl border border-slate-800 bg-slate-900/50"
+          >
+            <h3 class="text-xl font-semibold">CLI Harnesses</h3>
+            <p class="text-slate-400">
+              Route commands for beads, gwc, commiat, docker, kubectl, gh, aws,
+              terraform, and more via manifests or passthrough adapters.
+            </p>
+          </article>
+          <article
+            class="p-6 rounded-2xl border border-slate-800 bg-slate-900/50"
+          >
+            <h3 class="text-xl font-semibold">OpenAPI & HTTP</h3>
+            <p class="text-slate-400">
+              Import specs, auto-generate skills, and let agents execute
+              normalized HTTP requests with schema validation.
+            </p>
+          </article>
+          <article
+            class="p-6 rounded-2xl border border-slate-800 bg-slate-900/50"
+          >
+            <h3 class="text-xl font-semibold">MCP + Workflows</h3>
+            <p class="text-slate-400">
+              Expose MCP tools, AI-driven plans, and declarative workflows as
+              first-class skills with consistent envelopes.
+            </p>
+          </article>
+        </div>
+      </section>
+
+      <section class="grid gap-10 md:grid-cols-2 items-center">
+        <div class="order-2 md:order-1">
+          <p class="text-sm uppercase tracking-widest text-brand-200">
+            Architecture
+          </p>
+          <h2 class="text-3xl font-display font-semibold mb-4">
+            From agent request to tool execution.
+          </h2>
+          <p class="text-slate-300 mb-2">
+            Skills flow through a discovery layer, router, and harness/adapters
+            that target CLIs, APIs, or custom runtimes.
+          </p>
+          <pre
+            class="bg-slate-900 border border-slate-800 rounded-2xl p-6 text-sm leading-relaxed overflow-x-auto"
+          ><code>Agent → Skill Discovery → Router → Harness / Adapter → Tool</code></pre>
+        </div>
+        <div class="order-1 md:order-2">
+          <div class="rounded-3xl border border-slate-800 p-6 bg-slate-900/40">
+            <ul class="space-y-4 text-slate-300">
+              <li>
+                <span class="font-semibold text-slate-100">Discovery</span> –
+                catalog every skill with metadata & policy.
+              </li>
+              <li>
+                <span class="font-semibold text-slate-100">Routing</span> –
+                resolve namespaces to adapters automatically.
+              </li>
+              <li>
+                <span class="font-semibold text-slate-100">Execution</span> –
+                normalize inputs/outputs and exit codes.
+              </li>
+              <li>
+                <span class="font-semibold text-slate-100">Extension</span> –
+                drop in new harnesses, plugins, or specs.
+              </li>
+            </ul>
+          </div>
+        </div>
+      </section>
+
+      <section class="space-y-6">
+        <div
+          class="flex items-center gap-3 text-brand-200 text-sm uppercase tracking-widest"
+        >
+          <span class="h-px w-10 bg-brand-200/60"></span>
+          Skill Mesh Vision
+        </div>
+        <div class="grid gap-5 md:grid-cols-2">
+          <article
+            class="p-6 rounded-2xl border border-slate-800 bg-slate-900/60"
+          >
+            <h3 class="text-2xl font-display mb-3">
+              Toward a universal skill mesh.
+            </h3>
+            <p class="text-slate-300">
+              supercli is growing into a mesh that handles discovery, routing,
+              execution, composition, and governance for every capability in
+              your environment.
+            </p>
+          </article>
+          <article
+            class="p-6 rounded-2xl border border-slate-800 bg-slate-900/60"
+          >
+            <ul class="list-disc list-inside text-slate-300 space-y-2">
+              <li>Graph-native discovery & tagging</li>
+              <li>Execution DAG observability</li>
+              <li>Agent-facing HTTP/WebSocket endpoints</li>
+              <li>Policy controls across harnesses</li>
+            </ul>
+          </article>
+        </div>
+        <p class="text-sm text-slate-400">
+          Follow along in the docs for upcoming mesh capabilities and long-term
+          direction.
+        </p>
+      </section>
+
+      <section class="space-y-10">
+        <div class="space-y-3">
+          <p class="text-sm uppercase tracking-widest text-brand-200">
+            Plugin Explorer
+          </p>
+          <h2 class="text-3xl font-display font-semibold">
+            Discover and search plugins
+          </h2>
+          <p class="text-slate-300 max-w-2xl">
+            Browse the official supercli plugins that add new skills, wrappers,
+            and integrations to your agent toolkit.
+          </p>
+        </div>
+        <div class="space-y-4">
+          <div
+            class="flex flex-col md:flex-row md:items-start md:justify-between"
+          >
+            <label for="plugin-search" class="block mb-2 text-slate-300"
+              >Search plugins</label
+            >
+            <input
+              type="text"
+              id="plugin-search"
+              placeholder="Search by name, tag, or description"
+              class="input input-bordered w-full md:w-64"
+            />
+          </div>
+          <div
+            id="plugin-list"
+            class="grid gap-4 md:grid-cols-2 lg:grid-cols-3"
+          >
+            <!-- Plugin cards will be inserted here by JavaScript -->
+          </div>
+        </div>
+      </section>
+    </main>
+
+    <footer
+      class="border-t border-slate-800/60 py-8 text-center text-sm text-slate-400"
+    >
+      <a href="https://www.linkedin.com/in/arancibiajav/" target="_blank">
+        <p>© <span id="year"></span> by Javier Leandro Arancibia</p>
+      </a>
+
+      <div class="flex justify-center gap-4 mt-3">
+        <a class="underline" href="./docs/index.html#getting-started">Start</a>
+        <a class="underline" href="./docs/index.html">Docs</a>
+        <a class="underline" href="./docs/index.html#skill-vision"
+          >Skill vision</a
+        >
+      </div>
+    </footer>
+
+    <script>
+      document.getElementById("year").textContent = new Date().getFullYear();
+    </script>
+
+    <script>
+      // Plugin Explorer Script
+      document.addEventListener("DOMContentLoaded", function () {
+        const pluginList = document.getElementById("plugin-list");
+        const searchInput = document.getElementById("plugin-search");
+
+        // Fetch the plugins manifest
+        fetch("plugins/plugins.json")
+          .then((response) => {
+            if (!response.ok) {
+              throw new Error("Failed to fetch plugins");
+            }
+            return response.json();
+          })
+          .then((data) => {
+            const plugins = data.plugins;
+            renderPlugins(plugins);
+
+            // Add event listener for search
+            searchInput.addEventListener("input", (e) => {
+              const query = e.target.value.toLowerCase();
+              const filtered = plugins.filter(
+                (plugin) =>
+                  plugin.name.toLowerCase().includes(query) ||
+                  plugin.description.toLowerCase().includes(query) ||
+                  (plugin.tags || []).some((tag) =>
+                    tag.toLowerCase().includes(query),
+                  ),
+              );
+              renderPlugins(filtered);
+            });
+          })
+          .catch((error) => {
+            pluginList.innerHTML = `<p class="text-slate-400 col-span-3">Error loading plugins: ${error.message}</p>`;
+          });
+
+        function renderPlugins(plugins) {
+          if (plugins.length === 0) {
+            pluginList.innerHTML = `<p class="text-slate-400 col-span-3">No plugins found.</p>`;
+            return;
+          }
+
+          pluginList.innerHTML = plugins
+            .map((plugin) => {
+              const tagsHtml = (plugin.tags || [])
+                .map(
+                  (tag) => `<span class="badge badge-secondary">${tag}</span>`,
+                )
+                .join("");
+
+              return `
+              <article class="p-6 rounded-2xl border border-slate-800 bg-slate-900/50">
+                <h3 class="text-xl font-semibold">${plugin.name}</h3>
+                <p class="text-slate-400">${plugin.description}</p>
+                <div class="flex flex-wrap gap-2 mt-3">${tagsHtml}</div>
+              </article>
+            `;
+            })
+            .join("");
+        }
+      });
+    </script>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superacli",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "license": "MIT",
   "main": "server/app.js",
@@ -9,7 +9,7 @@
     "scli": "./cli/supercli.js",
     "superacli": "./cli/supercli.js",
     "supercli": "./cli/supercli.js",
-    "sc":"./cli/supercli.js"
+    "sc": "./cli/supercli.js"
   },
   "scripts": {
     "start": "node server/app.js",