ptywright 0.3.0 → 0.5.0

package/README.md

@@ -315,64 +315,71 @@ expose the terminal root as `[data-terminal-root]`.
 
 ```bash
 # First run records snapshots, screenshots, replay metadata, and report.
-bun run bin/ptywright agent run examples/agent_deterministic.json --update-snapshots
+bun run src/cli.ts agent run examples/agent_deterministic.json --update-snapshots
 
 # Later runs compare terminal + DOM snapshots like a test snapshot.
-bun run bin/ptywright agent run examples/agent_deterministic.json
+bun run src/cli.ts agent run examples/agent_deterministic.json
 
 # Replay does not need AI; it uses the recorded flow artifact.
-bun run bin/ptywright agent replay .tmp/agent/agent_deterministic/agent_deterministic.agent-run.json
+bun run src/cli.ts agent replay .tmp/agent/agent_deterministic/agent_deterministic.agent-run.json
 
 # Cassette files are also directly replayable.
-bun run bin/ptywright agent replay .tmp/agent/agent_deterministic/agent_deterministic.cassette.json
+bun run src/cli.ts agent replay .tmp/agent/agent_deterministic/agent_deterministic.cassette.json
 
 # Promote a live run/cassette into the committed non-AI regression suite.
-bun run bin/ptywright agent promote \
+bun run src/cli.ts agent promote \
   .tmp/agent/agent_deterministic/agent_deterministic.cassette.json \
   --update-snapshots
 
 # Batch replay committed cassettes/run records as a regression suite.
-bun run bin/ptywright agent replay-all .tmp/agent --artifacts-root .tmp/agent-replay-all
+bun run src/cli.ts agent replay-all .tmp/agent --artifacts-root .tmp/agent-replay-all
 
 # Rerun directly from a generated summary artifact.
-bun run bin/ptywright agent rerun .tmp/agent-promote/agent_deterministic/agent-promote.summary.json
-bun run bin/ptywright agent rerun .tmp/agent-check/agent-check.summary.json
-bun run bin/ptywright agent rerun .tmp/agent-check/agent-replay.summary.json --update-snapshots
+bun run src/cli.ts agent rerun .tmp/agent-promote/agent_deterministic/agent-promote.summary.json
+bun run src/cli.ts agent rerun .tmp/agent-check/agent-check.summary.json
+bun run src/cli.ts agent rerun .tmp/agent-check/agent-replay.summary.json --update-snapshots
 
 # Read reusable commands from any supported agent artifact.
-bun run bin/ptywright agent commands .tmp/agent-check/agent-check.summary.json --json
-bun run bin/ptywright agent commands .tmp/agent-check/agent-check.summary.json --command rerun
-bun run bin/ptywright agent commands .tmp/agent-check --json
-bun run bin/ptywright agent inspect .tmp/agent-check
-bun run bin/ptywright agent inspect .tmp/agent-check --json
-bun run bin/ptywright agent validate .tmp/agent-check
-bun run bin/ptywright agent exec .tmp/agent-check --command rerun
-bun run bin/ptywright agent exec .tmp/agent-check --command updateSnapshots
-bun run bin/ptywright agent exec .tmp/agent-check/agent-check.summary.json --command rerun
-bun run bin/ptywright agent exec .tmp/agent-check/agent-check.summary.json --command updateSnapshots
+bun run src/cli.ts agent commands .tmp/agent-check/agent-check.summary.json --json
+bun run src/cli.ts agent commands .tmp/agent-check/agent-check.summary.json --command rerun
+bun run src/cli.ts agent commands .tmp/agent-check --json
+bun run src/cli.ts agent inspect .tmp/agent-check
+bun run src/cli.ts agent inspect .tmp/agent-check --json
+bun run src/cli.ts agent validate .tmp/agent-check
+bun run src/cli.ts agent exec .tmp/agent-check --command rerun
+bun run src/cli.ts agent exec .tmp/agent-check --command updateSnapshots
+bun run src/cli.ts agent exec .tmp/agent-check/agent-check.summary.json --command rerun
+bun run src/cli.ts agent exec .tmp/agent-check/agent-check.summary.json --command updateSnapshots
 
 # Validate flow/cassette/run-record/summary artifacts before committing.
-bun run bin/ptywright agent validate .tmp/agent-replay-all
+bun run src/cli.ts agent validate .tmp/agent-replay-all
 
 # Run committed cassette replay regression without launching live agents.
-bun run bin/ptywright agent check
-bun run bin/ptywright agent check --json
+bun run src/cli.ts agent check
+bun run src/cli.ts agent check --json
 
 # Update terminal/DOM baselines from committed cassettes intentionally.
-bun run bin/ptywright agent replay-all tests/agent-cassettes --update-snapshots
+bun run src/cli.ts agent replay-all tests/agent-cassettes --update-snapshots
 
 # Record browser interactions into a replayable flow spec.
-bun run bin/ptywright agent record examples/agents/codex_browser_smoke.json \
+bun run src/cli.ts agent record examples/agents/codex_browser_smoke.json \
   --out scripts/agents/codex_recorded.flow.json \
   --duration-ms 60000 \
   --headed
 
 # Generate starter specs for real agents.
-bun run bin/ptywright agent init codex examples/agents/codex_browser_smoke.json
-bun run bin/ptywright agent init claude examples/agents/claude_browser_smoke.json
-bun run bin/ptywright agent init droidx examples/agents/droidx_browser_smoke.json
+bun run src/cli.ts agent init codex examples/agents/codex_browser_smoke.json
+bun run src/cli.ts agent init claude examples/agents/claude_browser_smoke.json
+bun run src/cli.ts agent init droidx examples/agents/droidx_browser_smoke.json
 ```
 
