@vforsh/argus 0.1.18 → 0.1.19

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

@@ -0,0 +1,145 @@
+# Script Injection on Watcher Attach
+
+Inject custom JavaScript when the watcher attaches to a target. Runs immediately on attach and on every page navigation/reload.
+
+## Config
+
+```json
+{
+	"watcher": {
+		"start": {
+			"id": "app",
+			"url": "localhost:3000",
+			"inject": {
+				"file": "./scripts/debug-helpers.js",
+				"exposeArgus": true
+			}
+		}
+	}
+}
+```
+
+| Field         | Required | Description                                                        |
+| ------------- | -------- | ------------------------------------------------------------------ |
+| `file`        | Yes      | Path to JavaScript file (resolved relative to config file)         |
+| `exposeArgus` | No       | Set `window.__ARGUS__` metadata before script runs (default: true) |
+
+## Timing
+
+1. **On attach**: Script runs immediately via `Runtime.evaluate`
+2. **On navigation**: Script runs at document start via `Page.addScriptToEvaluateOnNewDocument`
+
+This ensures the script is active both when attaching to an existing page and after any reload/navigation.
+
+## window.**ARGUS**
+
+When `exposeArgus: true` (default), `window.__ARGUS__` is set before your script runs:
+
+```typescript
+window.__ARGUS__ = {
+	watcherId: string       // e.g., "app"
+	watcherHost: string     // e.g., "127.0.0.1"
+	watcherPort: number     // e.g., 52341
+	watcherPid: number      // Node.js process ID
+	attachedAt: number      // Unix timestamp (ms)
+	target: {
+		title: string | null
+		url: string | null
+		type: string         // "page" | "iframe" | ...
+		parentId: string | null
+	}
+}
+```
+
+Use this to conditionally enable features or communicate with the watcher.
+
+## Use Cases
+
+### Debug Helpers
+
+```js
+// scripts/debug-helpers.js
+window.dumpState = () => console.log(JSON.stringify(window.appState, null, 2))
+window.toggleDebug = () => {
+	window.DEBUG = !window.DEBUG
+}
+```
+
+### Error Monitoring
+
+```js
+// Wrap errors with extra context
+window.onerror = (msg, src, line, col, err) => {
+	console.error('[ARGUS-INJECTED]', { msg, src, line, col, stack: err?.stack })
+}
+```
+
+### Global Mocks
+
+```js
+// Mock Date for deterministic testing
+const fakeNow = new Date('2025-01-01T00:00:00Z').getTime()
+Date.now = () => fakeNow
+```
+
+### Performance Markers
+
+```js
+// Auto-add performance marks
+const origFetch = window.fetch
+window.fetch = async (...args) => {
+	const id = Math.random().toString(36).slice(2, 8)
+	performance.mark(`fetch-start-${id}`)
+	const res = await origFetch(...args)
+	performance.mark(`fetch-end-${id}`)
+	return res
+}
+```
+
+### Conditional Debug Mode
+
+```js
+// Enable verbose logging only when Argus is attached
+if (window.__ARGUS__) {
+	window.DEBUG = true
+	console.log(`[DEBUG] Watcher ${window.__ARGUS__.watcherId} attached`)
+}
+```
+
+## CLI Usage
+
+```bash
+# Via CLI flag
+argus watcher start --id app --url localhost:3000 --inject ./scripts/debug-helpers.js
+
+# Via config file (inject.file resolved relative to config)
+argus watcher start --id app --url localhost:3000
+```
+
+## Limitations
+
+- Script file must be readable at watcher start
+- Empty scripts are skipped with a warning
+- Script errors are caught and logged but don't prevent watcher attachment
+- Cross-origin iframe scripts need separate injection (see [IFRAMES.md](./IFRAMES.md))
+
+## Programmatic API
+
+When using `@vforsh/argus-watcher` directly, pass script text (not file path):
+
+```js
+import { startWatcher } from '@vforsh/argus-watcher'
+import fs from 'node:fs'
+
+const script = fs.readFileSync('./scripts/debug.js', 'utf8')
+
+await startWatcher({
+	id: 'app',
+	match: { url: 'localhost:3000' },
+	chrome: { host: '127.0.0.1', port: 9222 },
+	inject: {
+		script,
+		exposeArgus: true,
+	},
+})
+```

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

