superacli 1.1.6 → 1.1.8

package/plugins/agent-browser/README.md

@@ -0,0 +1,69 @@
+# agent-browser Plugin Harness
+
+This plugin integrates `agent-browser` into supercli with a few human-friendly wrappers and full passthrough for the entire upstream CLI.
+
+## What You Get
+
+- quick wrappers for common setup and workflow steps
+- full passthrough for every upstream `agent-browser` command
+- learn content via `supercli plugins learn agent-browser`
+
+## Prerequisites
+
+Install the upstream CLI globally (recommended for speed):
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+## Install Plugin
+
+```bash
+supercli plugins learn agent-browser
+supercli plugins install agent-browser --json
+```
+
+## Wrapper Commands
+
+```bash
+supercli agent-browser cli version
+supercli agent-browser browser install
+supercli agent-browser browser open --url https://example.com
+supercli agent-browser browser snapshot
+supercli agent-browser browser close
+```
+
+## Full Passthrough Examples
+
+```bash
+supercli agent-browser open example.com
+supercli agent-browser snapshot -i --json
+supercli agent-browser click @e1
+supercli agent-browser fill @e2 "test@example.com"
+supercli agent-browser screenshot --annotate
+supercli agent-browser close
+```
+
+## Recommended Human Workflow
+
+1. Open page: `supercli agent-browser open <url>` or `supercli agent-browser browser open --url <url>`
+2. Capture refs: `supercli agent-browser snapshot -i`
+3. Interact with refs: `click @eN`, `fill @eN "..."`
+4. Re-snapshot after page changes
+5. Close when done: `supercli agent-browser close`
+
+## Important Caveats
+
+- `browser open` wrapper requires `--url` (named argument). Check schema with `supercli inspect agent-browser browser open --json`.
+- Wrappers are intentionally minimal. Use passthrough (`supercli agent-browser <upstream args...>`) for full upstream options.
+- Ref ids (`@e1`, `@e2`, etc.) are snapshot-scoped and can change after navigation or refresh. Run a fresh `snapshot -i` before using refs.
+- `browser snapshot` returns a full accessibility tree; `snapshot -i` returns a compact refs map and is better for click/fill automation loops.
+- Real pages may expose noisy or translated link labels (social embeds, widgets). Prefer ref-based actions over brittle text matching.
+- After `browser close`, `browser snapshot` may return a minimal empty document. Re-open a URL before continuing automation.
+
+## Notes
+
+- The plugin uses long timeouts (`180000ms`) because browser tasks can take longer than standard CLI commands.
+- Use `--json` on passthrough commands when you need machine-readable output.
+- If you see missing dependency errors, ensure `agent-browser` is on your `PATH` and rerun `agent-browser install`.

package/plugins/agent-browser/plugin.json

