superacli 1.0.1 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
-# SuperACLI - SuperCLI - DCLI - Super Agentic CLI
+# supercli — Universal Skill Router for AI Agents
 
-Config-driven, AI-friendly CLI that dynamically generates commands from cloud configuration.
+Discover and execute skills across CLIs, APIs, MCP servers, workflows, and custom automations through a single agent-friendly interface.
 
 ## BIN Aliases
 
@@ -9,27 +9,93 @@ Config-driven, AI-friendly CLI that dynamically generates commands from cloud co
 - scli (Brand smaller)
 - superacli (What was available) (Super Agent/ic CLI)
 
+## What Is a Skill Layer?
+
+Everything the system exposes becomes a **skill**:
+
+| Source | Turns into |
+| --- | --- |
+| CLI command | Skill |
+| OpenAPI endpoint | Skill |
+| MCP tool | Skill |
+| HTTP request | Skill |
+| Workflow / plan step | Skill |
+
+Agents query the skill layer once, and supercli handles discovery, routing, and execution across every connected ecosystem. Skills are addressable (e.g., `beads.issue.list` or `docker.container.ps`), searchable, and consistently described so agents never need bespoke integrations per tool.
+
+### Core Responsibilities
+
+1. **Discovery** – build a real-time catalog of skills across bundled harnesses, adapters, and plugins.
+2. **Routing** – resolve the right execution adapter (CLI, HTTP, MCP, custom runtime) from an incoming skill ID.
+3. **Execution** – normalize inputs/outputs, enforce envelopes, and surface deterministic status codes.
+4. **Extension** – let teams add new skills by dropping in manifests, OpenAPI specs, or plugin harnesses.
+
+Example skill executions:
+
+```bash
+supercli beads issue list              # Calls beads skill adapter
+supercli gwc drive files list          # Calls Google Workspace adapter
+supercli docker container ps           # Calls Docker plugin (when installed)
+```
+
+## Skill Sources
+
+supercli generates skills from six primary channels:
+
+- **Bundled Harnesses** – beads (tasks/issues), gwc (Google Workspace), commiat (commit automation)
+- **Built-in Adapters** – OpenAPI specs, raw HTTP integrations, MCP (Model Context Protocol) servers
+- **Plugin Harnesses** – community or internal CLIs installed via `supercli plugins install`
+- **AI & Plans** – natural-language `ask` commands create execution DAGs composed of skills
+- **Workflows** – repeatable plans and stored executions referenced as skills
+- **Future Extensions** – popular CLIs such as gh, aws, docker, kubectl, terraform, etc.
+
 ## Architecture
 
 ```
-         Web UI (EJS + Vue3 + DaisyUI)
-                    │
-                REST API
-                    │
-           NodeJS + MongoDB
-                    │
-              CLI Runtime
-                    │
-          ┌────────┼────────┐
-       OpenAPI    HTTP     MCP
-       Adapter   Adapter  Adapter
+           Agents / Humans
+                  │
+            supercli runtime
+                  │
+            Skill Discovery Layer
+                  │
+             Skill Router Core
+                  │
+   ┌──────────────┼──────────────┬───────────────┐
+   │              │              │               │
+ CLI Harnesses  OpenAPI / HTTP  MCP Servers   Workflows / Plugins
 ```
 
