superacli 1.1.20 → 1.1.21

package/cli/supercli.js

@@ -14,6 +14,7 @@ const { execute } = require("./executor");
 const { buildCapabilities } = require("./help-json");
 const { handleMcpRegistryCommand } = require("./mcp-local");
 const { handlePluginsCommand } = require("./plugins-command");
+const { handleServerCommand } = require("./server-command");
 const { handleHarnessOnboard, handleHarnessOffboard } = require("./harness-onboard");
 const {
   buildLocalPlan,
@@ -235,6 +236,7 @@ function renderTopLevelHelp(config) {
       console.log('  AI: supercli ask "<your natural language query>"   # LLM-powered suggestions (no execution)');
     }
     console.log("  Server: supercli --server");
+    console.log("  Server CLI: supercli server status | supercli server plugins <list|add|remove> | supercli server mcp <list|add|remove> | supercli server commands <list|add|remove> | supercli server jobs <list|prune>");
     console.log(
       "  Flags: --help | --json | --human | --compact | --schema | --help-json | --server\n",
     );
@@ -367,7 +369,15 @@ async function main() {
     }
 
     if (flags.help) {
-      displayComprehensiveHelp();
+      if (flags.human) {
+        displayComprehensiveHelp();
+      } else if (flags.json || flags.compact) {
+        output(displayJsonHelp());
+      } else if (humanMode) {
+        displayComprehensiveHelp();
+      } else {
+        output(displayJsonHelp());
+      }
       return;
     }
 
@@ -469,6 +479,7 @@ async function main() {
         ok: true,
         message: "Config synced",
         server_plugins: result.server_plugins || null,
+        cli_adapters: result.cli_adapters || null,
       });
       return;
     }
@@ -504,6 +515,18 @@ async function main() {
       return;
     }
 