@@ -0,0 +1,111 @@
+{
+  "name": "agent-browser",
+  "version": "0.1.0",
+  "description": "agent-browser CLI plugin with quick wrappers and passthrough",
+  "source": "https://github.com/vercel-labs/agent-browser",
+  "checks": [
+    { "type": "binary", "name": "agent-browser" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "agent-browser",
+      "resource": "cli",
+      "action": "version",
+      "description": "Show installed agent-browser version",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["--version"],
+        "parseJson": false,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "install",
+      "description": "Install browser runtime dependencies for agent-browser",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["install"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "open",
+      "description": "Open a URL in agent-browser",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["open"],
+        "positionalArgs": ["url"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": [
+        {
+          "name": "url",
+          "type": "string",
+          "required": true,
+          "description": "URL to open"
+        }
+      ]
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "snapshot",
+      "description": "Capture accessibility snapshot for ref-based automation",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["snapshot"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "close",
+      "description": "Close active agent-browser session",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["close"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any agent-browser CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "passthrough": true,
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/agent-browser/skills/quickstart/SKILL.md

@@ -0,0 +1,66 @@
+---
+skill_name: agent-browser.quickstart
+description: Agent workflow to install and run agent-browser through supercli with snapshot-ref automation.
+tags: agent-browser,browser,automation,playwright,agents
+---
+
+# agent-browser Quickstart
+
+Use this when you need deterministic browser automation for agent tasks.
+
+## 1) Install plugin and dependency
+
+```bash
+supercli plugins learn agent-browser
+supercli plugins install agent-browser --json
+supercli agent-browser browser install
+```
+
+If the binary is missing, install globally first:
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+## 2) Validate setup
+
+```bash
+supercli agent-browser cli version
+```
+
+## 3) Recommended agent workflow
+
+```bash
+supercli agent-browser browser open --url https://example.com
+supercli agent-browser browser snapshot
+supercli agent-browser click @e1
+supercli agent-browser fill @e2 "test@example.com"
+supercli agent-browser wait --load networkidle
+supercli agent-browser screenshot --annotate
+supercli agent-browser browser close
+```
+
+## 4) Use passthrough for full command coverage
+
+```bash
+supercli agent-browser find role button click --name "Submit"
+supercli agent-browser get url
+supercli agent-browser diff snapshot
+```
+
+## 5) Structured output for tool chains
+
+```bash
+supercli agent-browser snapshot --json
+supercli agent-browser get text @e1 --json
+```
+
+## 6) Important caveats
+
+- `browser open` wrapper requires `--url` (named arg). Use `supercli inspect agent-browser browser open --json` to confirm the active schema.
+- Wrapper commands are intentionally minimal. For advanced flags and full upstream coverage, use passthrough commands like `supercli agent-browser <upstream args...>`.
+- Ref ids (`@e1`, `@e2`, etc.) are snapshot-scoped and can change after navigation or refresh. Run a new `snapshot -i` before acting on refs.
+- `browser snapshot` returns the full accessibility tree text; `snapshot -i` returns a compact refs map that is easier for reliable click/fill automation.
+- Link labels may be verbose, translated, or indirect on real sites (for example social widgets). Prefer refs over brittle text matching.
+- After `browser close`, a snapshot may still return a minimal empty document. Always `open` a target URL again before continuing task steps.

package/plugins/aider/README.md

@@ -0,0 +1,53 @@
+# Aider Plugin
+
+Agent-friendly SuperCLI integration for `aider`, focused on one-shot non-interactive coding tasks.
+
+## Why This Plugin
+
+Aider is interactive by default, but it exposes strong scripting flags:
+
+- `--message` / `--message-file`
+- `--yes-always`
+- `--no-auto-commits`
+- `--dry-run`
+- `--no-pretty`
+- `--no-stream`
+
+This plugin wraps those options into predictable JSON output for agents.
+
+## Setup
+
+```bash
+dcli aider cli setup
+```
+
+You will also need a supported model/provider configuration, for example `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or another aider-supported provider.
+
+## Commands
+
+- `aider cli setup`: install `aider-chat`
+- `aider cli help-json`: inspect the wrapper contract
+- `aider models list --query sonnet`: list matching model names
+- `aider code apply`: run a one-shot editing task in a target repo
+- `aider code dry-run`: run the same flow without modifying files
+
+## Important Constraints
+
+- pass `--cwd` to target the repo or project directory
+- use `files` and `read` to constrain the task scope when possible
+- the wrapper disables auto-commits and pretty streaming output
+- stdout is JSON; raw aider stdout/stderr are returned inside the JSON payload
+
+## Stability Checklist
+
+- keep non-interactive flags enabled for wrapped commands
+- preserve `--no-auto-commits` and let SuperCLI or the user decide how to commit
+- capture changed files by comparing git status before and after the run
+- treat provider/API-key errors as structured failures, not free-form output
+
+## Skills
+
+- `plugins/aider/skills/quickstart/SKILL.md`
+- `plugins/aider/skills/one-shot-edits.md`
+- `plugins/aider/skills/dry-run-review.md`
+- `plugins/aider/skills/model-and-provider.md`

package/plugins/aider/plugin.json

@@ -0,0 +1,105 @@
+{
+  "name": "aider",
+  "version": "0.1.0",
+  "description": "Aider CLI plugin with one-shot non-interactive coding wrappers",
+  "source": "https://aider.chat/docs/scripting.html",
+  "checks": [
+    { "type": "binary", "name": "python3" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "aider",
+      "resource": "cli",
+      "action": "setup",
+      "description": "Install aider-chat for one-shot use",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["scripts/setup-aider.js"],
+        "parseJson": false,
+        "timeout_ms": 120000
+      },
+      "args": []
+    },
+    {
+      "namespace": "aider",
+      "resource": "cli",
+      "action": "help-json",
+      "description": "Show machine-readable help for the aider wrapper",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["scripts/aider-wrapper.js", "help-json"],
+        "parseJson": true,
+        "timeout_ms": 15000
+      },
+      "args": []
+    },
+    {
+      "namespace": "aider",
+      "resource": "models",
+      "action": "list",
+      "description": "List aider models matching a partial query",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["scripts/aider-wrapper.js", "models"],
+        "parseJson": true,
+        "timeout_ms": 30000,
+        "missingDependencyHelp": "Please run 'dcli aider cli setup' to install aider-chat."
+      },
+      "args": [
+        { "name": "query", "type": "string", "required": true, "description": "Partial model name to search" }
+      ]
+    },
+    {
+      "namespace": "aider",
+      "resource": "code",
+      "action": "apply",
+      "description": "Run a one-shot aider coding task that may modify files",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["scripts/aider-wrapper.js", "apply"],
+        "parseJson": true,
+        "timeout_ms": 120000,
+        "missingDependencyHelp": "Please run 'dcli aider cli setup' to install aider-chat."
+      },
+      "args": [
+        { "name": "cwd", "type": "string", "required": true, "description": "Absolute path to the target project directory" },
+        { "name": "prompt", "type": "string", "required": true, "description": "One-shot natural language instruction" },
+        { "name": "model", "type": "string", "required": false, "description": "Optional aider model name" },
+        { "name": "files", "type": "string", "required": false, "description": "Comma-separated editable files" },
+        { "name": "read", "type": "string", "required": false, "description": "Comma-separated read-only files" },
+        { "name": "timeout-seconds", "type": "number", "required": false, "description": "Aider API timeout in seconds" },
+        { "name": "verbose", "type": "boolean", "required": false, "description": "Enable verbose aider output" }
+      ]
+    },
+    {
+      "namespace": "aider",
+      "resource": "code",
+      "action": "dry-run",
+      "description": "Run a one-shot aider coding task without modifying files",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["scripts/aider-wrapper.js", "dry-run"],
+        "parseJson": true,
+        "timeout_ms": 120000,
+        "missingDependencyHelp": "Please run 'dcli aider cli setup' to install aider-chat."
+      },
+      "args": [
+        { "name": "cwd", "type": "string", "required": true, "description": "Absolute path to the target project directory" },
+        { "name": "prompt", "type": "string", "required": true, "description": "One-shot natural language instruction" },
+        { "name": "model", "type": "string", "required": false, "description": "Optional aider model name" },
+        { "name": "files", "type": "string", "required": false, "description": "Comma-separated editable files" },
+        { "name": "read", "type": "string", "required": false, "description": "Comma-separated read-only files" },
+        { "name": "timeout-seconds", "type": "number", "required": false, "description": "Aider API timeout in seconds" },
+        { "name": "verbose", "type": "boolean", "required": false, "description": "Enable verbose aider output" }
+      ]
+    }
+  ]
+}

package/plugins/aider/scripts/aider-wrapper.js

@@ -0,0 +1,243 @@
+const fs = require("fs")
+const path = require("path")
+const { spawnSync } = require("child_process")
+
+const VERSION = "1.0"
+const EXIT_CODES = {
+  success: 0,
+  invalidInput: 80,
+  invalidState: 90,
+  integrationFailure: 100,
+  internalFailure: 110
+}
+
+const HELP = {
+  version: VERSION,
+  name: "aider-wrapper",
+  commands: {
+    models: {
+      required: ["--query"],
+      description: "List aider models matching a partial name."
+    },
+    apply: {
+      required: ["--cwd", "--prompt"],
+      description: "Run a one-shot aider edit task with writes enabled."
+    },
+    "dry-run": {
+      required: ["--cwd", "--prompt"],
+      description: "Run a one-shot aider edit task without modifying files."
+    }
+  },
+  notes: [
+    "The wrapper always disables auto-commits.",
+    "The wrapper returns JSON with stdout, stderr, exit_code, and changed_files."
+  ]
+}
+
+function parseArgs(argv) {
+  const args = { _: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith("--")) {
+      args._.push(token)
+      continue
+    }
+    const trimmed = token.slice(2)
+    const eq = trimmed.indexOf("=")
+    if (eq >= 0) {
+      args[trimmed.slice(0, eq)] = trimmed.slice(eq + 1)
+      continue
+    }
+    const next = argv[i + 1]
+    if (!next || next.startsWith("--")) {
+      args[trimmed] = true
+      continue
+    }
+    args[trimmed] = next
+    i += 1
+  }
+  return args
+}
+
+function printJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`)
+}
+
+function fail(code, type, message, details = {}, suggestions = []) {
+  printJson({
+    version: VERSION,
+    status: "error",
+    error: { code, type, message, details, recoverable: false, retry_after: null, suggestions }
+  })
+  process.exit(code)
+}
+
+function splitCsv(value) {
+  if (!value) {
+    return []
+  }
+  return String(value).split(",").map((item) => item.trim()).filter(Boolean)
+}
+
+function ensureAbsoluteDir(dir) {
+  if (typeof dir !== "string" || dir.trim() === "") {
+    fail(EXIT_CODES.invalidInput, "missing_cwd", "Provide --cwd with an absolute target directory.", {}, ["Example: --cwd /absolute/path/to/repo"])
+  }
+  if (!path.isAbsolute(dir)) {
+    fail(EXIT_CODES.invalidInput, "cwd_not_absolute", `Target directory must be absolute: ${dir}`)
+  }
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    fail(EXIT_CODES.invalidInput, "cwd_not_found", `Target directory not found: ${dir}`)
+  }
+}
+
+function readGitState(cwd) {
+  const result = spawnSync("git", ["status", "--porcelain"], {
+    cwd,
+    encoding: "utf-8"
+  })
+  if (result.error || result.status !== 0) {
+    return null
+  }
+
+  const entries = new Set()
+  for (const line of result.stdout.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue
+    }
+    entries.add(line.slice(3).trim())
+  }
+  return entries
+}
+
+function diffGitState(before, after) {
+  if (!after) {
+    return []
+  }
+  if (!before) {
+    return Array.from(after).sort()
+  }
+  return Array.from(after).filter((item) => !before.has(item)).sort()
+}
+
+function runModels(args) {
+  if (!args.query) {
+    fail(EXIT_CODES.invalidInput, "missing_query", "Provide --query for aider model lookup.")
+  }
+  const result = spawnSync("aider", ["--list-models", String(args.query)], {
+    encoding: "utf-8",
+    env: { ...process.env, NO_COLOR: "1", AIDER_GITIGNORE: "false", AIDER_ANALYTICS_DISABLE: "true" }
+  })
+  if (result.error) {
+    fail(EXIT_CODES.integrationFailure, "aider_not_available", result.error.message, {}, ["Run 'dcli aider cli setup' to install aider-chat."])
+  }
+  printJson({
+    version: VERSION,
+    status: result.status === 0 ? "success" : "error",
+    data: {
+      query: String(args.query),
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exit_code: result.status
+    }
+  })
+  process.exit(result.status || 0)
+}
+
+function buildAiderArgs(mode, args) {
+  const aiderArgs = [
+    "--yes-always",
+    "--no-auto-commits",
+    "--no-gitignore",
+    "--no-pretty",
+    "--no-stream",
+    "--no-suggest-shell-commands",
+    "--no-check-update",
+    "--analytics-disable",
+    "--message",
+    String(args.prompt)
+  ]
+
+  if (args.model) {
+    aiderArgs.push("--model", String(args.model))
+  }
+  if (args["timeout-seconds"]) {
+    aiderArgs.push("--timeout", String(args["timeout-seconds"]))
+  }
+  if (args.verbose) {
+    aiderArgs.push("--verbose")
+  }
+  if (mode === "dry-run") {
+    aiderArgs.push("--dry-run")
+  }
+
+  for (const file of splitCsv(args.files)) {
+    aiderArgs.push("--file", file)
+  }
+  for (const file of splitCsv(args.read)) {
+    aiderArgs.push("--read", file)
+  }
+
+  return aiderArgs
+}
+
+function runTask(mode, args) {
+  ensureAbsoluteDir(args.cwd)
+  if (!args.prompt) {
+    fail(EXIT_CODES.invalidInput, "missing_prompt", "Provide --prompt for the aider task.")
+  }
+
+  const before = readGitState(args.cwd)
+  const result = spawnSync("aider", buildAiderArgs(mode, args), {
+    cwd: args.cwd,
+    encoding: "utf-8",
+    env: { ...process.env, NO_COLOR: "1", AIDER_GITIGNORE: "false", AIDER_ANALYTICS_DISABLE: "true" }
+  })
+
+  if (result.error) {
+    fail(EXIT_CODES.integrationFailure, "aider_execution_failed", result.error.message, {}, ["Run 'dcli aider cli setup' to install aider-chat."])
+  }
+
+  const after = readGitState(args.cwd)
+  const payload = {
+    version: VERSION,
+    status: result.status === 0 ? "success" : "error",
+    data: {
+      mode,
+      cwd: args.cwd,
+      prompt: String(args.prompt),
+      model: args.model || null,
+      dry_run: mode === "dry-run",
+      changed_files: diffGitState(before, after),
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exit_code: result.status
+    }
+  }
+  printJson(payload)
+  process.exit(result.status || 0)
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2)
+  if (command === "help-json") {
+    printJson(HELP)
+    return
+  }
+
+  const args = parseArgs(rest)
+  if (command === "models") {
+    runModels(args)
+    return
+  }
+  if (command === "apply" || command === "dry-run") {
+    runTask(command, args)
+    return
+  }
+
+  fail(EXIT_CODES.invalidInput, "unknown_command", `Unknown command: ${command || "<missing>"}`)
+}
+
+if (require.main === module) {
+  main()
+}

package/plugins/aider/scripts/setup-aider.js

@@ -0,0 +1,37 @@
+const { spawnSync } = require("child_process")
+
+function run(command, args) {
+  return spawnSync(command, args, { stdio: "inherit", encoding: "utf-8" })
+}
+
+function fail(message, code = 1) {
+  console.error(message)
+  process.exit(code)
+}
+
+function main() {
+  console.log("Installing aider-chat...")
+
+  let result = run("python3", ["-m", "pip", "install", "--user", "aider-chat"])
+  if (result.error) {
+    fail(`Failed to start python3: ${result.error.message}`)
+  }
+
+  if (result.status !== 0) {
+    console.log("pip install failed, trying pipx...")
+    result = run("pipx", ["install", "aider-chat"])
+    if (result.error) {
+      fail(`Failed to install aider-chat via pip or pipx: ${result.error.message}`)
+    }
+    if (result.status !== 0) {
+      fail(`Failed to install aider-chat. Exit code: ${result.status}`, result.status || 1)
+    }
+  }
+
+  console.log("aider-chat installed.")
+  console.log("Next step: ensure your provider API key is configured before using the plugin.")
+}
+
+if (require.main === module) {
+  main()
+}