@vforsh/argus 0.1.2 → 0.1.4

package/README.md

@@ -6,52 +6,275 @@ CLI for querying Argus watchers.
 
 ```bash
 npm install -g @vforsh/argus
+bunx @vforsh/argus --help
+bunx --package @vforsh/argus argus list
 ```
 
 ## Usage
 
 ```bash
 argus list
-argus logs <id>
-argus tail <id>
+argus logs [id]
+argus tail [id]
+argus eval [id] "<expression>"
+argus page <subcommand>
+argus chrome <subcommand>
+argus watcher list
+argus watcher status [id]
+argus watcher stop [id]
+argus watcher start --id <id> --url <pattern>
+argus config init
+argus doctor
+```
+
+## Config defaults
+
+Argus can load defaults for `argus chrome start` and `argus watcher start` from a repo-local config file.
+
+- Auto-discovery order: `.argus/config.json`, `.config/argus.json`, `argus.config.json`, `argus/config.json`.
+- Use `--config <path>` to point at an explicit file (relative to `cwd` if not absolute).
+- CLI options override config values.
+- `watcher.start.artifacts` is resolved relative to the config file directory.
+
+Example:
+
+```json
+{
+	"$schema": "file:///.../node_modules/@vforsh/argus/schemas/argus.config.schema.json",
+	"chrome": {
+		"start": {
+			"url": "http://localhost:3000",
+			"profile": "default-lite",
+			"devTools": true
+		}
+	},
+	"watcher": {
+		"start": {
+			"id": "app",
+			"url": "localhost:3000",
+			"chromeHost": "127.0.0.1",
+			"chromePort": 9222,
+			"artifacts": "./artifacts",
+			"pageIndicator": true
+		}
+	}
+}
 ```
 
 ### Commands
 
-- **`argus list`**: Discover running Argus watchers and their IDs.
-    - Use this first to find the `<id>` you’ll pass to other commands (often something like `app`).
+- **`argus list`**: Discover registered Argus watchers and their IDs.
+    - Use this first to find the `<id>` you'll pass to other commands (often something like `app`).
     - Tip: add `--json` for scripting.
     - Tip: add `--by-cwd <substring>` to filter watchers by their working directory.
+    - Tip: use `argus watcher prune` to remove unreachable watchers from the registry.
 
-- **`argus logs <id>`**: Fetch a bounded slice of log history for a watcher.
+- **`argus logs [id]`**: Fetch a bounded slice of log history for a watcher.
     - Best for “what already happened?” (e.g. “show me errors from the last 10 minutes”).
-    - Combine with `--since`, `--levels`, and `--grep` to narrow results.
+    - Combine with `--since`, `--levels`, `--match`, and `--source` to narrow results.
+    - If `<id>` is omitted, Argus tries the watcher in your current `cwd`, then the only reachable watcher.
 
-- **`argus tail <id>`**: Stream logs as they arrive (follow mode).
+- **`argus tail [id]`**: Stream logs as they arrive (follow mode).
     - Best for “what’s happening right now?” while you reproduce an issue.
