superacli 1.1.6 → 1.1.7

package/plugins/lightpanda/skills/quickstart/SKILL.md

@@ -0,0 +1,103 @@
+# Lightpanda Skill
+
+Use Lightpanda through `dcli` when you need fast, headless browser automation with structured JSON output for agents.
+
+## Skill Map
+
+Use the plugin-local skills directory for focused guidance:
+
+- `plugins/lightpanda/skills/generic-extraction.md`
+- `plugins/lightpanda/skills/contact-discovery.md`
+- `plugins/lightpanda/skills/resilient-navigation.md`
+
+## Quick Start
+
+### 1. Setup
+Install the local runtime dependencies for the plugin:
+```bash
+dcli lightpanda cli setup
+```
+
+### 2. Inspect Wrapper Capabilities
+Get machine-readable command help:
+```bash
+dcli lightpanda cli help-json
+```
+
+### 3. Run an Inline Script
+Visit a page and return structured data:
+```bash
+dcli lightpanda script run \
+  --url https://example.com \
+  --code "return { title: await page.title(), url: await page.url() }"
+```
+
+### 4. Run a File-Based Script
+Execute a script from an absolute file path:
+```bash
+dcli lightpanda script run --file /absolute/path/to/script.js
+```
+
+### 5. Pipe Script Content Through Stdin
+Compose the wrapper with other tools:
+```bash
+cat /absolute/path/to/script.js | dcli lightpanda script run
+```
+
+### 6. Run a Generic Extraction
+Use the extraction runner when the agent should supply dynamic extraction code:
+```bash
+dcli lightpanda extract run \
+  --url https://example.com \
+  --code "return { heading: $('h1').first().text(), mode: context.navigation?.mode }"
+```
+
+### 7. Discover Contact Channels
+Use the opinionated multi-page discovery flow when the goal is to find owner contact channels:
+```bash
+dcli lightpanda contacts discover --url https://example.com --max-pages 5
+```
+
+## Choosing The Right Command
+
+- Use `script run` for general browser automation.
+- Use `extract run` for data extraction with `cheerio`, `fetch`, `$`, `html`, and `resilientGoto(...)`.
+- Use `contacts discover` for the focused contact-channel crawler.
+
+## Injected Runtime
+Your script receives these bindings automatically:
+- `browser`: connected `puppeteer-core` browser instance.
+- `page`: a new page created for the run.
+- `puppeteer`: the imported `puppeteer-core` module.
+- `lightpanda`: the imported `@lightpanda/browser` module.
+- `cheerio`: server-side HTML parser for fallback or HTML-first extraction.
+- `fetch`: built-in fetch for direct HTTP retrieval.
+- `context`: metadata about the run (`endpoint`, `args`, `startedAt`).
+- `console`: stderr-backed console for debug logs that will not corrupt JSON stdout.
+- `$`: a Cheerio instance for the current HTML when `extract run` navigates or falls back successfully.
+- `html`: the HTML string paired with `$` in `extract run`.
+- `resilientGoto(url, options)`: navigation helper that falls back to HTTP + Cheerio when Lightpanda hits frame-detached or TLS issues.
+
+## Script Pattern
+Write the body as if it lives inside an async function:
+```js
+await page.goto("https://news.ycombinator.com")
+
+const posts = await page.evaluate(() => {
+  return Array.from(document.querySelectorAll(".titleline > a")).slice(0, 5).map((link) => ({
+    title: link.textContent,
+    href: link.href
+  }))
+})
+
+return posts
+```
+
+## Agent Notes
+- The wrapper is non-interactive by default.
+- Stdout is reserved for one JSON payload.
+- Use `console.log(...)` inside the script for diagnostics; those logs go to stderr.
+- Use `--verbose` when you need Lightpanda process logs on stderr.
+- Use `--timeout-ms` to cap long runs and keep automation deterministic.
+- `extract run` returns your custom `data` plus `meta` fields like `execution_ms`, `extraction_mode`, `target_url`, and `navigation_error`.
+- `contacts discover` scans the landing page plus a small set of likely contact/about/legal pages and returns emails, phones, `mailto:`, `tel:`, and social links.

package/plugins/lightpanda/skills/resilient-navigation.md

