superacli 1.1.0 → 1.1.2

package/cli/supercli.js

@@ -100,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) {
@@ -574,7 +586,13 @@ async function main() {
             __rawArgs: passthrough.passthroughArgs,
             __passthroughInteractive: humanMode && isTTY,
           },
-          { server: SERVER || "", config },
+          {
+            server: SERVER || "",
+            config,
+            onStreamEvent: passthrough.command.adapterConfig && passthrough.command.adapterConfig.stream === "jsonl"
+              ? makeStreamEmitter(`${passthrough.namespace}.passthrough`)
+              : null,
+          },
         );
         const duration = Date.now() - start;
         const envelope = {
@@ -710,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/plugins.md

@@ -39,4 +39,6 @@ Default is `fail`.
 - `plugins list` shows installed plugins.
 - `plugins explore` shows discoverable plugins from `plugins/plugins.json`.
 - `plugins install` supports local path, registry name, and direct remote git manifest installs.
+- Plugin manifests can define `post_install` hooks (`script`, optional `runtime`, optional `timeout_ms`) that execute from the plugin folder after install.
 - `agency-agents` is a bundled zero-command plugin. Installing it adds a remote skills provider named `agency-agents` and refreshes the local skills catalog.
+- `visual-explainer` is a bundled zero-command plugin. Installing it adds a remote skills provider named `visual-explainer` sourced from normalized markdown skills in `javimosch/visual-explainer` and refreshes the local skills catalog.

package/docs/skills/cline-non-interactive/SKILL.md

@@ -0,0 +1,59 @@
+---
+skill_name: cline-non-interactive
+description: Use the supercli cline harness for unattended, JSON-streamed Cline execution.
+tags: cline,agents,automation,streaming
+---
+
+# Cline Non-Interactive
+
+Use this skill when you want to delegate a task to the local Cline CLI through SuperCLI in a way that is safe for agents and easy to parse.
+
+## Preferred Commands
+
+Use the wrapped commands first:
+
+```bash
+supercli cline task run --prompt "<task>" --cwd <path> --timeout 30 --json
+supercli cline task plan --prompt "<task>" --cwd <path> --timeout 30 --json
+```
+
+- `cline task run` uses Cline act mode with `-a -y --json`
+- `cline task plan` uses Cline plan mode with `-p -y --json`
+- both commands emit streamed JSON event envelopes before a final completion envelope
+
+## When To Use Which
+
+- use `cline task run` when you want Cline to execute the task autonomously
+- use `cline task plan` when you want a plan-first answer or want to inspect the intended approach before acting
+- use passthrough only if you need a Cline flag or subcommand that the wrapped commands do not expose yet
+
+## Output Contract
+
+When `--json` is used on the SuperCLI command, output is newline-delimited:
+
+1. zero or more streamed event envelopes:
+
+```json
+{"version":"1.0","command":"cline.task.run","stream":true,"data":{"type":"say","say":"task","text":"..."}}
+```
+
+2. one final summary envelope:
+
+```json
+{"version":"1.0","command":"cline.task.run","duration_ms":1234,"data":{"streamed":true,"stream":"jsonl","event_count":4,"last_event":{"type":"say","say":"completion_result","text":"..."}}}
+```
+
+## Safety Defaults
+
+- always pass `--cwd` so Cline operates in the intended workspace
+- prefer `--timeout` for unattended runs
+- avoid secrets in prompts because they can appear in logs or downstream tool output
+- use a clean branch or a clearly scoped task when running autonomous edit flows
+
+## Examples
+
+```bash
+supercli cline task run --prompt "List files with more LOC in cwd" --cwd . --timeout 30 --json
+supercli cline task plan --prompt "Plan how to split SearchForm.vue below 500 LOC" --cwd . --json
+supercli cline cli version --json
+```

package/docs/skills-catalog.md

@@ -44,3 +44,38 @@ supercli skills get agency-agents:engineering.engineering-frontend-developer
 `agency-agents` maps skills 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.
+
+## Remote Provider Example: visual-explainer
+
+```bash
+supercli plugins install visual-explainer --json
+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
+`plugins/visual-explainer-normalized` in `javimosch/visual-explainer`.
+
+## Remote Provider Example: nullclaw
+
+```bash
+supercli plugins install nullclaw --json
+supercli skills list --catalog --provider nullclaw --json
+supercli skills get nullclaw:root.agents
+supercli skills get nullclaw:docs.en.commands
+```
+
+`nullclaw` indexes curated upstream markdown from `nullclaw/nullclaw` so agents can pull
+project overview, operator docs, security guidance, and implementation notes on demand.
+It also exposes the local `nullclaw` binary through wrapped commands and full passthrough.
+
+## Local Repo Skill Example: cline-non-interactive
+
+```bash
+supercli skills sync --json
+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
+`supercli cline task run` and `supercli cline task plan` commands for unattended Cline usage.

package/docs/visual-overview.md

@@ -0,0 +1,21 @@
+# dcli visual overview
+
+The architecture blueprint for dcli lives in the self-contained HTML artifact generated via the `visual-explainer` plugin.
+
+- **File**: `~/.agent/diagrams/dcli-visual-architecture.html`
+- **Open**: `xdg-open ~/.agent/diagrams/dcli-visual-architecture.html`
+- **Source**: Created with `supercli skills get visual-explainer:visual-explainer.skill` guidance.
+
+## What the HTML covers
+
+1. **Skill routing pipeline** – Mermaid snapshot of `cli/supercli.js`, the skills catalog, plugin harness manager, server APIs, and adapters. Includes zoom, pan, and expand controls per the visual-explainer requirements.
+2. **Runtime pillars** – Card grid summarizing the CLI runtime, catalog, plugin manager, and Express backend with file references such as `cli/plugins-manager.js` and `server/app.js`.
+3. **Plugin & skill lifecycle** – Timeline of registry discovery → install → catalog sync → execution, tying back to commands like `supercli skills list --catalog`.
+4. **Capability matrix** – HTML table comparing bundled harnesses, built-in adapters, remote providers, and the server API, highlighting when to use commands such as `supercli sync`.
+5. **Operational cues** – Details blocks that document behaviors like plan building and storage fallbacks.
+
+## Regenerating or extending
+
+1. Ensure the `visual-explainer` provider is installed (`supercli plugins install visual-explainer`).
+2. Re-open the reference templates (`visual-explainer:visual-explainer.templates.architecture`, `...templates.data-table`, etc.) to stay within the mandated aesthetics.
+3. Update the HTML under `~/.agent/diagrams/` and refresh this markdown with any new sections you add. Keep this file as the only place in the repo that references the artifact’s path.

package/jest.config.js

@@ -6,9 +6,12 @@ module.exports = {
   coverageProvider: "v8",
   collectCoverageFrom: [
     "cli/**/*.js",
+    "server/**/*.js",
     "!cli/supercli.js",
-    "!cli/adapters/**"
+    "!cli/plugin-agency-agents.js",
+    "!server/public/**"
   ],
+  testPathIgnorePatterns: ["/node_modules/", "/ref-btcbot/"],
   coverageDirectory: "coverage",
   coverageReporters: ["text", "lcov", "clover"],
   coverageThreshold: {

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "superacli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "main": "server/app.js",
   "bin": {
     "dcli": "./cli/supercli.js",
     "scli": "./cli/supercli.js",
     "superacli": "./cli/supercli.js",
-    "supercli": "./cli/supercli.js"
+    "supercli": "./cli/supercli.js",
+    "sc":"./cli/supercli.js"
   },
   "scripts": {
     "start": "node server/app.js",
     "dev": "node server/app.js",
-    "test:unit": "jest --coverage",
+    "test:unit": "jest --coverage --runInBand",
     "test:unit:watch": "jest --watch"
   },
   "dependencies": {

package/plugins/agency-agents/plugin.json

@@ -6,5 +6,10 @@
   "checks": [
     { "type": "binary", "name": "curl" }
   ],
+  "post_install": {
+    "script": "scripts/post-install.js",
+    "runtime": "node",
+    "timeout_ms": 15000
+  },
   "commands": []
 }

package/{cli/plugin-agency-agents.js → plugins/agency-agents/scripts/post-install.js}

@@ -1,5 +1,5 @@
 const { spawnSync } = require("child_process")
-const { addProvider, syncCatalog } = require("./skills-catalog")
+const { addProvider, syncCatalog } = require("../../../cli/skills-catalog")
 
 const OWNER = "msitarzewski"
 const REPO = "agency-agents"
@@ -82,7 +82,7 @@ function buildRemoteEntriesFromTree(treeResponse) {
   return entries
 }
 
-function installAgencyAgentsSkillProvider() {
+function run() {
   const treeResponse = fetchJson(TREE_URL)
   const entries = buildRemoteEntriesFromTree(treeResponse)
   if (entries.length === 0) {
@@ -106,7 +106,17 @@ function installAgencyAgentsSkillProvider() {
   }
 }
 
+if (require.main === module) {
+  try {
+    const result = run()
+    process.stdout.write(JSON.stringify(result))
+  } catch (err) {
+    process.stderr.write(err.message)
+    process.exit(1)
+  }
+}
+
 module.exports = {
-  installAgencyAgentsSkillProvider,
+  run,
   buildRemoteEntriesFromTree
 }

package/plugins/aws/README.md

@@ -0,0 +1,46 @@
+# AWS CLI Plugin Harness
+
+This plugin integrates the AWS CLI into dcli with one wrapped core command and full namespace passthrough.
+
+## Prerequisites
+
+Install AWS CLI with your preferred package manager, then verify it is available:
+
+```bash
+aws --version
+```
+
+Configure credentials before running account or service commands:
+
+```bash
+aws configure
+```
+
+## Available Commands
+
+### Account Identity (Wrapped)
+
+Returns the active caller identity via `aws sts get-caller-identity`.
+
+```bash
+dcli aws account identity --json
+```
+
+### Full Passthrough
+
+You can run any AWS CLI command through the `aws` namespace.
+
+```bash
+# List S3 buckets
+dcli aws s3api list-buckets
+
+# List EC2 regions
+dcli aws ec2 describe-regions
+
+# Show CLI help
+dcli aws --help
+```
+
+## Output
+
+Wrapped commands and passthrough responses are returned in dcli envelope format when `--json` is used with dcli-level commands.

package/plugins/aws/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "aws",
+  "version": "0.1.0",
+  "description": "AWS CLI plugin for dcli",
+  "source": "https://docs.aws.amazon.com/cli/latest/reference/",
+  "checks": [
+    {
+      "type": "binary",
+      "name": "aws"
+    }
+  ],
+  "commands": [
+    {
+      "namespace": "aws",
+      "resource": "account",
+      "action": "identity",
+      "description": "Show AWS caller identity for the active credentials",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "aws",
+        "baseArgs": ["sts", "get-caller-identity"],
+        "parseJson": true,
+        "missingDependencyHelp": "Please install AWS CLI to use this command."
+      },
+      "args": []
+    },
+    {
+      "namespace": "aws",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any AWS CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "aws",
+        "passthrough": true,
+        "parseJson": true,
+        "missingDependencyHelp": "Please install AWS CLI to use this command."
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/az/README.md

@@ -0,0 +1,46 @@
+# Azure CLI Plugin Harness
+
+This plugin integrates the Azure CLI (`az`) into dcli with one wrapped core command and full namespace passthrough.
+
+## Prerequisites
+
+Install Azure CLI with your preferred package manager, then verify it is available:
+
+```bash
+az version
+```
+
+Authenticate before running account or resource commands:
+
+```bash
+az login
+```
+
+## Available Commands
+
+### Account Show (Wrapped)
+
+Returns the active Azure subscription via `az account show`.
+
+```bash
+dcli az account show --json
+```
+
+### Full Passthrough
+
+You can run any Azure CLI command through the `az` namespace.
+
+```bash
+# List subscriptions
+dcli az account list
+
+# List resource groups
+dcli az group list
+
+# Show CLI help
+dcli az --help
+```
+
+## Output
+
+Wrapped commands and passthrough responses are returned in dcli envelope format when `--json` is used with dcli-level commands.

package/plugins/az/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "az",
+  "version": "0.1.0",
+  "description": "Azure CLI plugin for dcli",
+  "source": "https://learn.microsoft.com/cli/azure/",
+  "checks": [
+    {
+      "type": "binary",
+      "name": "az"
+    }
+  ],
+  "commands": [
+    {
+      "namespace": "az",
+      "resource": "account",
+      "action": "show",
+      "description": "Show the active Azure subscription",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "az",
+        "baseArgs": ["account", "show"],
+        "parseJson": true,
+        "missingDependencyHelp": "Please install Azure CLI to use this command."
+      },
+      "args": []
+    },
+    {
+      "namespace": "az",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any Azure CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "az",
+        "passthrough": true,
+        "parseJson": true,
+        "missingDependencyHelp": "Please install Azure CLI to use this command."
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/clickup/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "clickup",
+  "version": "0.1.0",
+  "description": "ClickUp CLI (cu) for AI agents - task management, sprint tracking, and project workflows",
+  "source": "https://github.com/krodak/clickup-cli",
+  "tags": ["clickup", "tasks", "project-management", "sprint", "ai-agents"],
+  "checks": [
+    { "type": "binary", "name": "cu" }
+  ],
+  "post_install": {
+    "script": "scripts/post-install.js",
+    "runtime": "node",
+    "timeout_ms": 15000
+  },
+  "post_uninstall": {
+    "script": "scripts/post-uninstall.js",
+    "runtime": "node",
+    "timeout_ms": 15000
+  },
+  "commands": [
+    {
+      "namespace": "clickup",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any cu CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "cu",
+        "passthrough": true,
+        "parseJson": true,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Please install clickup-cli: npm install -g @krodak/clickup-cli, then run: cu init"
+      },
+      "args": []
+    }
+  ]
+}
+

package/plugins/clickup/scripts/post-install.js

@@ -0,0 +1,107 @@
+const { spawnSync } = require("child_process")
+const { addProvider, syncCatalog } = require("../../../cli/skills-catalog")
+
+const OWNER = "krodak"
+const REPO = "clickup-cli"
+const REF = "main"
+const SOURCE_REPO = `https://github.com/${OWNER}/${REPO}`
+const TREE_URL = `https://api.github.com/repos/${OWNER}/${REPO}/git/trees/${REF}?recursive=1`
+const RAW_BASE_URL = `https://raw.githubusercontent.com/${OWNER}/${REPO}/${REF}`
+
+const SKILLS_PATH = "skills/clickup-cli/SKILL.md"
+
+function integrationError(message, suggestions = []) {
+  return Object.assign(new Error(message), {
+    code: 105,
+    type: "integration_error",
+    recoverable: true,
+    suggestions
+  })
+}
+
+function fetchJson(url) {
+  const res = spawnSync("curl", ["-fsSL", url], { encoding: "utf-8", timeout: 15000 })
+  if (res.error) {
+    throw integrationError(`Failed to fetch clickup-cli skill: ${res.error.message}`, ["Check internet connectivity", "Retry: supercli plugins install clickup"])
+  }
+  if (res.status !== 0) {
+    throw integrationError(`Failed to fetch clickup-cli skill: ${(res.stderr || "").trim() || `exit ${res.status}`}`, ["Check internet connectivity", "Retry: supercli plugins install clickup"])
+  }
+  try {
+    return JSON.parse((res.stdout || "").trim() || "{}")
+  } catch (err) {
+    throw integrationError(`Invalid clickup-cli skill response: ${err.message}`)
+  }
+}
+
+function run() {
+  // Fetch the skill file directly
+  const skillUrl = `${RAW_BASE_URL}/${SKILLS_PATH}`
+  const res = spawnSync("curl", ["-fsSL", skillUrl], { encoding: "utf-8", timeout: 15000 })
+  
+  if (res.error || res.status !== 0) {
+    throw integrationError(`Failed to fetch clickup-cli SKILL.md: ${res.error?.message || `exit ${res.status}`}`, ["Check internet connectivity", "Retry: supercli plugins install clickup"])
+  }
+
+  const markdown = (res.stdout || "").trim()
+  
+  // Parse frontmatter for name and description
+  let name = "ClickUp CLI"
+  let description = "Use when managing ClickUp tasks, sprints, or comments via the cu CLI tool"
+  
+  if (markdown.startsWith("---\n")) {
+    const end = markdown.indexOf("\n---\n", 4)
+    if (end > 0) {
+      const frontmatter = markdown.slice(4, end)
+      for (const line of frontmatter.split("\n")) {
+        const idx = line.indexOf(":")
+        if (idx > 0) {
+          const key = line.slice(0, idx).trim()
+          const value = line.slice(idx + 1).trim().replace(/^"|"$/g, "")
+          if (key === "name") name = value
+          if (key === "description") description = value
+        }
+      }
+    }
+  }
+
+  // Add as a remote static provider with a single skill entry
+  addProvider({
+    name: "clickup",
+    type: "remote_static",
+    enabled: true,
+    source_repo: SOURCE_REPO,
+    ref: REF,
+    entries: [
+      {
+        id: "clickup",
+        name: name,
+        description: description,
+        path: SKILLS_PATH,
+        source_url: skillUrl
+      }
+    ]
+  })
+
+  const index = syncCatalog()
+  return {
+    provider: "clickup",
+    entries: 1,
+    synced_skills: Array.isArray(index.skills) ? index.skills.length : 0
+  }
+}
+
+if (require.main === module) {
+  try {
+    const result = run()
+    process.stdout.write(JSON.stringify(result))
+  } catch (err) {
+    process.stderr.write(err.message)
+    process.exit(1)
+  }
+}
+
+module.exports = {
+  run
+}
+

package/plugins/clickup/scripts/post-uninstall.js

@@ -0,0 +1,30 @@
+const { removeProvider, syncCatalog } = require("../../../cli/skills-catalog")
+
+function run() {
+  const removed = removeProvider("clickup")
+  
+  if (removed) {
+    // Re-sync catalog to remove clickup skills
+    syncCatalog()
+  }
+  
+  return {
+    provider: "clickup",
+    removed: removed
+  }
+}
+
+if (require.main === module) {
+  try {
+    const result = run()
+    process.stdout.write(JSON.stringify(result))
+  } catch (err) {
+    process.stderr.write(err.message)
+    process.exit(1)
+  }
+}
+
+module.exports = {
+  run
+}
+

package/plugins/cline/README.md

@@ -0,0 +1,48 @@
+# Cline Plugin
+
+This plugin integrates the Cline CLI into dcli with rich non-interactive task wrappers and full namespace passthrough.
+
+## Prerequisites
+
+Ensure `cline` is available on your machine:
+
+```bash
+cline --version
+```
+
+## Wrapped Commands
+
+### CLI Version
+
+```bash
+supercli cline cli version --json
+```
+
+### Non-Interactive Task Run
+
+Runs Cline in act mode with `-a -y --json` and streams one JSON event envelope per line before the final summary envelope.
+
+```bash
+supercli cline task run --prompt "List files with most LOC in cwd" --cwd . --timeout 30 --json
+```
+
+### Non-Interactive Task Plan
+
+Runs Cline in plan mode with `-p -y --json` and the same streaming behavior.
+
+```bash
+supercli cline task plan --prompt "Plan a refactor of the auth module" --cwd . --json
+```
+
+## Full Passthrough
+
+```bash
+supercli cline --help
+supercli cline -a -y --json "List files with more LOC in cwd"
+```
+
+## Notes
+
+- Prefer the wrapped `cline task run` and `cline task plan` commands for agent automation.
+- Those wrappers bake in the documented headless-safe defaults: `--json` plus `-y`, with `-a` or `-p` selected for you.
+- Passthrough remains available when you need flags or flows not yet wrapped.