@jackwener/opencli 1.6.2 → 1.6.3

package/docs/guide/electron-app-cli.md

@@ -1,200 +0,0 @@
----
-description: How to turn a new Electron desktop app into an OpenCLI adapter
----
-
-# Add a New Electron App CLI
-
-This guide is the **fast entry point** for turning a new Electron desktop application into an OpenCLI adapter.
-
-If you want the full background and deeper SOP, read:
-- [CLI-ifying Electron Applications](/advanced/electron)
-- [Chrome DevTools Protocol](/advanced/cdp)
-- [TypeScript Adapter Guide](/developer/ts-adapter)
-
-## When to use this guide
-
-Use this workflow when the target app:
-- is built with **Electron**, or at least exposes a working **Chrome DevTools Protocol (CDP)** endpoint
-- can be launched with `--remote-debugging-port=<port>`
-- should be automated through its real UI instead of a public HTTP API
-
-If the app is **not** Electron and does **not** expose CDP, use the native desktop automation pattern instead. See [CLI-ifying Electron Applications](/advanced/electron#non-electron-pattern-applescript).
-
-## The shortest path
-
-### 1. Confirm the app is Electron
-
-Typical macOS check:
-
-```bash
-ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
-```
-
-If Electron is present, the next step is usually to launch the app with a debugging port.
-
-### 2. Launch it with CDP enabled
-
-```bash
-/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
-```
-
-Then point OpenCLI at that CDP endpoint:
-
-```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
-```
-
-### 3. Start with the 5-command pattern
-
-For a new Electron adapter, implement these commands first in `src/clis/<app>/`:
-
-- `status.ts` — verify the app is reachable through CDP
-- `dump.ts` — inspect DOM and snapshot structure before guessing selectors
-- `read.ts` — extract the visible context you actually need
-- `send.ts` — inject text and submit through the real editor
-- `new.ts` — create a new session, tab, thread, or document
-
-This is the standard baseline because it gives you:
-- a connection check
-- a reverse-engineering tool
-- one read path
-- one write path
-- one session reset path
-
-The full rationale and examples are in [CLI-ifying Electron Applications](/advanced/electron).
-
-## Recommended implementation workflow
-
-### Step 1: Build `status`
-
-Goal: prove CDP connectivity before touching app-specific logic.
-
-Typical checks:
-- current URL
-- document title
-- app shell presence
-
-If `status` is unstable, stop there and fix connectivity first.
-
-### Step 2: Build `dump`
-
-Do **not** guess selectors from the rendered UI.
-
-Dump:
-- `document.body.innerHTML`
-- accessibility snapshot
-- any stable attributes such as `data-testid`, `role`, `aria-*`, framework-specific markers
-
-Use the dump to identify real containers, buttons, composers, and conversation regions.
-
-### Step 3: Build `read`
-
-Target only the app region that matters.
-
-Good targets:
-- message list
-- editor history
-- visible thread content
-- selected document panel
-
-Avoid dumping the entire page text into the final command output.
-
-### Step 4: Build `send`
-
-Most Electron apps use React-style controlled editors, so direct `.value = ...` assignments are often ignored.
-
-Prefer editor-aware input patterns such as:
-- focus the editable region
-- use `document.execCommand('insertText', false, text)` when applicable
-- use real key presses like `Enter`, `Meta+Enter`, or app-specific shortcuts
-
-### Step 5: Build `new`
-
-Many desktop apps rely on keyboard shortcuts for “new chat”, “new tab”, or “new note”.
-
-Typical pattern:
-
-```ts
-const isMac = process.platform === 'darwin';
-await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
-await page.wait(1);
-```
-
-## Where to put files
-
-For a TypeScript desktop adapter, the usual layout is:
-
-```text
-src/clis/<app>/status.ts
-src/clis/<app>/dump.ts
-src/clis/<app>/read.ts
-src/clis/<app>/send.ts
-src/clis/<app>/new.ts
-src/clis/<app>/utils.ts
-```
-
-If the app grows beyond the baseline, add higher-level commands such as:
-- `ask`
-- `history`
-- `model`
-- `screenshot`
-- `export`
-
-## What to document when you add a new app
-
-When the adapter is ready, also add:
-
-- an adapter doc under `docs/adapters/desktop/`
-- command list and examples
-- launch instructions with `--remote-debugging-port`
-- any required environment variables
-- platform-specific caveats
-
-Examples to study:
-- `docs/adapters/desktop/codex.md`
-- `docs/adapters/desktop/chatwise.md`
-- `docs/adapters/desktop/notion.md`
-- `docs/adapters/desktop/discord.md`
-
-## Common failure modes
-
-### CDP endpoint exists, but commands are flaky
-
-Usually one of these:
-- the wrong window/tab is selected
-- the app has not finished rendering
-- selectors were guessed instead of discovered from `dump`
-- the editor is controlled and ignores direct value assignment
-
-### The app is Chromium-based but not truly controllable
-
-Some desktop apps embed Chromium but do not expose a usable CDP surface.
-In that case, switch to the non-Electron desktop automation approach instead of forcing the Electron pattern.
-
-### You already have a browser workflow and wonder whether to reuse it
-
-If the app exposes a normal web URL and the browser flow is enough, a browser adapter is usually simpler.
-Use an Electron adapter only when the desktop app is the real integration surface.
-
-## Recommended reading order
-
-If you are starting from zero:
-
-1. This page
-2. [CLI-ifying Electron Applications](/advanced/electron)
-3. [Chrome DevTools Protocol](/advanced/cdp)
-4. [TypeScript Adapter Guide](/developer/ts-adapter)
-5. One concrete desktop adapter doc under `docs/adapters/desktop/`
-
-## Practical rule
-
-Do not start with a large feature surface.
-
-Start with:
-- `status`
-- `dump`
-- `read`
-- `send`
-- `new`
-
-Once those are stable, extend outward.

package/docs/guide/getting-started.md

@@ -1,79 +0,0 @@
-# Getting Started
-
-> **Make any website or Electron App your CLI.**
-> Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
-
-[![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
-[![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
-[![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](https://github.com/jackwener/opencli/blob/main/LICENSE)
-
-OpenCLI turns **any website** or **Electron app** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, and [many more](/adapters/) — powered by browser session reuse and AI-native discovery.
-
-## Highlights
-
-- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively.
-- **Account-safe** — Reuses Chrome's logged-in state; your credentials never leave the browser.
-- **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies.
-- **Self-healing setup** — `opencli doctor` auto-starts the daemon and diagnoses extension + live browser connectivity.
-- **Dynamic Loader** — Simply drop `.ts` or `.yaml` adapters into the `clis/` folder for auto-registration.
-- **Dual-Engine Architecture** — Supports both YAML declarative data pipelines and robust browser runtime TypeScript injections.
-
-## Quick Start
-
-### Install via npm
-
-```bash
-npm install -g @jackwener/opencli
-```
-
-### Basic Usage
-
-```bash
-opencli list                              # See all commands
-opencli hackernews top --limit 5          # Public API, no browser
-opencli bilibili hot --limit 5            # Browser command
-opencli zhihu hot -f json                 # JSON output
-```
-
-### Output Formats
-
-All built-in commands support `--format` / `-f`:
-
-```bash
-opencli bilibili hot -f table   # Default: rich terminal table
-opencli bilibili hot -f json    # JSON (pipe to jq or LLMs)
-opencli bilibili hot -f yaml    # YAML (human-readable)
-opencli bilibili hot -f md      # Markdown
-opencli bilibili hot -f csv     # CSV
-opencli bilibili hot -v         # Verbose: show pipeline debug
-```
-
-### Tab Completion
-
-OpenCLI supports intelligent tab completion to speed up command input:
-
-```bash
-# Add shell completion to your startup config
-echo 'eval "$(opencli completion zsh)"' >> ~/.zshrc              # Zsh
-echo 'eval "$(opencli completion bash)"' >> ~/.bashrc            # Bash
-echo 'opencli completion fish | source' >> ~/.config/fish/config.fish  # Fish
-
-# Restart your shell, then press Tab to complete:
-opencli [Tab]          # Complete site names (bilibili, zhihu, twitter...)
-opencli bilibili [Tab] # Complete commands (hot, search, me, download...)
-```
-
-The completion includes:
-- All available sites and adapters
-- Built-in commands (list, explore, validate...)
-- Command aliases
-- Real-time updates as you add new adapters
-
-## Next Steps
-
-- [Installation details](/guide/installation)
-- [Browser Bridge setup](/guide/browser-bridge)
-- [Plugins — extend with community adapters](/guide/plugins)
-- [All available adapters](/adapters/)
-- [For developers / AI agents](/developer/contributing)
-- [Add a new Electron app CLI](/guide/electron-app-cli)

package/docs/guide/installation.md

@@ -1,37 +0,0 @@
-# Installation
-
-## Requirements
-
-- **Node.js**: >= 20.0.0
-- **Chrome** running and logged into the target site (for browser commands)
-
-## Install via npm (Recommended)
-
-```bash
-npm install -g @jackwener/opencli
-```
-
-## Install from Source
-
-```bash
-git clone git@github.com:jackwener/opencli.git
-cd opencli
-npm install
-npm run build
-npm link      # Link binary globally
-opencli list  # Now you can use it anywhere!
-```
-
-## Update
-
-```bash
-npm install -g @jackwener/opencli@latest
-```
-
-## Verify Installation
-
-```bash
-opencli --version   # Check version
-opencli list        # List all commands
-opencli doctor      # Diagnose connectivity
-```

package/docs/guide/plugins.md

@@ -1,261 +0,0 @@
-# Plugins
-
-OpenCLI supports community-contributed plugins. Install third-party adapters from GitHub, and they're automatically discovered alongside built-in commands.
-
-## Quick Start
-
-```bash
-# Install a plugin
-opencli plugin install github:ByteYue/opencli-plugin-github-trending
-
-# List installed plugins
-opencli plugin list
-
-# Update one plugin
-opencli plugin update github-trending
-
-# Update all installed plugins
-opencli plugin update --all
-
-# Use the plugin (it's just a regular command)
-opencli github-trending repos --limit 10
-
-# Remove a plugin
-opencli plugin uninstall github-trending
-```
-
-## How Plugins Work
-
-Plugins live in `~/.opencli/plugins/<name>/`. Each subdirectory is scanned at startup for `.yaml`, `.ts`, or `.js` command files — the same formats used by built-in adapters.
-
-### Supported Source Formats
-
-```bash
-# GitHub shorthand
-opencli plugin install github:user/repo
-opencli plugin install github:user/repo/subplugin   # install specific sub-plugin from monorepo
-opencli plugin install https://github.com/user/repo
-
-# Any git-cloneable URL
-opencli plugin install https://gitlab.example.com/team/repo.git
-opencli plugin install ssh://git@gitlab.example.com/team/repo.git
-opencli plugin install git@gitlab.example.com:team/repo.git
-
-# Local plugin (for development)
-opencli plugin install file:///path/to/plugin
-opencli plugin install /path/to/plugin
-```
-
-The repo name prefix `opencli-plugin-` is automatically stripped for the local directory name. For example, `opencli-plugin-hot-digest` becomes `hot-digest`.
-
-## Plugin Manifest (`opencli-plugin.json`)
-
-Plugins can include an `opencli-plugin.json` manifest file at the repo root to declare metadata:
-
-```json
-{
-  "name": "my-plugin",
-  "version": "1.0.0",
-  "opencli": ">=1.0.0",
-  "description": "My awesome plugin"
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `name` | Plugin name (overrides repo-derived name) |
-| `version` | Semantic version |
-| `opencli` | Required opencli version range (e.g. `>=1.0.0`, `^1.2.0`) |
-| `description` | Human-readable description |
-| `plugins` | Monorepo sub-plugin declarations (see below) |
-
-The manifest is optional — plugins without one continue to work exactly as before.
-
-## Monorepo Plugins
-
-A single repository can contain multiple plugins by declaring a `plugins` field in `opencli-plugin.json`:
-
-```json
-{
-  "version": "1.0.0",
-  "opencli": ">=1.0.0",
-  "description": "My plugin collection",
-  "plugins": {
-    "polymarket": {
-      "path": "packages/polymarket",
-      "description": "Prediction market analysis",
-      "version": "1.2.0"
-    },
-    "defi": {
-      "path": "packages/defi",
-      "description": "DeFi protocol data",
-      "version": "0.8.0",
-      "opencli": ">=1.2.0"
-    },
-    "experimental": {
-      "path": "packages/experimental",
-      "disabled": true
-    }
-  }
-}
-```
-
-### Installing
-
-```bash
-# Install ALL enabled sub-plugins from a monorepo
-opencli plugin install github:user/opencli-plugins
-
-# Install a SPECIFIC sub-plugin
-opencli plugin install github:user/opencli-plugins/polymarket
-```
-
-### How It Works
-
-- The monorepo is cloned once to `~/.opencli/monorepos/<repo>/`
-- Each sub-plugin gets a symlink in `~/.opencli/plugins/<name>/` pointing to its subdirectory
-- Command discovery works transparently — symlinks are scanned just like regular directories
-- Disabled sub-plugins (with `"disabled": true`) are skipped during install
-- Sub-plugins can specify their own `opencli` compatibility range
-
-### Updating
-
-Updating any sub-plugin from a monorepo pulls the entire repo and refreshes all sub-plugins:
-
-```bash
-opencli plugin update polymarket   # updates the monorepo, refreshes all
-```
-
-### Uninstalling
-
-```bash
-opencli plugin uninstall polymarket   # removes just this sub-plugin's symlink
-```
-
-When the last sub-plugin from a monorepo is uninstalled, the monorepo clone is automatically cleaned up.
-
-## Version Tracking
-
-OpenCLI records installed plugin versions in `~/.opencli/plugins.lock.json`. Each entry stores the plugin source, current git commit hash, install time, and last update time. `opencli plugin list` shows the short commit hash when version metadata is available.
-
-## Creating a Plugin
-
-### Option 1: YAML Plugin (Simplest)
-
-Zero dependencies, no build step. Just create a `.yaml` file:
-
-```
-my-plugin/
-├── my-command.yaml
-└── README.md
-```
-
-Example `my-command.yaml`:
-
-```yaml
-site: my-plugin
-name: my-command
-description: My custom command
-strategy: public
-browser: false
-
-args:
-  limit:
-    type: int
-    default: 10
-
-pipeline:
-  - fetch:
-      url: https://api.example.com/data
-  - map:
-      title: ${{ item.title }}
-      score: ${{ item.score }}
-  - limit: ${{ args.limit }}
-
-columns: [title, score]
-```
-
-### Option 2: TypeScript Plugin
-
-For richer logic (multi-source aggregation, custom transformations, etc.):
-
-```
-my-plugin/
-├── package.json
-├── my-command.ts
-└── README.md
-```
-
-`package.json`:
-
-```json
-{
-  "name": "opencli-plugin-my-plugin",
-  "version": "0.1.0",
-  "type": "module",
-  "peerDependencies": {
-    "@jackwener/opencli": ">=1.0.0"
-  }
-}
-```
-
-`my-command.ts`:
-
-```typescript
-import { cli, Strategy } from '@jackwener/opencli/registry';
-
-cli({
-  site: 'my-plugin',
-  name: 'my-command',
-  description: 'My custom command',
-  strategy: Strategy.PUBLIC,
-  browser: false,
-  args: [
-    { name: 'limit', type: 'int', default: 10, help: 'Number of items' },
-  ],
-  columns: ['title', 'score'],
-  func: async (_page, kwargs) => {
-    const res = await fetch('https://api.example.com/data');
-    const data = await res.json();
-    return data.items.slice(0, kwargs.limit).map((item: any, i: number) => ({
-      title: item.title,
-      score: item.score,
-    }));
-  },
-});
-```
-
-### TS Plugin Install Lifecycle
-
-When you run `opencli plugin install`, TS plugins are automatically set up:
-
-1. **Clone** — `git clone --depth 1` from GitHub
-2. **npm install** — Resolves regular dependencies
-3. **Host symlink** — Links the running `@jackwener/opencli` into the plugin's `node_modules/` so `import from '@jackwener/opencli/registry'` always resolves against the host
-4. **Transpile** — Compiles `.ts` → `.js` via `esbuild` (production `node` cannot load `.ts` directly)
-
-On startup, if both `my-command.ts` and `my-command.js` exist, the `.js` version is loaded to avoid duplicate registration.
-
-## Example Plugins
-
-| Repo | Type | Description |
-|------|------|-------------|
-| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |
-| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | Multi-platform trending aggregator (zhihu, weibo, bilibili, v2ex, stackoverflow, reddit, linux-do) |
-| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金 (Juejin) hot articles, categories, and article feed |
-| [opencli-plugin-rubysec](https://github.com/nullptrKey/opencli-plugin-rubysec) | TS | RubySec advisory archive and advisory article reader |
-
-## Troubleshooting
-
-### Command not found after install
-
-Restart opencli (or open a new terminal) — plugins are discovered at startup.
-
-### TS plugin import errors
-
-If you see `Cannot find module '@jackwener/opencli/registry'`, the host symlink may be broken. Reinstall the plugin:
-
-```bash
-opencli plugin uninstall my-plugin
-opencli plugin install github:user/opencli-plugin-my-plugin
-```

package/docs/guide/troubleshooting.md

@@ -1,72 +0,0 @@
-# Troubleshooting
-
-## Common Issues
-
-### "Extension not connected"
-
-- Ensure the opencli Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
-- Run `opencli doctor` to diagnose connectivity.
-
-### Empty data or 'Unauthorized' error
-
-- Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page.
-- Some sites have geographic restrictions (e.g., Bilibili, Zhihu from outside China).
-
-### Browser command opens the page but still cannot read context
-
-- A healthy Browser Bridge connection does not guarantee that the current page target exposes the data your adapter expects.
-- Some browser adapters are sensitive to the active host or page context.
-- Example: `opencli 1688 item` may fail with `did not expose product context` if the target is too broad.
-- Retry on a real item page, refresh the page in Chrome, and if needed narrow the target, for example:
-
-```bash
-OPENCLI_CDP_TARGET=detail.1688.com opencli 1688 item 841141931191 -f json
-```
-
-### Node API errors
-
-- Make sure you are using **Node.js >= 20**. Some dependencies require modern Node APIs.
-- Run `node --version` to verify.
-
-### Daemon issues
-
-```bash
-# Check daemon status (PID, uptime, extension connection, memory)
-opencli daemon status
-
-# View extension logs
-curl localhost:19825/logs
-
-# Stop or restart the daemon
-opencli daemon stop
-opencli daemon restart
-
-# Full diagnostics
-opencli doctor
-```
-
-> The daemon auto-exits after 4 hours of inactivity (no CLI requests and no extension connection). Override with `OPENCLI_DAEMON_TIMEOUT` (milliseconds, `0` = never timeout).
-
-### Desktop adapter connection issues
-
-For Electron/CDP-based adapters (Cursor, Codex, etc.):
-
-1. Make sure the app is launched with `--remote-debugging-port=XXXX`
-2. Verify the endpoint is set: `echo $OPENCLI_CDP_ENDPOINT`
-3. Test the endpoint: `curl http://127.0.0.1:XXXX/json/version`
-
-### Build errors
-
-```bash
-# Clean rebuild
-rm -rf dist/
-npm run build
-
-# Type check
-npx tsc --noEmit
-```
-
-## Getting Help
-
-- [GitHub Issues](https://github.com/jackwener/opencli/issues) — Bug reports and feature requests
-- Run `opencli doctor` for comprehensive diagnostics

package/docs/index.md

@@ -1,35 +0,0 @@
----
-layout: home
-
-hero:
-  name: OpenCLI
-  text: Make any website or Electron App your CLI
-  tagline: Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /guide/getting-started
-    - theme: alt
-      text: View on GitHub
-      link: https://github.com/jackwener/opencli
-
-features:
-  - icon: 🖥️
-    title: CLI All Electron
-    details: Turn ANY Electron application into a CLI tool — Cursor, Codex, Antigravity, ChatGPT, Notion, and more. AI can control itself natively.
-  - icon: 🔐
-    title: Account Safe
-    details: Reuses Chrome's logged-in state. Your credentials never leave the browser — no tokens, no exposed passwords.
-  - icon: 🤖
-    title: AI Agent Ready
-    details: "explore discovers APIs, synthesize generates adapters, cascade finds auth strategies. Built for AI-first workflows."
-  - icon: ⚡
-    title: Dual-Engine Architecture
-    details: Supports both YAML declarative data pipelines and robust browser runtime TypeScript injections for maximum flexibility.
-  - icon: 🔧
-    title: Self-Healing Setup
-    details: "opencli doctor auto-starts the daemon and diagnoses extension + live browser connectivity."
-  - icon: 📦
-    title: Dynamic Loader
-    details: Simply drop .ts or .yaml adapters into the clis/ folder for auto-registration. Zero boilerplate.
----