@@ -0,0 +1,42 @@
+# Lightpanda Resilient Navigation Skill
+
+Some sites trigger Lightpanda navigation problems such as detached frames or TLS verification failures. The plugin handles those cases in extraction mode with `resilientGoto(...)`.
+
+## Recoverable Browser Errors
+
+The extraction runtime treats these as recoverable navigation failures:
+
+- `Navigating frame was detached`
+- `Attempted to use detached Frame`
+- `PeerFailedVerification`
+
+## What `resilientGoto(...)` Returns
+
+`resilientGoto(url, options)` returns an object with:
+
+- `mode`: `browser` or `http_fallback`
+- `requested_url`
+- `final_url`
+- `status`
+- `html`
+- `$`
+- `error`
+
+## Example
+
+```js
+const pageData = await resilientGoto("https://example.com/contact")
+
+return {
+  mode: pageData.mode,
+  finalUrl: pageData.final_url,
+  title: pageData.$ ? pageData.$("title").first().text() : null,
+  navigationError: pageData.error
+}
+```
+
+## Guidance
+
+- Prefer `extract run` when navigation stability matters.
+- Inspect `context.navigation.mode` and `meta.extraction_mode` to understand whether the browser path or fallback path was used.
+- If the browser path is required, run with `--verbose` and inspect stderr logs before deciding whether the target is currently unsupported by Lightpanda.

package/plugins/monty/README.md

