chrome-devtools-axi 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,13 @@
-# chrome-devtools-axi
+<h1 align="center">chrome-devtools-axi</h1>
 
-[![CI](https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/ci.yml/badge.svg)](https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/ci.yml)
-[![Release](https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/release-please.yml/badge.svg)](https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/release-please.yml)
-![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)
-[![X](https://img.shields.io/badge/X-@kunchenguid-black?logo=x)](https://x.com/kunchenguid)
+<p align="center">
+  <a href="https://www.npmjs.com/package/chrome-devtools-axi"><img alt="npm" src="https://img.shields.io/npm/v/chrome-devtools-axi?style=flat-square" /></a>
+  <a href="https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/ci.yml?style=flat-square&label=CI" /></a>
+  <a href="https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/release-please.yml"><img alt="Release" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/release-please.yml?style=flat-square&label=Release" /></a>
+  <a href="#"><img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" /></a>
+  <a href="https://x.com/kunchenguid"><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square" /></a>
+  <a href="https://discord.gg/BW4aJuQhTf"><img alt="Discord" src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord" /></a>
+</p>
 
 <h3 align="center">Highly agent-ergonomic browser automation</h3>
 
@@ -34,19 +38,10 @@ snapshot:
 
 ## Install
 
-**npm**
+**Tell your agent:**
 
-```sh
-npm install -g chrome-devtools-axi
 ```
-
-**From source**
-
-```sh
-git clone https://github.com/kunchenguid/chrome-devtools-axi.git
-cd chrome-devtools-axi
-npm install && npm run build
-npm link
+Execute `npm i -g chrome-devtools-axi` and run `chrome-devtools-axi` for browser automation.
 ```
 
 ## How It Works
@@ -74,28 +69,103 @@ npm link
 
 ## CLI Reference
 
-| Command              | Description                         |
-| -------------------- | ----------------------------------- |
-| `open <url>`         | Navigate to URL and snapshot        |
-| `snapshot`           | Capture current page state          |
-| `click @<uid>`       | Click an element by ref             |
-| `fill @<uid> <text>` | Fill a form field                   |
-| `type <text>`        | Type text at current focus          |
-| `press <key>`        | Press a keyboard key                |
-| `scroll <dir>`       | Scroll: up, down, top, bottom       |
-| `back`               | Navigate back                       |
-| `wait <ms\|text>`    | Wait for time or text to appear     |
-| `eval <js>`          | Evaluate JavaScript in page context |
-| `start`              | Start the bridge server             |
-| `stop`               | Stop the bridge server              |
+### Navigation
+
+| Command           | Description                         |
+| ----------------- | ----------------------------------- |
+| `open <url>`      | Navigate to URL and snapshot        |
+| `snapshot`        | Capture current page state          |
+| `screenshot <p>`  | Save a screenshot to a file         |
+| `scroll <dir>`    | Scroll: up, down, top, bottom       |
+| `back`            | Navigate back                       |
+| `wait <ms\|text>` | Wait for time or text to appear     |
+| `eval <js>`       | Evaluate JavaScript in page context |
+
+### Interaction
+
+| Command                    | Description                    |
+| -------------------------- | ------------------------------ |
+| `click @<uid>`             | Click an element by ref        |
+| `fill @<uid> <text>`       | Fill a form field              |
+| `type <text>`              | Type text at current focus     |
+| `press <key>`              | Press a keyboard key           |
+| `hover @<uid>`             | Hover over an element          |
+| `drag @<from> @<to>`       | Drag an element onto another   |
+| `fillform @<uid>=<val>...` | Fill multiple form fields      |
+| `dialog <accept\|dismiss>` | Handle a browser dialog        |
+| `upload @<uid> <path>`     | Upload a file through an input |
+
+### Page Management
+
+| Command           | Description                 |
+| ----------------- | --------------------------- |
+| `pages`           | List all open tabs          |
+| `newpage <url>`   | Open a new tab              |
+| `selectpage <id>` | Switch to a tab by ID       |
+| `closepage <id>`  | Close a tab by ID           |
+| `resize <w> <h>`  | Resize the browser viewport |
+
+### Emulation
+
+| Command   | Description                     |
+| --------- | ------------------------------- |
+| `emulate` | Emulate device/network/viewport |
+
+### DevTools Debugging
+
+| Command            | Description                    |
+| ------------------ | ------------------------------ |
+| `console`          | List console messages          |
+| `console-get <id>` | Get a specific console message |
+| `network`          | List network requests          |
+| `network-get [id]` | Get a specific network request |
+
+### Performance
+
+| Command                     | Description                   |
+| --------------------------- | ----------------------------- |
+| `lighthouse`                | Run a Lighthouse audit        |
+| `perf-start`                | Start a performance trace     |
+| `perf-stop`                 | Stop the performance trace    |
+| `perf-insight <set> <name>` | Analyze a performance insight |
+| `heap <path>`               | Capture a heap snapshot       |
+
+### Bridge
+
+| Command | Description             |
+| ------- | ----------------------- |
+| `start` | Start the bridge server |
+| `stop`  | Stop the bridge server  |
 
 Running with no command is equivalent to `snapshot`.
 
 ### Flags
 
-| Flag     | Description            |
-| -------- | ---------------------- |
-| `--help` | Show usage information |
+| Flag                        | Description                                 |
+| --------------------------- | ------------------------------------------- |
+| `--help`                    | Show usage information                      |
+| `--full`                    | Show complete snapshot without truncation   |
+| `--background`              | Open new page in background (newpage)       |
+| `--uid @<uid>`              | Target a specific element (screenshot)      |
+| `--full-page`               | Capture entire scrollable page (screenshot) |
+| `--format <fmt>`            | Image format: png, jpeg, webp (screenshot)  |
+| `--viewport <spec>`         | Viewport like "390x844x3,mobile" (emulate)  |
+| `--color-scheme <value>`    | dark, light, or auto (emulate)              |
+| `--network <condition>`     | Network throttle: Slow 3G, etc. (emulate)   |
+| `--cpu <rate>`              | CPU throttling rate 1-20 (emulate)          |
+| `--geolocation <lat>x<lon>` | Set geolocation (emulate)                   |
+| `--user-agent <string>`     | Custom user agent (emulate)                 |
+| `--type <type>`             | Filter by type (console, network)           |
+| `--limit <n>`               | Max items to return (console, network)      |
+| `--page <n>`                | Pagination (console, network)               |
+| `--device <device>`         | desktop or mobile (lighthouse)              |
+| `--mode <mode>`             | navigation or snapshot (lighthouse)         |
+| `--output-dir <path>`       | Directory for reports (lighthouse)          |
+| `--no-reload`               | Skip page reload (perf-start)               |
+| `--no-auto-stop`            | Disable auto-stop (perf-start)              |
+| `--file <path>`             | Save trace data to file (perf-start/stop)   |
+| `--response-file <path>`    | Save response body (network-get)            |
+| `--request-file <path>`     | Save request body (network-get)             |
 
 ## Configuration
 

package/dist/src/cli.d.ts

@@ -1 +1,59 @@
+export declare function getCommandHelp(command: string): string | null;
+export interface ScreenshotArgs {
+    filePath: string | null;
+    uid: string | undefined;
+    fullPage: boolean;
+    format: string | undefined;
+}
+export declare function parseScreenshotArgs(args: string[]): ScreenshotArgs;
+export declare function formatScreenshotOutput(filePath: string): string;
+/** Parse MCP list_pages markdown into structured data. */
+export declare function parsePagesList(text: string): {
+    id: number;
+    url: string;
+    selected: boolean;
+}[];
+/** Format raw MCP text result as AXI output: labeled block + truncation + suggestions. */
+export declare function formatMcpResult(label: string, text: string, suggestions: string[]): string;
+export declare function parseFillFormArgs(args: string[]): {
+    entries: {
+        uid: string;
+        value: string;
+    }[];
+};
+export interface EmulateArgs {
+    viewport?: string;
+    colorScheme?: string;
+    networkConditions?: string;
+    cpuThrottlingRate?: number;
+    geolocation?: string;
+    userAgent?: string;
+}
+export declare function parseEmulateArgs(args: string[]): EmulateArgs;
+export declare function parseConsoleArgs(args: string[]): {
+    types?: string[];
+    pageSize?: number;
+    pageIdx?: number;
+};
+export declare function parseNetworkArgs(args: string[]): {
+    resourceTypes?: string[];
+    pageSize?: number;
+    pageIdx?: number;
+};
+export declare function parseNetworkGetArgs(args: string[]): {
+    reqid?: number;
+    responseFilePath?: string;
+    requestFilePath?: string;
+};
+export declare function parseLighthouseArgs(args: string[]): {
+    device?: string;
+    mode?: string;
+    outputDirPath?: string;
+};
+export declare function parsePerfStartArgs(args: string[]): {
+    reload?: boolean;
+    autoStop?: boolean;
+    filePath?: string;
+};
+export declare function formatStopOutput(wasStopped: boolean): string;
 export declare function main(argv: string[]): Promise<void>;