+The router intelligently:
+- **Discovers** available skills from every adapter and caches metadata for fast lookup
+- **Routes** commands to the correct harness based on namespace and capability metadata
+- **Executes** with unified error handling, envelopes, and output formatting
+- **Surfaces** machine-readable descriptions so agents can plan against the skill graph
+
+## Why Skills Matter
+
+Traditional CLIs force agents to learn tool-specific syntax. supercli replaces that effort with a discoverable skill graph so agents can:
+
+- Search (`supercli skills search "database"`) to find relevant capabilities instantly
+- Inspect (`supercli skills get beads.issue.create`) to pull schema-rich metadata
+- Compose (`supercli plan …`) to build DAGs out of skills without writing glue code
+- Delegate execution to the same router regardless of whether the source is a CLI, API, or MCP tool
+
+## Skill Mesh Vision
+
+supercli is steadily evolving toward a broader **skill mesh** that provides discovery, routing, execution, composition, and governance across every tool in the stack. Near-term focus areas include:
+
+- **Deeper skill registry** with richer metadata, tagging, and policy controls
+- **Graph-native discovery** so agents can traverse related skills and capability clusters
+- **Execution DAG observability** for multi-skill plans with retries and status streaming
+- **Agent endpoints** that expose the router over HTTP/webhooks for direct agent access beyond the CLI
+
+These directional goals keep the README aligned with the system’s trajectory without overpromising unshipped features.
+
 ## Quick Start
 
 ```bash
 # Quick usage (no install, local-only by default)
-npx supercli help
+npx supercli help                      # List available harnesses
 npx supercli skills teach
 
 # Install
@@ -46,57 +112,88 @@ npm start
 # 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]
+# CLI usage - Multi-harness routing
+supercli help                          # List all harnesses
+supercli beads                         # List beads skills
+supercli gwc                           # List Google Workspace skills
+supercli beads issue list              # Execute beads command
+supercli gwc drive files list          # Execute Google Workspace command
 
-# Optional: sync commands from a remote SuperCLI server
-export SUPERCLI_SERVER=http://localhost:3000
-node cli/supercli.js sync
+# Skills discovery across harnesses
+supercli skills list                   # All skills from all harnesses
+supercli skills search "database"      # Full-text search across harnesses
+
+# AI-driven multi-harness execution
+supercli ask "show my tasks and recent commits"
+
+# Manage plugin harnesses
+supercli plugins list
+supercli plugins explore               # Browse available plugins
+supercli plugins install commiat       # Install community plugin
 ```
 
 ## CLI Usage
 
+### Multi-Harness Routing
+
 ```bash
+# Basic harness routing
+supercli <harness>                          # List skills in harness
+supercli <harness> <skill-group> <action>   # Execute skill
+
+# Examples across different harnesses
+supercli beads issue create --title "Fix bug"
+supercli beads issue list --status open
+supercli gwc drive files list --limit 10
+supercli commiat validate --commit-msg "my message"
+
 # Discovery
-supercli help                              # List namespaces
-supercli <namespace>                       # List resources
-supercli <namespace> <resource>            # List actions
+supercli help                              # List all harnesses
+supercli skills list                       # List all skills from all harnesses
+supercli skills search --harness beads     # Search within harness
+supercli skills search "database"          # Full-text search across harnesses
 
 # Inspection
-supercli inspect <ns> <res> <act>          # Command details + schema
-supercli <ns> <res> <act> --schema         # Input/output schema
+supercli inspect beads issue create        # Command details + schema
+supercli skills get beads.issue.create     # Get skill metadata
 
 # 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
+supercli beads issue create --title "New task"      # Standard execution
+supercli beads issue list --json                    # JSON output
+supercli beads issue list --compact                 # Token-optimized output
 
-# 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
+# Plans (DAG execution)
+supercli plan beads issue create --title "Task"     # Dry-run execution plan
+supercli execute <plan_id>                         # Execute stored plan
 
 # 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
+export OPENAI_BASE_URL=https://api.openai.com/v1   # Enable AI resolution
+supercli ask "list my tasks and summarize them"     # Execute across harnesses
 
 # Config & Server
-supercli sync                              # Sync local cache from SUPERCLI_SERVER (when set)
+supercli sync                              # Sync local cache from server
 supercli config show                       # Show cache info
-supercli --server                          # Start the SuperCLI backend server directly
+supercli --server                          # Start backend server
+
+# Plugin Harness Management
+supercli plugins list                      # List installed harnesses
+supercli plugins explore                   # Browse plugin registry
+supercli plugins explore --tags git,ai     # Search registry by tags
+supercli plugins install commiat           # Install from registry
+supercli plugins install --git https://github.com/org/repo.git --ref main
+supercli plugins show commiat              # Show harness details
+supercli plugins doctor commiat            # Check harness health
+```
+
+### Built-in Adapters
 