+    if (positional[0] === "server") {
+      await handleServerCommand({
+        positional,
+        flags,
+        humanMode,
+        output,
+        outputHumanTable,
+        outputError,
+      });
+      return;
+    }
+
     if (positional[0] === "onboard") {
       await handleHarnessOnboard({
         positional,
@@ -985,6 +1008,64 @@ async function main() {
   }
 }
 
+function displayJsonHelp() {
+  return {
+    name: "SuperCLI",
+    description: "Universal Capability Router for AI Agents",
+    repository: "https://github.com/javimosch/supercli",
+    quick_overview: [
+      "Capabilities: namespace.resource.action commands",
+      "Plugin System: Install external CLIs as harnesses",
+      "MCP Support: Model Context Protocol server integration",
+      "Skill Docs: Agent-facing guidance in SKILL.md format",
+      "AI Integration: Natural language query execution"
+    ],
+    getting_started: [
+      "supercli help                  # List available harnesses",
+      "supercli skills teach          # Learn about skill documents",
+      "supercli plugins explore       # Browse available plugins",
+      'supercli discover --intent "<task>"  # Find capabilities for a task'
+    ],
+    core_commands: [
+      "supercli <namespace> <resource> <action>  # Execute capability",
+      "supercli inspect <ns> <res> <act>       # View command details",
+      "supercli plan <ns> <res> <act>          # Create execution plan",
+      "supercli execute <plan_id>              # Run stored plan",
+      'supercli ask "<query>"                  # LLM-powered suggestions (no execution)'
+    ],
+    plugin_management: [
+      "supercli plugins list           # Show installed plugins",
+      "supercli plugins install <name> # Install a plugin",
+      "supercli plugins explore        # Browse plugin registry"
+    ],
+    harness_onboarding: [
+      "supercli onboard                # Auto-detect and install skill",
+      "supercli onboard --detect       # List detected harnesses",
+      "supercli onboard --harness claude,cursor,opencode,windsurf",
+      "supercli offboard              # Remove installed skill"
+    ],
+    documentation: [
+      "Full README: https://github.com/javimosch/supercli#readme",
+      "Supported Harnesses: docs/supported-harnesses.md",
+      "Plugin Creation Guide: docs/plugin-harness-guide.md"
+    ],
+    output_modes: [
+      "(default)   JSON if piped, human-readable if TTY",
+      "--json      Structured JSON envelope",
+      "--human     Formatted tables and key-value output",
+      "--compact   Compressed JSON (shortened keys)"
+    ],
+    exit_codes: [
+      { code: 0, description: "success" },
+      { code: 82, description: "validation_error" },
+      { code: 85, description: "invalid_argument" },
+      { code: 92, description: "resource_not_found" },
+      { code: 105, description: "integration_error" },
+      { code: 110, description: "internal_error" }
+    ]
+  };
+}
+
 function displayComprehensiveHelp() {
   console.log("\n  ⚡ SuperCLI - Universal Capability Router for AI Agents\n");
   console.log("  Repository: https://github.com/javimosch/supercli\n");

package/docs/adapters.md

@@ -0,0 +1,159 @@
+# Custom Adapters
+
+Custom adapters are JavaScript modules that extend supercli's execution capabilities. They can be created and managed entirely through the server UI, with integrated code editing, package management, and sandboxed execution.
+
+## Overview
+
+Custom adapters allow you to define custom execution logic for commands. Unlike built-in adapters (http, openapi, mcp, shell, process), custom adapters are user-defined JavaScript functions that can:
+
+- Execute arbitrary JavaScript code in a sandboxed environment
+- Install and use NPM packages
+- Run in either server context (on the server) or CLI context (synced to local CLI)
+- Configure timeout, memory limits, and network access
+- Be tested directly from the UI
+
+## Execution Contexts
+
+Custom adapters support two execution contexts:
+
+### Server Context
+- Adapter code runs on the supercli server
+- Executes via vm2 sandbox
+- When CLI delegates to server, the adapter runs server-side
+- Ideal for adapters that need server resources or centralized execution
+
+### CLI Context
+- Adapter code syncs to local CLI via `sc sync`
+- Executes locally on the CLI machine using vm2 sandbox
+- Stored in `.supercli/adapters/` directory
+- Ideal for adapters that need local machine access (e.g., local databases, filesystem)
+
+## Creating an Adapter
+
+1. Navigate to `/adapters` in the server UI
+2. Click "+ New Adapter"
+3. Fill in the adapter details:
+   - **Name**: Unique identifier (used as adapter name in commands)
+   - **Description**: Human-readable description
+   - **Execution Context**: "server" or "cli"
+   - **Timeout**: Maximum execution time in milliseconds (default: 30000)
+   - **Memory Limit**: Maximum memory in MB (default: 128)
+   - **Network Access**: Allow NPM packages to make network requests (default: false)
+4. Write your adapter code in the CodeMirror editor
+5. Click "Save Adapter"
+
+## Adapter Code Structure
+
+Custom adapters must export an `execute` function:
+
+```javascript
+/**
+ * @name my-adapter
+ * @description My custom adapter
+ * @context server
+ */
+
+async function execute(cmd, flags, context) {
+  // cmd: Command object with namespace, resource, action, adapter, adapterConfig
+  // flags: Command arguments/flags passed at runtime
+  // context: Execution context (config, server, etc.)
+  
+  // Your custom logic here
+  const result = {
+    success: true,
+    data: { /* your output */ }
+  }
+  
+  return result
+}
+
+module.exports = { execute }
+```
+
+## Using Custom Adapters
+
+Once created, custom adapters appear in the adapter dropdown when creating/editing commands:
+
+1. Navigate to `/commands` in the server UI
+2. Create or edit a command
+3. Select your custom adapter from the "Custom" section of the adapter dropdown
+4. Configure adapterConfig as needed by your adapter
+5. Save the command
+
+The command will now use your custom adapter for execution.
+
+## Package Management
+
+Custom adapters can depend on NPM packages:
+
+1. Navigate to `/adapters/{name}/packages` for your adapter
+2. Add packages by name (e.g., `axios`, `lodash`)
+3. Click "Add Package" to install
+4. Packages are installed in a node_modules directory for that adapter
+5. Use packages in your adapter code via standard `require()`
+
+```javascript
+const axios = require('axios')
+
+async function execute(cmd, flags, context) {
+  const response = await axios.get('https://api.example.com/data')
+  return { data: response.data }
+}
+
+module.exports = { execute }
+```
+
+### Package Operations
+
+- **Add**: Install a new NPM package
+- **Remove**: Uninstall a package
+- **Prune**: Remove unused dependencies
+
+## Testing Adapters
+
+Server-context adapters can be tested directly from the UI:
+
+1. Navigate to `/adapters`
+2. Click "Test" on your adapter
+3. Provide test flags (JSON object)
+4. Click "Run Test"
+5. View execution result, duration, and any errors
+
+## CLI Sync
+
+CLI-context adapters are synced to the local CLI via `sc sync`:
+
+```bash
+export SUPERCLI_SERVER=http://localhost:3000
+sc sync
+```
+
+During sync:
+- CLI-context adapters are fetched from the server
+- Adapter source code is written to `.supercli/adapters/{name}.js`
+- Metadata header is added to the file (timeout, memory, network settings)
+- Sync result shows total, synced, and failed counts
+
+## Security
+
+Custom adapters run in a vm2 sandbox with:
+
+- **Timeout**: Prevents infinite loops (configurable per adapter)
+- **Memory limits**: Prevents memory exhaustion (configurable per adapter)
+- **Network control**: Optional network access for NPM packages
+- **Console sandboxing**: Console output is suppressed in sandbox
+
+## API Endpoints
+
+The server exposes the following API endpoints for custom adapters:
+
+- `GET /api/adapters` - List all adapters
+- `POST /api/adapters` - Create new adapter
+- `GET /api/adapters/:name` - Get adapter metadata
+- `GET /api/adapters/:name/source` - Get adapter source code
+- `PUT /api/adapters/:name` - Update adapter
+- `DELETE /api/adapters/:name` - Delete adapter
+- `POST /api/adapters/:name/test` - Test adapter execution
+- `POST /api/adapters/:name/packages` - Add package
+- `DELETE /api/adapters/:name/packages/:package` - Remove package
+- `POST /api/adapters/execute` - Execute adapter (for CLI delegation)

package/docs/changelog-2026-04.html

@@ -155,6 +155,9 @@
             <li>Add googlews plugin for Google Workspace CLI</li>
             <li>Add domain-check plugin for domain availability</li>
             <li>Add ghgrab plugin for GitHub file download</li>
+            <li>Add server dashboard with command overview and job monitoring</li>
+            <li>Add adapter management UI with package installation and configuration</li>
+            <li>Add 12 new plugins: biome, bore, ccf-deadlines, code2prompt, dua-cli, forever, gitmoji-cli, quarto, readme-md-generator, vale, volta, wgcf</li>
           </ul>
         </section>
 
@@ -166,6 +169,16 @@
             <li>Remove humanenv-usage skill due to security concerns</li>
             <li>Clarify that ask command provides suggestions only, not execution; update help text and metadata for accuracy</li>
             <li>Align SKILL.md format with frontmatter standard</li>
+            <li>Add vm2 dependency for executor sandboxing</li>
+          </ul>
+        </section>
+
+        <section class="changelog-section">
+          <h2 class="text-2xl font-display font-semibold text-amber-400 mb-4 flex items-center gap-2">
+            <span>⚠️</span> Deprecations
+          </h2>
+          <ul class="space-y-2 text-slate-300">
+            <li><strong>builtin adapter removed</strong> - Migrated beads, gwc, and commiat plugins to use isolated <code>install-guidance.json</code> files with shell adapter. Removed builtin from server UI dropdown, adapter registry, validation schema, and all test references.</li>
           </ul>
         </section>
 
@@ -199,6 +212,8 @@
             <li>Update plugin discovery and registration documentation with new meta.json convention</li>
             <li>Add supercli skills and plugins documentation with usage examples</li>
             <li>Add FFmpeg plugin quickstart guide with commands and examples</li>
+            <li>Add server documentation with dashboard and adapter management guides</li>
+            <li>Add adapters documentation with usage examples</li>
           </ul>
         </section>