@@ -0,0 +1,175 @@
+## Inspect Commands
+
+Use this as the command catalog after a watcher is attached. For eval-specific flags, polling, file scripts, and args, see [EVAL.md](./EVAL.md). For network capture, filtering, bodies, export, and mocks, see [NET.md](./NET.md).
+
+## Logs
+
+```bash
+argus logs app --since 10m
+argus logs app --levels error,warning
+argus logs app --match "Error|Exception" --ignore-case
+argus logs app --source console
+argus logs app --json
+argus logs app --json-full
+argus logs tail app
+argus logs tail app --levels error --json
+```
+
+## Eval / Wait
+
+```bash
+argus js app "location.href"
+argus eval app "await fetch('/ping').then(r => r.status)"
+argus eval app "document.title" --json
+argus eval app "window.store.getState()" --inject ./debug-hooks.js
+argus eval-until app "document.querySelector('#loaded')"
+argus eval-until app "window.APP_READY" --interval 500 --total-timeout 30s
+argus wait app --file ./ready.js --arg level=10 --total-timeout 20s
+```
+
+`js` is the short alias for `eval`; `wait` is the short alias for `eval-until`.
+
+## Screenshots / Recording
+
+```bash
+argus screenshot app --out shot.png
+argus screenshot app --selector "canvas" --out canvas.png
+argus record app --duration 5s --out demo.mp4
+argus record app --duration 3s --selector "canvas" --out canvas.mp4
+```
+
+See [CAPTURE.md](./CAPTURE.md) for crop semantics, iframe behavior, recording start/stop, `ffmpeg`, and troubleshooting.
+
+## DOM / Snapshot / Locate
+
+```bash
+argus dom tree app --selector "body"
+argus dom tree app --testid "main-content"
+argus dom tree app --selector "div" --all --depth 3
+argus dom info app --selector "#root"
+argus dom info app --ref e3
+argus snapshot app
+argus snapshot app --interactive
+argus snapshot app --selector "form" --depth 3
+argus locate role app button --name "Submit"
+argus locate text app "Continue"
+argus locate label app "Email" --action fill --value "me@example.com"
+```
+
+`--testid <id>` is shorthand for `--selector "[data-testid='<id>']"`. `snapshot` and `locate` emit stable watcher-local refs such as `e5`, which ref-aware commands can reuse.
+
+## Interaction
+
+```bash
+argus click app --selector "button.submit"
+argus click app --testid "submit-btn"
+argus click app --ref e5
+argus click app --selector ".delayed-btn" --wait 5s
+argus click app --pos 100,200
+argus drag app --selector "#piece" --by 120,0
+argus drag app --selector "canvas" --pos 320,240 --by 80,-30
+argus drag app --pos 200,300 --to 500,300
+argus hover app --selector ".menu-item"
+argus fill app --selector "#username" "Bob"
+argus fill app --selector "#desc" --value-file ./description.txt
+echo "hello" | argus fill app --selector "#input" --value-stdin
+argus keydown app --key Enter
+argus keydown app --key a --selector "#input"
+argus keydown app --key a --modifiers shift,ctrl
+argus scroll-to app --selector "#footer"
+argus scroll-to app --to 0,1000
+argus scroll-to app --selector ".panel" --by 0,500
+```
+
+`drag` uses real Chrome mouse input (`mousePressed` → `mouseMoved` → `mouseReleased`), which works for canvas/WebGL game interactions. With `--selector`/`--ref`, `--pos` is an offset from the element top-left; without an element target, `--pos` is the viewport start.
+
+`--wait <duration>` on click/fill/drag polls for the selector before acting. Duration examples: `5s`, `500ms`, `2m`.
+
+## Dialogs
+
+```bash
+argus dialog status app
+argus dialog accept app
+argus dialog dismiss app
+argus dialog prompt app --text "updated value"
+argus dialog status app --json
+```
+
+Browser JavaScript dialogs include `alert`, `confirm`, `prompt`, and `beforeunload`.
+
+## DOM Helpers
+
+```bash
+argus dom focus app --selector "#input"
+argus dom focus app --testid "search-box"
+argus dom focus app --ref e5
+argus dom set-file app --selector "input[type=file]" --file ./build.zip
+argus dom upload app --selector "input[type=file]" --file ~/Downloads/test.zip
+argus dom scroll app --by 0,300
+argus dom wheel app --selector "input[type=number]" --by 0,-120
+argus dom scroll app --selector ".panel" --by 0,200
+argus dom scroll app --pos 400,300 --by 0,200
+```
+
+`dom scroll` dispatches real wheel input via CDP. `dom set-file` / `dom upload` set file inputs.
+
+## Storage
+
+```bash
+argus storage local get app theme
+argus storage local set app theme dark
+argus storage local remove app theme
+argus storage local ls app
+argus storage local clear app
+argus storage session get app draftId
+argus storage session set app draftId abc123
+argus storage session remove app draftId
+argus storage session ls app
+argus storage session clear app
+```
+
+## Auth
+
+```bash
+argus auth cookies list app
+argus auth cookies list app --show-values --json
+argus auth cookies ls app --for-origin --exclude-tracking
+argus auth cookies get app session --domain .example.com --path /
+argus auth cookies set app session token123 --domain .example.com --path / --secure --http-only
+argus auth cookies delete app session --domain .example.com --path /
+argus auth cookies clear app --for-origin
+argus auth cookies clear app --site --auth-only
+argus auth export-cookies app --format netscape
+argus auth export-state app --out auth.json
+argus auth load-state app --in auth.json
+argus auth clone extension-2 --to app
+argus chrome start --auth-state auth.json
+argus start --id app --auth-from extension-2
+```
+
+`auth export-state` writes cookies, `localStorage`, `sessionStorage`, and metadata. `auth load-state` rehydrates into the current watcher tab. `auth clone` copies auth state directly between watchers.
+
+## Trace
+
+```bash
+argus trace app --duration 3s --out trace.json
+argus trace start app --categories "devtools.timeline"
+argus trace stop app --out trace.json
+```
+
+## Emulation / Visibility / Throttle
+
+```bash
+argus page emulation set app --device iphone-14
+argus page emulation set app --width 1600 --height 900
+argus page emulation clear app
+argus page emulation status app --json
+argus page show app
+argus ext show --url localhost
+argus page hide app
+argus throttle set app 4
+argus throttle clear app
+argus throttle status app
+```
+
+`page show` / `ext show` keeps a page shown and focused so timers and `requestAnimationFrame` do not throttle while debugging.

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

