ptywright 0.1.0 → 0.1.1

package/README.md

@@ -1,188 +1,245 @@
 # ptywright
 
-一个通用的“终端版 DevTools / Playwright driver”原型：通过 PTY 启动任意 CLI/TUI，把 ANSI/VT 输出喂给 `@xterm/headless` 重建屏幕网格，并以 MCP（stdio）暴露工具接口。
+[中文文档](./README_ZH.md)
 
-## Run
+A universal "Terminal DevTools / Playwright driver": Launch any CLI/TUI via PTY, feed ANSI/VT output to `@xterm/headless` to rebuild the screen grid, and expose it as MCP (stdio) tools.
+
+## Installation
 
 ```bash
-bun install
+# Recommended: Run with bunx (no install needed)
+bunx ptywright@latest --help
 
-# 默认：启动 MCP server（等价 `ptywright mcp`）
-bun run bin/ptywright
+# Or install globally
+bun add -g ptywright
+ptywright --help
+
+# Or via npm/npx
+npx -y ptywright@latest --help
+npm install -g ptywright
+```
 
-# 显式写法：
-# bun run bin/ptywright mcp
+## Quick Start
+
+### Use as MCP Server
+
+```bash
+# stdio mode (default)
+bunx ptywright@latest mcp
 
-# 可选：以 Streamable HTTP 方式启动（Web transport）
-# bun run bin/ptywright mcp-http --port 3000
+# HTTP mode
+bunx ptywright@latest mcp-http --port 3000
 
-# 可选：减少 tool 数量（降低 Agent 上下文压力）
-# bun run bin/ptywright mcp --caps core
-# 或：PTYWRIGHT_CAPS=core bun run bin/ptywright
+# Minimal tools (reduce Agent context pressure)
+bunx ptywright@latest mcp --caps core
 ```
 
-## Tools (MVP)
+### Configure MCP Client
 
-工具默认全量开启（等价 `PTYWRIGHT_CAPS=all`）。如需减少 tool 数量，可设置 `PTYWRIGHT_CAPS=core` 或按需组合：
+**Claude Desktop / Cursor** (`~/.config/claude/claude_desktop_config.json`):
 
-- 默认：`PTYWRIGHT_CAPS=all`
-- 最小：`PTYWRIGHT_CAPS=core`
-- 组合：`PTYWRIGHT_CAPS=core,debug,script,recording`
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp"]
+    }
+  }
+}
+```
 
-### core
+**Minimal mode** (load core tools only):
 
-- `list_sessions` / `select_session`：管理与选择会话
-- `launch_session`：启动 PTY 会话（会自动成为默认会话）
-- `send_text` / `press_key`：发送输入
-- `snapshot_text`：返回可见屏幕文本（适合 Agent “看界面”与做 golden）
-- `snapshot_view`：更适合人看的快照（带元信息+行号）
-- `wait_for_text`：等待文本/正则出现
-- `wait_for_stable_screen`：等待屏幕在 quiet window 内稳定（降低 flaky）
-- `assert`：对当前屏幕做断言（text/regex/semantic）
-- `close_session`：关闭会话
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp", "--caps", "core"]
+    }
+  }
+}
+```
 
-### debug（可选）
+**HTTP mode** (for Web clients):
 
-- `snapshot_ansi`：返回带 ANSI/SGR 样式的可见屏幕（适合 debug/人眼验收）
-- `snapshot_view_ansi`：带 ANSI/SGR 样式的 `snapshot_view`
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp-http", "--port", "3000"]
+    }
+  }
+}
+```
 
-### script（可选）
+### CLI Commands
 
-- `run_routine`：一键执行多步交互（type/key/wait/assert/snapshot）
-- `run_script`：运行 `scriptPath=file.json|file.ts` 并产出 artifacts（cast/report/失败快照）
-- `run_all_scripts`：批量运行目录内脚本（递归；支持 `includeEntries/maxEntries` 控制输出）
-- `generate_test_from_doc`：从文档（本地/URL）生成可执行脚本
-- `inspect_failure`：查看最近一次失败的屏幕与错误
+```bash
+# Run a single test script
+bunx ptywright@latest run scripts/demo.json
 
-### recording（可选）
+# Run all scripts (generate HTML report)
+bunx ptywright@latest run-all --dir scripts
 
