cssprobe-cli 0.2.26 → 0.3.1

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 `cssprobe-cli` — Runtime CSS probe for layout/scroll/overflow/color/font inspection with session-based browser management. Entrypoint: `bin/cssprobe-cli.js` → `require('../dist/index')`.
 Build: `npm run build` (= `tsc` + `esbuild` collector IIFE bundle + `esbuild` daemon entry + `tsx scripts/generate-help.ts`).
-Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 58 tests).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 108 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -21,19 +21,23 @@ src/
 ├── daemon/
 │   ├── session.ts             # Session management (single session, Unix socket)
 │   ├── daemon.ts              # Daemon process: browser lifecycle + command execution
+│   ├── flowRunner.ts          # Flow script loader/runner (run command): dynamic import, API injection, console capture
 │   └── daemonEntry.ts         # Daemon entry point (spawned as child process)
 ├── engine/
 │   ├── types.ts               # Shared types: Snapshot, TreeNode, Finding, Confidence
 │   ├── collector.ts           # Browser-side: DOM traversal, computed styles, declared values
 │   ├── analyzer.ts            # Node-side: pure functions, confidence model, pattern detection
+│   ├── evalSerializer.ts      # Self-contained serializer for eval results (runs in-page via JSHandle.evaluate)
 │   └── renderer.ts            # Markdown / JSON rendering
 ├── browser/
-│   └── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+│   ├── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+│   └── interactions.ts        # Interaction primitives: click/hover/type/wait-for (shared by daemon + run API)
 ├── config/
 │   ├── config.ts              # Config loader (CLI → env → ~/.cssprobe-clirc profiles)
 │   └── helpGenerator.ts       # Build-time: Zod schemas → dist/help.json
 └── utils/
-    └── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    ├── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    └── screenshot.ts          # Screenshot data-URL → file saving (shared by CLI + flow runner)
 ```
 
 ## Key Patterns
@@ -73,11 +77,32 @@ src/
 - `resize <width> <height>` — Resize browser viewport
 - `eval <expression>` — Evaluate JavaScript (browser context)
   - Returns raw string values (not JSON-quoted) for string results
+  - DOM nodes / circular structures are auto-serialized (descriptors, `[Circular]`, `[Function: name]`, depth cap 6)
 - `playwright <call>` — Execute Playwright API call (Node.js context)
   - Returns `{ ok: true, value: null, note: ... }` when the call returns no value; throws a clear error message on failure
 - `screenshot` — Take a screenshot
   - `--out <path>` — Output file path (default: `~/.cssprobe-cli/screenshots/<timestamp>.png`)
 
+### Interaction
+- `click <selector>` — Real mouse click (auto-scroll + actionability wait, works with custom React components)
+  - `--nth <n>` — 1-based match index (default: first match; multiple matches without `--nth` fail — strict)
+  - `--force` — skip actionability checks
+  - `--timeout <ms>` — action timeout (default 30000)
+- `hover <selector>` — Real mouse hover (`--nth` / `--force` / `--timeout` as above)
+- `type <selector> <text>` — Type text
+  - Default: `fill()` (replaces the value); `--sequential` for real key events (custom editors), `--clear` clears first
+  - `--press <key>` — press a key after typing (e.g. `Enter`)
+  - `--delay <ms>` — keystroke delay for `--sequential`
+- `wait-for` — Wait for a condition (three mutually exclusive modes)
+  - `wait-for <selector>` — selector state: `--state visible|hidden|attached|detached` (default visible)
+  - `wait-for --js "<predicate>"` — wait until a JS predicate is truthy
+  - `wait-for --network-idle` — wait until the page is network-idle
+  - `--timeout <ms>` — default 30000; timeout errors name the target
+- `run <file>` — Run a multi-step flow script inside the daemon
+  - Script default-exports an async function receiving the API object: `page`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `log` (CJS also supported)
+  - `--timeout <ms>` — whole-script guard (default 300000, 0 = unlimited); failure exits 1 and keeps the session alive
+  - `screenshot` relative paths resolve against the script's directory; logs collected and returned
+
 ### State
 - `state-import [file]` — Import cookies from Netscape format
   - `--out <file>` — Output state file path (default: `~/.cssprobe-cli/states/imported.json`)
@@ -151,6 +176,6 @@ cssprobe-cli close
 | Output | Single markdown string | Markdown (default) / JSON (--json) |
 | Config | `window.__DOM_REPORT_CFG` global + eval two-step | CLI flags → env → rc file, one command |
 | ROOT_SELECTOR | Manual or eval probe | `--auto-root` auto-detection |
-| Tests | None | 45 unit tests (command, analyzer, output, renderer) |
+| Tests | None | 45+ unit tests (command, analyzer, output, renderer) |
 | Build | Regex stripping CJS module.exports | esbuild IIFE + CJS bundle, clean build |
 | Session | None (blocking commands) | Session-based daemon architecture |

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes are documented on the [GitHub Releases](https://github.com/mack-peng/cssprobe-cli/releases) page.
 
+## [0.3.0] - 2026-09-16
+
+### Added
+- MCP server (`cssprobe-cli mcp`, stdio): 10 tools — open / inspect / tree / layout / findings / eval / screenshot / inject_css / close / status
+- `mcp-install` / `mcp-uninstall`: auto-configure MCP clients (Claude Code, Cursor, Codex CLI, opencode, Gemini CLI, Hermes)
+- `mcpName` (`io.github.mack-peng/cssprobe-cli`) for the official MCP Registry
+- README MCP section; `llms.txt` MCP pointer
+
+### Changed
+- Session commands (open/close/status/inspect/…) now share one implementation between CLI and MCP (`src/cli/session-ops.ts`); behavior unchanged
+
 ## [0.2.26] - 2026-09-16
 
 ### Added

package/README.md

@@ -119,6 +119,30 @@ cssprobe-cli inspect body --json
 cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
 ```
 