@@ -0,0 +1,108 @@
+## Network Commands
+
+Use this after a watcher is attached and you need request summaries, fresh capture windows, request/response bodies, WebSockets, SSE, HAR export, or network mocking.
+
+For iframe-active extension watchers, choose scope deliberately:
+
+- `--scope selected` / `--frame selected` means traffic for the selected iframe target.
+- page/tab scope means traffic for the top page.
+- reload-driven `net watch`, `net export`, and `net inspect` reject selected-frame scope because reloading an iframe target is ambiguous.
+
+## Quick Read
+
+```bash
+argus net app --since 5m
+argus net app --grep api
+argus net app --json
+argus net tail app --grep api --json
+argus net summary app
+argus net clear app
+```
+
+`net clear` resets the watcher buffer so the next inspection starts clean.
+
+## Fresh Capture
+
+```bash
+argus net watch app --reload --settle 3s
+argus net watch app --reload --settle-after "window.appReady" --settle 2s
+argus net watch app --reload --settle 3s --ignore-pattern /poll
+argus net watch app --reload --settle 3s --max-timeout 30s
+```
+
+`net watch` tails matching requests until no new matches arrive for `--settle`. `--settle-after "<expr>"` polls the page first, then starts the quiet-window countdown only after the expression becomes truthy.
+
+## Inspect One Endpoint
+
+```bash
+argus net inspect /api/init app --reload
+argus net inspect /api/post app --settle-after "window.appReady" --settle 400ms
+argus net inspect /api/init app --reload --request --response
+```
+
+`net inspect` captures a fresh window, picks the newest URL match, prints a compact request summary, and can include request/response bodies.
+
+## Filters
+
+```bash
+argus net extension --scope selected --host game-frame-host.example --resource-type Fetch
+argus net extension --first-party --slow-over 500ms --status 4xx
+argus net extension --large-over 100kb --mime application/json
+argus net app --method POST --host api.example.com
+argus net app --failed-only
+argus net app --domain example.com
+```
+
+Common filters: host, domain, method, status/status class (`2xx`), resource type, MIME prefix, first-party/third-party, failed-only, slow-over, large-over, and scope/frame.
+
+## Show And Bodies
+
+```bash
+argus net show 42 app
+argus net show 90829.507 extension --json
+argus net body 42 app
+argus net body 42 app --request
+```
+
+`net show` drills into one buffered request by Argus id or raw CDP request id, including redacted headers, initiator, redirect chain, cache/service-worker flags, timing phases, and body availability. `net body` lazily fetches response body by default; add `--request` for request body.
+
+## Export / WebSockets / SSE
+
+```bash
+argus net export app --out boot.har
+argus net export app --reload --settle 3s --out boot.har
+argus net ws app
+argus net ws show 1 app
+argus net sse app
+```
+
+`net export --format har` writes the current buffer or a fresh reload capture as HAR. `net ws show` prints WebSocket handshake headers plus bounded recent frame previews. `net sse` lists EventSource/text-event-stream requests at request level; CDP does not reliably expose SSE event payloads.
+
+## Network Mocking
+
+Intercept live requests via CDP Fetch: block, fail with a real network error, stub responses, inject latency, or rewrite requests.
+
+```bash
+argus net mock add app --url "*/analytics/*" --block
+argus net mock add app --url "*/api/save" --fail ConnectionRefused
+argus net mock add app --url "*/api/init" --fail TimedOut --times 1
+argus net mock add app --url "*/api/config" --status 200 --body-file ./fixtures/config.json
+argus net mock add app --url "*/api/config" --status 500 --body '{"error":"maintenance"}'
+echo '{"flags":{"newShop":true}}' | argus net mock add app --url "*/api/flags" --body -
+argus net mock add app --url "*/api/*" --delay 2s --method POST
+argus net mock add app --url "*/api/*" --set-header "x-debug: 1"
+argus net mock add app --url "cdn.prod.com" --rewrite-host localhost:3000
+argus net mock ls app
+argus net mock rm 2 app
+argus net mock clear app
+```
+
+Rules persist across reloads and reattach until removed. First matching rule wins. `--url` is a case-insensitive wildcard pattern over the full request URL; `*` matches anything, and no `*` means substring match. Use `--times N` for one-shot failures.
+
+Exactly one primary action per rule:
+
+- `--block` aborts as `BlockedByClient`.
+- `--fail <reason>` aborts with a CDP network error such as `TimedOut` or `ConnectionRefused`.
+- `--status` with `--body`, `--body-file`, and optional headers stubs a response.
+
+Without a primary action, rules pass requests through with optional latency, request-header changes, or host/origin rewrites.

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

