@zenalexa/unicli 0.217.3 → 0.218.1

package/skills/unicli/references/output.md

@@ -0,0 +1,238 @@
+# AgentEnvelope v2 — Output Format Reference
+
+All unicli commands emit a **v2 AgentEnvelope**. This is the stable machine contract
+since v0.215. This reference covers every field, error codes, parsing patterns, and
+format-specific behavior.
+
+---
+
+## Complete Schema
+
+```typescript
+// Success envelope
+{
+  ok: true,
+  schema_version: "2",          // always "2"
+  command: "site.command",      // e.g. "hackernews.top"
+  meta: {
+    duration_ms: number,        // wall-clock time in ms
+    count?: number,             // rows in data[]
+    surface?: "web" | "desktop" | "system" | "mobile",
+    adapter_version?: string,   // YAML/TS adapter version string
+    operator?: string,          // browser operator handle if used
+    pagination?: {
+      next_cursor?: string,     // opaque cursor; pass via --cursor
+      has_more?: boolean,       // true when more pages exist
+    }
+  },
+  data: T[],                    // payload — array or object depending on adapter
+  error: null,
+  next_actions: AgentNextAction[]
+}
+
+// Failure envelope
+{
+  ok: false,
+  schema_version: "2",
+  command: "site.command",
+  meta: { duration_ms: number },
+  data: null,
+  error: {
+    code: string,               // see error code table below
+    exit_code: number,          // sysexits.h aligned
+    message: string,            // human-readable
+    adapter_path?: string,      // YAML file to repair (if applicable)
+    step: number,               // pipeline step index that failed (0-based)
+    retryable: boolean,         // true = retry after fix; false = args/config issue
+    suggestion: string,         // what to do next
+    remedy?: {
+      message: string,
+      command?: string,         // exact CLI command to run as remedy
+      deeplink?: string,
+      doc?: string
+    },
+    diff_candidate?: string,    // suggested YAML diff for repair
+    minimum_capability?: string // e.g. "browser.cdp" — needed transport
+  },
+  next_actions: AgentNextAction[]
+}
+```
+
+---
+
+## Error Code Reference
+
+### Transport / network (5 codes)
+
+| Code                | Exit | Meaning                             | Action                                  |
+| ------------------- | ---- | ----------------------------------- | --------------------------------------- |
+| `network_error`     | 75   | TCP/TLS/DNS failure, timeout        | Retry once; check connectivity          |
+| `rate_limited`      | 75   | 429 or upstream quota               | Wait and retry; reduce `--limit`        |
+| `upstream_error`    | 75   | 5xx or malformed body from upstream | Retry; if persists load `unicli-repair` |
+| `api_error`         | 1    | 4xx non-auth error                  | Read `message` + `suggestion`           |
+| `not_authenticated` | 77   | Credentials expired or missing      | `unicli auth setup <site>`              |
+
+### Input / validation (3 codes)
+
+| Code            | Exit | Meaning                        | Action                                   |
+| --------------- | ---- | ------------------------------ | ---------------------------------------- |
+| `invalid_input` | 2    | Arg failed validation          | Fix args; `unicli describe <site> <cmd>` |
+| `selector_miss` | 1    | CSS/XPath matched nothing      | Load `unicli-repair` — selector changed  |
+| `not_found`     | 66   | HTTP 404 or "no such resource" | Check the resource ID or URL             |
+
+### Authorization (2 codes)
+
+| Code                | Exit | Meaning                       | Action                                 |
+| ------------------- | ---- | ----------------------------- | -------------------------------------- |
+| `auth_required`     | 77   | Missing cookie file           | `unicli auth setup <site>`             |
+| `permission_denied` | 77   | Authenticated but lacks scope | Different account or check permissions |
+
+### Runtime (2 codes)
+
+| Code             | Exit | Meaning                             | Action                                              |
+| ---------------- | ---- | ----------------------------------- | --------------------------------------------------- |
+| `internal_error` | 1    | Uncaught exception in unicli        | Report to GitHub issues                             |
+| `quarantined`    | 1    | Adapter gated by `quarantine:` flag | `unicli repair --quarantined`; load `unicli-repair` |
+
+### Ref-locator (3 codes, browser mode only)
+
+| Code            | Exit | Meaning                                | Action                                       |
+| --------------- | ---- | -------------------------------------- | -------------------------------------------- |
+| `stale_ref`     | 1    | Browser snapshot ref detached from DOM | Re-run `unicli browser state` for fresh refs |
+| `ambiguous`     | 1    | Ref maps to multiple elements          | Use a more specific `--css` selector         |
+| `ref_not_found` | 1    | Ref not in current snapshot            | Re-run `unicli browser state`                |
+
+---
+
+## next_actions — HATEOAS Navigation
+
+`next_actions` are generated from the adapter schema. **Trust them** — they are not
+suggested by an LLM but computed from the command's type, args, and response context.
+
+```json
+"next_actions": [
+  {
+    "command": "unicli describe hackernews top",
+    "description": "Inspect the command's JSON schema, channels, and example payload"
+  },
+  {
+    "command": "unicli hackernews top --args-file <path.json>",
+    "description": "Re-run with a JSON payload from file",
+    "params": {
+      "path": {
+        "description": "Absolute path to a JSON object file with command args"
+      }
+    }
+  },
+  {
+    "command": "unicli hackernews top --cursor <next_cursor>",
+    "description": "Fetch next page",
+    "params": {
+      "next_cursor": {
+        "value": "eyJwIjoyLCJsIjoyNX0=",
+        "description": "Pagination cursor from current response"
+      }
+    }
+  }
+]
+```
+
+`params[].value` pre-fills the value from the current response (e.g. the cursor).
+`params[].enum` constrains valid choices. `params[].default` shows the implicit default.
+
+---
+
+## Output Format Comparison
+
+| Format    | Flag              | Use case                                                |
+| --------- | ----------------- | ------------------------------------------------------- |
+| `md`      | default / `-f md` | Display to user; agent-native Markdown with frontmatter |
+| `json`    | `-f json`         | Programmatic parsing with jq or code                    |
+| `yaml`    | `-f yaml`         | Config-style output                                     |
+| `csv`     | `-f csv`          | Spreadsheet export; array data only                     |
+| `compact` | `-f compact`      | One row per line, `\|` separator; array data only       |
+
+`UNICLI_OUTPUT=json` environment variable sets `json` globally without per-call flags.
+
+---
+
+## Parsing Patterns
+
+### Extract titles
+
+```bash
+unicli hackernews top -f json | jq '.data[].title'
+```
+
+### Filter by field value
+
+```bash
+unicli xueqiu hot -f json | jq '.data[] | select(.change | tonumber > 5)'
+```
+
+### Extract nested field
+
+```bash
+unicli bilibili hot -f json | jq '.data[] | {title: .title, view: .stat.view}'
+```
+
+### Pagination loop
+
+```bash
+cursor=""
+while true; do
+  result=$(unicli reddit hot --limit 25 ${cursor:+--cursor $cursor} -f json)
+  echo "$result" | jq '.data[].title'
+  cursor=$(echo "$result" | jq -r '.meta.pagination.next_cursor // empty')
+  has_more=$(echo "$result" | jq -r '.meta.pagination.has_more // false')
+  [ "$has_more" = "true" ] || break
+done
+```
+
+### Check success before parsing
+
+```bash
+result=$(unicli hackernews top -f json)
+if echo "$result" | jq -e '.ok' >/dev/null 2>&1; then
+  echo "$result" | jq '.data[].title'
+else
+  echo "Error: $(echo "$result" | jq -r '.error.message')"
+  echo "Action: $(echo "$result" | jq -r '.error.suggestion')"
+fi
+```
+
+### Error-first pattern (recommended)
+
+```bash
+unicli twitter search "AI agents" -f json | jq '
+  if .ok then
+    .data[] | {title: .text, author: .author}
+  else
+    "ERROR[\(.error.code)]: \(.error.message) → \(.error.suggestion)"
+  end
+'
+```
+
+---
+
+## Surface Field
+
+`meta.surface` indicates the access method used:
+
+| Value     | Meaning                                       |
+| --------- | --------------------------------------------- |
+| `web`     | HTTP/REST API call                            |
+| `desktop` | Local app via AppleScript / Accessibility API |
+| `system`  | macOS system call                             |
+| `mobile`  | Mobile device bridge                          |
+
+---
+
+## Schema Version History
+
+| Version | Since       | Notes                             |
+| ------- | ----------- | --------------------------------- |
+| `2`     | v0.215      | Current. All agent-facing output. |
+| `1`     | v0.1–v0.214 | Legacy. Removed in v0.215.        |
+
+v2 is the only version. If you see `schema_version: "1"` in output, upgrade unicli.