+```bash
 # 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)
+# Stdio MCP demo
 node examples/mcp-stdio/install-demo.js
 supercli ai text summarize --text "Hello world" --json
 
@@ -118,6 +215,85 @@ supercli --help-json                       # Machine-readable capabilities
 | `--human`   | Formatted tables and key-value output     |
 | `--compact` | Compressed JSON (shortened keys)          |
 
+## Plugins as Harnesses
+
+A **plugin harness** bridges dcli to an external CLI tool. Each plugin:
+- Defines a manifest (`plugin.json`) with available commands
+- Maps CLI arguments to dcli's command structure
+- Supports command wrapping, passthrough, remote skills catalogs, or any combination of those patterns
+- Includes dependency checks and installation guidance
+
+### Currently Supported Harnesses
+
+**Bundled with dcli:**
+- **beads** (`br`) — Task/issue management via beads_rust
+- **gwc** (`gws`) — Google Workspace CLI with full passthrough
+- **commiat** — Commit automation with full passthrough
+
+**Built-in Adapters:**
+- **OpenAPI** — Generic OpenAPI spec resolution
+- **HTTP** — Raw HTTP requests
+- **MCP** — Model Context Protocol tools (stdio and SSE/HTTP)
+
+**Popular Community Harnesses** (via plugins):
+- GitHub CLI (`gh`)
+- AWS CLI (`aws`)
+- Google Cloud CLI (`gcloud`)
+- Azure CLI (`az`)
+- Docker (`docker`)
+- Kubernetes (`kubectl`)
+- Terraform (`terraform`)
+- npm, pip, cargo (package managers)
+- git, git-cliff (version control)
+- And many more...
+
+See [docs/supported-harnesses.md](docs/supported-harnesses.md) for the complete list.
+
+### Installing Plugin Harnesses
+
+```bash
+# From built-in registry
+supercli plugins install commiat
+
+# From GitHub repository
+supercli plugins install --git https://github.com/org/plugin-harness.git --ref main
+
+# Local directory (development)
+supercli plugins install ./path/to/plugin
+
+# Browse registry
+supercli plugins explore
+supercli plugins explore --tags "github,ai"
+```
+
+### Creating Your Own Harness
+
+Turn any CLI into a dcli harness:
+
+1. Create a `plugin.json` manifest defining commands
+2. Specify wrapping or passthrough behavior
+3. Include dependency checks and help guidance
+4. Test with `supercli plugins install ./path`
+5. Publish to registry with `supercli plugins publish`
+
+See [docs/plugin-harness-guide.md](docs/plugin-harness-guide.md) for detailed instructions and examples.
+
+### Planned Harnesses
+
+The dcli community is actively developing plugins for popular CLIs:
+
+- **GitHub Ecosystem**: gh (GitHub CLI), GitHub Actions workflows
+- **Cloud Platforms**: aws, gcloud, az CLI tools
+- **Container & DevOps**: docker, docker-compose, kubectl, helm, terraform
+- **Version Control**: git, git-cliff, commitizen
+- **Package Managers**: npm, pip, cargo, pnpm, yarn
+- **AI/ML Tools**: huggingface, langchain, LLM CLIs
+- **Infrastructure**: ansible, pulumi
+- **Monitoring**: datadog, prometheus CLIs
+- Many others based on community requests
+
+Want to contribute a plugin harness? [See plugin guide](docs/plugin-harness-guide.md) and submit to the registry!
+
 ## Output Envelope
 
 Every command returns a deterministic envelope:
@@ -158,11 +334,16 @@ Every command returns a deterministic envelope:
 | GET    | `/api/jobs`                   | Execution history        |
 | GET    | `/api/jobs/stats`             | Aggregate stats          |
 
-## Adapters
+## Built-in Harnesses & Adapters
+
+The following are built-in to dcli (no plugins required):
 
 - **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)
+- **beads** — Task/issue management (if br is installed)
+- **gwc** — Google Workspace (if gws is installed)
+- **commiat** — Commit automation (if commiat is installed)
 
 ## Tech Stack
 
@@ -170,6 +351,8 @@ Every command returns a deterministic envelope:
 - Pluggable KV Storage (Local JSON files by default, MongoDB optional)
 - EJS + Vue3 CDN + Tailwind CDN + DaisyUI CDN
 - Zero build tools
+- Extensible plugin system for registering new harnesses
+- Support for OpenAPI, HTTP, MCP, and custom CLI adapters
 
 ## Contributors
 

package/__tests__/adapter-schema.test.js

@@ -0,0 +1,119 @@
+const { validateAdapterConfig } = require("../cli/adapter-schema")
+
+describe("adapter-schema", () => {
+  test("accepts valid process adapter", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "process",
+      adapterConfig: { command: "br", baseArgs: ["list"], timeout_ms: 5000 }
+    })).not.toThrow()
+  })
+
+  test("ignores unknown adapters", () => {
+    expect(() => validateAdapterConfig({ adapter: "custom" })).not.toThrow()
+  })
+
+  test("rejects non-object adapterConfig", () => {
+    expect(() => validateAdapterConfig({ adapter: "http", adapterConfig: "string" })).toThrow(/requires adapterConfig object/)
+  })
+
+  test("rejects invalid common types", () => {
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", parseJson: "yes" } })).toThrow(/must be boolean/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", cwd: 123 } })).toThrow(/must be string/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", safetyLevel: true } })).toThrow(/must be string/)
+  })
+
+  test("timeout_ms validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", timeout_ms: "none" } })).toThrow(/positive number/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", timeout_ms: -1 } })).toThrow(/positive number/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", timeout_ms: 20000 } })).toThrow(/cannot exceed 15000ms/)
+  })
+
+  test("http adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "http", adapterConfig: { url: 123 } })).toThrow(/requires adapterConfig.url/)
+    expect(() => validateAdapterConfig({ adapter: "http", adapterConfig: { url: "u", method: 1 } })).toThrow(/method must be string/)
+    expect(() => validateAdapterConfig({ adapter: "http", adapterConfig: { url: "u" } })).not.toThrow()
+  })
+
+  test("openapi adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "openapi", adapterConfig: { spec: 1 } })).toThrow(/requires adapterConfig.spec/)
+    expect(() => validateAdapterConfig({ adapter: "openapi", adapterConfig: { spec: "s", operationId: 1 } })).toThrow(/requires adapterConfig.operationId/)
+    expect(() => validateAdapterConfig({ adapter: "openapi", adapterConfig: { spec: "s", operationId: "o" } })).not.toThrow()
+  })
+
+  test("mcp adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "mcp", adapterConfig: { tool: 1 } })).toThrow(/requires adapterConfig.tool/)
+    expect(() => validateAdapterConfig({ adapter: "mcp", adapterConfig: { tool: "t" } })).toThrow(/requires one source/)
+    expect(() => validateAdapterConfig({ adapter: "mcp", adapterConfig: { tool: "t", server: "s" } })).not.toThrow()
+  })
+
+  test("process adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: 1 } })).toThrow(/requires adapterConfig.command/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", baseArgs: "none" } })).toThrow(/must be an array/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", positionalArgs: "none" } })).toThrow(/must be an array/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", passthrough: "yes" } })).toThrow(/must be boolean/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", flagsBeforePositionals: "yes" } })).toThrow(/must be boolean/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", missingDependencyHelp: 1 } })).toThrow(/must be string/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", env: [] } })).toThrow(/must be object/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", stream: true } })).toThrow(/must be string/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", stream: "sse" } })).toThrow(/must be 'jsonl'/)
+    expect(() => validateAdapterConfig({ adapter: "process", adapterConfig: { command: "a", stream: "jsonl" } })).not.toThrow()
+  })
+
+  test("builtin adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "builtin", adapterConfig: { builtin: 1 } })).toThrow(/requires adapterConfig.builtin/)
+    expect(() => validateAdapterConfig({ adapter: "builtin", adapterConfig: { builtin: "b" } })).not.toThrow()
+  })
+
+  test("shell adapter validation", () => {
+    expect(() => validateAdapterConfig({ adapter: "shell", adapterConfig: { script: 1, unsafe: true } })).toThrow(/requires adapterConfig.script/)
+    expect(() => validateAdapterConfig({ adapter: "shell", adapterConfig: { script: "s", unsafe: true, shell: 1 } })).toThrow(/shell must be string/)
+    expect(() => validateAdapterConfig({ adapter: "shell", adapterConfig: { script: "s", unsafe: true, env: "none" } })).toThrow(/must be object/)
+  })
+
+  test("rejects interactive config", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "http",
+      adapterConfig: { url: "https://example.com", non_interactive: false }
+    })).toThrow(/Interactive command execution is not supported/)
+  })
+
+  test("requires unsafe true for shell adapter", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "shell",
+      adapterConfig: { script: "echo hi" }
+    })).toThrow(/unsafe=true/)
+  })
+
+  test("accepts shell adapter with unsafe true", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "shell",
+      adapterConfig: { script: "echo '{\"ok\":true}'", unsafe: true, timeout_ms: 1000 }
+    })).not.toThrow()
+  })
+
+  test("accepts process safety metadata", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "process",
+      adapterConfig: {
+        command: "docker",
+        safetyLevel: "guarded",
+        interactiveFlags: ["-i", "--interactive"],
+        requiresInteractive: false
+      }
+    })).not.toThrow()
+  })
+
+  test("rejects non-array interactiveFlags", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "process",
+      adapterConfig: { command: "docker", interactiveFlags: "--tty" }
+    })).toThrow(/interactiveFlags must be an array/)
+  })
+
+  test("rejects non-string interactiveFlags values", () => {
+    expect(() => validateAdapterConfig({
+      adapter: "process",
+      adapterConfig: { command: "docker", interactiveFlags: ["--tty", 42] }
+    })).toThrow(/interactiveFlags values must be strings/)
+  })
+})