ptywright 0.2.0 → 0.4.0

package/README.md

@@ -107,7 +107,7 @@ bunx ptywright@latest pty validate tests/cassettes/codex.pty.json
 bunx ptywright@latest pty inspect tests/cassettes/codex.pty.json
 ```
 
-External projects do not need to depend on aitty. Use the structural
+External projects do not need a ptywright-specific PTY wrapper. Use the structural
 `wrapPtyLike` API for `node-pty`/`bun-pty` style objects:
 
 ```ts
@@ -308,9 +308,10 @@ Recording artifacts are best for failure diagnosis or manual review; prefer `sna
 
 ## Browser Agent Regression
 
-The new destructive path is browser-first: ptywright can launch an agent through
-`@aitty/cli`, drive the browser-hosted wterm DOM with Playwright, and persist a
-replayable run artifact plus terminal/DOM snapshots.
+The browser-first path is integration-agnostic: ptywright launches any command
+that prints a browser URL, drives the terminal DOM with Playwright, and persists
+a replayable run artifact plus terminal/DOM snapshots. The browser page must
+expose the terminal root as `[data-terminal-root]`.
 
 ```bash
 # First run records snapshots, screenshots, replay metadata, and report.
@@ -379,9 +380,77 @@ Artifacts are split intentionally:
 - `tests/agent-snapshots/<name>/` contains stable terminal/DOM baselines.
 - `--update-snapshots` is the explicit update path for intentional UI changes.
 
-`launch.mode=aitty` runs `aitty exec --launch print -- <agent>`. By default
-ptywright resolves the sibling `../aitty/packages/cli/dist/cli.js`; set
-`PTYWRIGHT_AITTY_CLI` or `launch.aitty.command` to override it.
+### 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
+URL is embedded in structured output. Set `launch.agentFlavor` explicitly when
+the command is a wrapper, so mask presets still match the underlying agent.
+
+`launch.mode=url` skips process launch and points ptywright at an already
+running browser terminal.
+
+A wrapper integration is just a normal command that prints its browser URL:
+
+```json
+{
+  "name": "codex_browser_replay",
+  "launch": {
+    "mode": "command",
+    "agentFlavor": "codex",
+    "command": "node_modules/.bin/browser-terminal-launcher",
+    "args": [
+      "--replay",
+      "test/recordings/codex-yolo.pty.json",
+      "--speed",
+      "0",
+      "--print-url"
+    ],
+    "waitForUrlMs": 15000
+  },
+  "steps": [
+    { "type": "waitForStableDom" },
+    { "type": "snapshot", "name": "codex", "targets": ["terminal", "dom"] }
+  ]
+}
+```
 
 Set `launch.agentFlavor` to `codex`, `claude`, `droid`, or `generic` to opt
 into built-in mask presets for timestamps, generated ids, model names, token

package/dist/agent.mjs

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

package/dist/bin/ptywright.mjs

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

package/dist/{cli-DIUx2w6X.mjs → cli-C40H_ElC.mjs}

@@ -1,7 +1,8 @@
 import { c as createDefaultPtyAdapter, l as resolvePtyBackend } from "./runner-zApMYWZx.mjs";
