ptywright 0.1.0 → 0.2.0

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.
 

package/bin/ptywright

@@ -1,4 +0,0 @@
-#!/usr/bin/env bun
-import { main } from "../src/cli";
-
-await main();

package/src/cli.ts

@@ -1,414 +0,0 @@
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-import type { PtywrightCapability } from "./mcp/server";
-import { createPtywrightServer } from "./mcp/server";
-import { startPtywrightHttpServer } from "./mcp/http_server";
-import { runAllScripts } from "./script/run_all";
-import { runScriptPath } from "./script/path";
-
-function usage(): string {
-  return [
-    "ptywright <command>",
-    "",
-    "Commands:",
-    "  mcp                 Start the MCP server over stdio (default)",
-    "  mcp-http            Start the MCP server over Streamable HTTP",
-    "  run <file>           Run one script (JSON/TS) and write artifacts",
-    "  run-all [dir]        Run all scripts in a directory and write a suite report",
-    "  help                Show help",
-    "",
-    "Run options:",
-    "  --artifacts-dir <dir>    Override artifacts directory",
-    "  --steps <module.ts>      Inject custom step handlers",
-    "  --update-goldens         Update golden snapshots",
-    "",
-    "Run-all options:",
-    "  --dir <dir>              Directory to scan (default: scripts)",
-    "  --artifacts-root <dir>   Suite artifacts root (default: .tmp/run-all)",
-    "  --steps <module.ts>      Inject custom step handlers",
-    "  --update-goldens         Update golden snapshots",
-    "",
-    "MCP options:",
-    "  --caps <list>            Capabilities: all|core|debug|script|recording",
-    "",
-    "MCP HTTP options (mcp-http):",
-    "  --host <host>            Bind host (default: 127.0.0.1)",
-    "  --port <port>            Bind port (default: 3000)",
-    "  --allowed-origins <list> Comma/space separated Origin allowlist",
-    "  --no-cors                Disable CORS headers",
-  ].join("\n");
-}
-
-function isHelp(arg: string | undefined): boolean {
-  return arg === "-h" || arg === "--help" || arg === "help";
-}
-
-function logLines(lines: Array<string | null | undefined>, stderr: boolean): void {
-  const filtered = lines.map((l) => l?.trim()).filter(Boolean) as string[];
-  for (const line of filtered) {
-    // eslint-disable-next-line no-console
-    (stderr ? console.error : console.log)(line);
-  }
-}
-
-function parseCaps(value: string): PtywrightCapability[] {
-  const parts = value
-    .split(/[\s,]+/g)
-    .map((p) => p.trim().toLowerCase())
-    .filter(Boolean);
-
-  const out: PtywrightCapability[] = [];
-  for (const p of parts) {
-    if (p === "all") out.push("all");
-    else if (p === "core") out.push("core");
-    else if (p === "debug") out.push("debug");
-    else if (p === "script" || p === "scripts" || p === "runner" || p === "run") out.push("script");
-    else if (p === "recording" || p === "record" || p === "rec") out.push("recording");
-    else throw new Error(`unknown capability: ${p}`);
-  }
-  return out;
-}
-
-function parseRunArgs(argv: string[]): {
-  scriptPath: string;
-  artifactsDir?: string;
-  stepsPath?: string;
-  updateGoldens: boolean;
-} {
-  const out: {
-    scriptPath?: string;
-    artifactsDir?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  } = { updateGoldens: false };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    if (!out.scriptPath && arg && !arg.startsWith("-")) {
-      out.scriptPath = arg;
-      continue;
-    }
-
-    if (arg === "--artifacts-dir" && next) {
-      out.artifactsDir = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--steps" && next) {
-      out.stepsPath = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--update-goldens") {
-      out.updateGoldens = true;
-      continue;
-    }
-
-    throw new Error(`unknown arg: ${arg ?? ""}`);
-  }
-
-  if (!out.scriptPath) {
-    throw new Error("missing <file>\n\n" + usage());
-  }
-
-  return out as {
-    scriptPath: string;
-    artifactsDir?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  };
-}
-
-function parseRunAllArgs(argv: string[]): {
-  dir?: string;
-  artifactsRoot?: string;
-  stepsPath?: string;
-  updateGoldens: boolean;
-} {
-  const out: {
-    dir?: string;
-    artifactsRoot?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  } = { updateGoldens: false };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    if (!out.dir && arg && !arg.startsWith("-")) {
-      out.dir = arg;
-      continue;
-    }
-
-    if (arg === "--dir" && next) {
-      out.dir = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--artifacts-root" && next) {
-      out.artifactsRoot = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--steps" && next) {
-      out.stepsPath = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--update-goldens") {
-      out.updateGoldens = true;
-      continue;
-    }
-
-    throw new Error(`unknown arg: ${arg ?? ""}`);
-  }
-
-  return out as {
-    dir?: string;
-    artifactsRoot?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  };
-}
-
-async function cmdMcp(argv: string[]): Promise<void> {
-  let capabilities: PtywrightCapability[] | undefined;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    if (isHelp(arg)) {
-      // eslint-disable-next-line no-console
-      console.log(usage());
-      return;
-    }
-
-    if (arg === "--caps" && next) {
-      capabilities = parseCaps(next);
-      i += 1;
-      continue;
-    }
-
-    throw new Error(`unknown arg: ${arg ?? ""}`);
-  }
-
-  const { server, sessions } = createPtywrightServer({ capabilities });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-
-  function shutdown(): void {
-    sessions.closeAll();
-    void server.close();
-  }
-
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-}
-
-async function cmdMcpHttp(argv: string[]): Promise<void> {
-  let capabilities: PtywrightCapability[] | undefined;
-  let hostname: string | undefined;
-  let port: number | undefined;
-  let allowedOrigins: string[] | undefined;
-  let cors = true;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    if (isHelp(arg)) {
-      // eslint-disable-next-line no-console
-      console.log(usage());
-      return;
-    }
-
-    if (arg === "--caps" && next) {
-      capabilities = parseCaps(next);
-      i += 1;
-      continue;
-    }
-
-    if ((arg === "--host" || arg === "--hostname") && next) {
-      hostname = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--port" && next) {
-      const value = Number.parseInt(next, 10);
-      if (!Number.isFinite(value) || value < 0) {
-        throw new Error(`invalid --port: ${next}`);
-      }
-      port = value;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--allowed-origins" && next) {
-      allowedOrigins = next
-        .split(/[\s,]+/g)
-        .map((v) => v.trim())
-        .filter(Boolean);
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--no-cors") {
-      cors = false;
-      continue;
-    }
-
-    throw new Error(`unknown arg: ${arg ?? ""}`);
-  }
-
-  const handle = await startPtywrightHttpServer({
-    hostname,
-    port,
-    capabilities,
-    allowedOrigins,
-    cors,
-  });
-
-  // eslint-disable-next-line no-console
-  console.log(`listening ${handle.url}`);
-  // eslint-disable-next-line no-console
-  console.log(`health http://${handle.hostname}:${handle.port}/health`);
-
-  function shutdown(): void {
-    void handle.close();
-  }
-
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-}
-
-async function cmdRun(argv: string[]): Promise<number> {
-  const args = parseRunArgs(argv);
-  const result = await runScriptPath(args.scriptPath, {
-    artifactsDir: args.artifactsDir,
-    updateGoldens: args.updateGoldens,
-    stepsPath: args.stepsPath,
-  });
-
-  if (!result.ok) {
-    logLines(
-      [
-        result.error,
-        result.artifactsDir ? `artifacts=${result.artifactsDir}` : null,
-        result.reportPath ? `report=${result.reportPath}` : null,
-        result.castPath ? `cast=${result.castPath}` : null,
-        result.failureArtifacts?.lastViewPath
-          ? `last=${result.failureArtifacts.lastViewPath}`
-          : null,
-        result.failureArtifacts?.errorPath ? `error=${result.failureArtifacts.errorPath}` : null,
-      ],
-      true,
-    );
-    return 1;
-  }
-
-  logLines(
-    [
-      `ok artifacts=${result.artifactsDir}`,
-      result.reportPath ? `report=${result.reportPath}` : null,
-      result.castPath ? `cast=${result.castPath}` : null,
-    ],
-    false,
-  );
-  return 0;
-}
-
-async function cmdRunAll(argv: string[]): Promise<number> {
-  const args = parseRunAllArgs(argv);
-  const result = await runAllScripts({
-    dir: args.dir,
-    artifactsRoot: args.artifactsRoot,
-    stepsPath: args.stepsPath,
-    updateGoldens: args.updateGoldens,
-  });
-
-  const failures = result.entries.filter((e) => !e.result.ok);
-
-  if (failures.length === 0) {
-    // eslint-disable-next-line no-console
-    console.log(
-      `ok count=${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`,
-    );
-    return 0;
-  }
-
-  // eslint-disable-next-line no-console
-  console.error(
-    `failed count=${failures.length}/${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`,
-  );
-  for (const f of failures) {
-    if (f.result.ok) continue;
-    // eslint-disable-next-line no-console
-    console.error(`- ${f.filePath}: ${f.result.error}`);
-    if (f.result.failureArtifacts) {
-      // eslint-disable-next-line no-console
-      console.error(`  artifacts=${f.result.artifactsDir ?? ""}`);
-      // eslint-disable-next-line no-console
-      console.error(`  last=${f.result.failureArtifacts.lastViewPath}`);
-      // eslint-disable-next-line no-console
-      console.error(`  error=${f.result.failureArtifacts.errorPath}`);
-    }
-  }
-  return 1;
-}
-
-export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
-  const [command, ...rest] = argv;
-
-  if (!command) {
-    await cmdMcp([]);
-    return;
-  }
-
-  if (isHelp(command)) {
-    // eslint-disable-next-line no-console
-    console.log(usage());
-    return;
-  }
-
-  if (command === "mcp") {
-    await cmdMcp(rest);
-    return;
-  }
-
-  if (command === "mcp-http") {
-    await cmdMcpHttp(rest);
-    return;
-  }
-
-  if (command === "run") {
-    process.exitCode = await cmdRun(rest);
-    return;
-  }
-
-  if (command === "run-all") {
-    process.exitCode = await cmdRunAll(rest);
-    return;
-  }
-
-  throw new Error(`unknown command: ${command}\n\n` + usage());
-}
-
-if (import.meta.main) {
-  try {
-    await main();
-  } catch (error) {
-    // eslint-disable-next-line no-console
-    console.error((error as Error).message);
-    process.exitCode = 1;
-  }
-}