@@ -0,0 +1,172 @@
+# CLI Plugins
+
+Argus plugins are normal ESM modules loaded before Commander parses the CLI command. They can register extra top-level commands and use stable host helpers from `@vforsh/argus-plugin-api`.
+
+## Load Sources
+
+```bash
+# Global config: persistent for every workspace
+argus plugin add --global foo=~/dev/foo-plugin/dist/index.js
+argus foo ...
+
+# Workspace config: persistent for this workspace
+argus plugin list
+
+# Env: useful for shells/scripts
+ARGUS_PLUGINS=foo argus plugin list
+
+# Dynamic: one invocation only
+argus --plugin foo plugin list
+
+# Config mutation
+argus plugin add gsheets
+argus plugin add --global foo=./plugins/foo.js
+argus plugin add foo=./plugins/foo.js
+argus plugin remove google-sheets
+```
+
+Load order:
+
+1. `plugins` from per-user config at `ARGUS_HOME/config.json` (default `~/.argus/config.json`)
+2. `plugins` from repo-local Argus config
+3. `ARGUS_PLUGINS` comma-separated entries
+4. `--plugin <module-or-path-or-alias>` entries
+
+Duplicate specifiers are loaded once, preserving first occurrence.
+
+## Inspect
+
+```bash
+argus plugin list
+argus plugin list --json
+argus --plugin ./plugins/foo.js plugin list --json
+```
+
+`plugin list` reports the config path, cwd, and one entry per discovered plugin:
+
+```json
+{
+	"entries": [
+		{
+			"source": "cli",
+			"spec": "foo",
+			"resolvedSpec": "./plugins/foo.js",
+			"alias": "foo",
+			"status": "loaded",
+			"name": "foo",
+			"version": "1.2.3",
+			"description": "Foo commands for Argus",
+			"commands": ["foo"],
+			"homepage": null,
+			"minArgusVersion": null,
+			"url": "file:///repo/plugins/foo.js"
+		}
+	]
+}
+```
+
+Failures are non-fatal: Argus prints a warning and keeps registering the rest.
+
+## Manage Config
+
+```bash
+argus plugin add <module-or-path-or-alias>
+argus plugin add <alias>=<module-or-path>
+argus plugin add --global <alias>=<module-or-path>
+argus plugin remove <specifier-or-name>
+argus plugin remove --global <specifier-or-name>
+argus plugin add ./plugins/foo.js --path argus.config.json
+```
+
+`plugin add` creates `.argus/config.json` when no workspace config exists, appends the specifier once, and preserves the rest of the config. `--global` writes `ARGUS_HOME/config.json`, so the plugin command is available from any directory without passing `--plugin`. `plugin add foo=./plugins/foo.js` writes both `plugins: ["foo"]` and `pluginAliases.foo`. `plugin remove` accepts the full specifier, alias, or package shorthand (`google-sheets` removes `gsheets` / `@vforsh/argus-plugin-google-sheets`).
+
+## Resolution
+
+- Built-in aliases resolve first: `gsheets` and `gs` point at `@vforsh/argus-plugin-google-sheets`.
+- Config aliases in `pluginAliases` override built-ins.
+- `file:` URLs load directly.
+- `~`, relative, and absolute paths resolve from the owning config directory first, then other discovered config directories, then cwd.
+- Package specifiers resolve next to Argus first, then from config directory / cwd.
+
+Use dynamic loading for local development:
+
+```bash
+npm run build --workspace @vforsh/argus-plugin-google-sheets
+argus --plugin ./packages/argus-plugin-google-sheets/dist/index.js sheets read extension-3 --range A1:C5
+argus --plugin gs sheets read extension-3 --range A1:C5
+```
+
+## Plugin Contract
+
+```ts
+import { ARGUS_PLUGIN_API_VERSION, type ArgusPluginV1 } from '@vforsh/argus-plugin-api'
+
+const plugin: ArgusPluginV1 = {
+	apiVersion: ARGUS_PLUGIN_API_VERSION,
+	name: 'my-plugin',
+	version: '1.0.0',
+	description: 'Short human description.',
+	commands: ['mycmd'],
+	register(ctx) {
+		ctx.program.command('mycmd').action(() => {})
+	},
+}
+
+export default plugin
+```
+
+Plugins may also export the plugin as `argusPlugin`.
+
+## Host Helpers
+
+`ctx.host` exposes stable helpers:
+
+- `createOutput(options)` for Argus stdout/stderr conventions
+- `requestWatcherJson(input)` for watcher HTTP calls
+- `writeRequestError(result, output)` for standard watcher errors
+- `runChromeOpen(options)` for opening tabs through Argus Chrome resolution
+- `defineWatcherCommand(spec)` for stable watcher-backed command runners with JSON/human formatting
+- `argus.eval`, `argus.dom.click/drag/info/keydown`, and `argus.screenshot` for common watcher calls without raw paths
+
+Minimal watcher command:
+
+```ts
+ctx.program
+	.command('title [id]')
+	.option('--json')
+	.action(
+		ctx.host.defineWatcherCommand({
+			build: () => ({ path: '/eval', method: 'POST', body: { expression: 'document.title', returnByValue: true } }),
+			formatHuman: (response: { ok: true; result: unknown }, { output }) => output.writeHuman(String(response.result ?? '')),
+		}),
+	)
+```
+
+## Google Sheets Plugin
+
+```bash
+argus --plugin ./packages/argus-plugin-google-sheets/dist/index.js plugin list
+argus sheets list extension-3
+argus sheets list extension-3 --with-gid
+argus sheets info extension-3
+argus sheets switch extension-3 "Sheet 2"
+argus sheets open extension-3 2
+argus sheets add extension-3
+argus sheets rename extension-3 "Sheet 2" "Archive"
+argus sheets move extension-3 "Archive" 1
+argus sheets remove extension-3 "Sheet 3" --force
+argus sheets rows add extension-3 5 --count 2 --before
+argus sheets rows remove extension-3 5 --count 2 --force
+argus sheets columns add extension-3 3 --after
+argus sheets columns remove extension-3 3 --force
+argus sheets read extension-3 --range A1:C5
+argus sheets export extension-3 --range A1:C5 --format tsv
+argus sheets find extension-3 "needle" --column ru --ignore-case
+argus sheets write extension-3 B12 --value "Новое значение"
+```
+
+`sheets`/`gs` works against an attached Google Sheets tab. `list` reports visible sheet tabs; `--with-gid` briefly switches through them and restores the original sheet. `switch`/`open`, `rename`, `move`, and `remove` accept a visible sheet name, 1-based visible index, or gid. `add` creates a sheet through the live UI; `remove` requires `--force`. `rows add/remove` and `columns add/remove` mutate the active sheet by 1-based index; add commands require `--before` or `--after`, and remove commands require `--force`. Reads use authenticated CSV export from inside the tab; writes select a range in the live UI and paste TSV.
+
+## No Unload
+
+Argus is a short-lived CLI. To unload a plugin, remove it from config/env or stop passing `--plugin` on the next invocation.

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