-    - With `--json`, emits newline-delimited JSON events (NDJSON) for piping into tools.
+    - With `--json`, emits bounded newline-delimited JSON events (NDJSON) for piping into tools.
+    - With `--json-full`, emits full NDJSON events (can be very large).
+
+- **`argus eval [id] <expression>`**: Evaluate a JS expression in the connected page.
+    - Best for quick one-off inspection (“what’s `location.href` right now?”).
+    - Defaults: awaits returned promises; returns values “by value” when possible.
+    - Tip: add `--json` for scripting (and check `.exception`).
+    - Tip: add `--no-fail-on-exception` to keep exit code 0 when the expression throws.
+
+#### Chrome commands
+
+Manage and query a running Chrome instance with remote debugging enabled (CDP).
+
+- **`argus chrome start`**: Launch Chrome with CDP enabled.
+    - Options: `--url <url>`, `--from-watcher <watcherId>`, `--profile <temp|default-full|default-medium|default-lite>`, `--dev-tools`, `--config <path>`, `--json`.
+    - Example: `argus chrome start --url http://localhost:3000`.
+    - Note: `--profile default-full` launches Chrome with a copied snapshot of your default profile.
+    - Note: `--profile default-medium` adds History, Local Storage, and IndexedDB to the lite profile.
+    - Note: `--profile default-lite` copies only auth-related files to keep the profile lightweight.
+    - Why: recent Chrome versions require a non-default user data dir to expose `--remote-debugging-port`, so Argus copies your default profile into a temp directory and launches Chrome from that copy (keeps your real default profile closed + untouched).
+    - Reference:
+        ```
+        https://developer.chrome.com/blog/remote-debugging-port
+        ```
+
+- **`argus chrome version`**: Show Chrome version info from the CDP endpoint.
+    - Options: `--cdp <host:port>`, `--id <watcherId>`, `--json`.
+
+- **`argus chrome status`**: Check if Chrome CDP endpoint is reachable.
+    - Prints `ok <host>:<port> <browser>` on success; exits with code 1 if unreachable.
+
+- **`argus chrome stop`**: Close the Chrome instance via CDP.
+    - Alias: `quit`.
+    - Example: `argus chrome stop`.
+
+#### Page commands
+
+Manage tabs/targets via CDP (aliases: `tab`).
+
+- **`argus page targets`**: List all Chrome targets (tabs, workers, extensions).
+    - Aliases: `list`, `ls`.
+    - Options: `--type <type>` to filter (e.g. `--type page` for tabs only), `--json`.
+    - Example: `argus page targets --type page`.
+
+- **`argus page open --url <url>`**: Open a new tab in Chrome.
+    - Alias: `new`.
+    - URL normalization: if no scheme, `http://` is prepended.
+    - Example: `argus page open --url localhost:3000`.
+
+- **`argus page activate [targetId]`**: Activate (focus) a Chrome target.
+    - Fuzzy selection: `--title`, `--url`, or `--match` (case-insensitive substring).
+    - If multiple matches and TTY: interactive picker. If non-TTY: prints candidates and exits 2.
+    - Example: `argus page activate --title "Docs"`.
+
+- **`argus page close <targetId>`**: Close a Chrome target.
+    - Example: `argus page close E63A3ED201BFC02DA06134F506A7498C`.
+
+- **`argus page reload [targetId]`**: Reload a Chrome target.
+    - Omit `targetId` with `--id <watcherId>` to reload the watcher's attached page.
+    - Use `--param`/`--params` to update query params before reload.
+    - Example: `argus page reload --id app`.
+
+**CDP endpoint resolution** (applies to `chrome version/status/stop` and all `page` commands):
+
+- `--cdp <host:port>`: Use explicit host/port.
+- `--id <watcherId>`: Use chrome config from a registered watcher's `chrome.host`/`chrome.port`.
+- Default: `127.0.0.1:9222`.
+- `--cdp` and `--id` are mutually exclusive.
+
+#### Watcher commands
+
+Also available via `argus watchers` (plural alias).
+
+- **`argus watcher list`**: Same output as `argus list`, but namespaced under `watcher`.
+    - Aliases: `ls`.
+    - Example: `argus watcher list --by-cwd my-project`.
+
+- **`argus watcher status [id]`**: Check whether a watcher is reachable.
+    - Alias: `ping`.
+    - Example: `argus watcher status app`.
+
+- **`argus watcher stop [id]`**: Ask a watcher to shut down (falls back to SIGTERM).
+    - Alias: `kill`.
+    - Example: `argus watcher stop app`.
+
+- **`argus watcher start`**: Start an Argus watcher process.
+    - Required (CLI or config): `--id <watcherId>`, `--url <pattern>`.
+    - Optional: `--chrome-host <host>` (default: `127.0.0.1`), `--chrome-port <port>` (default: `9222`), `--no-page-indicator`, `--config <path>`, `--json`.
+    - Note: the in-page watcher indicator badge is enabled by default.
+    - Example: `argus watcher start --id app --url localhost:3000 --chrome-port 9223`.
+
+- **`argus watcher prune`**: Remove unreachable watchers from the registry.
+    - Alias: `clean`.
+    - Options: `--by-cwd <substring>` to filter candidates, `--dry-run` to preview without removing, `--json`.
+    - Examples:
+        - `argus watcher prune`
+        - `argus watcher prune --by-cwd my-project`
+        - `argus watcher prune --dry-run`
+        - `argus watcher prune --dry-run --json`
+
+- **`argus config init`**: Create an Argus config file.
+    - Default path: `.argus/config.json`.
+    - Options: `--path <file>`, `--force`.
+    - Example: `argus config init --path argus.config.json`.
+
+#### Diagnostics
+
+- **`argus doctor`**: Run environment diagnostics for registry, watchers, WebSocket availability, Chrome bin, and CDP.
+    - Tip: add `--json` for scripting.
+
+#### Watcher selection defaults
+
+For commands that accept `[id]`:
+
+- If `<id>` is provided, Argus uses it.
+- Else if exactly one watcher has `cwd === process.cwd()`, Argus uses it.
+- Else if exactly one reachable watcher exists, Argus uses it.
+- Otherwise Argus exits with an error and lists candidates (TTY prompts are only used for page target selection, not watcher IDs).
 
 #### `logs` vs `tail`
 
 - **`logs`**: one-time query of **past** log events (bounded).
 - **`tail`**: continuous stream of **new** log events (unbounded until you stop it).
 