-- `start_script_recording` / `stop_script_recording`：录制 MCP 工具调用并导出可复跑脚本（JSON + goldens）
-- `mark`：在 trace 中打点（asciicast marker event）
+# Show help
+bunx ptywright@latest --help
+```
 
-`mask`（可选）：`snapshot_text/snapshot_ansi/snapshot_view/snapshot_view_ansi` 支持 `mask=[{regex,flags?,replacement?,preserveLength?}]`，用于把随机 id/时间戳等变成可 diff 的稳定快照
+## Tools
 
-### `press_key` Key Spec
+All tools are enabled by default (`--caps all`). Use `--caps core` or combine as needed:
 
-支持单键与“修饰键 + 单键”的组合写法（大小写不敏感，`+`/`-` 都可作为分隔符）：
-- 单字符：`"a"` / `"?"`（原样写入 PTY）
-- 特殊键：`Enter|Return`、`Esc|Escape`、`Backspace`、`Space`、`Tab`、`BackTab`
-- 组合键：`Ctrl+C`、`Ctrl+Shift+R`、`Alt+X`/`Meta+X`、`Shift+Tab`、`Ctrl+Up`
-- 导航键：`Up/Down/Left/Right`、`Home/End`、`PageUp/PageDown`、`Insert/Delete`、`F1..F12`
-- 兼容：`c-x`（等价 `Ctrl+X`）
+- Default: `--caps all`
+- Minimal: `--caps core`
+- Combined: `--caps core,debug,script,recording`
 
-## Tests
+### core
 
-```bash
-bun test
-```
+- `list_sessions` / `select_session`: Manage and select sessions
+- `launch_session`: Start a PTY session (becomes default session)
+- `send_text` / `press_key`: Send input
+- `snapshot_text`: Return visible screen text (for Agent "seeing" and golden snapshots)
+- `snapshot_view`: Human-friendly snapshot (with metadata + line numbers)
+- `wait_for_text`: Wait for text/regex to appear
+- `wait_for_stable_screen`: Wait for screen to stabilize within quiet window (reduce flaky)
+- `assert`: Assert on current screen (text/regex/semantic)
+- `close_session`: Close session
 
-包含：
-- PTY + xterm 解析与快照测试
-- MCP server 端到端 smoke（client 通过 stdio 启动 server 并调用 tools）
+### debug (optional)
 
-## Use With MCP Clients（可选）
+- `snapshot_ansi`: Return visible screen with ANSI/SGR styles (for debug/human review)
+- `snapshot_view_ansi`: `snapshot_view` with ANSI/SGR styles
 
-本仓库也提供了一个可选的 Codex skill：`skills/ptywright-testing/`，用于指导 Agent 如何用 ptywright MCP/CLI 跑回归并读取 `run.summary.json`（尽量不把超长报告塞进上下文）。
+### script (optional)
 
-本项目是一个 stdio transport 的 MCP server。直接启动：
+- `run_routine`: Execute multi-step interactions in one call (type/key/wait/assert/snapshot)
+- `run_script`: Run `scriptPath=file.json|file.ts` and produce artifacts (cast/report/failure snapshots)
+- `run_all_scripts`: Run scripts in directory recursively (supports `includeEntries/maxEntries`)
+- `generate_test_from_doc`: Generate executable scripts from documentation (local/URL)
+- `inspect_failure`: View last failure screen and error
 
-```bash
-# 默认等价 `ptywright mcp`
-bun run bin/ptywright
-```
+### recording (optional)
 
-也可以用 Streamable HTTP 启动（默认 endpoint: `http://127.0.0.1:3000/mcp`）：
+- `start_script_recording` / `stop_script_recording`: Record MCP tool calls and export replayable scripts (JSON + goldens)
+- `mark`: Add marker to trace (asciicast marker event)
 
-```bash
-bun run bin/ptywright mcp-http --port 3000
-```
+### `mask` Parameter
 
-然后在你使用的 MCP client 里把它作为一个 stdio server 配置进去即可（不同 client 的配置方式不同）。
+`snapshot_text/snapshot_ansi/snapshot_view/snapshot_view_ansi` support `mask=[{regex,flags?,replacement?,preserveLength?}]` to convert random IDs/timestamps into diffable stable snapshots.
+
+### `press_key` Key Spec
+
+Supports single keys and modifier combinations (case-insensitive, `+`/`-` as separator):
+- Single char: `"a"` / `"?"` (written to PTY as-is)
+- Special keys: `Enter|Return`, `Esc|Escape`, `Backspace`, `Space`, `Tab`, `BackTab`
+- Combos: `Ctrl+C`, `Ctrl+Shift+R`, `Alt+X`/`Meta+X`, `Shift+Tab`, `Ctrl+Up`
+- Navigation: `Up/Down/Left/Right`, `Home/End`, `PageUp/PageDown`, `Insert/Delete`, `F1..F12`
+- Compatible: `c-x` (equals `Ctrl+X`)
 
 ## Script Runner (JSON)
 