+### 4. Use as an MCP Server (AI clients)
+
+cssprobe-cli ships an MCP server (stdio), so AI clients call it as a native tool — no shell needed:
+
+```bash
+cssprobe-cli mcp-install          # auto-detect and configure installed clients
+cssprobe-cli mcp-install --target=claude,cursor,codex
+cssprobe-cli mcp-install --local  # write project-scoped config
+```
+
+Manual configuration for any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
+  }
+}
+```
+
+Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprobe_layout`,
+`cssprobe_findings`, `cssprobe_eval`, `cssprobe_screenshot`, `cssprobe_inject_css`,
+`cssprobe_close`, `cssprobe_status`. Remove with `cssprobe-cli mcp-uninstall`.
+
 ---
 
 ## Commands
@@ -158,10 +182,24 @@ cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
 | Command | Description |
 |---------|-------------|
 | `resize <width> <height>` | Resize browser viewport |
-| `eval <expression>` | Evaluate JavaScript (browser context) |
+| `eval <expression>` | Evaluate JavaScript (browser context); DOM nodes are auto-serialized |
 | `playwright <call>` | Execute Playwright API (Node.js context) |
 | `screenshot` | Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override) |
 
+### Interaction
+
+| Command | Description |
+|---------|-------------|
+| `click <selector>` | Real mouse click (auto-scroll + actionability wait; works with custom React components) |
+| `hover <selector>` | Real mouse hover |
+| `type <selector> <text>` | Fill text (replaces value); `--press Enter` to submit; `--sequential` for real key events |
+| `wait-for <selector>` | Wait for selector state (`--state visible\|hidden\|attached\|detached`, `--timeout ms`) |
+| `wait-for --js "<predicate>"` | Wait until a JS predicate is truthy |
+| `wait-for --network-idle` | Wait until the page is network-idle |
+| `run <file>` | Run a multi-step flow script |
+
+`click` / `hover` support `--nth N` (1-based, default first match), `--force` (skip actionability checks) and `--timeout ms`. Without `--nth`, multiple matches fail (strict) to prevent wrong-target clicks.
+
 ### State
 
 | Command | Description |