+#### `eval` gotchas / quirks
+
+- **Shell quoting**: `<expression>` is a single CLI argument.
+    - Use quotes for anything with spaces/special chars (zsh/bash): `argus eval app 'location.href'`.
+    - If you need quotes _inside_ the expression, prefer swapping quote types or escaping.
+
+- **“await” behavior**:
+    - By default, Argus sets CDP `awaitPromise=true`, so if your expression **returns a Promise**, Argus waits for it and prints the resolved value.
+    - You typically don’t need to use the `await` keyword—just return a Promise (e.g. `fetch("/ping").then(r => r.status)`).
+    - With `--no-await`, Argus won’t wait; you’ll get a Promise-ish preview instead.
+
+- **Return value shape is intentionally shallow**:
+    - By default, Argus requests `returnByValue=true` (best effort “JSON-ish” values).
+    - When a value can’t be returned by value, Argus falls back to a **bounded preview** (often shallow object properties, capped; nested objects are not expanded).
+    - You may see truncation markers like `…: "+N more"`.
+    - If you specifically want preview/remote-object behavior, use `--no-return-by-value`.
+
+- **Exceptions fail the process by default**:
+    - By default, exceptions set exit code 1 and are routed to stderr.
+    - Use `--no-fail-on-exception` to keep exit code 0 and treat exceptions as successful output.
+    - For automation, prefer `--json` and check `.exception`.
+
+- **Timeouts**:
+    - `--timeout <ms>` sets the watcher-side eval timeout (non-numeric / <= 0 is ignored).
+    - The CLI HTTP request timeout includes a small buffer on top of the eval timeout.
+
+- **Watcher registry cleanup**:
+    - Argus does **not** remove watchers on single failures by default.
+    - Use `argus watcher prune` to explicitly remove unreachable watchers from the registry.
+    - Use `argus watcher prune --dry-run` to preview what would be removed.
+
+#### `eval` options
+
+- **`--no-fail-on-exception`**: keep exit code 0 when the evaluation throws.
+- **`--retry <n>`**: retry failed evaluations (transport failures always; exceptions only when `--no-fail-on-exception` is not set).
+- **`-q, --silent`**: suppress success output; still emits errors.
+- **`--interval <ms|duration>`**: re-evaluate on a fixed cadence (e.g. `500`, `250ms`, `3s`).
+- **`--count <n>`**: stop after N iterations (requires `--interval`).
+- **`--until <condition>`**: stop when local condition becomes truthy (requires `--interval`).
+    - Evaluated locally in Node with context `{ result, exception, iteration, attempt }`.
+    - **Warning**: executes arbitrary local JS; don’t paste untrusted input.
+
 ### Options
 
 - **`--json`**: output machine-readable JSON.
-    - **What**: switches from human text formatting to JSON; for `tail`, this is newline-delimited JSON (NDJSON) so each event is one line.
+    - **What**: switches from human text formatting to JSON.
+    - **Streaming**: commands that can emit multiple objects use **NDJSON** (one JSON object per line).
+    - **Stderr**: when `--json` is set, all non-machine logs go to **stderr**.
     - **When**: when piping into tools like `jq`, writing to a file, or building scripts around Argus.
     - **Why**: stable structure is easier to parse than terminal-friendly text.
 