-把一次 TUI 测试写成 JSON：启动 → 输入 → 等待 → 快照（可 mask）→ 断言，并自动产出 `.cast` + `report.html`。
+Write TUI tests as JSON: launch → input → wait → snapshot (with mask) → assert, automatically producing `.cast` + `report.html`.
 
-可选：在 JSON 顶部加上 schema（编辑器补全/校验更友好）：
+Optional: Add schema for editor completion/validation:
 
 ```json
-{ "$schema": "../schemas/ptywright-script.schema.json" }
+{ "$schema": "node_modules/ptywright/schemas/ptywright-script.schema.json" }
 ```
 
 ```bash
-bun run script:run scripts/m5_mask_demo.json
-# 或（CLI）
-bun run bin/ptywright run scripts/m5_mask_demo.json
-# 或
-bun run script:m5-mask-demo
+# Run single script
+bunx ptywright@latest run scripts/m5_mask_demo.json
+
+# Run all scripts
+bunx ptywright@latest run-all --dir scripts
 ```
 
-批量执行（本地/CI）：
+Artifacts go to `.tmp/runs/<name>/` by default (override with `--artifacts-dir`).
 
-```bash
-bun run script:run-all
-# 或（CLI）
-bun run bin/ptywright run-all
-```
+Batch runs generate an overview report:
+- Default: `.tmp/run-all/index.html` + `.tmp/run-all/run.summary.json`
+- With `--artifacts-root <dir>`: `<dir>/index.html` + `<dir>/run.summary.json`
 
-会生成一个总览报告（类似 Playwright report 首页）：
-- 默认：`.tmp/run-all/index.html` + `.tmp/run-all/run.summary.json`
-- 若传入 `--artifacts-root <dir>`：写到 `<dir>/index.html` + `<dir>/run.summary.json`
+On failure, additional files are saved:
+- `failure.error.txt` (error stack)
+- `failure.step.json` (failed step info)
+- `failure.last.txt` / `failure.last.view.txt` (last frame snapshot)
 
-如果 JSON 里用到了 `type:"custom"`，用 `--steps <module.ts>` 注入 handlers（模块导出 `steps` 对象即可）：
+`report.html` includes **Timeline View** showing screen snapshots after each step. Click the `debug` badge to switch to debug view.
+
+Built-in steps (no `--steps` needed):
+- `assert`: Assert text/regex (`text`/`regex`)
+- `assertSemantic`: Semantic assertion placeholder (`prompt`)
+- `sleep`: Fixed wait
+- `expectMeta`: Assert terminal meta
+- `waitForExit`: Wait for process exit
+- `sendMouse`: Send SGR mouse events
+
+For `type:"custom"` steps, inject handlers with `--steps <module.ts>`:
 
 ```bash
-bun run script:run examples/json_custom_steps_demo.json --steps scripts/m6_json_custom_steps.ts
+bunx ptywright@latest run demo.json --steps custom_steps.ts
 ```
 
-产物默认写到 `.tmp/runs/<name>/`（可用 `--artifacts-dir` 覆盖）。
+## Script Recording (MCP)
 
-失败时会额外落盘：
-- `failure.error.txt`（错误堆栈）
-- `failure.step.json`（失败的 step 信息）
-- `failure.last.txt` / `failure.last.view.txt`（最后一帧快照）
+Record tool calls into replayable scripts from any MCP client/Agent:
 
-`report.html` 现在包含 **Timeline View**，展示每一步操作后的屏幕快照（不仅是失败时）。点击顶部 `debug` badge 可切换到调试视图。
+1) `start_script_recording(name="my_flow")`
+2) Execute normally: `launch_session/send_text/press_key/wait_for_*`
+3) Add checkpoints: `mark(label="checkpoint")` (auto-generates `snapshot + expectGolden`)
+4) `stop_script_recording(recordingId=...)` (writes `scripts/my_flow.json` + `tests/golden/scripts/my_flow/*.txt`)
 