@@ -182,6 +220,51 @@ cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
 
 ---
 
+## Multi-step Flows
+
+The interaction commands drive a page step by step; `run` turns a sequence into a versionable script:
+
+```bash
+cssprobe-cli open https://example.com/editor
+cssprobe-cli wait-for .editor-canvas
+cssprobe-cli click ".layout-switch" --nth 1
+cssprobe-cli type ".block-title input" "Hello" --press Enter
+cssprobe-cli inspect .block-grid --json
+cssprobe-cli close
+```
+
+For repeatable flows, write a script and run it with one command. The script runs inside the daemon session (full Playwright `page` access):
+
+```js
+// flow.js
+export default async ({ page, click, waitFor, type, inspect, screenshot, log }) => {
+  await page.goto('https://example.com/editor', { waitUntil: 'domcontentloaded' });
+  await waitFor('.editor-canvas', { state: 'visible', timeout: 10000 });
+
+  await click('.layout-switch', { nth: 1 });
+  await waitFor({ js: "() => document.body.dataset.layout === 'two-col'" });
+
+  await type('.block-title input', 'Hello', { press: 'Enter', sequential: true, clear: true });
+  await waitFor({ networkIdle: true });
+
+  const { findings } = await inspect('.block-grid', { format: 'json' });
+  log('findings:', findings.length);
+  await screenshot({ path: './after-layout-switch.png' });
+
+  return { findings: findings.length };
+};
+```
+
+```bash
+cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)
+```
+
+Scripts must `default-export` an async function receiving the API object: `page`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `log`. `screenshot` relative paths resolve against the script's directory; logs (`log()` and `console.*`) are collected and returned with the result. On failure the command exits `1`, prints the collected logs, and keeps the session alive.
+
+> Scripts are executed by the local daemon with full Node privileges — only run trusted scripts.
+
+---
+
 ## Confidence Model
 
 Every finding carries a confidence level:

package/dist/browser/interactions.d.ts

@@ -0,0 +1,48 @@
+import type { Page } from 'playwright-core';
+export interface ElementDescriptor {
+    tag: string;
+    classes: string[];
+    text: string;
+}
+export interface TargetResult {
+    matches: number;
+    nth: number;
+    descriptor: ElementDescriptor | null;
+}
+export type WaitState = 'visible' | 'hidden' | 'attached' | 'detached';
+export type WaitTarget = {
+    kind: 'selector';
+    selector: string;
+    state: WaitState;
+} | {
+    kind: 'js';
+    expression: string;
+} | {
+    kind: 'networkIdle';
+};
+export declare function clickElement(page: Page, selector: string, opts?: {
+    nth?: number;
+    force?: boolean;
+    timeout?: number;
+}): Promise<TargetResult>;
+export declare function hoverElement(page: Page, selector: string, opts?: {
+    nth?: number;
+    force?: boolean;
+    timeout?: number;
+}): Promise<TargetResult>;
+export interface TypeOptions {
+    press?: string;
+    sequential?: boolean;
+    clear?: boolean;
+    delay?: number;
+    nth?: number;
+    timeout?: number;
+}
+export declare function typeInto(page: Page, selector: string, text: string, opts?: TypeOptions): Promise<void>;
+export declare function describeWaitTarget(target: WaitTarget): string;
+export declare function resolveWaitTarget(selector: string | undefined, opts: {
+    js?: string;
+    networkIdle?: boolean;
+    state?: string;
+}): WaitTarget;
+export declare function waitForCondition(page: Page, target: WaitTarget, timeout: number): Promise<number>;

package/dist/browser/interactions.js

