@zenalexa/unicli 0.218.0 → 0.219.0

package/skills/unicli-claude-code/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: unicli-claude-code
+description: >
+  Make Uni-CLI reliable when invoked from Claude Code. MANDATES JSON-in
+  channels (stdin / --args-file) for any payload containing quotes, emoji,
+  newlines, or inline JSON — shell-quoted invocations hit TC0 circuit
+  limits and drop to <50% success above ICS=4. Also covers --describe
+  introspection and next_actions-driven navigation.
+version: 0.219.0
+depends-on:
+  - talk-normal
+triggers:
+  - "unicli"
+  - "ics"
+  - "args-file"
+  - "stdin-json"
+  - "quoted payload"
+  - "emoji in query"
+---
+
+# Uni-CLI × Claude Code — Reliable Invocation
+
+> **TL;DR** — If the payload contains ANY of: quotes, emoji, newlines, JSON,
+> non-ASCII, or is longer than ~60 chars, PIPE IT. Never inline.
+
+## Why this skill exists
+
+Transformers live in TC0. Matching balanced `"` and `'` pairs with arbitrary
+nesting is a mod-2 state-tracking problem that TC0 cannot solve in constant
+decode depth. Empirically, top LLMs land <43% on 0→1 CLI generation
+(CLI-Tool-Bench arXiv:2604.06742) and 62% of agent-tool bugs cluster at the
+tool-invocation / execution stages (arXiv:2603.20847).
+
+Uni-CLI gives you THREE invocation channels. One of them (shell-args) inherits
+the TC0 bottleneck. The other two do not.
+
+## The decision rule
+
+| If the payload has …                     | Use channel     |
+| ---------------------------------------- | --------------- |
+| Only ASCII, no quotes, <60 chars         | `shell` OK      |
+| Any quote or backslash                   | **stdin-JSON**  |
+| Emoji / CJK / non-ASCII                  | **stdin-JSON**  |
+| Newlines or inline JSON                  | **stdin-JSON**  |
+| Being reused across multiple invocations | **--args-file** |
+
+When unsure → stdin-JSON. It never makes things worse.
+
+## The three channels
+
+### 1 — stdin-JSON (preferred for complex payloads)
+
+```bash
+echo '{"query": "she said \"hi\" 🎉", "limit": 10}' | unicli twitter search
+```
+
+- Uni-CLI auto-detects non-TTY stdin whose body starts with `{`
+- Precedence: stdin-JSON > `--args-file` > shell flags > defaults
+- Works for EVERY command — no per-adapter opt-in needed
+
+### 2 — --args-file (preferred when payload is reused)
+
+```bash
+cat > /tmp/q.json <<'EOF'
+{ "query": "machine learning", "limit": 20, "locale": "en_US" }
+EOF
+unicli arxiv search --args-file /tmp/q.json
+```
+
+- Absolute paths recommended
+- JSON only (YAML and TOML deliberately not supported — minimize format ambiguity)
+
+### 3 — shell args (only for trivial payloads)
+
+```bash
+unicli hackernews top --limit 5
+```
+
+Fine when every value is ASCII, no quotes, no emoji.
+
+## Runtime introspection — `unicli describe`
+
+Before invoking any unfamiliar command, run:
+
+```bash
+unicli describe <site> <command>
+```
+
+You get back a JSON object containing:
+
+- `args_schema` — JSON Schema draft-2020-12 for the argument bag
+- `example_stdin` — a realistic JSON body you can modify and pipe
+- `channels` — the three invocation templates
+- `next_actions` — hints for what to run next
+
+This replaces reading docs. The CLI is the documentation.
+
+## The response envelope (v2)
+
+Every successful call returns:
+
+```json
+{
+  "ok": true,
+  "schema_version": "2",
+  "command": "twitter.search",
+  "meta": { "duration_ms": 847, "count": 10, "surface": "web" },
+  "data": [ ... ],
+  "error": null,
+  "next_actions": [
+    { "command": "unicli describe twitter search", "description": "…" },
+    { "command": "unicli twitter search --args-file <path.json>", "description": "…" }
+  ]
+}
+```
+
+Errors return `ok: false` with a structured `error` object (`adapter_path`,
+`step`, `suggestion`) and `next_actions` biased toward `unicli repair`. If
+you see `invalid_input` from the hardening layer, that means the arg bag
+tripped a safety check — read `error.suggestion` for the exact fix.
+
+## --dry-run — preview before committing
+
+```bash
+echo '{"query": "🎉", "limit": 5}' | unicli twitter search --dry-run
+```
+
+Prints the resolved ArgBag, the source channel, and the pipeline step count
+without touching the network / filesystem. Use this whenever you want to
+confirm the agent built the payload correctly.
+
+## Common failure modes → fixes
+
+| Symptom                                       | Root cause                             | Fix                                       |
+| --------------------------------------------- | -------------------------------------- | ----------------------------------------- |
+| `invalid_input: control characters`           | Embedded 0x01..0x1F in a string arg    | Strip control chars; use \\t \\n \\r only |
+| `invalid_input: path escapes CWD`             | `../` or absolute path outside $HOME   | Keep outputs inside cwd or $HOME/.unicli  |
+| `invalid_input: id contains URL punctuation`  | You pasted a full URL as a resource id | Strip the `?`, `#`, or `%XX` sequences    |
+| Command appears to run but gets wrong args    | Shell ate your quotes                  | Switch to stdin-JSON                      |
+| Unexpected shell expansion (`$HOME`, `` ` ``) | Bash interpolated your payload         | Single-quote, or better, use stdin-JSON   |
+
+## Recipes
+
+### Search with a complex query
+
+```bash
+printf '%s\n' '{"query": "large language models \"emergent\" behaviour", "limit": 25}' \
+  | unicli arxiv search
+```
+
+### Multi-arg desktop command
+
+```bash
+cat > /tmp/render.json <<'EOF'
+{ "scene": "/Users/me/project/main.blend", "output_dir": "~/renders", "frame_start": 1, "frame_end": 240 }
+EOF
+unicli blender render --args-file /tmp/render.json
+```
+
+### Debug-first workflow
+
+```bash
+unicli describe youtube transcript         # 1. understand the contract
+echo '{"url": "https://…"}' | unicli youtube transcript --dry-run   # 2. preview
+echo '{"url": "https://…"}' | unicli youtube transcript             # 3. run
+```
+
+## Version contract
+
+- v0.214.0+ required for stdin-JSON auto-detect, `--describe`, and consistent MCP tool discovery metadata
+- v0.213.1 or earlier agents should fall back to `unicli schema <site> <cmd>`
+  and explicit `--` flag args

package/skills/unicli-explorer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: unicli-explorer
+description: >
+  Create new Uni-CLI adapters by exploring websites and APIs. Use when adding
+  support for a new site, desktop app, or service that unicli doesn't cover yet.
+version: 1.0.0
+triggers:
+  - "create adapter"
+  - "new adapter"
+  - "add site"
+  - "explore site"
+allowed-tools: [Bash, Read, Write]
+protocol: 2.0
+---
+
+## When to Use
+
+Adding a new website, API, or local app to Uni-CLI's adapter catalog (~20-line YAML files).
+
+## Workflow
+
+### 1. Discover the API
+
+```bash
+unicli browser start                     # Ensure Chrome is running
+unicli operate open <target-url>         # Navigate to target page
+unicli operate state                     # Inspect DOM structure
+unicli operate network                   # List captured JSON API requests
+unicli operate click <ref>               # Trigger lazy-loaded APIs
+unicli operate network                   # Check for new requests
+```
+
+### 2. Choose Strategy
+
+| Condition                 | Strategy    | Browser? |
+| ------------------------- | ----------- | -------- |
+| `fetch(url)` returns data | `public`    | No       |
+| Needs login cookies       | `cookie`    | Yes      |
+| Needs CSRF/Bearer token   | `header`    | Yes      |
+| Complex signed requests   | `intercept` | Yes      |
+| No API, DOM only          | `ui`        | Yes      |
+
+### 3. Write YAML Adapter
+
+Create `src/adapters/<site>/<command>.yaml`:
+
+```yaml
+site: mysite
+name: mycommand
+description: What this command does
+type: web-api
+strategy: public
+args:
+  query: { type: str, required: true, positional: true }
+  limit: { type: int, default: 20 }
+pipeline:
+  - fetch:
+      {
+        url: "https://api.example.com/search",
+        params: { q: "${{ args.query }}" },
+      }
+  - select: data.results
+  - map: { title: "${{ item.title }}", url: "${{ item.url }}" }
+  - limit: ${{ args.limit }}
+columns: [title, url]
+```
+
+### 4. Test
+
+```bash
+npm run dev -- mysite mycommand "test" --limit 3
+npm run verify
+```
+
+### 5. Self-Repair
+
+When adapters break: read error JSON `adapter_path` -> fix the ~20-line YAML ->
+save to `~/.unicli/adapters/<site>/<cmd>.yaml` -> `unicli test <site>`.
+
+## Key Pipeline Steps
+
+`fetch`, `fetch_text`, `parse_rss`, `html_to_md`, `select`, `map`, `filter`, `sort`,
+`limit`, `exec`, `navigate`, `evaluate`, `intercept`, `click`, `type`, `wait`,
+`press`, `scroll`, `snapshot`, `download`, `set`, `if`, `each`, `parallel`
+
+## Pipe Filters
+
+`${{ item.field | join(', ') | truncate(100) }}` -- available: `join`, `urlencode`,
+`slice`, `replace`, `lowercase`, `uppercase`, `trim`, `default`, `split`, `first`,
+`last`, `length`, `strip_html`, `truncate`

package/skills/unicli-hermes/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: unicli-hermes
+description: >
+  Use Uni-CLI to interact with 237 websites, desktop apps, and system tools.
+  Trigger when: user asks to check a website, fetch data, control a desktop app,
+  or interact with social media, news, finance, or AI platforms.
+version: 0.219.0
+depends-on:
+  - talk-normal
+triggers:
+  - "unicli"
+  - "website"
+  - "fetch from"
+  - "check twitter"
+  - "bilibili"
+  - "hackernews"
+---
+
+# Uni-CLI Agent Skill
+
+Universal CLI for AI agents — 237 sites, 3,319 commands.
+
+## Install
+
+```bash
+npm install -g @zenalexa/unicli
+```
+
+## Quick Reference
+
+```bash
+unicli <site> <command> [--limit N] [-f json]  # Run any command
+unicli list [--site <name>]                     # Discover commands
+unicli schema <site> <command>                  # Get input/output schema
+unicli repair <site> <command>                  # Fix broken adapter
+unicli test <site>                              # Validate adapter
+```
+
+## When to Use
+
+- **Web data**: `unicli twitter search "query"`, `unicli hackernews top`
+- **Chinese platforms**: `unicli bilibili hot`, `unicli zhihu trending`
+- **Finance**: `unicli bloomberg latest`, `unicli xueqiu hot`
+- **Desktop apps**: `unicli blender render scene.blend`, `unicli ffmpeg compress video.mp4`
+- **macOS system**: `unicli macos volume 50`, `unicli macos screenshot`
+
+## Output
+
+- Default: v2 AgentEnvelope rendered as Markdown
+- JSON: pass `-f json` or set `UNICLI_OUTPUT=json`
+- Errors: structured envelope to stderr with `adapter_path`, `step`, `suggestion`
+
+## Self-Repair
+
+When a command fails:
+
+1. Read the error JSON — it includes the adapter file path
+2. Read the YAML adapter (~20 lines)
+3. Fix the issue (selector changed? API versioned? auth needed?)
+4. Save to `~/.unicli/adapters/<site>/<command>.yaml`
+5. Verify: `unicli repair <site> <command>`
+
+## MCP Server (Hermes / agentskills.io)
+
+Add to your Hermes agent configuration:
+
+```yaml
+mcp_servers:
+  unicli:
+    command: "npx"
+    args: ["-y", "@zenalexa/unicli", "mcp", "serve"]
+    tools:
+      include: [unicli_run, unicli_list, unicli_search, unicli_explore]
+```
+
+Or run the expanded server to expose all 3,319 commands as individual tools:
+
+```yaml
+mcp_servers:
+  unicli:
+    command: "npx"
+    args: ["-y", "@zenalexa/unicli", "mcp", "serve", "--expanded"]
+```

package/skills/unicli-oneshot/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: unicli-oneshot
+description: >
+  Quick single-command adapter generation for unicli. Use when you need to
+  create a one-off command for a specific URL and goal — 4 steps done.
+---
+
+# unicli One-Shot Adapter
+
+Generate a single unicli command from a URL + goal in 4 steps.
+
+## Process
+
+### Step 1: Open the Page
+
+```bash
+unicli operate open "<URL>"
+unicli operate state
+```
+
+### Step 2: Discover the API
+
+Open browser DevTools Network tab. Look for XHR/Fetch requests that return JSON data matching your goal.
+
+Key signals:
+
+- `/api/` or `/v1/` in URL → REST endpoint
+- JSON response with array of items → listable data
+- Query parameters → filterable
+
+### Step 3: Write the YAML
+
+Create `src/adapters/<site>/<command>.yaml`:
+
+```yaml
+site: <site-name>
+name: <command>
+description: <what it does>
+type: web-api
+strategy: public # or cookie if auth needed
+pipeline:
+  - fetch:
+      url: <discovered-api-url>
+      params: <query-params>
+  - select: <path.to.data>
+  - map:
+      title: ${{ item.title }}
+      # ... map fields
+columns: [title, ...]
+```
+
+### Step 4: Test
+
+```bash
+npm run dev -- <site> <command>
+npm run dev -- <site> <command> -f json
+```
+
+Done. One YAML file, one command, zero code.

package/skills/unicli-operate/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: unicli-operate
+description: >
+  Compatibility guide for `unicli operate`. Prefer `unicli browser`, which now
+  exposes the same operator surface plus daemon/session diagnostics.
+version: 1.0.0
+triggers:
+  - "operate browser"
+  - "click element"
+  - "fill form"
+  - "extract page data"
+  - "unicli operate"
+allowed-tools: [Bash]
+protocol: 2.0
+---
+
+## When to Use
+
+Prefer `unicli browser` for new work:
+
+```bash
+unicli browser open <url>
+unicli browser state
+unicli browser click <ref>
+unicli browser type <ref> <text>
+unicli browser find --css <selector>
+unicli browser extract
+unicli browser tabs
+unicli browser frames
+```
+
+`unicli operate ...` still works, but it is now the compatibility path over the same implementation.
+
+## Core Workflow
+
+1. `open` -> navigate to URL
+2. `state` -> inspect DOM, get `[ref]` numbers for interactive elements
+3. interact -> `click`, `type`, `select`, `keys` using ref numbers
+4. verify -> `state` again or `get value <ref>` to confirm
+5. extract -> `eval` for structured data
+
+**Always `state` before interacting. Never guess ref numbers.**
+
+## All Operate Subcommands
+
+```bash
+# Navigation
+unicli operate open <url>             # Navigate to URL
+unicli operate back                   # Go back in history
+unicli operate scroll [direction]     # down, up, bottom, top
+unicli operate close                  # Close automation window
+
+# Inspection
+unicli operate state                  # DOM tree with [ref] indices
+unicli operate screenshot [path]      # Save visual capture
+
+# Get data
+unicli operate get title|url          # Page title or URL
+unicli operate get text <ref>         # Element text by ref
+unicli operate get value <ref>        # Input value (verify after type)
+unicli operate get html [selector]    # Page or scoped HTML
+unicli operate get attributes <ref>   # Element attributes
+
+# Interaction
+unicli operate click <ref>            # Click element
+unicli operate type <ref> <text>      # Type into element
+unicli operate select <ref> <option>  # Select dropdown
+unicli operate keys <key>             # Press key (Enter, Escape, Control+a)
+unicli operate upload <ref> <path>    # Upload file
+unicli operate hover <ref>            # Hover over element
+
+# Wait
+unicli operate wait time <ms>         # Fixed delay
+unicli operate wait selector <sel>    # Until element appears
+unicli operate wait text <str>        # Until text appears
+
+# Advanced
+unicli operate eval <js>              # Execute JS in page
+unicli operate network [pattern]      # Captured network requests
+unicli operate observe <query>        # Natural language observation
+```
+
+## Patterns
+
+```bash
+# Browse + extract
+unicli operate open "https://news.ycombinator.com" && unicli operate state
+unicli operate eval "JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a=>({title:a.textContent,url:a.href})))"
+
+# Fill form (chain to reduce round trips)
+unicli operate type 3 "user@example.com" && unicli operate type 5 "pass" && unicli operate click 7
+
+# API discovery
+unicli operate open "https://example.com/feed" && unicli operate wait time 3000
+unicli operate network                # See captured JSON APIs
+```
+
+## Rules
+
+1. Always `state` first -- never guess refs
+2. `eval` is read-only -- never `eval "el.click()"`, use `click <ref>`
+3. Verify inputs with `get value <ref>` after `type`
+4. Re-inspect after navigation -- run `state` after `open` or link clicks
+5. Prefer API over DOM -- if `network` reveals JSON APIs, use YAML adapters
+
+## Troubleshooting
+
+| Problem                | Fix                                     |
+| ---------------------- | --------------------------------------- |
+| Browser not connected  | `unicli browser start`                  |
+| Element not found      | `scroll down` then `state`              |
+| Stale refs after click | `state` to refresh                      |
+| eval returns undefined | Wrap: `"(function(){ return ...; })()"` |