npm - superacli - Versions diffs - 1.0.1 → 1.1.2 - Mend

superacli 1.0.1 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (389) hide show

package/docs/index.html ADDED Viewed

@@ -0,0 +1,164 @@
+<!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>
+        <div class="flex flex-wrap justify-center gap-4">
+          <a class="btn btn-primary px-6" href="./docs.html#getting-started">Start Building</a>
+          <a class="btn btn-outline border-brand-400/50 text-brand-200 px-6" href="./docs.html">Explore the Docs</a>
+          <a class="btn btn-ghost text-slate-300 px-6" href="https://github.com/opencode-somewhere/dcli" 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>
+    </main>
+    <footer class="border-t border-slate-800/60 py-8 text-center text-sm text-slate-400">
+      <p>© <span id="year"></span> supercli — Universal Skill Router for AI Agents.</p>
+      <div class="flex justify-center gap-4 mt-3">
+        <a class="underline" href="./docs.html#getting-started">Start</a>
+        <a class="underline" href="./docs.html">Docs</a>
+        <a class="underline" href="./docs.html#skill-vision">Skill vision</a>
+      </div>
+    </footer>
+    <script>
+      document.getElementById('year').textContent = new Date().getFullYear();
+    </script>
+  </body>
+</html>

package/docs/plugin-examples.md ADDED Viewed

