@vforsh/argus 0.1.18 → 0.1.20

package/dist/skill/argus/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: argus
+description: Guides use of the Argus CLI to debug and inspect web apps via Chrome CDP or the Argus Chrome extension, including authenticated browser sessions, iframe targets, logs, eval, DOM, network, and screenshots.
+---
+
+## Argus CLI
+
+Debug web apps through either:
+
+- **Extension-control**: normal user Chrome profile, cookies, login state, existing extensions. Best for authenticated portal apps and ordinary browser sessions.
+- **CDP Chrome**: Argus-launched/debuggable Chrome. Best for local apps, temp profiles, clean repros, headless runs, and raw Chrome target control.
+
+Install/run:
+
+```bash
+npm i -g @vforsh/argus
+argus --help
+npx -y @vforsh/argus --help
+argus skill
+```
+
+`argus skill` prints the absolute path to the installed `SKILL.md`. Use it when an agent needs to locate the packaged Argus skill files.
+
+**Long-running commands:** `argus start`, `argus chrome start`, `argus watcher start`, and log tails do not exit on their own. Start them in the background when using an agent shell.
+
+---
+
+## Pick The Mode
+
+Use **extension-control** when the task needs the user's normal Chrome profile, saved login, cookies, local storage, or already-open tabs.
+
+Use **CDP Chrome** when the task needs an isolated browser, headless run, custom CDP port, script injection at startup, or raw `chrome://`/target-id control.
+
+Use **iframe target selection** when the app is embedded in a portal page and `eval`/DOM/click/screenshot must run inside the embedded app, not the host page.
+
+Read:
+
+- [START.md](./reference/START.md) for CDP startup, watcher lifecycle, config defaults, and Node API.
+- [EXTENSION.md](./reference/EXTENSION.md) for extension setup and runtime limitations.
+- [INSPECT.md](./reference/INSPECT.md) for command catalogs: logs, eval, capture, DOM, interaction, auth, storage, trace, pages, emulation.
+- [CAPTURE.md](./reference/CAPTURE.md) for screenshots, recordings, crop semantics, iframe capture, and recording troubleshooting.
+- [NET.md](./reference/NET.md) for network capture, filtering, inspection, bodies, WebSockets, SSE, HAR export, and mocks.
+
+---
+
+## Authenticated Browser Profile Flow
+
+Use this for any app that needs the user's normal browser profile, cookies, local storage, extensions, or saved login state. Do **not** use `argus start`, `argus chrome start --profile temp`, headless Chrome, or a fresh CDP profile for this flow; those lose the real login/session context.
+
+First-time setup is one command: `argus extension install` (installs native hosts, opens chrome://extensions, waits for connect). The extension ID is pinned and the build ships with the CLI — see [EXTENSION.md](./reference/EXTENSION.md).
+
+```bash
+APP_URL="https://portal.example/app"
+WATCHER_ID="app"
+
+open -a "Google Chrome" "$APP_URL"
+argus ext doctor --json
+argus ext tabs --url "$APP_URL" --json
+argus ext use --url "$APP_URL" --as "$WATCHER_ID" --json
+argus eval "$WATCHER_ID" "({ title: document.title, href: location.href })" --json
+```
+
+If multiple tabs match, do not guess. Run `argus ext tabs --url "$APP_URL" --json`, choose the intended `tabId`, then use:
+
+```bash
+argus ext use --tab <tabId> --as "$WATCHER_ID" --json
+```
+
+If the tab is restored in the background or app boot looks stuck, make it visible and reload:
+
+```bash
+argus ext show "$WATCHER_ID"
+argus reload "$WATCHER_ID"
+argus eval-until "$WATCHER_ID" "document.readyState === 'complete'" --total-timeout 30s
+```
+
+---
+
+## Extension Iframe Flow
+
+Use this when the real app lives in an iframe inside a host page.
+
+```bash
+APP_URL="https://portal.example/app"
+WATCHER_ID="app"
+
+open -a "Google Chrome" "$APP_URL"
+argus ext use --url "$APP_URL" --as "$WATCHER_ID" --iframe-url game-frame-host.example --json
+argus eval "$WATCHER_ID" "({ title: document.title, origin: location.origin })" --json
+```
+
+If iframe selection fails because the iframe is not present yet:
+
+```bash
+argus ext use --url "$APP_URL" --as "$WATCHER_ID" --json
+argus ext show "$WATCHER_ID"
+argus reload "$WATCHER_ID"
+argus eval-until "$WATCHER_ID" "document.querySelectorAll('iframe').length > 0" --total-timeout 30s
+argus ext targets "$WATCHER_ID" --tree
+argus ext select "$WATCHER_ID" --iframe-url game-frame-host.example --json
+```
+
+Useful selectors:
+
+```bash
+argus ext select "$WATCHER_ID" --iframe-url game-frame-host.example
+argus ext select "$WATCHER_ID" --iframe-title "Game Title"
+argus ext select "$WATCHER_ID" --iframe auto
+argus ext select "$WATCHER_ID" --page
+argus ext doctor --watcher "$WATCHER_ID"
+```
+
+`--iframe auto` is a convenience heuristic and should fail closed when multiple iframes look equally plausible. Prefer `--iframe-url` or `--iframe-title` when correctness matters.
+
+---
+
+## Inspect Loop
+
+Once a watcher is attached, use quick bounded commands first:
+
+```bash
+argus logs app --since 10m --levels error,warning
+argus eval app "({ href: location.href, title: document.title })" --json
+argus screenshot app --out shot.png
+argus record app --duration 5s --selector "canvas" --out demo.mp4
+argus dom tree app --selector body --depth 2
+argus snapshot app --interactive
+```
+
+For interaction:
+
+```bash
+argus locate role app button --name "Submit"
+argus click app --selector "button.submit"
+argus click app --ref e5
+argus drag app --selector "canvas" --pos 320,240 --by 80,-30
+argus fill app --selector "#email" "user@example.com"
+argus keydown app --key Enter
+argus scroll-to app --selector "#footer"
+```
+
+For iframe-active extension watchers, commands run against the selected iframe target. Screenshots, recordings, selectors, and eval are resolved relative to that iframe.
+
+For deeper command lists, use [INSPECT.md](./reference/INSPECT.md). For screenshots/recording details, use [CAPTURE.md](./reference/CAPTURE.md). For eval flags, polling, file scripts, and args, use [EVAL.md](./reference/EVAL.md).
+
+---
+
+## CDP Quick Start
+
+Use CDP for local apps and clean repros where a temp/debuggable browser is acceptable.
+
+```bash
+npm run dev
+argus start --id app --url localhost:3000
+argus eval app "location.href"
+argus screenshot app --out shot.png
+argus record app --duration 3s --out demo.mp4
+```
+
+`argus start` launches Chrome and a watcher together. For more control:
+
+```bash
+argus chrome start --url http://localhost:3000
+argus watcher start --id app --url localhost:3000 --chrome-port 9222
+```
+
+Keep these commands in the background in agent shells. See [START.md](./reference/START.md) for profile modes, auth-state hydration, watcher target flags, config defaults, and programmatic watcher APIs.
+
+---
+
+## Troubleshooting
+
+**No extension-control watcher** — First time? Run `argus extension install`. Otherwise open/reload the extension, then run `argus ext doctor --json`.
+
+**Multiple tabs matched** — Use `argus ext tabs --url <url> --json`, choose a `tabId`, then pass `--tab <tabId>`.
+
+**Iframe not found** — `argus ext show <id>`, `argus reload <id>`, wait for iframes, then `argus ext targets <id> --tree`.
+
+**Eval runs on host page** — Select the iframe first: `argus ext select <id> --iframe-url <substring>`.
+
+**Watcher cannot attach in CDP mode** — Check the Chrome port: `argus chrome status --cdp 127.0.0.1:9222`.
+
+**Wrong CDP target matched** — Use `--type iframe`, `--origin`, `--parent`, or `--target`. See [IFRAMES.md](./reference/IFRAMES.md).
+
+**Need to keep a page unthrottled** — Use `argus page show <id>` or `argus ext show <id>`. Hide later with `argus page hide <id>`.
+
+---
+
+## References
+
+- [START.md](./reference/START.md) — CDP startup, watcher lifecycle, config defaults, Node API.
+- [EXTENSION.md](./reference/EXTENSION.md) — Extension setup and extension-control details.
+- [INSPECT.md](./reference/INSPECT.md) — Logs, capture summary, DOM, interaction, auth, storage, trace, emulation.
+- [CAPTURE.md](./reference/CAPTURE.md) — Screenshots, recordings, crop semantics, iframe capture, recording troubleshooting.
+- [NET.md](./reference/NET.md) — Network capture, filtering, inspection, export, and mocks.
+- [EVAL.md](./reference/EVAL.md) — Eval syntax, polling, files, args, iframe eval.
+- [RUNTIME_CODE.md](./reference/RUNTIME_CODE.md) — Runtime JS/CSS discovery and live CSS edits.
+- [IFRAMES.md](./reference/IFRAMES.md) — CDP iframe targeting and iframe concepts.
+- [EXTENSION_IFRAME_EVAL.md](./reference/EXTENSION_IFRAME_EVAL.md) — Cross-origin iframe helper mechanics.
+- [INJECT.md](./reference/INJECT.md) — Script injection on watcher attach/navigation.
+- [DIALOG.md](./reference/DIALOG.md) — Browser dialog status and handling.
+- [PLUGINS.md](./reference/PLUGINS.md) — CLI plugin loading and Google Sheets plugin.

package/dist/skill/argus/reference/CAPTURE.md

@@ -0,0 +1,77 @@
+## Capture Commands
+
+Use this when you need page pixels: screenshots for quick state checks, recordings for motion/gameplay/repro clips.
+
+## Screenshots
+
+```bash
+argus screenshot app --out shot.png
+argus screenshot app --selector "canvas" --out canvas.png
+argus screenshot app --clip 100,80,640,360 --out crop.png
+argus screenshot app --testid "game-canvas" --out game.png
+```
+
+`--selector` and `--clip` are mutually exclusive. `--clip` is viewport-relative in CSS pixels. `--testid <id>` is shorthand for `--selector "[data-testid='<id>']"`.
+
+## Recording
+
+```bash
+argus record app --duration 5s --out demo.mp4
+argus record app --duration 3s --selector "canvas" --out canvas.mp4
+argus record app --duration 3s --clip 100,80,640,360 --out crop.mp4
+argus record app --duration 3s --testid "game-canvas" --out game.mp4
+```
+
+Recordings are silent MP4/H.264 files by default. WebM is supported with `--format webm` or a `.webm` output path. Default FPS is 30; use `--fps <1-60>` for large canvases or lighter artifacts.
+
+```bash
+argus record app --duration 5s --selector "canvas" --fps 12 --out canvas.mp4
+argus record app --duration 5s --selector "canvas" --format webm --out canvas.webm
+```
+
+For manual interaction windows:
+
+```bash
+argus record start app --selector "canvas" --out canvas.mp4
+argus click app --selector "#play"
+argus record stop app
+```
+
+## Crop Semantics
+
+Viewport capture records or screenshots the visible page viewport. Selector capture resolves the element once at capture start, then crops page pixels to that element rectangle. Clip capture uses `x,y,width,height` in viewport CSS pixels.
+
+If the selected element moves or resizes during a recording, Argus keeps the original crop rectangle for that recording. Prefer a stable canvas/container selector for games.
+
+## Extension / Iframes
+
+For iframe-active extension watchers, capture commands resolve selectors inside the selected iframe, then capture top-level page pixels with the translated crop. This is the same target model used by `eval`, DOM commands, and screenshots.
+
+```bash
+argus ext use --url portal.example --as app --iframe-url game-frame-host.example
+argus record app --duration 5s --selector "canvas" --out game.mp4
+```
+
+If capture runs against the host page instead of the app, select the iframe first:
+
+```bash
+argus ext targets app --tree
+argus ext select app --iframe-url game-frame-host.example
+```
+
+## Troubleshooting
+
+If recording fails with no frames, make the page visible and unthrottled:
+
+```bash
+argus page show app
+argus record app --duration 3s --selector "canvas" --out canvas.mp4
+```
+
+If recording fails because `ffmpeg` is missing, install it or point Argus at it:
+
+```bash
+ARGUS_FFMPEG=/opt/homebrew/bin/ffmpeg argus record app --duration 3s --out demo.mp4
+```
+
+MP4 output requires an ffmpeg build with `libx264`. If your ffmpeg lacks it, install a full build or record WebM with `--format webm`.

package/dist/skill/argus/reference/DIALOG.md

@@ -0,0 +1,31 @@
+# argus dialog
+
+Inspect and handle browser JavaScript dialogs on the watcher-attached page.
+
+## Syntax
+
+```bash
+argus dialog status [id] [--json]
+argus dialog accept [id] [--json]
+argus dialog dismiss [id] [--json]
+argus dialog prompt [id] --text "<value>" [--json]
+```
+
+## Examples
+
+```bash
+argus dialog status app
+argus dialog accept app
+argus dialog dismiss app
+argus dialog prompt app --text "hello"
+argus dialog status app --json
+```
+
+## Behavior
+
+- `status` returns the single active dialog, or `null` when nothing is open.
+- `accept` resolves the active dialog with OK / Leave / equivalent browser action.
+- `dismiss` resolves the active dialog with Cancel / Stay / equivalent browser action.
+- `prompt` is just `accept` plus submitted text. It fails if the active dialog is not a prompt.
+
+Chrome only exposes one active JavaScript dialog at a time, so Argus models dialog state as a single current snapshot instead of a list.

package/dist/skill/argus/reference/EVAL.md

@@ -0,0 +1,137 @@
+# argus eval
+
+Evaluate JavaScript in page connected to watcher.
+
+Alias: `argus js`
+
+## Syntax
+
+```bash
+argus eval [id] "<expression>" [flags]
+argus js [id] "<expression>" [flags]
+```
+
+## Examples
+
+```bash
+argus eval app "location.href"
+argus eval app "document.title"
+argus eval app "await fetch('/ping').then(r => r.status)"
+argus eval app "window.store.getState()" --inject ./debug-hooks.js
+argus eval app --file ./script.js --arg level=10 --arg mode=fast
+argus eval app --file ./script.js --args ./args.json
+argus eval app "document.title" --json --out ./result.json
+argus eval app --file ./script.js --bundle
+argus eval app --file ./script.js --no-bundle
+```
+
+`--file` with leading `import`/`export` auto-enables bundling (one-line stderr note). `--bundle` forces bundling; `--no-bundle` reads the file as-is. Bundling resolves the entry and any import graph esbuild can resolve from the current working directory (including paths outside the entry directory and packages under `node_modules`). Node built-ins (`node:fs`, etc.) are rejected. TypeScript is transpiled without typechecking. Helpers may `export` symbols; the entry file must not emit top-level `export` into the bundle.
+
+Poll until condition:
+
+```bash
+argus eval app "document.title" --interval 250ms --until 'result === "ready"'
+argus eval app "Date.now()" --interval 500 --count 10 --out ./poll.ndjson
+argus eval app "Date.now()" --interval 500 --count 10 --out ./frames.json --rotate
+```
+
+## Output
+
+- Default: compact preview
+- `--json`: JSON object (NDJSON with `--interval`)
+- `--out <path>`: write result to file; single eval overwrites, polling appends NDJSON, `--rotate` writes one numbered file per iteration
+
+## Behavior Flags
+
+| Flag                     | Effect                              |
+| ------------------------ | ----------------------------------- |
+| `--no-await`             | Don't await promises                |
+| `--timeout <duration>`   | Eval timeout (`60000`, `60s`, `2m`) |
+| `--no-return-by-value`   | Preview-style results               |
+| `--no-fail-on-exception` | Don't exit 1 on throw               |
+| `--retry <n>`            | Retry failed evals                  |
+| `--silent` / `-q`        | Suppress success output             |
+| `--inject <file>`        | Run setup code before expression    |
+| `--bundle`               | Force bundling for `--file`         |
+| `--no-bundle`            | Skip bundling (disables auto)       |
+| `--arg <key=value>`      | Expose string arg as `args[key]`    |
+| `--args <path>`          | Load args map from JSON file        |
+| `--out <path>`           | Write result to file                |
+| `--rotate`               | One file per poll iteration         |
+
+## Script Args
+
+`--arg <key=value>` is repeatable on `eval`/`js` and `eval-until`/`wait`. It exposes a frozen `args` object to the evaluated source:
+
+```bash
+argus js app --file ./open-level.js --arg level=10 --arg variant=arrows
+argus js app --file ./open-level.js --args ./fixtures/level.json --arg variant=arrows
+argus js app "window.store.getState()" --inject ./debug-hooks.js --arg user=qa
+cat ./click-test-id.js | argus js app --stdin --arg testId=arrows.boosters.button.ruler
+argus wait app --file ./ready.js --arg level=10 --total-timeout 20s
+```
+
+Values stay strings; cast in the script:
+
+```js
+const level = Number(args.level)
+const variant = String(args.variant ?? 'arrows')
+```
+
+Duplicate keys use the last value. Values are split at the first `=`, so URLs and query strings work. Invalid values like `--arg level`, `--arg =10`, or `--arg ""` exit with code 2 before contacting the watcher.
+
+`--args <path>` loads a JSON object from disk. Primitive values (`string`, `number`, `boolean`, `null`) are coerced to strings; nested objects/arrays are rejected. CLI `--arg` flags override file entries.
+
+## Polling Flags
+
+| Flag                    | Effect                              |
+| ----------------------- | ----------------------------------- |
+| `--interval <duration>` | Re-run periodically (`250ms`, `3s`) |
+| `--count <n>`           | Stop after n iterations             |
+| `--until <condition>`   | Stop when truthy                    |
+
+`--until` context: `{ result, exception, iteration, attempt }`
+
+## eval-until
+
+Poll until expression returns truthy (`Boolean(result)`). Defaults to 250ms interval; silent intermediate output.
+
+```bash
+argus eval-until [id] "<expression>" [flags]
+```
+
+```bash
+argus eval-until app "document.querySelector('#loaded')"
+argus eval-until app "window.APP_READY" --interval 500
+argus eval-until app "document.title === 'Ready'" --total-timeout 30s
+argus eval-until app "window.data" --verbose --count 20
+argus eval-until app --file ./check.js --total-timeout 1m
+argus wait app --file ./ready.js --arg level=10 --total-timeout 20s
+```
+
+| Flag                         | Effect                                  |
+| ---------------------------- | --------------------------------------- |
+| `--interval <ms\|duration>`  | Polling interval (default: 250ms)       |
+| `--count <n>`                | Max iterations                          |
+| `--total-timeout <duration>` | Max wall-clock time (`30s`, `2m`, `1h`) |
+| `--verbose`                  | Print intermediate (falsy) results      |
+
+Also supports all behavior flags (`--no-await`, `--timeout 60s`, `--json`, `--retry`, etc.) and iframe flags.
+Also supports `--arg <key=value>`, `--args <path>`, and `--out <path>`.
+
+**Exit codes:** 0 = truthy found, 1 = error/exhausted, 2 = invalid args, 130 = SIGINT/SIGTERM.
+
+**vs `eval --interval --until`:** `eval-until` defaults interval to 250ms, uses implicit `Boolean(result)` condition, suppresses intermediate output by default, and adds `--total-timeout`.
+
+## Iframe Eval (extension mode)
+
+Cross-origin iframes need helper script:
+
+```bash
+argus eval iframe-helper --out src/argus-helper.js
+argus eval app "window.gameState" --iframe "iframe#game"
+```
+
+Options: `--iframe <selector>`, `--iframe-namespace <name>`, `--iframe-timeout <duration>` (`5000`, `5s`, `1m`)
+
+See [EXTENSION_IFRAME_EVAL.md](./EXTENSION_IFRAME_EVAL.md).

package/dist/skill/argus/reference/EXTENSION.md

@@ -0,0 +1,43 @@
+## Extension Workflow
+
+Debug normal Chrome session without CDP flags.
+
+### One-Time Setup
+
+```bash
+# Installs native hosts, opens chrome://extensions, waits for the extension to connect:
+argus extension install
+#   → click "Load unpacked" and select the printed folder (enable Developer mode if hidden)
+```
+
+The extension ID is **pinned** (via a `key` in the manifest), so there's no ID to copy/paste and the prebuilt extension ships with the CLI — no build step. Useful sub-commands:
+
+```bash
+argus extension path      # absolute folder to "Load unpacked"
+argus extension status    # native host config + extension ID
+argus extension install --no-wait   # scripted/non-interactive (skip the connect wait)
+```
+
+Advanced: `argus extension setup [extensionId]` installs only the native hosts (pass an id to override the pinned one for a differently-keyed build).
+
+> Migration: if you previously loaded an unkeyed build, reload the extension once at `chrome://extensions` so it picks up the pinned ID.
+
+### Usage
+
+1. Click Argus extension icon
+2. Click **Attach** on target tab
+3. Chrome shows orange "debugging" bar (expected)
+
+```bash
+argus list
+argus logs extension
+argus eval extension "document.title"
+```
+
+### Limitations
+
+- Debugging bar can't be hidden (Chrome security)
+- One debugger per tab
+- Tab must stay open
+- Manual tab selection (no `--url` matching)
+- Cross-origin iframes: use helper script (see [IFRAMES.md](./IFRAMES.md))

package/dist/skill/argus/reference/EXTENSION_IFRAME_EVAL.md

@@ -0,0 +1,58 @@
+# Cross-Origin Iframe Eval (Extension Mode)
+
+Extension mode can't eval directly in cross-origin iframes. Use postMessage bridge.
+
+## Setup
+
+```bash
+# Generate helper
+argus eval iframe-helper --out src/argus-helper.js
+argus eval iframe-helper --iife --out dist/argus-helper.js  # Wrap in IIFE
+argus eval iframe-helper --namespace myapp                   # Custom namespace
+```
+
+Include in iframe HTML:
+
+```html
+<script src="argus-helper.js"></script>
+```
+
+## Usage
+
+```bash
+argus eval app "document.title" --iframe "iframe"
+argus eval app "window.gameState" --iframe "iframe#game"
+argus eval app "heavyComputation()" --iframe "iframe" --iframe-timeout 10000
+```
+
+## Message Format
+
+Request (parent → iframe):
+
+```json
+{ "type": "argus:eval", "id": "<uuid>", "code": "<expression>" }
+```
+
+Response (iframe → parent):
+
+```json
+{ "type": "argus:eval-result", "id": "<uuid>", "ok": true, "result": "<value>" }
+```
+
+## When to Use
+
+| Scenario                 | Approach                               |
+| ------------------------ | -------------------------------------- |
+| CDP + any iframe         | `--type iframe` / `--origin` targeting |
+| Extension + same-origin  | Eval reaches iframe directly           |
+| Extension + cross-origin | **`--iframe` option** (needs helper)   |
+
+## Security
+
+Helper uses `eval()`. Dev/debug builds only. Consider removing from production.
+
+## Limitations
+
+- Requires modifying iframe source
+- Results must be serializable
+- Async needs explicit `await` in code string

package/dist/skill/argus/reference/IFRAMES.md

@@ -0,0 +1,46 @@
+# Iframes and Target Selection (CDP)
+
+For embedded apps/games in iframes. Simple `--url` matching can attach to wrong target when parent page has iframe URL in query string.
+
+## Targeting Flags
+
+```bash
+# Only iframes
+argus watcher start --id game --type iframe --url localhost:3007
+
+# Match by origin (ignores query params)
+argus watcher start --id game --origin https://localhost:3007
+
+# Explicit target ID
+argus page targets --type iframe
+argus watcher start --id game --target CC1135709D9AC3B9CC0446F8B58CC344
+
+# Match parent URL pattern
+argus watcher start --id game --type iframe --parent yandex.ru --url localhost:3007
+```
+
+## Discovering Targets
+
+```bash
+argus page targets              # List all
+argus page targets --tree       # Parent-child tree
+argus page targets --type iframe
+```
+
+## Example (embedded game)
+
+```bash
+# Terminal 1
+argus chrome start --url "https://yandex.ru/games/app/123"
+
+# Terminal 2
+argus watcher start --id game --type iframe --url localhost:3007
+
+# Terminal 3
+argus logs game --levels error,warning
+argus eval game "window.gameState"
+```
+
+## Extension Mode
+
+Cross-origin iframes need helper script + `argus eval --iframe`. See [EXTENSION_IFRAME_EVAL.md](./EXTENSION_IFRAME_EVAL.md).