+- **`--json-full`**: output full, raw JSON.
+    - **What**: emits the full event payload with no preview caps; for streaming commands this is NDJSON.
+    - **When**: when you need exact fidelity and are ok with large output.
+    - **Why**: preserves complete structures for deep debugging or archival.
+
 - **`--levels <comma-separated>`**: filter by log severity.
     - **What**: only returns/emits events whose `level` is in the list (e.g. `error,warning`).
     - **When**: when you want to focus on signal (errors/warnings) and ignore noisy `log`/`debug` output.
     - **Why**: reduces volume so important events don’t get buried.
 
-- **`--grep <substring>`**: filter by message content.
-    - **What**: only returns/emits events whose text contains the given substring.
-    - **When**: when you’re hunting for a specific error (“Unhandled”, “ECONNREFUSED”, a request ID, etc.).
-    - **Why**: quickly narrows large streams/histories without post-processing.
+- **`--match <regex>`**: filter by message content (repeatable).
+    - **What**: only returns/emits events whose text matches any provided regex pattern.
+    - **When**: when you need server-side regex filtering (e.g. multiple tokens or alternation).
+    - **Why**: reduces client-side `rg`/`tail` loops.
+
+- **`--ignore-case` / `--case-sensitive`**: toggle regex case sensitivity.
+    - **What**: controls how `--match` compares text.
+    - **When**: when you need strict casing or want to avoid missing matches.
+    - **Why**: keeps filtering predictable across environments.
+
+- **`--source <substring>`**: filter by log source.
+    - **What**: only returns/emits events whose `source` contains the given substring (e.g. `console`, `exception`, `system`).
+    - **When**: when you only want console logs or only exceptions.
+    - **Why**: reduces noise without post-processing.
 
 - **`--by-cwd <substring>`**: filter watchers by working directory.
     - **What**: only returns watchers whose `cwd` contains the given substring.
@@ -60,13 +283,13 @@ argus tail <id>
 
 - **`--since <duration>`**: time window (history).
     - **What**: limits results to events within the last duration (e.g. `10m`, `2h`, `30s`).
-    - **When**: when you only care about “recent” history (typically with `logs`).
+    - **When**: when you only care about "recent" history (typically with `logs`).
     - **Why**: avoids dumping an entire backlog when you only need the latest slice.
 
 ## Output
 
 - Text output uses 4-character level tags (e.g. `LOG `, `DEBG`, `WARN`, `ERR `, `INFO`, `EXCP`).
-- JSON output preserves the raw `level` values.
+- JSON output preserves the raw `level` values; `--json` uses bounded preview values, `--json-full` is raw.
 
 ## Examples
 
@@ -74,5 +297,31 @@ argus tail <id>
 argus list --json
 argus list --by-cwd my-project
 argus logs app --since 10m --levels error,warning
-argus tail app --grep "Unhandled"
+argus logs app --match "\\[perf\\]" --match "OrderRewards|CustomerMakingOrderSelfService"
+argus tail app --match "Unhandled"
+argus eval app 'location.href'
+argus eval app 'fetch("/ping").then(r => r.status)'
+argus eval app 'document.title' --json | jq
+argus eval app 'throw new Error("boom")'
+argus eval app '1+1' --silent
+argus eval app 'Date.now()' --interval 500 --count 3
+argus eval app 'document.title' --interval 250 --until 'result === "argus-e2e"'
+
+# Chrome commands
+argus chrome status --cdp 127.0.0.1:9222
+argus chrome version --json
+argus chrome stop
+
+# Page commands
+argus page targets --type page
+argus page ls --type page --json
+argus page open --url localhost:3000
+argus page activate --title \"Docs\"
+argus page close E63A3ED201BFC02DA06134F506A7498C
+argus page reload --id app
+
+# Watcher with custom Chrome port
+argus chrome start --json  # note the cdpPort in output
+argus watcher start --id app --url localhost:3000 --chrome-port 9223
+argus doctor
 ```