-import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-VHuEWWj_.mjs";
-import { C as isAgentManifestLike, E as writeAgentManifestPath, S as agentManifestPath, T as validateAgentManifestFiles, _ as normalizeAgentFlowSpec, a as runAgentSpecPath, b as launchAittyBrowserSession, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as readAgentCassettePath, h as isAgentCassetteLike, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as sanitizeArtifactName, w as readAgentManifestPath, x as AGENT_MANIFEST_FILE_NAME, y as launchAgentBrowser } from "./runner-DzZlFrt1.mjs";
-import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-Cpkh_O9B.mjs";
+import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-h--2U0Ic.mjs";
+import { C as agentManifestPath, D as writeAgentManifestPath, E as validateAgentManifestFiles, S as AGENT_MANIFEST_FILE_NAME, T as readAgentManifestPath, _ as isAgentCassetteLike, a as runAgentSpecPath, b as sanitizeArtifactName, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as normalizeAgentFlowSpecWithConfig, h as resolveAgentLaunchTarget, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as readAgentCassettePath, w as isAgentManifestLike, x as launchAgentBrowser, y as normalizeAgentFlowSpec } from "./runner-CembqDgJ.mjs";
+import { n as loadPtywrightConfig } from "./config-B0r-JCFI.mjs";
+import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-DqCo7XdB.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -1901,7 +1902,7 @@ async function promoteAgentCassette(options) {
 	const sourceCassette = readAgentCassettePath(resolveSourceCassettePath(resolve(process.cwd(), options.sourcePath)));
 	const name = sanitizeArtifactName(sourceCassette.name);
 	const cassetteDir = options.cassetteDir ?? "tests/agent-cassettes";
-	const snapshotDir = options.snapshotDir ?? join("tests", "agent-snapshots", name);
+	const snapshotDir = options.snapshotDir ?? join(options.snapshotRoot ?? "tests/agent-snapshots", name);
 	const artifactsRoot = options.artifactsRoot ?? join(".tmp", "agent-promote", name);
 	const targetDir = join(cassetteDir, name);
 	const targetCassettePath = join(targetDir, `${name}.cassette.json`);
@@ -2130,18 +2131,16 @@ function emptyReplayResult(dir, suiteDir, updateSnapshots) {
 //#endregion
 //#region src/agent/recorder.ts
 async function recordAgentSpecPath(specPath, options) {
-	return recordAgentSpec((await loadAgentSpec(specPath)).spec, options);
+	return recordAgentSpec((await loadAgentSpec(specPath)).raw, options);
 }
 async function recordAgentSpec(input, options) {
-	const spec = normalizeAgentFlowSpec(input);
+	const spec = normalizeAgentFlowSpecWithConfig(input, options.config);
 	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
-	const launchMode = spec.launch.mode ?? (spec.launch.url ? "url" : "aitty");
 	const outPath = isAbsolute(options.outPath) ? options.outPath : resolve(process.cwd(), options.outPath);
 	const durationMs = options.durationMs ?? 3e4;
 	const steps = [];
 	let browser = null;
-	const session = launchMode === "aitty" ? await launchAittyBrowserSession(spec.launch, { rootDir }) : null;
-	const url = launchMode === "url" ? spec.launch.url : session.url;
+	const launchTarget = await resolveAgentLaunchTarget(spec.launch, { rootDir });
 	try {
 		browser = await launchAgentBrowser({ headless: options.headless ?? false });
 		const viewport = spec.viewports?.[0] ?? {
@@ -2160,7 +2159,7 @@ async function recordAgentSpec(input, options) {
 		});
 		const page = await context.newPage();
 		await installRecorderHooks(page);
-		await page.goto(url, {
+		await page.goto(launchTarget.url, {
 			waitUntil: "domcontentloaded",
 			timeout: spec.defaults?.timeoutMs ?? 3e4
 		});
@@ -2198,19 +2197,19 @@ async function recordAgentSpec(input, options) {
 			ok: true,
 			outPath,
 			stepCount: recorded.steps.length,
-			url
+			url: launchTarget.url
 		};
 	} catch (error) {
 		return {
 			ok: false,
 			outPath,
 			stepCount: steps.length,
-			url,
+			url: launchTarget.url,
 			error: error instanceof Error ? error.message : String(error)
 		};
 	} finally {
 		await browser?.close();
-		await session?.close();
+		await launchTarget.session?.close();
 	}
 }
 async function installRecorderHooks(page) {
@@ -2925,6 +2924,7 @@ function usage() {
 		"  --json                   Print machine-readable script artifact output",
 		"",
 		"Agent options:",
+		"  --config <file>          Use a ptywright.config.* file",
 		"  --artifacts-dir <dir>    Override agent run artifact directory",
 		"  --cassette-dir <dir>     Committed cassette directory for promote/check",
 		"  --snapshot-dir <dir>     Snapshot directory for promoted cassettes",
@@ -3266,6 +3266,12 @@ function parseAgentArgs(argv) {
 			out.flavor = parseAgentFlavor(arg);
 			continue;
 		}
+		if (arg === "--config") {
+			if (!next) throw new Error(`missing <file> for --config`);
+			out.configPath = next;
+			i += 1;
+			continue;
+		}
 		if (arg === "--artifacts-root" && next) {
 			out.artifactsRoot = next;
 			i += 1;
@@ -3336,13 +3342,32 @@ function parseAgentArgs(argv) {
 		outPath: out.outPath,
 		durationMs: out.durationMs,
 		commandName: out.commandName,
+		configPath: out.configPath,
 		updateSnapshots: out.updateSnapshots,
 		headed: out.headed,
 		json: out.json
 	};
 }
+function shouldLoadAgentConfig(mode) {
+	return mode === "run" || mode === "record" || mode === "replay" || mode === "promote" || mode === "replay-all" || mode === "rerun" || mode === "check";
+}
+function resolveAgentHeadless(args, config) {
+	if (args.headed) return false;
+	return config?.agent?.defaults?.headless ?? true;
+}
+function resolveAgentConfigPath(config, path) {
+	if (!path) return void 0;
+	if (isAbsolute(path)) return path;
+	return resolve(config?.rootDir ?? process.cwd(), path);
+}
+function resolveCliPath(path) {
+	if (!path) return void 0;
+	return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
 async function cmdAgent(argv) {
 	const args = parseAgentArgs(argv);
+	const config = shouldLoadAgentConfig(args.mode) ? await loadPtywrightConfig({ configPath: args.configPath }) : void 0;
+	const headless = resolveAgentHeadless(args, config);
 	if (args.mode === "init") {
 		const spec = createAgentTemplateSpec(args.flavor ?? "generic");
 		const path = args.path;
@@ -3358,7 +3383,8 @@ async function cmdAgent(argv) {
 		const result = await recordAgentSpecPath(args.path, {
 			outPath: args.outPath,
 			durationMs: args.durationMs,
-			headless: !args.headed
+			headless,
+			config
 		});
 		logLines([
 			`${result.ok ? "ok" : "failed"} record=${result.outPath}`,
@@ -3422,13 +3448,17 @@ async function cmdAgent(argv) {
 		const argv = selected.command.argv;
 		validateAgentCommandArgv(argv, selected.name);
 		const [, , subcommand, ...rest] = argv;
-		return cmdAgent([subcommand ?? "", ...rest]);
+		return cmdAgent([
+			subcommand ?? "",
+			...rest,
+			...args.configPath ? ["--config", args.configPath] : []
+		]);
 	}
 	if (args.mode === "check") {
 		const result = await checkAgentRegression({
-			cassetteDir: args.path ?? args.cassetteDir,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			cassetteDir: args.path ?? args.cassetteDir ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (args.json) logLines([JSON.stringify(formatAgentCheckJson(result), null, 2)], false);
@@ -3438,10 +3468,11 @@ async function cmdAgent(argv) {
 	if (args.mode === "promote") {
 		const result = await promoteAgentCassette({
 			sourcePath: args.path,
-			cassetteDir: args.cassetteDir,
+			cassetteDir: args.cassetteDir ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
 			snapshotDir: args.snapshotDir,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			snapshotRoot: args.snapshotDir ? void 0 : resolveAgentConfigPath(config, config?.agent?.snapshotDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (args.json) logLines([JSON.stringify(formatAgentPromoteSummary(result), null, 2)], false);
@@ -3451,8 +3482,8 @@ async function cmdAgent(argv) {
 	if (args.mode === "rerun") {
 		const rerun = await rerunAgentSummary({
 			path: args.path,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (rerun.kind === "check-summary") {
@@ -3482,9 +3513,9 @@ async function cmdAgent(argv) {
 	}
 	if (args.mode === "replay-all") {
 		const result = await replayAllAgentRecords({
-			dir: args.path,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			dir: args.path ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		const failures = result.entries.filter((entry) => !entry.result.ok);
@@ -3509,9 +3540,10 @@ async function cmdAgent(argv) {
 		return 1;
 	}
 	const options = {
-		artifactsDir: args.artifactsDir,
+		artifactsDir: resolveCliPath(args.artifactsDir),
 		updateSnapshots: args.updateSnapshots,
-		headless: !args.headed
+		headless,
+		config
 	};
 	const result = args.mode === "run" ? await runAgentSpecPath(args.path, options) : await replayAgentRecordPath(args.path, options);
 	if (args.json) {

package/dist/cli.mjs

@@ -1,2 +1,2 @@
-import { t as main } from "./cli-DIUx2w6X.mjs";
+import { t as main } from "./cli-C40H_ElC.mjs";
 export { main };

package/dist/config-B0r-JCFI.mjs

@@ -0,0 +1,52 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+//#region src/config.ts
+const CONFIG_FILE_NAMES = [
+	"ptywright.config.ts",
+	"ptywright.config.mts",
+	"ptywright.config.cts",
+	"ptywright.config.js",
+	"ptywright.config.mjs",
+	"ptywright.config.cjs"
+];
+function defineConfig(config) {
+	return config;
+}
+async function loadPtywrightConfig(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const configPath = resolveConfigPath({
+		cwd,
+		configPath: options.configPath
+	});
+	if (!configPath) return { rootDir: cwd };
+	const mod = await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`);
+	return {
+		...normalizePtywrightConfig(mod.default ?? mod.config, configPath),
+		configPath,
+		rootDir: dirname(configPath)
+	};
+}
+function resolveConfigPath(options) {
+	if (options.configPath) {
+		const explicitPath = isAbsolute(options.configPath) ? options.configPath : resolve(options.cwd, options.configPath);
+		if (!existsSync(explicitPath)) throw new Error(`ptywright config not found: ${options.configPath}`);
+		return explicitPath;
+	}
+	let current = options.cwd;
+	while (true) {
+		for (const fileName of CONFIG_FILE_NAMES) {
+			const candidate = resolve(current, fileName);
+			if (existsSync(candidate)) return candidate;
+		}
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+}
+function normalizePtywrightConfig(input, configPath) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`invalid ptywright config: expected object in ${configPath}`);
+	return input;
+}
+//#endregion
+export { loadPtywrightConfig as n, defineConfig as t };

package/dist/config.mjs

@@ -0,0 +1,2 @@
+import { n as loadPtywrightConfig, t as defineConfig } from "./config-B0r-JCFI.mjs";
+export { defineConfig, loadPtywrightConfig };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as createPtywrightServer } from "./server-VHuEWWj_.mjs";
+import { t as createPtywrightServer } from "./server-h--2U0Ic.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/index.ts
 const { server, sessions } = createPtywrightServer();

package/dist/mcp.mjs

@@ -1,2 +1,2 @@
-import { t as createPtywrightServer } from "./server-VHuEWWj_.mjs";
+import { t as createPtywrightServer } from "./server-h--2U0Ic.mjs";
 export { createPtywrightServer };

package/dist/pty-cassette.mjs

@@ -1,4 +1,4 @@
-import { S as dataToBytes, _ as ptyCassetteSchema, a as inspectPtyCassette, b as byteLength, c as createPtyCassetteReplay, d as PTY_CASSETTE_SCHEMA_URL, f as normalizePtyCassette, g as ptyCassetteResizeEventSchema, h as ptyCassetteExitEventSchema, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, m as ptyCassetteEventSchema, n as PtyCassetteRecorder, o as inspectPtyCassettePath, p as ptyCassetteDataEventSchema, r as createPtyCassetteRecorder, s as PtyCassetteReplay, t as wrapPtyLike, u as writePtyCassettePath, v as validatePtyCassette, x as dataToBase64, y as base64ToBytes } from "./pty_like-Cpkh_O9B.mjs";
+import { S as dataToBytes, _ as ptyCassetteSchema, a as inspectPtyCassette, b as byteLength, c as createPtyCassetteReplay, d as PTY_CASSETTE_SCHEMA_URL, f as normalizePtyCassette, g as ptyCassetteResizeEventSchema, h as ptyCassetteExitEventSchema, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, m as ptyCassetteEventSchema, n as PtyCassetteRecorder, o as inspectPtyCassettePath, p as ptyCassetteDataEventSchema, r as createPtyCassetteRecorder, s as PtyCassetteReplay, t as wrapPtyLike, u as writePtyCassettePath, v as validatePtyCassette, x as dataToBase64, y as base64ToBytes } from "./pty_like-DqCo7XdB.mjs";
 //#region src/pty-cassette/bun_terminal.ts
 function wrapBunTerminalOptions(options, recorder) {
 	const onData = options.data;