-Cast Playback（完整录屏）会优先加载 report 同目录的 `asciinema-player.min.js` / `asciinema-player.css`（生成 report 时自动复制），因此离线打开 report 也可播放；若本地资源缺失则会 fallback 到 CDN。
+## Script DSL (TypeScript)
 
-内置 steps（无需 `--steps`）：
-- `assert`：**[NEW]** 断言文本/正则（`text`/`regex`）
-- `assertSemantic`：**[NEW]** 语义断言占位符（`prompt`）
-- `sleep`：固定等待
-- `expectMeta`：断言终端 meta
-- `waitForExit`：等待进程退出
-- `sendMouse`：发送 SGR 鼠标事件
+Write scripts with TS builder (type-safe, composable, custom steps):
 
-## Script Recording (MCP)
+```bash
+bunx ptywright@latest run scripts/demo.ts
+```
 
-如果你设置了 `PTYWRIGHT_CAPS` 且未包含 `recording`，需要开启 `recording`（例如 `PTYWRIGHT_CAPS=core,recording`）。
+Conventions:
+- Module default export (`export default`), or export `script`.
+- Optional `steps` export (custom step handlers) for `type:"custom"` steps.
+- Use `pasteText("...", { bracketed: true })` for bracketed paste testing.
 
-在任意 MCP client/Agent 通过 MCP tools 驱动时，可以一键把工具调用“录成脚本”，并在 `mark` 处自动落盘 golden：
+## Cast -> SVG/GIF (Optional)
 
-1) `start_script_recording(name="my_flow")`
-2) 正常执行：`launch_session/send_text/press_key/wait_for_*`
-3) 关键节点打点：`mark(label="checkpoint")`（会自动生成 `snapshot + expectGolden`）
-4) `stop_script_recording(recordingId=...)`（写入 `scripts/my_flow.json` + `tests/golden/scripts/my_flow/*.txt`）
+Recording artifacts are best for failure diagnosis or manual review; prefer `snapshot_grid` diff for stable regression.
 