+DOM artifact viewers use `@aitty/snapshot` as the report renderer. ptywright
+copies `@aitty/snapshot/style.css` and the classic
+`@aitty/snapshot/web-component.global.js` bundle into the report artifacts, then
+renders snapshots through `<aitty-snapshot>`. Terminal internals such as wterm
+rows, ANSI styling, termvision, and viewport-pan come from `@aitty/snapshot`;
+ptywright only supplies the report frame and copied assets.
+
 Artifacts are split intentionally:
 - `.tmp/agent/<name>/` contains run output, screenshots, `*.flow.json`,
   `*.agent-run.json`, `*.cassette.json`, `index.html`, and
@@ -380,6 +387,44 @@ Artifacts are split intentionally:
 - `tests/agent-snapshots/<name>/` contains stable terminal/DOM baselines.
 - `--update-snapshots` is the explicit update path for intentional UI changes.
 
+### Project Config
+
+For repeated agent regression work, put project-level defaults in
+`ptywright.config.ts` instead of repeating paths and browser defaults in every
+flow file. The CLI discovers `ptywright.config.ts|mts|cts|js|mjs|cjs` from the
+current directory upward, and `--config <file>` selects one explicitly.
+
+```ts
+import { defineConfig } from "ptywright/config";
+
+export default defineConfig({
+  agent: {
+    artifactsRoot: ".tmp/agent",
+    cassetteDir: "tests/agent-cassettes",
+    snapshotDir: "tests/agent-snapshots",
+    defaults: {
+      headless: true,
+      timeoutMs: 45_000,
+      screenshot: false,
+      viewports: [{ name: "desktop", width: 1280, height: 820 }],
+      mask: [{ regex: "session_[a-z0-9]+", replacement: "<session>" }],
+    },
+  },
+});
+```
+
+```bash
+ptywright agent run tests/agents/codex.flow.json --update-snapshots
+ptywright agent check
+ptywright agent replay-all --update-snapshots
+ptywright agent promote .tmp/agent/codex/codex.cassette.json --update-snapshots
+```
+
+Config paths are resolved relative to the config file directory. CLI arguments
+override config defaults, and fields written in a flow file override config
+defaults for that flow. The flow file remains the test case; the config file is
+only for shared project defaults and common artifact locations.
+
 `launch.mode=command` is the recommended integration contract. `command` and
 `args` are spawned directly, and ptywright reads the first URL printed to stdout
 or stderr. Use `waitForUrlMs` to tune startup timeouts and `urlRegex` when the
@@ -529,7 +574,7 @@ details.
 bun install
 
 # Start MCP server
-bun run bin/ptywright mcp
+bun run src/cli.ts mcp
 
 # Run tests
 bun run test
@@ -543,11 +588,11 @@ 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
+bun run src/cli.ts run scripts/m5_mask_demo.json
+bun run src/cli.ts run-all
 
 # Run browser agent regression
-bun run bin/ptywright agent run examples/agent_deterministic.json --update-snapshots
+bun run src/cli.ts agent run examples/agent_deterministic.json --update-snapshots
 ```
 
 ## Environment Variables

package/dist/agent.mjs

@@ -1,2 +1,2 @@
-import { a as runAgentSpecPath, i as runAgentSpec, n as printAgentLaunchPlan, r as replayAgentRecordPath, t as defaultSpecNameForPath } from "./runner-zi0nItvB.mjs";
-export { defaultSpecNameForPath, printAgentLaunchPlan, replayAgentRecordPath, runAgentSpec, runAgentSpecPath };
+import { a as formatAgentLaunchPlan, i as runAgentSpecPath, n as replayAgentRecordPath, r as runAgentSpec, t as defaultSpecNameForPath } from "./runner-C1gPRyCM.mjs";
+export { defaultSpecNameForPath, formatAgentLaunchPlan, replayAgentRecordPath, runAgentSpec, runAgentSpecPath };

package/dist/bin/ptywright.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { t as main } from "../cli-CfvlbRoZ.mjs";
+import { t as main } from "../cli-PnG6UR43.mjs";
 //#region src/bin/ptywright.ts
 await main();
 //#endregion