@@ -0,0 +1,88 @@
+"use strict";
+// Interaction primitives shared by daemon commands and the run-script API.
+// Strict mode is preserved when no nth is given: multiple matches fail the action.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clickElement = clickElement;
+exports.hoverElement = hoverElement;
+exports.typeInto = typeInto;
+exports.describeWaitTarget = describeWaitTarget;
+exports.resolveWaitTarget = resolveWaitTarget;
+exports.waitForCondition = waitForCondition;
+const DEFAULT_TIMEOUT = 30_000;
+function resolveLocator(page, selector, nth) {
+    const base = page.locator(selector);
+    return nth ? base.nth(nth - 1) : base;
+}
+async function describeTarget(locator) {
+    return await locator
+        .evaluate(el => ({
+        tag: el.tagName.toLowerCase(),
+        classes: Array.from(el.classList),
+        text: (el.textContent ?? '').trim().slice(0, 60),
+    }))
+        .catch(() => null);
+}
+async function interactTarget(page, selector, opts, action) {
+    const base = page.locator(selector);
+    const locator = resolveLocator(page, selector, opts.nth);
+    const matches = await base.count();
+    const descriptor = await describeTarget(locator);
+    await action(locator, { force: opts.force, timeout: opts.timeout ?? DEFAULT_TIMEOUT });
+    return { matches, nth: opts.nth ?? 1, descriptor };
+}
+async function clickElement(page, selector, opts = {}) {
+    return interactTarget(page, selector, opts, (locator, o) => locator.click({ force: o.force, timeout: o.timeout }));
+}
+async function hoverElement(page, selector, opts = {}) {
+    return interactTarget(page, selector, opts, (locator, o) => locator.hover({ force: o.force, timeout: o.timeout }));
+}
+async function typeInto(page, selector, text, opts = {}) {
+    const locator = resolveLocator(page, selector, opts.nth);
+    const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+    if (opts.sequential) {
+        if (opts.clear)
+            await locator.fill('', { timeout });
+        await locator.pressSequentially(text, { delay: opts.delay ?? 0, timeout });
+    }
+    else {
+        await locator.fill(text, { timeout });
+    }
+    if (opts.press)
+        await locator.press(opts.press, { timeout });
+}
+function describeWaitTarget(target) {
+    switch (target.kind) {
+        case 'selector':
+            return `${target.selector} (state: ${target.state})`;
+        case 'js':
+            return `JS predicate: ${target.expression.slice(0, 80)}`;
+        case 'networkIdle':
+            return 'network idle';
+    }
+}
+function resolveWaitTarget(selector, opts) {
+    const modeCount = [selector, opts.js, opts.networkIdle].filter(Boolean).length;
+    if (modeCount !== 1)
+        throw new Error('wait-for requires exactly one of: <selector>, --js "<expression>", --network-idle');
+    if (selector)
+        return { kind: 'selector', selector, state: (opts.state ?? 'visible') };
+    if (opts.js)
+        return { kind: 'js', expression: opts.js };
+    return { kind: 'networkIdle' };
+}
+async function waitForCondition(page, target, timeout) {
+    const started = Date.now();
+    switch (target.kind) {
+        case 'selector':
+            await page.waitForSelector(target.selector, { state: target.state, timeout });
+            break;
+        case 'js':
+            await page.waitForFunction(target.expression, null, { timeout });
+            break;
+        case 'networkIdle':
+            await page.waitForLoadState('networkidle', { timeout });
+            break;
+    }
+    return Date.now() - started;
+}
+//# sourceMappingURL=interactions.js.map

package/dist/cli/commands.js

@@ -157,6 +157,75 @@ const playwrightCmd = (0, command_1.declareCommand)({
         call: z.string().describe('Playwright API call, e.g. "page.setViewportSize({width: 1280, height: 720})"'),
     }),
 });