@@ -4,13 +4,13 @@ Hybrid plugin for the [Monty](https://github.com/pydantic/monty) sandboxed Pytho
 
 ## Overview
 
-Monty is a minimal, secure Python interpreter written in Rust, designed for AI agents to run untrusted code safely. This plugin provides a Node.js wrapper for the `@pydantic/monty` package and indexes the upstream agent documentation into the SuperCLI skills catalog.
+Monty is a minimal, secure Python interpreter written in Rust, designed for AI agents to run untrusted code safely. This plugin provides a Node.js wrapper for the `@pydantic/monty` package and indexes the upstream agent documentation into the SuperCLI skill-doc catalog.
 
 ## Features
 
 - **Sandboxed Execution**: Runs Python code without access to the host filesystem, network, or environment.
 - **Dependency Management**: Controlled setup of the `@pydantic/monty` binary.
-- **Skills Indexing**: Teaches agents about Monty's capabilities by indexing remote `README.md` and `CLAUDE.md`.
+- **Skill Document Indexing**: Teaches agents about Monty's capabilities by indexing remote `README.md` and `CLAUDE.md`.
 - **Hybrid Support**: Combines local CLI wrappers with remote documentation.
 
 ## Installation

package/plugins/nullclaw/README.md

@@ -1,6 +1,6 @@
 # nullclaw Plugin
 
-This plugin is a hybrid harness: it indexes NullClaw's upstream docs into the dcli skills catalog and exposes the local `nullclaw` binary through wrapped commands plus full passthrough.
+This plugin is a hybrid harness: it indexes NullClaw's upstream docs into the dcli skill-doc catalog and exposes the local `nullclaw` binary through wrapped commands plus full passthrough.
 
 ## What It Adds
 
@@ -14,7 +14,7 @@ This plugin is a hybrid harness: it indexes NullClaw's upstream docs into the dc
 supercli plugins install nullclaw --json
 ```
 
-## Explore Indexed Skills
+## Explore Indexed Skill Documents
 
 ```bash
 supercli skills list --catalog --provider nullclaw --json
@@ -42,4 +42,4 @@ supercli nullclaw agent -m "hello"
 - This plugin indexes remote markdown from `https://github.com/nullclaw/nullclaw`.
 - It does not install the upstream `nullclaw` binary for you.
 - If you also want the runtime locally, follow the upstream install path such as `brew install nullclaw`.
-- Removing the plugin also removes its registered skills provider from the local catalog.
+- Removing the plugin also removes its registered skill-doc provider from the local catalog.

package/plugins/offline-ai/README.md

@@ -0,0 +1,23 @@
+# offline-ai Plugin
+
+`offline-ai` wraps `@offline-ai/cli` for script-first, non-interactive usage in supercli.
+
+## Install
+
+```bash
+supercli plugins install ./plugins/offline-ai --json
+npm install -g @offline-ai/cli
+```
+
+## Commands
+
+- `supercli offline-ai cli version`
+- `supercli offline-ai script run --entry translator --input '{"file":"./todo.md","target":"en"}'`
+- `supercli offline-ai script run-file --file ./scripts/translator.ai --input '{"target":"en"}'`
+- `supercli offline-ai <any upstream args...>`
+
+## Notes
+
+- Prefer one-shot `script run` or `script run-file` in CI to avoid interactive sessions.
+- Keep payloads deterministic (JSON strings) for repeatable runs.
+- Use passthrough for advanced CLI options not exposed in wrappers.

package/plugins/offline-ai/plugin.json

@@ -0,0 +1,82 @@
+{
+  "name": "offline-ai",
+  "version": "0.1.0",
+  "description": "offline-ai CLI plugin with script-first wrappers and passthrough",
+  "source": "https://github.com/offline-ai/cli",
+  "tags": ["offline-ai", "ai", "scripts", "automation", "passthrough"],
+  "checks": [
+    { "type": "binary", "name": "ai" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "offline-ai",
+      "resource": "cli",
+      "action": "version",
+      "description": "Show installed offline-ai CLI version",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "ai",
+        "baseArgs": ["--version"],
+        "parseJson": false,
+        "missingDependencyHelp": "Install with: npm install -g @offline-ai/cli"
+      },
+      "args": []
+    },
+    {
+      "namespace": "offline-ai",
+      "resource": "script",
+      "action": "run",
+      "description": "Run an offline-ai script entry with optional input payload",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "ai",
+        "baseArgs": ["run"],
+        "positionalArgs": ["entry", "input"],
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g @offline-ai/cli"
+      },
+      "args": [
+        { "name": "entry", "type": "string", "required": true, "description": "Script name or entry identifier" },
+        { "name": "input", "type": "string", "required": false, "description": "Optional JSON/string payload" }
+      ]
+    },
+    {
+      "namespace": "offline-ai",
+      "resource": "script",
+      "action": "run-file",
+      "description": "Run an offline-ai script file with optional input payload",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "ai",
+        "baseArgs": ["run", "-f"],
+        "positionalArgs": ["file", "input"],
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g @offline-ai/cli"
+      },
+      "args": [
+        { "name": "file", "type": "string", "required": true, "description": "Path to script file" },
+        { "name": "input", "type": "string", "required": false, "description": "Optional JSON/string payload" }
+      ]
+    },
+    {
+      "namespace": "offline-ai",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any offline-ai CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "ai",
+        "passthrough": true,
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g @offline-ai/cli"
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/offline-ai/skills/quickstart/SKILL.md

@@ -0,0 +1,43 @@
+---
+skill_name: offline-ai.quickstart
+description: Agent workflow for running offline-ai scripts in deterministic non-interactive mode.
+tags: offline-ai,ai,scripting,automation,headless
+---
+
+# offline-ai Quickstart
+
+Use this when you need programmable prompt-engine scripts in automation workflows.
+
+## 1) Install plugin and dependency
+
+```bash
+supercli plugins learn offline-ai
+supercli plugins install ./plugins/offline-ai --json
+npm install -g @offline-ai/cli
+```
+
+## 2) Validate setup
+
+```bash
+supercli offline-ai cli version
+```
+
+## 3) Run scripts non-interactively
+
+```bash
+supercli offline-ai script run --entry translator --input '{"file":"./TODO","target":"English"}'
+supercli offline-ai script run-file --file ./scripts/translator.ai --input '{"target":"English"}'
+```
+
+## 4) Full passthrough for advanced usage
+
+```bash
+supercli offline-ai run -f translator '{"file":"./TODO","target":"English"}'
+supercli offline-ai run translator '{"topic":"release notes"}'
+```
+
+## 5) Caveats
+
+- Prefer non-interactive script runs in CI; avoid REPL-style sessions.
+- Use explicit payloads so outputs remain deterministic and easy to parse.
+- If you need structured output modes, pass exact upstream flags via passthrough.

package/plugins/openhands/README.md

@@ -0,0 +1,25 @@
+# OpenHands Plugin
+
+The OpenHands plugin adds headless automation commands and passthrough support for the OpenHands CLI.
+
+## Install
+
+1. Install OpenHands CLI (`pip install openhands-ai`).
+2. Verify installation (`openhands --version`).
+3. Install this plugin:
+
+```bash
+supercli plugins install openhands
+```
+
+## Commands
+
+- `supercli openhands self version`
+- `supercli openhands task run --task "..."`
+- `supercli openhands task file --file ./task.txt`
+- `supercli openhands task json --task "..."`
+- `supercli openhands ...` (passthrough)
+
+## Safety Note
+
+OpenHands headless mode runs with always-approve behavior. Use it only in trusted repositories and controlled CI environments.

package/plugins/openhands/plugin.json

@@ -0,0 +1,116 @@
+{
+  "name": "openhands",
+  "version": "0.1.0",
+  "description": "OpenHands CLI plugin with headless automation wrappers and passthrough",
+  "source": "https://docs.openhands.dev/openhands/usage/cli/headless",
+  "checks": [
+    { "type": "binary", "name": "openhands" }
+  ],
+  "install_guidance": {
+    "plugin": "openhands",
+    "binary": "openhands",
+    "check": "openhands --version",
+    "install_steps": [
+      "pip install openhands-ai",
+      "openhands --version",
+      "supercli plugins install openhands"
+    ],
+    "note": "Headless mode runs in always-approve mode; use only in trusted repos and CI contexts."
+  },
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "openhands",
+      "resource": "self",
+      "action": "version",
+      "description": "Show OpenHands CLI version",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "openhands",
+        "baseArgs": ["--version"],
+        "parseJson": false,
+        "missingDependencyHelp": "Please install OpenHands CLI to use this command."
+      },
+      "args": []
+    },
+    {
+      "namespace": "openhands",
+      "resource": "task",
+      "action": "run",
+      "description": "Run an OpenHands task in headless mode",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "openhands",
+        "baseArgs": ["--headless", "-t"],
+        "positionalArgs": ["task"],
+        "parseJson": false,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Please install OpenHands CLI to use this command."
+      },
+      "args": [
+        { "name": "task", "type": "string", "required": true },
+        { "name": "json", "type": "boolean", "required": false },
+        { "name": "file-store", "type": "string", "required": false },
+        { "name": "config-file", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "openhands",
+      "resource": "task",
+      "action": "file",
+      "description": "Run an OpenHands task file in headless mode",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "openhands",
+        "baseArgs": ["--headless", "-f"],
+        "positionalArgs": ["file"],
+        "parseJson": false,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Please install OpenHands CLI to use this command."
+      },
+      "args": [
+        { "name": "file", "type": "string", "required": true },
+        { "name": "json", "type": "boolean", "required": false },
+        { "name": "file-store", "type": "string", "required": false },
+        { "name": "config-file", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "openhands",
+      "resource": "task",
+      "action": "json",
+      "description": "Run an OpenHands headless task with JSONL streaming",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "openhands",
+        "baseArgs": ["--headless", "--json", "-t"],
+        "positionalArgs": ["task"],
+        "stream": "jsonl",
+        "parseJson": false,
+        "timeout_ms": 15000,
+        "missingDependencyHelp": "Please install OpenHands CLI to use this command."
+      },
+      "args": [
+        { "name": "task", "type": "string", "required": true },
+        { "name": "file-store", "type": "string", "required": false },
+        { "name": "config-file", "type": "string", "required": false }
+      ]
+    },
+    {
+      "namespace": "openhands",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any OpenHands CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "openhands",
+        "passthrough": true,
+        "parseJson": false,
+        "missingDependencyHelp": "Please install OpenHands CLI to use this command."
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/openhands/skills/quickstart/SKILL.md

@@ -0,0 +1,26 @@
+# OpenHands Quickstart
+
+Use this plugin to run OpenHands in headless automation mode.
+
+## Prerequisites
+
+- Install OpenHands CLI: `pip install openhands-ai`
+- Verify CLI: `openhands --version`
+- Install plugin: `supercli plugins install openhands`
+
+## Common Commands
+
+- Version: `supercli openhands self version`
+- Headless task: `supercli openhands task run --task "Summarize this repo"`
+- Headless task from file: `supercli openhands task file --file ./task.txt`
+- JSONL stream mode: `supercli openhands task json --task "Add tests"`
+
+## Passthrough
+
+For any unsupported subcommand, use passthrough:
+
+`supercli openhands <raw openhands args>`
+
+## Important
+
+Headless mode is always non-interactive approval. Treat it as high-trust execution.

package/plugins/plandex/README.md

@@ -0,0 +1,25 @@
+# Plandex Plugin
+
+`plandex` wraps the Plandex CLI for agent-safe, non-interactive usage in supercli.
+
+## Install
+
+```bash
+supercli plugins install ./plugins/plandex --json
+# Install Plandex CLI from official docs and ensure `plandex` is on PATH
+```
+
+## Commands
+
+- `supercli plandex cli version`
+- `supercli plandex plan new --name "my-plan" --full`
+- `supercli plandex plan set-auto full`
+- `supercli plandex task tell --prompt "Implement X"`
+- `supercli plandex task chat --prompt "Explain Y"`
+- `supercli plandex <any upstream args...>`
+
+## Notes
+
+- Use `plan set-auto` to control autonomy in CI and local automation.
+- Prefer explicit, one-shot prompts for deterministic scripting.
+- Use passthrough for advanced commands not exposed by wrappers.

package/plugins/plandex/plugin.json

@@ -0,0 +1,130 @@
+{
+  "name": "plandex",
+  "version": "0.1.0",
+  "description": "Plandex CLI plugin with non-interactive planning wrappers and passthrough",
+  "source": "https://plandex.ai",
+  "tags": ["plandex", "ai", "planning", "automation", "passthrough"],
+  "checks": [
+    { "type": "binary", "name": "plandex" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "plandex",
+      "resource": "cli",
+      "action": "version",
+      "description": "Show installed Plandex CLI version",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "baseArgs": ["--version"],
+        "parseJson": false,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": []
+    },
+    {
+      "namespace": "plandex",
+      "resource": "plan",
+      "action": "new",
+      "description": "Create a new plan with optional autonomy flags",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "baseArgs": ["new"],
+        "optionalArgs": {
+          "name": "-n",
+          "context-dir": "-d",
+          "no-auto": "--no-auto",
+          "basic": "--basic",
+          "plus": "--plus",
+          "semi": "--semi",
+          "full": "--full"
+        },
+        "parseJson": false,
+        "timeout_ms": 120000,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": [
+        { "name": "name", "type": "string", "required": false, "description": "Optional plan name" },
+        { "name": "context-dir", "type": "string", "required": false, "description": "Optional context directory" },
+        { "name": "no-auto", "type": "boolean", "required": false, "description": "Set autonomy to none" },
+        { "name": "basic", "type": "boolean", "required": false, "description": "Set autonomy to basic" },
+        { "name": "plus", "type": "boolean", "required": false, "description": "Set autonomy to plus" },
+        { "name": "semi", "type": "boolean", "required": false, "description": "Set autonomy to semi" },
+        { "name": "full", "type": "boolean", "required": false, "description": "Set autonomy to full" }
+      ]
+    },
+    {
+      "namespace": "plandex",
+      "resource": "plan",
+      "action": "set-auto",
+      "description": "Set autonomy level for current plan",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "baseArgs": ["set-auto"],
+        "positionalArgs": ["level"],
+        "parseJson": false,
+        "timeout_ms": 60000,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": [
+        { "name": "level", "type": "string", "required": true, "description": "Autonomy level: none|basic|plus|semi|full" }
+      ]
+    },
+    {
+      "namespace": "plandex",
+      "resource": "task",
+      "action": "tell",
+      "description": "Run one-shot implementation instruction",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "baseArgs": ["tell"],
+        "positionalArgs": ["prompt"],
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": [
+        { "name": "prompt", "type": "string", "required": true, "description": "Instruction for Plandex" }
+      ]
+    },
+    {
+      "namespace": "plandex",
+      "resource": "task",
+      "action": "chat",
+      "description": "Run one-shot analysis question",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "baseArgs": ["chat"],
+        "positionalArgs": ["prompt"],
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": [
+        { "name": "prompt", "type": "string", "required": true, "description": "Question for Plandex" }
+      ]
+    },
+    {
+      "namespace": "plandex",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any Plandex CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "plandex",
+        "passthrough": true,
+        "parseJson": false,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install Plandex CLI from the official docs and ensure 'plandex' is on PATH."
+      },
+      "args": []
+    }
+  ]
+}