-## Script DSL (TypeScript)
+- SVG: `bunx svg-term --in <castPath> --out <outSvg>`
+- GIF: `agg --fps 30 <castPath> <outGif>` (requires [asciinema/agg](https://github.com/asciinema/agg))
 
-用 TS builder 写 script（类型安全，可组合，支持自定义 step），底层仍复用同一个 runner：
+## Development
 
 ```bash
-bun run script:run scripts/m6_dsl_demo.ts
+bun install
+
+# Start MCP server
+bun run bin/ptywright mcp
+
+# Run tests
+bun test
+
+# Lint & Format
+bun run lint
+bun run format:check
+
+# Run scripts
+bun run bin/ptywright run scripts/m5_mask_demo.json
+bun run bin/ptywright run-all
 ```
 
-约定：
-- module 默认导出（`export default`），或导出 `script`。
-- 可选导出 `steps`（custom step handlers），用于执行 `type:"custom"` 的步骤。
-- 常用 handlers 可复用：`src/script/steps/*`。
-- 需要测试“粘贴”时可用 `pasteText("...", { bracketed: true })`（bracketed paste）。
+## Environment Variables
 
-## Cast -> SVG/GIF (可选)
+- `TUI_TEST_PTY_BACKEND=auto|bun-terminal|bun-pty`
+  - default `auto`: macOS/Linux prefers `bun-terminal`, Windows uses `bun-pty`
+- `PTYWRIGHT_CAPS=all|core|debug|script|recording`
+  - Equivalent to `--caps` parameter
 
-录像类产物建议只用于失败诊断或人工验收；稳定回归优先用 `snapshot_grid` 做 diff。
+## License
 
-- SVG: `svg-term`（例如：`bunx svg-term --in <castPath> --out <outSvg>`）
-- TXT: `bun run src/trace/cast_to_txt.ts --in <castPath> --out <outTxt>`
-- GIF: `asciinema/agg`（例如：`agg --fps 30 <castPath> <outGif>`）
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ptywright",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Terminal/TUI automation driver over PTY + xterm, exposed as MCP tools",
   "keywords": [
     "agent",

package/skills/ptywright-testing/SKILL.md

@@ -3,20 +3,23 @@ name: ptywright-testing
 description: Terminal/TUI automation and regression testing using ptywright (PTY + xterm) via CLI or MCP tools. Use when you need to (1) drive a CLI/TUI app (send keys/mouse, wait, snapshot), (2) run scripted regressions (run/run-all) and review the HTML report (index.html + run.summary.json), or (3) record an interactive MCP-driven session into a replayable script with golden checkpoints.
 ---
 
-# Ptywright Testing / 使用指南
+# Ptywright Testing
 
-Use ptywright to run deterministic CLI/TUI regression tests with readable “terminal screenshots” and a Playwright-like HTML report.
+Use ptywright to run deterministic CLI/TUI regression tests with readable "terminal screenshots" and a Playwright-like HTML report.
 
-## How to run (发布版 vs 仓库内开发)
+## Installation & Usage
 
-This CLI is Bun-based (`#!/usr/bin/env bun`). For a released package, prefer `bunx`.
+```bash
+# 推荐：bunx 一次性运行
+bunx ptywright@latest <command>
 
-- **Published package (recommended):**
-  - one-off: `bunx ptywright@latest <command>`
-  - pinned: `bunx ptywright@0.1.0 <command>`
-  - global: `bun add -g ptywright` then `ptywright <command>`
-- **Inside this repo (dev):**
-  - `bun run bin/ptywright <command>`
+# 或全局安装
+bun add -g ptywright
+ptywright <command>
+
+# 本仓库内开发
+bun run bin/ptywright <command>
+```
 
 ## Choose the interface
 
@@ -25,42 +28,57 @@ This CLI is Bun-based (`#!/usr/bin/env bun`). For a released package, prefer `bu
 
 ## Start the MCP server
 
-- stdio (default):
-  - published: `bunx ptywright@latest mcp`
-  - repo: `bun run bin/ptywright mcp`
-- restrict tools to reduce context:
-  - published: `bunx ptywright@latest mcp --caps core`
-  - repo: `bun run bin/ptywright mcp --caps core` (or `PTYWRIGHT_CAPS=core`)
-- Streamable HTTP:
-  - published: `bunx ptywright@latest mcp-http --port 3000`
-  - repo: `bun run bin/ptywright mcp-http --port 3000`
+```bash
+# stdio (default)
+bunx ptywright@latest mcp
+
+# 精简 tools（降低上下文压力）
+bunx ptywright@latest mcp --caps core
+
+# HTTP 模式
+bunx ptywright@latest mcp-http --port 3000
+```
+
+Capabilities (`--caps`): `all|core|debug|script|recording` (comma separated)
 
-Capabilities (`--caps` / `PTYWRIGHT_CAPS`) match MCP tools:
+## Configure MCP Client
 
-- `all|core|debug|script|recording` (comma/space separated)
+**Claude Desktop / Cursor** (`~/.config/claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp"]
+    }
+  }
+}
+```
 
 ## Run scripts (deterministic regression)
 
 ### Run the whole suite (preferred)
 
-- CLI:
-  - published: `bunx ptywright@latest run-all --dir scripts`
-  - repo: `bun run bin/ptywright run-all --dir scripts`
-- Output to focus on:
-  - `reportPath` (open in a browser)
-  - `summaryPath` (`run.summary.json` for agents/CI)
+```bash
+bunx ptywright@latest run-all --dir scripts
+```
 
-MCP equivalent:
+Output to focus on:
+- `reportPath` (open in a browser)
+- `summaryPath` (`run.summary.json` for agents/CI)
 
+MCP equivalent:
 - `run_all_scripts` (defaults: `dir="scripts"`, suite report in `.tmp/run-all/`)
 - Keep MCP output small: `run_all_scripts(includeEntries="failures", maxEntries=20)`
 
 ### Run one script
 
-- CLI:
-  - published: `bunx ptywright@latest run <file.json|file.ts> [--artifacts-dir <dir>]`
-  - repo: `bun run bin/ptywright run <file.json|file.ts> [--artifacts-dir <dir>]`
-- MCP: `run_script(scriptPath=...)`
+```bash
+bunx ptywright@latest run <file.json|file.ts> [--artifacts-dir <dir>]
+```
+
+MCP: `run_script(scriptPath=...)`
 
 ## Debug a failure
 
@@ -85,7 +103,9 @@ Tip: for flaky waits, prefer `scope="buffer"` when the content may have scrolled
 
 To verify ptywright MCP tool coverage without relying on external apps/network, run:
 
-- `bun test tests/mcp_all_tools_smoke.test.ts`
+```bash
+bun test tests/mcp_all_tools_smoke.test.ts
+```
 
 This exercises `core + debug + script + recording` tools end-to-end.