+// ── interaction ──
+const click = (0, command_1.declareCommand)({
+    name: 'click',
+    category: 'core',
+    description: 'Click an element with real mouse events (works with custom React components)',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+    }),
+    options: z.object({
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        force: z.boolean().optional().describe('skip actionability checks'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const hover = (0, command_1.declareCommand)({
+    name: 'hover',
+    category: 'core',
+    description: 'Hover an element with real mouse events',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+    }),
+    options: z.object({
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        force: z.boolean().optional().describe('skip actionability checks'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const typeCmd = (0, command_1.declareCommand)({
+    name: 'type',
+    category: 'core',
+    description: 'Type text into an element (fill by default; --sequential for real key events)',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+        text: z.string().describe('text to type'),
+    }),
+    options: z.object({
+        press: z.string().optional().describe('key to press after typing (e.g. Enter, Tab, Control+A)'),
+        sequential: z.boolean().optional().describe('type with real key events (for custom editors)'),
+        clear: z.boolean().optional().describe('clear existing content before sequential typing'),
+        delay: numberArg.optional().describe('delay between keystrokes in ms (--sequential, default 0)'),
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const waitForCmd = (0, command_1.declareCommand)({
+    name: 'wait-for',
+    category: 'core',
+    description: 'Wait for a condition: selector state, JS predicate, or network idle',
+    args: z.object({
+        selector: z.string().optional().describe('CSS selector to wait for'),
+    }),
+    options: z.object({
+        state: z.enum(['visible', 'hidden', 'attached', 'detached']).optional().describe('selector state to wait for (default visible)'),
+        js: z.string().optional().describe('JS predicate, e.g. "() => document.querySelector(\'.x\')?.offsetHeight > 100"'),
+        'network-idle': z.boolean().optional().describe('wait until the page is network-idle'),
+        timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
+    }),
+});
+const runCmd = (0, command_1.declareCommand)({
+    name: 'run',
+    category: 'core',
+    description: 'Run a multi-step flow script (default-exports an async function receiving the API object)',
+    args: z.object({
+        file: z.string().describe('flow script path (.js / .mjs / .cjs)'),
+    }),
+    options: z.object({
+        timeout: numberArg.optional().describe('whole-script timeout in ms (default 300000, 0 = unlimited)'),
+    }),
+});
 // ── state management ──
 const stateImport = (0, command_1.declareCommand)({
     name: 'state-import',
@@ -247,6 +316,30 @@ const skillUninstall = (0, command_1.declareCommand)({
         path: z.string().optional().describe('custom base directory'),
     }),
 });
+// ── mcp ──
+const mcp = (0, command_1.declareCommand)({
+    name: 'mcp',
+    category: 'core',
+    description: 'Start MCP server (stdio transport) for AI clients',
+});
+const mcpInstall = (0, command_1.declareCommand)({
+    name: 'mcp-install',
+    category: 'core',
+    description: 'Install MCP server config into AI client configs',
+    options: z.object({
+        target: z.string().optional().describe('client target: auto, all, none, claude, cursor, codex, opencode, hermes, gemini (default: auto)'),
+        local: z.boolean().optional().describe('write project-local config instead of global'),
+    }),
+});
+const mcpUninstall = (0, command_1.declareCommand)({
+    name: 'mcp-uninstall',
+    category: 'core',
+    description: 'Remove MCP server config from AI client configs',
+    options: z.object({
+        target: z.string().optional().describe('client target: auto, all, none, claude, cursor, codex, opencode, hermes, gemini (default: auto)'),
+        local: z.boolean().optional().describe('remove project-local config instead of global'),
+    }),
+});
 // ── export ──
 const commandsArray = [
     // session management
@@ -255,12 +348,16 @@ const commandsArray = [
     inspect, tree, layout, findings, injectCss,
     // browser
     resize, evalCmd, playwrightCmd, screenshot,
+    // interaction
+    click, hover, typeCmd, waitForCmd, runCmd,
     // state
     stateImport, stateSave,
     // config
     configShow, configSet, configList, configUse, configNew, configPath,
     // skill
     skillInstall, skillUninstall,
+    // mcp
+    mcp, mcpInstall, mcpUninstall,
 ];
 exports.commands = Object.fromEntries(commandsArray.map(cmd => [cmd.name, cmd]));
 exports.inspectCommand = inspect;