@@ -0,0 +1,42 @@
+# Runtime Code Inspection
+
+Argus can inspect runtime JS/CSS resources exposed through CDP.
+
+## Commands
+
+```bash
+argus code ls app
+argus code ls app --pattern inline
+argus code read http://127.0.0.1:3333/ --id app
+argus code read inline://42 --id app --offset 20 --limit 80
+argus code grep '/featureFlag/' --id app
+argus code grep 'argusRuntimeProbe' --id app --url inline
+argus code grep showLogsByHost --id app --pretty
+argus code deminify http://127.0.0.1:3333/app.js --id app
+argus code edit http://127.0.0.1:3333/app.js --id app --search "DEBUG=false" --replace "DEBUG=true"
+argus code edit http://127.0.0.1:3333/app.js --id app --search '/logLevel\s*=\s*"info"/' --replace 'logLevel = "debug"' --all
+argus code edit http://127.0.0.1:3333/app.js --id app --file ./patched.js
+cat patched.css | argus code edit inline-css://1 --id app
+argus code strings app --url app.js
+argus code strings app --url app.js --kind url,identifier --match '/admin\\/api/'
+```
+
+## What It Does
+
+- `code ls`: list runtime scripts/stylesheets discovered via CDP
+- `code read`: return line-numbered source for one resource
+- `code grep`: search sources with a plain string or `/regex/flags`
+- `code grep --pretty`: render clipped context around each match, which is much nicer on minified bundles
+- `code deminify`: pretty-print a runtime resource for quick inspection
+- `code edit`: live-patch a runtime stylesheet via CDP (`CSS.setStyleSheetText`)
+- `code strings`: extract high-signal string literals such as URLs, keys, and camelCase identifiers, with ranking tuned for reverse-engineering
+
+## Behavior Notes
+
+- Resource URLs can be real URLs or synthetic inline IDs like `inline://42` and `inline-css://style-sheet-1`.
+- `code deminify` falls back to the original source if formatting fails.
+- `code edit` supports three input modes: `--search/--replace` for surgical text replacement (with optional `--all`), `--file` for full source replacement from disk, and piped stdin. Search patterns use the same plain-string or `/regex/flags` format as `code grep`. JS script editing is not supported on Chrome 145+ (V8 removed `Debugger.setScriptSource`); use `argus eval` for runtime JS modifications instead.
+- `code strings` favors signal over completeness by default. Use `--all` to include low-signal literals too.
+- `code strings --kind` accepts a comma-separated subset of `url,key,identifier,message,other`.
+- `code strings --match` reuses the same plain-string or `/regex/flags` pattern format as `code grep`.
+- `code grep` skips stale stylesheet handles, emits a warning on stderr, and still returns matches from healthy resources.