package/skills/unicli/references/sites.md

@@ -0,0 +1,259 @@
+# Site Catalog — Uni-CLI 237 Sites
+
+Load this file when you need to find which site to query. Organized by category.
+All commands: `unicli list --site <site>` · Full search: `unicli search "<topic>"`.
+
+---
+
+## News & Tech Media
+
+| Site          | Key commands                                                      |
+| ------------- | ----------------------------------------------------------------- |
+| `hackernews`  | `top`, `new`, `ask`, `show`, `jobs`, `search`, `comments`, `user` |
+| `bbc`         | `hot`, `tech`, `world`, `business`                                |
+| `cnn`         | `top`, `tech`                                                     |
+| `nytimes`     | `top`, `tech`                                                     |
+| `reuters`     | `top`, `tech`                                                     |
+| `36kr`        | `hot`, `new`, `recommend`, `search`                               |
+| `ithome`      | `hot`, `new`, `search`                                            |
+| `infoq`       | `hot`, `new`                                                      |
+| `v2ex`        | `hot`, `top`, `new`, `tab`                                        |
+| `linux-do`    | `hot`, `new`                                                      |
+| `devto`       | `hot`, `trending`, `new`, `search`                                |
+| `lobsters`    | `hot`, `new`                                                      |
+| `lesswrong`   | `hot`, `new`, `search`, many more                                 |
+| `producthunt` | `hot`, `top`, `search`                                            |
+
+---
+
+## Social & Community
+
+| Site        | Key commands                                      |
+| ----------- | ------------------------------------------------- |
+| `twitter`   | `search`, `trending`, `user`, `timeline`, `likes` |
+| `bluesky`   | `trending`, `search`, `user`, `feed`, many more   |
+| `reddit`    | `hot`, `new`, `top`, `search`, `subreddit`        |
+| `weibo`     | `hot`, `trending`, `search`, `user`               |
+| `zhihu`     | `hot`, `trending`, `search`, `question`, `answer` |
+| `jike`      | `hot`, `search`, `user`, `topic`                  |
+| `instagram` | `feed`, `search`, `user`, `stories`, many more    |
+| `facebook`  | `feed`, `search`, `groups`, many more             |
+| `tieba`     | `hot`, `search`, `posts`                          |
+| `threads`   | `hot`, `search`, `user`                           |
+
+---
+
+## Video & Streaming
+
+| Site       | Key commands                                                       |
+| ---------- | ------------------------------------------------------------------ |
+| `bilibili` | `hot`, `trending`, `search`, `user`, `video`, `bangumi`, many more |
+| `youtube`  | `search`, `trending`, `channel`, `comments`                        |
+| `tiktok`   | `search`, `trending`, `user`                                       |
+| `douyin`   | `hot`, `search`, `user`                                            |
+| `kuaishou` | `hot`, `search`                                                    |
+| `douyu`    | `hot`, `new`                                                       |
+| `hupu`     | `hot`, `new`, `search`, `match`                                    |
+
+---
+
+## Finance & Markets
+
+| Site            | Key commands                                    |
+| --------------- | ----------------------------------------------- |
+| `xueqiu`        | `hot`, `hot-stock`, `search`, `quote`, `news`   |
+| `eastmoney`     | `hot`, `news`, `fund`, `stock`, many more       |
+| `bloomberg`     | `markets`, `latest`, `search`, `tech`, `asia`   |
+| `binance`       | `hot`, `price`, `kline`, `orderbook`, many more |
+| `barchart`      | `hot`, `movers`, `futures`, `currencies`        |
+| `coinbase`      | `price`, `markets`                              |
+| `futu`          | `hot`, `news`                                   |
+| `yahoo-finance` | `search`, `quote`, `news`                       |
+| `exchangerate`  | `rate`, `convert`                               |
+
+---
+
+## E-commerce & Shopping
+
+| Site       | Key commands                                      |
+| ---------- | ------------------------------------------------- |
+| `amazon`   | `search`, `hot`, `deals`, `categories`, many more |
+| `jd`       | `search`, `hot`, `deals`, `flash-sale`, many more |
+| `taobao`   | `search`, `hot`, `new`                            |
+| `xianyu`   | `search`, `hot`                                   |
+| `smzdm`    | `hot`, `new`, `deal`                              |
+| `dangdang` | `hot`, `search`                                   |
+| `coupang`  | `hot`, `search`                                   |
+| `boss`     | `search`, `hot`, `company`, many more             |
+| `51job`    | `search`, `hot`                                   |
+| `linkedin` | `search`, `jobs`, `people`                        |
+| `maimai`   | `hot`, `search`                                   |
+
+---
+
+## AI Platforms
+
+| Site        | Key commands                                          |
+| ----------- | ----------------------------------------------------- |
+| `claude`    | `chat`, `vision`, `summarize`, `translate`, many more |
+| `chatgpt`   | `chat`, `image`, `vision`, many more                  |
+| `deepseek`  | `chat`, `code`, many more                             |
+| `gemini`    | `chat`, `vision`, `search`                            |
+| `doubao`    | `chat`, `image`, many more                            |
+| `grok`      | `chat`                                                |
+| `hf`        | `search`, `model`, `dataset`, `spaces`                |
+| `codex`     | `run`, `chat`, `code`, many more                      |
+| `hermes`    | `run`, `list`, `search`                               |
+| `autoagent` | `run`                                                 |
+
+---
+
+## Developer Tools & Code
+
+| Site                    | Key commands                               |
+| ----------------------- | ------------------------------------------ |
+| `github-trending`       | `daily`, `weekly`, `monthly`               |
+| `gh`                    | `pr`, `issue`, `repo`, `search`, many more |
+| `gitee`                 | `hot`, `search`, `trending`                |
+| `gitlab`                | `hot`, `search`                            |
+| `docker-hub`            | `search`, `hot`                            |
+| `docker`                | `ps`, `images`, `logs`                     |
+| `hackernews`            | `search` (dev content is strong here)      |
+| `crates-io`             | `search`, `hot`, `new`                     |
+| `cocoapods`             | `search`, `info`                           |
+| `npm` (via bridge `gh`) | use `gh` or `docker` bridges               |
+
+---
+
+## Academic & Research
+
+| Site                 | Key commands             |
+| -------------------- | ------------------------ |
+| `arxiv`              | `search`, `hot`, `paper` |
+| `huggingface-papers` | `hot`, `new`             |
+| `google-scholar`     | `search`, `author`       |
+| `baidu-scholar`      | `search`                 |
+| `cnki`               | `search`                 |
+| `semanticscholar`    | (via MCP, not unicli)    |
+
+---
+
+## Reading & Content
+
+| Site         | Key commands                                        |
+| ------------ | --------------------------------------------------- |
+| `douban`     | `hot`, `top250`, `search`, `book`, `movie`, `music` |
+| `weread`     | `ranking`, `hot`, `new`                             |
+| `wikipedia`  | `search`, `article`                                 |
+| `dictionary` | `define`, `translate`, `synonym`                    |
+| `itch-io`    | `hot`, `new`, `search`                              |
+
+---
+
+## Travel & Lifestyle
+
+| Site       | Key commands               |
+| ---------- | -------------------------- |
+| `ctrip`    | `hot`, `search`            |
+| `dianping` | `hot`, `search`            |
+| `ele`      | `hot`, `search`            |
+| `ke`       | `search`, `hot`, many more |
+| `band`     | `hot`, `events`            |
+
+---
+
+## Desktop Apps (macOS)
+
+### Productivity
+
+| Site             | Key commands                      |
+| ---------------- | --------------------------------- |
+| `cursor`         | `open`, `edit`, `run`, many more  |
+| `chatwise`       | `chat`, `create`, many more       |
+| `evernote-app`   | `search`, `note`, many more       |
+| `apple-notes`    | `search`, `create`, `list`        |
+| `apple-podcasts` | `search`, `play`                  |
+| `insomnia`       | `request`, `workspace`, many more |
+
+### Creative
+
+| Site          | Key commands                           |
+| ------------- | -------------------------------------- |
+| `blender`     | `render`, `info`, `script`, many more  |
+| `gimp`        | `open`, `resize`, `export`, many more  |
+| `figma`       | `export`, `pages`, many more           |
+| `inkscape`    | `export`, `info`                       |
+| `krita`       | `open`, `export`, many more            |
+| `kdenlive`    | `render`, `export`                     |
+| `imagemagick` | `resize`, `convert`, `info`, many more |
+
+### Development
+
+| Site             | Key commands                          |
+| ---------------- | ------------------------------------- |
+| `github-desktop` | `status`, `commit`, `push`, many more |
+| `gitkraken`      | `status`, `branch`, many more         |
+
+### Communication
+
+| Site          | Key commands                          |
+| ------------- | ------------------------------------- |
+| `discord-app` | `send`, `read`, `channels`, many more |
+| `imessage`    | `send`, `read`, `search`              |
+| `dingtalk`    | `send`, `read`, many more             |
+| `feishu`      | `send`, `read`, many more             |
+| `lark`        | `send`, `read`, many more             |
+
+---
+
+## Local & System Services
+
+| Site          | Key commands                                            |
+| ------------- | ------------------------------------------------------- |
+| `macos`       | `volume`, `brightness`, `screenshot`, `wifi`, many more |
+| `ffmpeg`      | `compress`, `convert`, `info`, many more                |
+| `jq`          | `filter`, `format`                                      |
+| `homebrew`    | `install`, `search`                                     |
+| `comfyui`     | `generate`, `workflow`, many more                       |
+| `ollama`      | (via service adapter)                                   |
+| `adguardhome` | `status`, `filter`, many more                           |
+| `bitwarden`   | `get`, `list`, many more                                |
+
+---
+
+## Cloud & Infrastructure
+
+| Site     | Key commands                 |
+| -------- | ---------------------------- |
+| `aws`    | `run` (bridge to aws CLI)    |
+| `az`     | `run` (bridge to az CLI)     |
+| `gcloud` | `run` (bridge to gcloud CLI) |
+| `doctl`  | `run` (bridge to doctl)      |
+| `flyctl` | `run` (bridge to fly CLI)    |
+
+---
+
+## Chinese Platforms (Specialty)
+
+| Site          | Key commands                 |
+| ------------- | ---------------------------- |
+| `1688`        | `search`, `hot`, many more   |
+| `chaoxing`    | `courses`, `search`          |
+| `jianyu`      | `search`, `hot`              |
+| `juejin`      | `hot`, `trending`            |
+| `gov-law`     | `search`, `hot`              |
+| `gov-policy`  | `search`, `latest`           |
+| `jimeng`      | `generate`, `hot`, many more |
+| `antigravity` | many commands                |
+
+---
+
+## Discover More
+
+```bash
+unicli list                          # full list, 3,319 commands
+unicli search "<topic>"              # semantic search
+unicli list --type desktop           # 2,068 desktop app commands
+unicli list --type service           # 43 local service commands
+unicli list --quarantined            # adapters needing repair
+```