@@ -0,0 +1,397 @@
+# Plugin Manifest Examples
+Real-world examples of plugin harnesses you can use as reference for creating your own.
+## Example 1: beads - Wrapped Commands
+The beads plugin demonstrates selective command wrapping. It exposes key beads_rust commands through dcli's interface.
+```json
+{
+  "name": "beads",
+  "version": "0.1.0",
+  "description": "Wrap beads_rust (br) issue tracking commands",
+  "source": "https://github.com/Dicklesworthstone/beads_rust",
+  "checks": [
+    { "type": "binary", "name": "br" }
+  ],
+  "commands": [
+    {
+      "namespace": "beads",
+      "resource": "install",
+      "action": "steps",
+      "description": "Show beads_rust installation steps for LLM automation",
+      "adapter": "builtin",
+      "adapterConfig": { "builtin": "beads_install_steps" },
+      "args": []
+    },
+    {
+      "namespace": "beads",
+      "resource": "workspace",
+      "action": "init",
+      "description": "Initialize beads workspace in current repository",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "br",
+        "baseArgs": ["init"],
+        "parseJson": false,
+        "missingDependencyHelp": "Run: supercli beads install steps"
+      },
+      "args": []
+    },
+    {
+      "namespace": "beads",
+      "resource": "issue",
+      "action": "create",
+      "description": "Create a beads issue",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "br",
+        "baseArgs": ["create"],
+        "positionalArgs": ["title"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Run: supercli beads install steps"
+      },
+      "args": [
+        { "name": "title", "type": "string", "required": true },
+        { "name": "type", "type": "string", "required": false },
+        { "name": "priority", "type": "integer", "required": false },
+        { "name": "description", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "beads",
+      "resource": "issue",
+      "action": "list",
+      "description": "List beads issues",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "br",
+        "baseArgs": ["list"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Run: supercli beads install steps"
+      },
+      "args": [
+        { "name": "status", "type": "string", "required": false },
+        { "name": "priority", "type": "string", "required": false },
+        { "name": "assignee", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "beads",
+      "resource": "issue",
+      "action": "update",
+      "description": "Update a beads issue",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "br",
+        "baseArgs": ["update"],
+        "positionalArgs": ["id"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Run: supercli beads install steps"
+      },
+      "args": [
+        { "name": "id", "type": "string", "required": true },
+        { "name": "status", "type": "string", "required": false },
+        { "name": "priority", "type": "integer", "required": false },
+        { "name": "assignee", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "beads",
+      "resource": "issue",
+      "action": "close",
+      "description": "Close a beads issue",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "br",
+        "baseArgs": ["close"],
+        "positionalArgs": ["id"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Run: supercli beads install steps"
+      },
+      "args": [
+        { "name": "id", "type": "string", "required": true },
+        { "name": "reason", "type": "string", "required": false }
+      ]
+    }
+  ]
+}
+```
+**Key Points**:
+- Uses wrapped commands (selective exposure)
+- JSON parsing for automation
+- Installation step handling via builtin adapter
+- Clear error messages with help guidance
+- Multiple related commands under same namespace/resource
+**Usage Examples**:
+```bash
+supercli beads issue create --title "Fix authentication bug" --priority 0
+supercli beads issue list --status open
+supercli beads issue update dcli-15q --status in_progress
+supercli beads issue close dcli-15q --reason "completed"
+```
+---
+## Example 2: gwc - Full Passthrough
+The Google Workspace CLI plugin demonstrates full passthrough, giving access to all gws commands without selective wrapping.
+```json
+{
+  "name": "gwc",
+  "version": "0.1.0",
+  "description": "Wrap Google Workspace CLI (gws) with passthrough support",
+  "source": "https://github.com/googleworkspace/cli",
+  "checks": [
+    { "type": "binary", "name": "gws" }
+  ],
+  "commands": [
+    {
+      "namespace": "gwc",
+      "resource": "install",
+      "action": "steps",
+      "description": "Show gws installation steps for LLM automation",
+      "adapter": "builtin",
+      "adapterConfig": { "builtin": "gwc_install_steps" },
+      "args": []
+    },
+    {
+      "namespace": "gwc",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough to gws CLI",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "gws",
+        "passthrough": true,
+        "parseJson": true,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Run: supercli gwc install steps"
+      },
+      "args": []
+    }
+  ]
+}
+```
+**Key Points**:
+- Single `_` wildcard command captures all gws functionality
+- Longer timeout for complex operations
+- Passthrough mode passes all arguments directly
+- Builtin adapter for installation guidance
+- Minimal manifest for maximum CLI access
+**Usage Examples**:
+```bash
+# Any gws command works transparently
+supercli gwc drive files list
+supercli gwc drive files get <file-id>
+supercli gwc sheets values get <sheet-id> A1:B10
+supercli gwc gmail messages list --query "from:user@example.com"
+supercli gwc docs get <doc-id>
+```
+---
+## Example 3: commiat - Simple Passthrough
+A minimal passthrough plugin for commit automation.
+```json
+{
+  "name": "commiat",
+  "version": "0.1.0",
+  "description": "Wrap commiat CLI with passthrough support",
+  "source": "https://www.npmjs.com/package/commiat",
+  "checks": [
+    { "type": "binary", "name": "commiat" }
+  ],
+  "commands": [
+    {
+      "namespace": "commiat",
+      "resource": "install",
+      "action": "steps",
+      "description": "Show commiat installation steps for LLM automation",
+      "adapter": "builtin",
+      "adapterConfig": { "builtin": "commiat_install_steps" },
+      "args": []
+    },
+    {
+      "namespace": "commiat",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough to commiat CLI",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "commiat",
+        "passthrough": true,
+        "parseJson": true,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Run: supercli commiat install steps"
+      },
+      "args": []
+    }
+  ]
+}
+```
+**Usage Examples**:
+```bash
+supercli commiat validate --commit-msg "fix: resolve bug #123"
+supercli commiat generate --changes src/file.js
+supercli commiat suggest
+```
+---
+## Example 4: Custom Plugin Template
+A template for creating your own wrapped command plugin:
+```json
+{
+  "name": "my-cli",
+  "version": "0.1.0",
+  "description": "Wrap my-cli with dcli integration",
+  "source": "https://github.com/user/my-cli",
+  "tags": ["category", "keyword"],
+  "author": "Your Name",
+  "checks": [
+    { "type": "binary", "name": "my-cli" }
+  ],
+  "commands": [
+    {
+      "namespace": "my-cli",
+      "resource": "feature",
+      "action": "list",
+      "description": "List features",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "my-cli",
+        "baseArgs": ["feature", "list"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "timeout_ms": 5000,
+        "missingDependencyHelp": "Install my-cli: npm install -g my-cli"
+      },
+      "args": [
+        {
+          "name": "filter",
+          "type": "string",
+          "required": false,
+          "description": "Filter by feature name"
+        }
+      ]
+    },
+    {
+      "namespace": "my-cli",
+      "resource": "feature",
+      "action": "create",
+      "description": "Create a new feature",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "my-cli",
+        "baseArgs": ["feature", "create"],
+        "positionalArgs": ["name"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "timeout_ms": 5000,
+        "missingDependencyHelp": "Install my-cli: npm install -g my-cli"
+      },
+      "args": [
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "Feature name"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "required": false,
+          "description": "Feature description"
+        }
+      ]
+    }
+  ]
+}
+```
+**Customization**:
+- Replace `my-cli` with your CLI name
+- Adjust `baseArgs` to match your CLI structure
+- Add/remove commands as needed
+- Update the binary name in `checks`
+- Add tags for discoverability
+---
+## Comparison: Wrapped vs. Passthrough
+| Aspect | Wrapped | Passthrough |
+|--------|---------|-------------|
+| **Definition** | Selectively expose specific commands | Expose all commands transparently |
+| **Best For** | Well-structured, stable CLIs | Large CLI with many commands |
+| **Manifest Size** | Larger (document each command) | Minimal (one wildcard) |
+| **Control** | Fine-grained control | Full CLI access |
+| **Examples** | beads (specific issue ops) | gwc (full Workspace access) |
+| **Maintenance** | More effort as CLI grows | Less maintenance |
+| **Discoverability** | Excellent (all exposed) | Good (passthrough handled) |
+**Choose wrapped when**:
+- The CLI has well-defined, stable commands
+- You want to curate the user experience
+- Different commands have different argument patterns
+- You want to provide rich documentation per command
+**Choose passthrough when**:
+- The CLI is stable and comprehensive
+- It has many commands that change frequently
+- You want full access without reimplementation
+- The CLI's interface is consistent
+---
+## Testing Plugin Manifests
+Validate your plugin manifest before installing:
+```bash
+# Syntax check
+jq . my-plugin/plugin.json
+# Schema validation (if schema available)
+ajv validate -s plugin-schema.json -d my-plugin/plugin.json
+# Install locally
+supercli plugins install ./my-plugin
+# Test a command
+supercli my-plugin resource action --test-arg value
+# Inspect command
+supercli inspect my-cli resource action
+# Show plugin health
+supercli plugins doctor my-cli
+```
+---
+## Next Steps
+1. **Choose your approach**: Wrapped commands or passthrough?
+2. **Create your manifest**: Use examples above as reference
+3. **Test locally**: Use `supercli plugins install ./path`
+4. **Iterate**: Refine based on usage feedback
+5. **Publish**: Share with the community via GitHub
+See [plugin-harness-guide.md](plugin-harness-guide.md) for detailed documentation.