package/skills/unicli-browser/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: unicli-browser
+description: >
+  Control browser automation sessions via unicli. The browser command now owns
+  lifecycle, interaction, introspection, and daemon diagnostics.
+version: 1.0.0
+triggers:
+  - "browser automation"
+  - "control chrome"
+  - "unicli browser"
+  - "launch chrome"
+allowed-tools: [Bash]
+protocol: 2.0
+---
+
+## When to Use
+
+Use `unicli browser` for both browser lifecycle and direct page interaction.
+`unicli operate` still exists, but it is now a compatibility alias over the same implementation.
+
+## Quick Start
+
+```bash
+unicli browser start          # Launch Chrome with CDP
+unicli browser status         # Check CDP + daemon/session status
+unicli browser open <url>     # Navigate to a page
+unicli browser state          # DOM accessibility tree with [ref] numbers
+unicli browser screenshot     # Visual capture to file
+unicli browser find --css ... # Structured DOM query + ref allocation
+unicli browser extract        # Chunked long-form text extraction
+```
+
+## Browser Lifecycle
+
+```bash
+unicli browser start          # Spawn Chrome + daemon (port 19825)
+unicli browser status         # Connection health check
+unicli daemon status          # Daemon process info
+unicli daemon stop            # Stop daemon
+unicli daemon restart         # Restart daemon
+```
+
+The daemon auto-exits after idle timeout. Chrome reuses your existing login sessions.
+
+## Authentication
+
+```bash
+unicli auth setup <site>      # Show required cookies + file template
+unicli auth check <site>      # Validate cookie file
+unicli auth list              # List configured sites
+```
+
+Cookie files: `~/.unicli/cookies/<site>.json` with format `{ "KEY": "value" }`.
+
+## Strategies Requiring Browser
+
+| Strategy    | How it works                                   |
+| ----------- | ---------------------------------------------- |
+| `cookie`    | Injects cookies from file into request headers |
+| `header`    | Cookie + auto-extracted CSRF token             |
+| `intercept` | Navigate page, capture XHR/fetch responses     |
+| `ui`        | Interact with page DOM (click, type, scroll)   |
+
+`public` strategy does NOT need a browser.
+
+## Architecture
+
+There are two browser paths:
+
+1. `browser start` / `browser cookies` use local Chrome + CDP directly.
+2. `browser open/state/click/...` use:
+   CLI -> daemon-client -> HTTP/WS -> daemon -> Browser Bridge extension -> Chrome tabs
+
+That means extension state, daemon port, workspace, focus/background mode, and tab binding are all part of the real runtime story.
+
+Useful controls:
+
+```bash
+unicli browser --daemon-port 19826 sessions
+unicli browser --workspace profile-a bind --match-domain example.com
+unicli browser --isolated open https://example.com
+unicli browser --background open https://example.com
+```
+
+## Diagnostics
+
+```bash
+unicli doctor                                    # Full system health check
+UNICLI_DIAGNOSTIC=1 unicli <site> <cmd>          # Enhanced error context
+```
+
+## Troubleshooting
+
+| Problem                 | Fix                                   |
+| ----------------------- | ------------------------------------- |
+| "Browser not connected" | `unicli browser start`                |
+| Exit 69 (unavailable)   | `unicli browser start` then retry     |
+| Exit 77 (auth)          | `unicli auth setup <site>` then retry |
+| CDP connection dropped  | `unicli daemon restart`               |