ccqa 0.1.6 → 0.3.3

package/dist/bin/ccqa.mjs

@@ -0,0 +1,1702 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { accessSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { access, mkdir, mkdtemp, readFile, readdir, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import matter from "gray-matter";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+//#region src/prompts/trace.ts
+function generateSessionName() {
+	return `ccqa-trace-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
+}
+function buildTraceSystemPrompt(spec, options) {
+	const sessionName = options?.sessionName ?? generateSessionName();
+	const skipCookiesClear = options?.skipCookiesClear ?? false;
+	const stepsText = spec.steps.map((step) => `### ${step.id}: ${step.title}
+- **Instruction**: ${step.instruction}
+- **Expected**: ${step.expected}`).join("\n\n");
+	const prereqText = spec.prerequisites ? `## Prerequisites\n${spec.prerequisites}\n\n` : "";
+	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
+
+## Session
+
+SESSION NAME: \`${sessionName}\`
+
+Always pass \`--session ${sessionName}\` to every \`agent-browser\` command.
+
+## Browser Commands
+
+\`\`\`
+agent-browser --session SESSION open <url>
+agent-browser --session SESSION snapshot
+agent-browser --session SESSION click "<selector>"
+agent-browser --session SESSION fill "<selector>" "<value>"
+agent-browser --session SESSION check "<selector>"
+agent-browser --session SESSION uncheck "<selector>"
+agent-browser --session SESSION press <Key>
+agent-browser --session SESSION select "<selector>" "<value>"
+agent-browser --session SESSION hover "<selector>"
+agent-browser --session SESSION wait --text "<text>"
+agent-browser --session SESSION cookies clear
+\`\`\`
+
+## Selector Rules
+
+**ALLOWED — these formats only:**
+
+| Format | Use when |
+|--------|----------|
+| \`[aria-label='label']\` | Element has aria-label (check snapshot output) — **FIRST CHOICE** |
+| \`text=visible text\` | Unique visible text, no aria-label |
+| \`[placeholder='text']\` | Input identified by placeholder |
+| \`[type='password']\` | Password inputs only |
+| \`a[href*='pattern']\` | Links where \`text=\` fails — use the URL pattern from the ARIA snapshot (e.g. \`a[href*='/settings']\`) |
+
+**FORBIDDEN — these will break recorded tests or are not valid commands:**
+
+- \`@ref\` / \`@e1\` / \`e14\` — reference IDs are session-specific and change every run; never use them
+- \`[role='button']\` or \`[type='checkbox']\` alone — matches too many elements
+- Bare tag selectors: \`button\`, \`td\`, \`tr\`, \`main a\`, \`table tbody tr:nth-child(N)\` — these are positional/non-deterministic and will fail on replay
+- \`find ...\`, \`textbox ...\`, \`label ...\` — not valid agent-browser commands; these are **blocked** and will fail
+- JavaScript execution (\`eval\`, \`js\`) — **blocked** at the hook level; cannot bypass this restriction
+
+**Selector workflow:**
+1. Run \`snapshot\` — read the ARIA tree output carefully
+2. Find the element; note its exact \`aria-label\` value if present
+3. If aria-label present → use \`[aria-label='...']\`; otherwise → use \`text=...\`
+4. If \`text=...\` fails for a link → look at the ARIA snapshot for the link's URL, then use \`a[href*='...']\` with a distinctive URL substring (e.g. \`a[href*='/dashboard']\`, \`a[href*='filter=active']\`)
+5. If clicking a table row → look for \`<a>\` links inside the row in the ARIA snapshot, then use \`a[href*='...']\` targeting that link's URL pattern
+6. For checkboxes: try \`check "text=Label"\` or \`check "[aria-label='Label']"\`
+7. Never guess — if a selector fails once, take a fresh snapshot before retrying
+
+## Test Specification
+
+Title: ${spec.title}
+Base URL: ${spec.baseUrl}
+
+${prereqText}## Steps
+
+${stepsText}
+
+## Execution Workflow
+
+For each step:
+1. Emit \`STEP_START|<step-id>|<step-title>\`
+2. Run \`snapshot\` and identify selectors from the ARIA tree
+3. Execute the action using an ALLOWED selector
+4. Emit \`AB_ACTION|...\` for every browser action (see below)
+5. Run \`snapshot\` again to verify the outcome
+6. Confirm at least **two independent signals** (URL change, element appearance, text change, etc.)
+7. For each verified signal, emit \`AB_ACTION|assert|...\` (see Assertion Protocol below)
+8. Emit \`ROUTE_STEP|...\`
+9. Emit \`STEP_DONE\`, \`ASSERTION_FAILED\`, or \`STEP_SKIPPED\`
+
+**After form submission or navigation:** take a snapshot before continuing. If an intermediate screen appears (e.g. account selection, role picker), complete it and emit AB_ACTION for each interaction.
+
+## Guardrails
+
+- **Stop after 3 consecutive failures on the same step** — emit \`ASSERTION_FAILED\` and report the blocker. Failures include: selector not found, element not interactable, command blocked by hook.
+- **Do NOT use workarounds** — if all ALLOWED selectors fail, do NOT fall back to \`mouse move\`, coordinate-based clicks, \`Tab\`+\`Enter\` keyboard navigation, or any other indirect method. These cannot be recorded as reliable test actions. Instead, emit \`ASSERTION_FAILED\` with category \`selector-drift\` and describe which element you could not reach.
+- **Do NOT use bare tag selectors** — never use \`click "button"\`, \`click "td"\`, \`click "main a"\`, or \`click "a"\` alone. These match too many elements and are non-deterministic. Always use a specific ALLOWED selector format.
+- Do NOT retry a selector without taking a fresh snapshot first
+- Do NOT work around blockers (login walls, missing data, captchas) — stop and report
+- **Do NOT suppress errors** — never use \`2>/dev/null\`, \`|| true\`, \`; other-command\`, or any other technique that hides agent-browser failures. Each \`agent-browser\` command must run standalone so failures are properly detected and recorded.
+
+## Source Code Reference
+
+You have access to **Read**, **Grep**, and **Glob** tools to inspect the application source code. Use them proactively to find correct selectors — do NOT guess \`a[href*='...']\` patterns by trial and error.
+
+**When to read source code:**
+- Before clicking a link: Grep for the link text or URL pattern in the codebase to find the exact \`href\` value
+- Before navigating to a new page: Glob for page/route files to understand the URL structure
+- When the ARIA snapshot shows an element but \`text=\` and \`[aria-label=]\` selectors fail: Read the component to find what HTML attributes the element has
+
+**How:**
+1. Use \`Grep\` to search for UI text, component names, or URL patterns
+2. Use \`Read\` to inspect the component's JSX/TSX and find \`href\`, \`aria-label\`, \`data-testid\`, or class names
+3. Build a precise ALLOWED selector from the discovered attributes
+
+**Rules:**
+- Only READ source files — never modify them
+- Keep source reading focused — search for specific strings, not entire directories
+
+## Waiting for Async Operations
+
+Prefer the \`wait\` command over polling:
+
+\`\`\`bash
+# Best: wait for expected text to appear
+agent-browser --session ${sessionName} wait --text "<completion text>"
+\`\`\`
+
+If polling is required (e.g. waiting for a spinner to disappear):
+
+\`\`\`bash
+for i in $(seq 1 18); do
+  sleep 10
+  result=$(agent-browser --session ${sessionName} snapshot 2>&1)
+  # Check result for the expected change and break when found
+  echo "$result" | grep -q "<done indicator>" && break
+done
+agent-browser --session ${sessionName} snapshot
+\`\`\`
+
+After waiting, always take a final snapshot. Emit \`AB_ACTION|wait|text=<text>|<label>\`.
+
+## AB_ACTION Protocol
+
+After **every** browser action, emit one line (outside any code block):
+
+\`\`\`
+AB_ACTION|cookies_clear
+AB_ACTION|open|<url>
+AB_ACTION|click|<selector>|<visible label>
+AB_ACTION|dblclick|<selector>|<visible label>
+AB_ACTION|fill|<selector>|<value>|<aria label>
+AB_ACTION|check|<selector>|<visible label>
+AB_ACTION|uncheck|<selector>|<visible label>
+AB_ACTION|press|<Key>
+AB_ACTION|select|<selector>|<value>|<aria label>
+AB_ACTION|hover|<selector>|<visible label>
+AB_ACTION|scroll|<direction>|<pixels>
+AB_ACTION|drag|<source selector>|<target selector>|<source label>
+AB_ACTION|wait|<selector or text>|<label>
+AB_ACTION|snapshot|<key observation, max 100 chars>
+AB_ACTION|assert|<assertType>|<selector or "">|<value or "">|<observation>
+\`\`\`
+
+The selector in AB_ACTION must be one of the ALLOWED formats above.
+
+## Assertion Protocol
+
+After verifying each step, emit \`AB_ACTION|assert\` lines for each signal you confirmed.
+
+**Available assertTypes:**
+
+| assertType | Use when | selector | value |
+|------------|----------|----------|-------|
+| \`text_visible\` | Stable text appears on page | (empty) | text to find |
+| \`text_not_visible\` | Text should be gone | (empty) | text that should be absent |
+| \`element_visible\` | Element is visible | CSS selector | (empty) |
+| \`element_not_visible\` | Element is hidden/removed | CSS selector | (empty) |
+| \`url_contains\` | URL contains a pattern | (empty) | URL substring |
+| \`element_enabled\` | Button/input is enabled | CSS selector | (empty) |
+| \`element_disabled\` | Button/input is disabled | CSS selector | (empty) |
+| \`element_checked\` | Checkbox is checked | CSS selector | (empty) |
+| \`element_unchecked\` | Checkbox is unchecked | CSS selector | (empty) |
+
+**Stability rules — CRITICAL:**
+- **NEVER** assert on: timestamps (dates, times), session IDs, exact numeric counts that vary between runs
+- For dynamic counts (e.g. "42 results"): assert on the STABLE part only (e.g. "results"), not the number
+- **PREFER** asserting on: status text, button labels, URL patterns, element enabled/disabled state
+
+**Page context rules — CRITICAL:**
+- After a page navigation (\`open\` or \`click\` that navigates), take a **fresh snapshot** BEFORE emitting any assertions
+- Only assert on text/elements that are visible on the **current** page — never assert on text from the previous page
+- If you navigated away from a page, its text is gone — do not emit \`text_visible\` for it
+
+**Selector rules for assert actions — CRITICAL:**
+- Use the **same ALLOWED formats** as browser actions — never invent aria-label values
+- Only use \`[aria-label='...']\` if that **exact** aria-label string appears in the current ARIA snapshot output
+- When unsure, prefer \`text_visible\`/\`text_not_visible\` (no selector needed) over guessing a selector
+- For \`element_disabled\`/\`element_enabled\`: use a CSS class selector if no aria-label is confirmed in the snapshot
+
+**Examples:**
+\`\`\`
+AB_ACTION|assert|url_contains|||/dashboard|Navigated to dashboard
+AB_ACTION|assert|element_disabled|.btn-submit||Submit button disabled before form is valid
+AB_ACTION|assert|element_enabled|.btn-submit||Submit button enabled after form is filled
+AB_ACTION|assert|text_visible|||Loading|Operation started
+AB_ACTION|assert|text_visible|||Done|Operation completed
+AB_ACTION|assert|text_visible|||Success|Confirmation message appeared
+\`\`\`
+
+## Status Protocol
+
+Emit exactly one status line per step (outside any code block):
+
+\`\`\`
+STEP_START|<step-id>|<step-title>
+STEP_DONE|<step-id>|<what was verified>
+ASSERTION_FAILED|<step-id>|<category: app-bug|env-issue|auth-blocked|missing-test-data|selector-drift|agent-misread>: <reason>
+STEP_SKIPPED|<step-id>|<reason>
+RUN_COMPLETED|passed|<summary>
+RUN_COMPLETED|failed|<summary>
+\`\`\`
+
+## Route Recording
+
+After each step (outside any code block):
+
+\`\`\`
+ROUTE_STEP|<step-id>|<step-title>|ACTION:<what you did>|OBSERVATION:<what you verified>|STATUS:<PASSED|FAILED|SKIPPED>
+\`\`\`
+
+## Start
+
+${skipCookiesClear ? `A setup procedure has already been executed in this session. Do NOT clear cookies — keep the existing session state.
+
+\`\`\`bash
+agent-browser --session ${sessionName} open ${spec.baseUrl}
+\`\`\`
+
+Emit:
+\`\`\`
+AB_ACTION|open|${spec.baseUrl}
+\`\`\`` : `\`\`\`bash
+agent-browser --session ${sessionName} cookies clear
+agent-browser --session ${sessionName} open ${spec.baseUrl}
+\`\`\`
+
+Emit:
+\`\`\`
+AB_ACTION|cookies_clear
+AB_ACTION|open|${spec.baseUrl}
+\`\`\``}
+
+Then emit \`STEP_START|step-01|...\` and begin.`;
+}
+function buildTracePrompt(spec) {
+	return `Execute the test for "${spec.title}" at ${spec.baseUrl}.`;
+}
+function buildSetupTraceSystemPrompt(spec) {
+	return buildTraceSystemPrompt({
+		title: spec.title,
+		baseUrl: "about:blank",
+		steps: spec.steps
+	});
+}
+function buildSetupTracePrompt(spec) {
+	return `Execute the setup procedure "${spec.title}". Follow each step precisely.`;
+}
+//#endregion
+//#region src/cli/logger.ts
+const STEP_ICONS = {
+	STEP_START: "▶",
+	STEP_DONE: "✓",
+	ASSERTION_FAILED: "✗",
+	STEP_SKIPPED: "⊘",
+	RUN_COMPLETED: "■"
+};
+function header(command, target) {
+	process.stdout.write(`\nccqa ${command}${target ? ` ${target}` : ""}\n\n`);
+}
+function meta(key, value) {
+	process.stdout.write(`  ${key}: ${value}\n`);
+}
+function blank() {
+	process.stdout.write("\n");
+}
+function info(message) {
+	process.stdout.write(`${message}\n`);
+}
+function step(type, stepId, detail) {
+	process.stdout.write(`  ${STEP_ICONS[type]} [${stepId}] ${detail}\n`);
+}
+function bash(command) {
+	process.stdout.write(`  $ ${command.slice(0, 120)}\n`);
+}
+function error(message) {
+	process.stderr.write(`error: ${message}\n`);
+}
+function warn(message) {
+	process.stderr.write(`warn: ${message}\n`);
+}
+function hint(message) {
+	process.stdout.write(`\nhint: ${message}\n`);
+}
+//#endregion
+//#region src/claude/invoke.ts
+async function invokeClaudeStreaming(options, onEvent) {
+	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, maxTurns, env, onAbAction, onAbActionFailed } = options;
+	let lastAbToolUseId = null;
+	const sdkOptions = {
+		systemPrompt,
+		maxTurns,
+		allowedTools: allowedTools ?? ["Bash(*)"],
+		permissionMode: "bypassPermissions",
+		allowDangerouslySkipPermissions: true,
+		...env ? { env: {
+			...process.env,
+			...env
+		} } : {},
+		...disableBuiltinTools ? { tools: [] } : {},
+		hooks: onAbAction || onAbActionFailed ? {
+			PreToolUse: [{ hooks: [async (input) => {
+				if (input.hook_event_name !== "PreToolUse") return {};
+				if (input.tool_name !== "Bash") return {};
+				const cmd = input.tool_input?.["command"];
+				if (typeof cmd !== "string") return {};
+				if (isBlockedAbSubcommand(cmd)) return {
+					decision: "block",
+					reason: "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait. Take a fresh snapshot to find the correct selector."
+				};
+				if (hasRefSelector(cmd)) return {
+					decision: "block",
+					reason: "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text."
+				};
+				const ab = extractAbActionFromBashCommand(cmd);
+				if (ab && onAbAction) {
+					lastAbToolUseId = input.tool_use_id;
+					onAbAction(ab);
+				} else lastAbToolUseId = null;
+				return {};
+			}] }],
+			PostToolUseFailure: [{ hooks: [async (input) => {
+				if (input.hook_event_name !== "PostToolUseFailure") return {};
+				if (input.tool_name !== "Bash") return {};
+				if (input.tool_use_id === lastAbToolUseId && onAbActionFailed) {
+					onAbActionFailed();
+					lastAbToolUseId = null;
+				}
+				return {};
+			}] }]
+		} : void 0
+	};
+	let result = "";
+	let isError = false;
+	const q = await buildMessageStream(prompt, sdkOptions);
+	for await (const msg of q) {
+		onEvent(msg);
+		if (msg.type === "assistant") {
+			for (const block of msg.message.content ?? []) if (block.type === "tool_use" && block.name === "Bash") {
+				const cmd = block.input?.["command"];
+				if (typeof cmd === "string") bash(cmd);
+			}
+		}
+		if (msg.type === "result") {
+			result = msg.subtype === "success" ? msg.result : "";
+			isError = msg.is_error ?? false;
+		}
+	}
+	return {
+		result,
+		isError
+	};
+}
+const BLOCKED_AB_SUBCOMMANDS = new Set([
+	"eval",
+	"js",
+	"find",
+	"label",
+	"textbox"
+]);
+/**
+* Shell-aware tokenizer: splits a command string into tokens respecting single/double quotes.
+* e.g. `click "[role='dialog'] button:last-child"` → ["click", "[role='dialog'] button:last-child"]
+*/
+function shellTokenize(s) {
+	const tokens = [];
+	let cur = "";
+	let quote = null;
+	for (let i = 0; i < s.length; i++) {
+		const ch = s[i];
+		if (quote) if (ch === quote) quote = null;
+		else cur += ch;
+		else if (ch === "\"" || ch === "'") quote = ch;
+		else if (ch === " " || ch === "	") {
+			if (cur) {
+				tokens.push(cur);
+				cur = "";
+			}
+		} else cur += ch;
+	}
+	if (cur) tokens.push(cur);
+	return tokens;
+}
+/** Extracts the subcommand from an `agent-browser [flags] <subcommand> [args...]` command string. */
+function extractAbSubcommand(cmd) {
+	const abIdx = cmd.indexOf("agent-browser");
+	if (abIdx === -1) return null;
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim());
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	return parts[i] ?? null;
+}
+/** Returns true if the agent-browser subcommand is blocked (eval/js/find/etc). */
+function isBlockedAbSubcommand(cmd) {
+	const sub = extractAbSubcommand(cmd);
+	return sub !== null && BLOCKED_AB_SUBCOMMANDS.has(sub);
+}
+/** Returns true if any argument to an agent-browser command uses a @ref selector (e.g. @e14). */
+function hasRefSelector(cmd) {
+	const abIdx = cmd.indexOf("agent-browser");
+	if (abIdx === -1) return false;
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim());
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	i++;
+	for (; i < parts.length; i++) if (/^@/.test(parts[i])) return true;
+	return false;
+}
+/**
+* Parse an `agent-browser --session <name> <cmd> [args...]` bash command
+* and return the corresponding AB_ACTION line, or null if not an agent-browser call.
+*/
+function extractAbActionFromBashCommand(cmd) {
+	const subCmd = extractAbSubcommand(cmd);
+	if (!subCmd) return null;
+	const abIdx = cmd.indexOf("agent-browser");
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim()).filter((t) => !/^(2?>|[|&>])/.test(t));
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	const args = parts.slice(i + 1);
+	switch (subCmd) {
+		case "cookies":
+			if (args[0] === "clear") return "AB_ACTION|cookies_clear";
+			return null;
+		case "open": return `AB_ACTION|open|${args[0] ?? ""}`;
+		case "press": return `AB_ACTION|press|${args[0] ?? ""}`;
+		case "scroll": return `AB_ACTION|scroll|${args.join("|")}`;
+		case "click":
+		case "dblclick":
+		case "check":
+		case "uncheck":
+		case "hover":
+		case "wait": return `AB_ACTION|${subCmd}|${args[0] ?? ""}|${args[1] ?? ""}`;
+		case "fill":
+		case "type":
+		case "select": return `AB_ACTION|${subCmd}|${args[0] ?? ""}|${args[1] ?? ""}|${args[2] ?? ""}`;
+		case "drag": return `AB_ACTION|drag|${args[0] ?? ""}|${args[1] ?? ""}|${args[2] ?? ""}`;
+		case "snapshot": return null;
+		default: return null;
+	}
+}
+async function buildMessageStream(prompt, options) {
+	const mockFile = process.env["CCQA_CLAUDE_MOCK_FILE"];
+	if (mockFile) return replayMockMessages(mockFile);
+	return query({
+		prompt,
+		options
+	});
+}
+async function* replayMockMessages(path) {
+	const raw = await readFile(path, "utf8");
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		yield JSON.parse(trimmed);
+	}
+}
+//#endregion
+//#region src/store/index.ts
+const CCQA_DIR = ".ccqa";
+function getCcqaDir(cwd = process.cwd()) {
+	return join(cwd, CCQA_DIR);
+}
+function parseSpecPath(specPath) {
+	const parts = specPath.split("/");
+	if (parts.length !== 2 || !parts[0] || !parts[1]) throw new Error(`Invalid spec path: "${specPath}". Expected format: "<feature>/<spec>"`);
+	return {
+		featureName: parts[0],
+		specName: parts[1]
+	};
+}
+function getFeatureDir(featureName, cwd) {
+	return join(getCcqaDir(cwd), "features", featureName);
+}
+function getSpecDir(featureName, specName, cwd) {
+	return join(getFeatureDir(featureName, cwd), "test-cases", specName);
+}
+async function ensureCcqaDir(cwd) {
+	await mkdir(join(getCcqaDir(cwd), "features"), { recursive: true });
+}
+async function readSpecFile(featureName, specName, cwd) {
+	const specPath = join(getSpecDir(featureName, specName, cwd), "test-spec.md");
+	return readFile(specPath, "utf-8").catch(() => {
+		throw new Error(`Spec file not found: ${specPath}`);
+	});
+}
+async function saveRoute(featureName, specName, route, cwd) {
+	const specDir = getSpecDir(featureName, specName, cwd);
+	await mkdir(specDir, { recursive: true });
+	const routePath = join(specDir, "route.md");
+	await writeFile(routePath, routeToMarkdown(route), "utf-8");
+	return routePath;
+}
+async function saveTraceActions(featureName, specName, actions, cwd) {
+	const specDir = getSpecDir(featureName, specName, cwd);
+	await mkdir(specDir, { recursive: true });
+	const actionsPath = join(specDir, "actions.json");
+	await writeFile(actionsPath, JSON.stringify(actions, null, 2), "utf-8");
+	return actionsPath;
+}
+function getSetupDir(name, cwd) {
+	return join(getCcqaDir(cwd), "setups", name);
+}
+async function readSetupSpecFile(name, cwd) {
+	const specPath = join(getSetupDir(name, cwd), "setup-spec.md");
+	return readFile(specPath, "utf-8").catch(() => {
+		throw new Error(`Setup spec not found: ${specPath}`);
+	});
+}
+async function saveSetupActions(name, actions, cwd) {
+	const dir = getSetupDir(name, cwd);
+	await mkdir(dir, { recursive: true });
+	const path = join(dir, "actions.json");
+	await writeFile(path, JSON.stringify(actions, null, 2), "utf-8");
+	return path;
+}
+async function getSetupActions(name, cwd) {
+	const path = join(getSetupDir(name, cwd), "actions.json");
+	const content = await readFile(path, "utf-8").catch(() => {
+		throw new Error(`No setup actions found for: ${name}. Run \`ccqa trace-setup ${name}\` first.`);
+	});
+	return {
+		path,
+		actions: JSON.parse(content)
+	};
+}
+async function saveSetupRoute(name, route, cwd) {
+	const dir = getSetupDir(name, cwd);
+	await mkdir(dir, { recursive: true });
+	const routePath = join(dir, "route.md");
+	await writeFile(routePath, routeToMarkdown(route), "utf-8");
+	return routePath;
+}
+async function getTraceActions(featureName, specName, cwd) {
+	const path = join(getSpecDir(featureName, specName, cwd), "actions.json");
+	const content = await readFile(path, "utf-8").catch(() => {
+		throw new Error(`No trace actions found for spec: ${featureName}/${specName}. Run \`ccqa trace\` first.`);
+	});
+	return {
+		path,
+		actions: JSON.parse(content)
+	};
+}
+async function saveTestScript(featureName, specName, content, cwd) {
+	const specDir = getSpecDir(featureName, specName, cwd);
+	await mkdir(specDir, { recursive: true });
+	const scriptPath = join(specDir, "test.spec.ts");
+	await writeFile(scriptPath, content, "utf-8");
+	return scriptPath;
+}
+async function getTestScript(featureName, specName, cwd) {
+	const path = join(getSpecDir(featureName, specName, cwd), "test.spec.ts");
+	return stat(path).then(() => path).catch(() => null);
+}
+async function listAllSpecs(cwd) {
+	const featuresDir = join(getCcqaDir(cwd), "features");
+	const featureDirs = await readdir(featuresDir).catch(() => []);
+	return (await Promise.all(featureDirs.map(async (featureName) => {
+		const testCasesDir = join(featuresDir, featureName, "test-cases");
+		const specDirs = await readdir(testCasesDir).catch(() => []);
+		return (await Promise.all(specDirs.map(async (specName) => {
+			return await stat(join(testCasesDir, specName, "test.spec.ts")).then(() => true).catch(() => false) ? {
+				featureName,
+				specName
+			} : null;
+		}))).filter((e) => e !== null);
+	}))).flat();
+}
+async function listSpecsForFeature(featureName, cwd) {
+	return readdir(join(getFeatureDir(featureName, cwd), "test-cases")).catch(() => []);
+}
+function routeToMarkdown(route) {
+	const lines = [
+		"---",
+		`specName: "${route.specName}"`,
+		`timestamp: "${route.timestamp}"`,
+		`status: "${route.status}"`,
+		"---",
+		""
+	];
+	for (const step of route.steps) {
+		lines.push(`## ${step.title}`);
+		lines.push(`- **action**: ${step.action}`);
+		lines.push(`- **observation**: ${step.observation}`);
+		lines.push(`- **status**: ${step.status}`);
+		if (step.reason) lines.push(`- **reason**: ${step.reason}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/spec/parser.ts
+function parseTestSpec(content) {
+	const { data, content: body } = matter(content);
+	const steps = parseSteps(body);
+	const prerequisites = parsePrerequisites(body);
+	return {
+		title: String(data["title"] ?? "Untitled"),
+		baseUrl: String(data["baseUrl"] ?? "http://localhost:3000"),
+		prerequisites: prerequisites || void 0,
+		setups: parseSetupRefs(data["setups"]),
+		steps
+	};
+}
+function parseSetupSpec(content) {
+	const { data, content: body } = matter(content);
+	const steps = parseSteps(body);
+	const placeholders = parsePlaceholders(data["placeholders"]);
+	return {
+		title: String(data["title"] ?? "Untitled"),
+		placeholders: Object.keys(placeholders).length > 0 ? placeholders : void 0,
+		steps
+	};
+}
+function parsePlaceholders(raw) {
+	if (!raw || typeof raw !== "object") return {};
+	const result = {};
+	for (const [key, val] of Object.entries(raw)) if (val && typeof val === "object" && "dummy" in val) {
+		const v = val;
+		result[key] = {
+			dummy: String(v["dummy"]),
+			description: v["description"] ? String(v["description"]) : void 0
+		};
+	}
+	return result;
+}
+function parseSetupRefs(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const refs = [];
+	for (const item of raw) if (typeof item === "object" && item !== null && "name" in item) {
+		const i = item;
+		refs.push({
+			name: String(i["name"]),
+			params: i["params"] && typeof i["params"] === "object" ? Object.fromEntries(Object.entries(i["params"]).map(([k, v]) => [k, String(v)])) : void 0
+		});
+	}
+	return refs.length > 0 ? refs : void 0;
+}
+function parsePrerequisites(body) {
+	const match = body.match(/##\s+Prerequisites\s+([\s\S]*?)(?=##|$)/);
+	if (!match || !match[1]) return null;
+	return match[1].trim();
+}
+function parseSteps(body) {
+	const stepBlocks = body.split(/###\s+Step\s+\d+:/);
+	const steps = [];
+	for (let i = 1; i < stepBlocks.length; i++) {
+		const block = stepBlocks[i];
+		if (!block) continue;
+		const titleMatch = block.match(/^(.+)/);
+		const instructionMatch = block.match(/\*\*Instruction\*\*:\s*(.+)/);
+		const expectedMatch = block.match(/\*\*Expected\*\*:\s*(.+)/);
+		if (!titleMatch || !instructionMatch || !expectedMatch) continue;
+		steps.push({
+			id: `step-${String(i).padStart(2, "0")}`,
+			title: titleMatch[1]?.trim() ?? "",
+			instruction: instructionMatch[1]?.trim() ?? "",
+			expected: expectedMatch[1]?.trim() ?? ""
+		});
+	}
+	return steps;
+}
+//#endregion
+//#region src/runtime/bundled-config.ts
+const CANDIDATES = [
+	"../runtime/vitest.config.mjs",
+	"./vitest.config.mjs",
+	"./vitest.config.ts"
+];
+function bundledVitestConfigPath() {
+	for (const rel of CANDIDATES) {
+		const candidate = fileURLToPath(new URL(rel, import.meta.url));
+		try {
+			accessSync(candidate);
+			return candidate;
+		} catch {}
+	}
+	return fileURLToPath(new URL("./vitest.config.ts", import.meta.url));
+}
+//#endregion
+//#region src/runtime/spawn-vitest.ts
+const require = createRequire(import.meta.url);
+function resolveVitestBin() {
+	const pkgPath = require.resolve("vitest/package.json");
+	const pkg = require(pkgPath);
+	const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vitest;
+	if (!binRel) throw new Error(`vitest package.json has no bin entry (resolved at ${pkgPath})`);
+	return resolve(dirname(pkgPath), binRel);
+}
+async function spawnVitestCaptured(args, opts = {}) {
+	const child = spawnVitestChild(args, opts, "pipe");
+	const [stdout, stderr, exitCode] = await Promise.all([
+		drain(child.stdout),
+		drain(child.stderr),
+		waitExit(child)
+	]);
+	return {
+		exitCode,
+		stdout,
+		stderr
+	};
+}
+function spawnVitestStreaming(args, opts = {}) {
+	const child = spawnVitestChild(args, opts, "pipe");
+	return {
+		child,
+		stdout: child.stdout,
+		stderr: child.stderr,
+		exited: waitExit(child)
+	};
+}
+function spawnVitestChild(args, opts, stdio) {
+	const vitestBin = resolveVitestBin();
+	return spawn(process.execPath, [vitestBin, ...args], {
+		cwd: opts.cwd,
+		env: opts.env ?? process.env,
+		stdio: [
+			"ignore",
+			stdio,
+			stdio
+		]
+	});
+}
+async function drain(stream) {
+	stream.setEncoding("utf8");
+	let buf = "";
+	for await (const chunk of stream) buf += chunk;
+	return buf;
+}
+function waitExit(child) {
+	return new Promise((resolvePromise, rejectPromise) => {
+		child.once("exit", (code) => resolvePromise(code ?? 0));
+		child.once("error", rejectPromise);
+	});
+}
+//#endregion
+//#region src/cli/trace.ts
+const traceCommand = new Command("trace").argument("<feature/spec>", "Spec to trace (e.g. tasks/create-and-complete)").description("Run agent-browser, verify assertions, and record structured actions").action(async (specPath) => {
+	const { featureName, specName } = parseSpecPath(specPath);
+	await runTrace(featureName, specName);
+});
+async function runTrace(featureName, specName) {
+	header("trace", `${featureName}/${specName}`);
+	await ensureCcqaDir();
+	const spec = parseTestSpec(await readSpecFile(featureName, specName));
+	const hasSetups = (spec.setups?.length ?? 0) > 0;
+	meta("spec", spec.title);
+	meta("url", spec.baseUrl);
+	if (hasSetups) meta("setups", spec.setups.map((s) => s.name).join(", "));
+	meta("steps", spec.steps.length);
+	blank();
+	const sessionName = generateSessionName();
+	if (hasSetups) {
+		info("Running setup procedures...");
+		await runSetups(spec.setups, sessionName);
+		blank();
+	}
+	const systemPrompt = buildTraceSystemPrompt(spec, {
+		sessionName,
+		skipCookiesClear: hasSetups
+	});
+	const prompt = buildTracePrompt(spec);
+	info("Running agent-browser session...");
+	blank();
+	const routeSteps = [];
+	let overallStatus = "passed";
+	const traceActions = [];
+	const { isError } = await invokeClaudeStreaming({
+		prompt,
+		systemPrompt,
+		allowedTools: [
+			"Bash(*)",
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		env: { AGENT_BROWSER_SESSION: sessionName },
+		onAbAction: (abAction) => {
+			const action = parseAbAction(abAction);
+			if (action) traceActions.push(action);
+		},
+		onAbActionFailed: () => {
+			traceActions.pop();
+		}
+	}, (msg) => {
+		if (msg.type !== "assistant") return;
+		for (const block of msg.message.content ?? []) {
+			if (block.type !== "text" || !block.text) continue;
+			const text = block.text;
+			const statusLine = parseStatusLine(text);
+			if (statusLine) step(statusLine.type, statusLine.stepId, statusLine.detail);
+			for (const line of text.split("\n")) {
+				const trimmed = line.trim();
+				if (trimmed.startsWith("ROUTE_STEP|")) {
+					const routeStep = parseRouteStep(trimmed);
+					if (routeStep) {
+						routeSteps.push(routeStep);
+						if (routeStep.status === "FAILED") overallStatus = "failed";
+					}
+				} else if (trimmed.startsWith("AB_ACTION|snapshot|") || trimmed.startsWith("AB_ACTION|assert|")) {
+					const action = parseAbAction(trimmed);
+					if (action) traceActions.push(action);
+				}
+			}
+		}
+	});
+	if (isError) overallStatus = "failed";
+	const route = {
+		specName,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		status: overallStatus,
+		steps: routeSteps
+	};
+	const [routePath, actionsPath] = await Promise.all([saveRoute(featureName, specName, route), saveTraceActions(featureName, specName, traceActions)]);
+	blank();
+	meta("route", routePath);
+	meta("saved", actionsPath);
+	meta("actions", traceActions.length);
+	meta("status", overallStatus.toUpperCase());
+	hint(`run 'ccqa generate ${featureName}/${specName}' to generate a test script`);
+}
+/**
+* Execute setup procedures by running their test.spec.ts via vitest with a fixed session name.
+* Creates a temporary runner script that sets the session and imports each setup's test body.
+*/
+async function runSetups(setups, sessionName) {
+	for (const ref of setups) {
+		info(`  setup: ${ref.name}`);
+		const scriptPath = join(getSetupDir(ref.name), "test.spec.ts");
+		let script = await readFile(scriptPath, "utf-8").catch(() => {
+			throw new Error(`Setup test script not found: ${scriptPath}. Run \`ccqa generate-setup ${ref.name}\` first.`);
+		});
+		for (const [key, value] of Object.entries(ref.params ?? {})) script = script.replaceAll(`{{${key}}}`, value);
+		script = script.replace(/process\.env\.AGENT_BROWSER_SESSION\s*=\s*`.+`;/, `process.env.AGENT_BROWSER_SESSION = ${JSON.stringify(sessionName)};`);
+		const tmpPath = join(getSetupDir(ref.name), `_run.spec.ts`);
+		await writeFile(tmpPath, script, "utf-8");
+		try {
+			const { exitCode, stdout, stderr } = await spawnVitestCaptured([
+				"run",
+				"--config",
+				bundledVitestConfigPath(),
+				tmpPath
+			]);
+			process.stdout.write(stdout);
+			if (stderr) process.stderr.write(stderr);
+			if (exitCode !== 0) throw new Error(`Setup '${ref.name}' failed (exit ${exitCode})`);
+		} finally {
+			await unlink(tmpPath).catch(() => {});
+		}
+	}
+}
+function parseStatusLine(text) {
+	for (const line of text.split("\n")) {
+		const match = line.match(/^(STEP_START|STEP_DONE|ASSERTION_FAILED|STEP_SKIPPED|RUN_COMPLETED)\|([^|]*)\|(.*)$/);
+		if (match) return {
+			type: match[1],
+			stepId: match[2] ?? "",
+			detail: match[3] ?? ""
+		};
+	}
+	return null;
+}
+function parseRouteStep(line) {
+	const parts = line.split("|");
+	if (parts.length < 6) return null;
+	const title = parts[2] ?? "";
+	const action = (parts[3] ?? "").replace(/^ACTION:/, "").trim();
+	const observation = (parts[4] ?? "").replace(/^OBSERVATION:/, "").trim();
+	const statusRaw = (parts[5] ?? "").replace(/^STATUS:/, "").trim();
+	return {
+		title,
+		action,
+		observation,
+		status: [
+			"PASSED",
+			"FAILED",
+			"SKIPPED"
+		].find((s) => s === statusRaw) ?? "FAILED"
+	};
+}
+function parseAbAction(line) {
+	if (!line.startsWith("AB_ACTION|")) return null;
+	const parts = line.split("|");
+	const command = parts[1];
+	switch (command) {
+		case "cookies_clear": return { command };
+		case "open": return {
+			command,
+			value: parts[2]
+		};
+		case "press": return {
+			command,
+			value: parts[2]
+		};
+		case "scroll": return {
+			command,
+			direction: parts[2],
+			pixels: parts[3]
+		};
+		case "snapshot": return {
+			command,
+			observation: parts[2]
+		};
+		case "assert": return {
+			command,
+			assertType: parts[2],
+			selector: parts[3] || void 0,
+			value: parts[4] || void 0,
+			observation: parts[5] || void 0
+		};
+		case "click":
+		case "dblclick":
+		case "check":
+		case "uncheck":
+		case "hover": return {
+			command,
+			selector: parts[2],
+			label: parts[3]
+		};
+		case "wait": {
+			const isTextWait = parts[2] === "--text";
+			return {
+				command,
+				selector: isTextWait ? `text=${parts[3]}` : parts[2],
+				label: isTextWait ? parts[4] : parts[3]
+			};
+		}
+		case "fill":
+		case "type":
+		case "select": return {
+			command,
+			selector: parts[2],
+			value: parts[3],
+			label: parts[4]
+		};
+		case "drag": return {
+			command,
+			selector: parts[2],
+			target: parts[3],
+			label: parts[4]
+		};
+		default: return null;
+	}
+}
+//#endregion
+//#region src/codegen/actions-to-script.ts
+function actionsToScript(actions, title, setupScripts) {
+	const parts = [...[
+		`import { test } from "vitest";`,
+		`import { spawnSync } from "node:child_process";`,
+		`import { ab, abWait, abAssertTextVisible, abAssertVisible, abAssertNotVisible, abAssertUrl, abAssertEnabled, abAssertDisabled, abAssertChecked, abAssertUnchecked } from "ccqa/test-helpers";`,
+		"",
+		`// Single session shared across all tests — reset per run via cookies clear in first test`,
+		`process.env.AGENT_BROWSER_SESSION = \`ccqa-run-\${Date.now()}\`;`,
+		""
+	]];
+	if (setupScripts?.length) for (const setup of setupScripts) parts.push(`test("setup: ${setup.name}", () => {`, setup.body, "}, 3 * 60 * 1000);", "");
+	const body = actionsToLines(actions).map((l) => `  ${l}`).join("\n");
+	parts.push(`test(${JSON.stringify(title)}, () => {`, body, "}, 5 * 60 * 1000);", "");
+	return parts.join("\n");
+}
+/** Commands that interact with page elements and need the page to be loaded */
+const ELEMENT_COMMANDS = new Set([
+	"click",
+	"dblclick",
+	"fill",
+	"type",
+	"check",
+	"uncheck",
+	"select",
+	"hover",
+	"drag"
+]);
+function actionsToLines(actions) {
+	const lines = [];
+	let prevLine = null;
+	let prevCommand = null;
+	for (const action of actions) {
+		const line = actionToLine(action);
+		if (line === null) continue;
+		if (line === prevLine) continue;
+		if (prevCommand === "open" && ELEMENT_COMMANDS.has(action.command)) lines.push(`spawnSync("sleep", ["3"], { stdio: "inherit" });`);
+		lines.push(line);
+		prevLine = line;
+		prevCommand = action.command;
+	}
+	return lines;
+}
+/** Returns true if a selector is a session-specific @ref that cannot be replayed. */
+function isRefSelector(selector) {
+	return typeof selector === "string" && /^@/.test(selector.trim());
+}
+function actionToLine(action) {
+	if ("selector" in action && isRefSelector(action.selector)) return null;
+	switch (action.command) {
+		case "cookies_clear": return `ab("cookies", "clear");`;
+		case "open": return `ab("open", ${j((action.value ?? "").replace(/^["']|["']$/g, ""))});`;
+		case "snapshot": return action.observation ? `// ${action.observation}` : null;
+		case "click": return `ab("click", ${j(action.selector)});`;
+		case "dblclick": return `ab("dblclick", ${j(action.selector)});`;
+		case "fill": return `ab("fill", ${j(action.selector)}, ${j(action.value)});`;
+		case "type": return `ab("fill", ${j(action.selector)}, ${j(action.value)});`;
+		case "check": return `ab("check", ${j(action.selector)});`;
+		case "uncheck": return `ab("uncheck", ${j(action.selector)});`;
+		case "press": return `ab("press", ${j(action.value)});`;
+		case "select": return `ab("select", ${j(action.selector)}, ${j(action.value)});`;
+		case "hover": return `ab("hover", ${j(action.selector)});`;
+		case "scroll": return `ab("scroll", ${[action.direction ?? "down", ...action.pixels ? [action.pixels] : []].map(j).join(", ")});`;
+		case "drag": return `ab("drag", ${j(action.selector)}, ${j(action.target)});`;
+		case "wait": {
+			const sel = action.selector;
+			if (/^\d+$/.test(sel)) return `spawnSync("sleep", [${j(sel)}], { stdio: "inherit" });`;
+			return `abWait(${j(sel)});`;
+		}
+		case "assert": {
+			const val = action.value ?? action.observation;
+			const sel = action.selector ?? action.observation;
+			const comment = action.observation ? `// Assert: ${action.observation}` : null;
+			let assertLine = null;
+			switch (action.assertType) {
+				case "text_visible":
+					if (val) assertLine = `abAssertTextVisible(${j(val)});`;
+					break;
+				case "text_not_visible":
+					if (val) assertLine = `abAssertNotVisible(${j("text=" + val)}, 180_000);`;
+					break;
+				case "element_visible":
+					if (sel) assertLine = `abAssertVisible(${j(sel)});`;
+					break;
+				case "element_not_visible":
+					if (sel) assertLine = `abAssertNotVisible(${j(sel)});`;
+					break;
+				case "url_contains":
+					if (val) assertLine = `abAssertUrl(${j(val)});`;
+					break;
+				case "element_enabled":
+					if (sel && !sel.startsWith("text=") && !sel.startsWith("[aria-label=")) assertLine = `abAssertEnabled(${j(sel)});`;
+					break;
+				case "element_disabled":
+					if (sel && !sel.startsWith("text=") && !sel.startsWith("[aria-label=")) assertLine = `abAssertDisabled(${j(sel)});`;
+					break;
+				case "element_checked":
+					if (sel) assertLine = `abAssertChecked(${j(sel)});`;
+					break;
+				case "element_unchecked":
+					if (sel) assertLine = `abAssertUnchecked(${j(sel)});`;
+					break;
+			}
+			if (comment && assertLine) return `${comment}\n  ${assertLine}`;
+			return assertLine ?? comment;
+		}
+		default: return null;
+	}
+}
+/** JSON.stringify — produces a quoted string literal safe for embedding in TS source. */
+const j = (s) => JSON.stringify(s);
+//#endregion
+//#region src/prompts/codegen.ts
+function buildAutoFixPrompt(script, failureLog) {
+	return `You are analyzing a failing E2E test script. The test fails because some browser actions execute before the page has finished loading or navigating.
+
+Your task: identify which line numbers need a sleep/wait inserted BEFORE them to fix timing issues.
+
+## Rules
+- ONLY identify lines where a sleep is needed — do NOT suggest any other changes
+- Common patterns that need a sleep:
+  - After \`ab("open", ...)\` when the next line interacts with elements (fill, click, etc.)
+  - After \`ab("press", "Enter")\` or \`ab("click", ...)\` when a page navigation occurs before the next action
+  - After any action that triggers a redirect or page reload
+- Look at the error log to identify WHICH lines failed, then determine if a sleep before that line would fix it
+- If a \`spawnSync("sleep", ...)\` already exists before a failing line, suggest increasing its duration instead
+- Output ONLY a JSON array of objects, no explanation, no markdown code fences
+
+## Output format
+Each object has:
+- "line": the 1-based line number to insert a sleep BEFORE
+- "seconds": recommended sleep duration (typically 3-5)
+- "reason": very short explanation (e.g., "page navigation after form submit")
+
+If a sleep already exists and needs to be increased:
+- "line": the line number of the existing sleep
+- "increase_to": the new duration in seconds
+- "reason": explanation
+
+Example output:
+[{"line": 15, "seconds": 3, "reason": "page navigation after press Enter"}, {"line": 22, "increase_to": 5, "reason": "slow page load"}]
+
+If no fixes are needed, return: []
+
+## Test Script (with line numbers)
+${script.split("\n").map((l, i) => `${i + 1}: ${l}`).join("\n")}
+
+## Failure Log
+${failureLog.slice(0, 3e3)}`;
+}
+function buildCleanupPrompt(actions) {
+	return `You are given a list of browser actions recorded during an E2E test trace.
+The trace contains noise: failed attempts, redundant retries, and duplicate operations recorded because the agent explored multiple strategies.
+
+Your task: return a **cleaned-up JSON array** of TraceAction objects that represents the minimal, correct sequence of actions needed to reproduce the test.
+
+Each TraceAction object has the following shape (use EXACTLY these field names):
+{ "command": "...", "assertType": "...", "selector": "...", "value": "...", "label": "...", "observation": "..." }
+Only include fields that are present in the original action. The "command" field is required. For assert actions, "assertType" is also required.
+
+Rules:
+- Remove actions that were failed attempts superseded by a later successful action (e.g., if \`fill selector="text=Foo"\` was followed by \`fill selector="[placeholder='Foo']"\`, keep only the latter)
+- Remove duplicate fill operations on the same field (keep only the last successful fill for each field)
+- For \`click\` and \`fill\` actions: if the selector starts with \`text=\`, it is a failed attempt — remove it (text= selectors only work with the wait command, not click/fill)
+- Keep all snapshot actions — they serve as comments/observations in the generated test
+- Keep all assert actions — they are the test's verification points and must not be removed
+- Do NOT invent new actions or change values
+- Output ONLY a valid JSON array, no explanation, no markdown code fences
+
+## Recorded Actions
+${actions.map((a, i) => {
+		const parts = [`${i + 1}. ${a.command}`];
+		if (a.assertType) parts.push(`assertType="${a.assertType}"`);
+		if (a.selector) parts.push(`selector="${a.selector}"`);
+		if (a.value) parts.push(`value="${a.value}"`);
+		if (a.observation) parts.push(`→ ${a.observation}`);
+		return parts.join(" ");
+	}).join("\n")}`;
+}
+//#endregion
+//#region src/cli/generate.ts
+const generateCommand = new Command("generate").argument("<feature/spec>", "Spec to generate test for (e.g. tasks/create-and-complete)").description("Generate agent-browser test script from recorded trace actions").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").action(async (specPath, opts) => {
+	const { featureName, specName } = parseSpecPath(specPath);
+	await runGenerate(featureName, specName, parseInt(opts.maxRetries, 10));
+});
+async function runGenerate(featureName, specName, maxRetries) {
+	header("generate", `${featureName}/${specName}`);
+	await ensureCcqaDir();
+	const { path: actionsPath, actions } = await getTraceActions(featureName, specName);
+	meta("trace", actionsPath);
+	meta("actions", actions.length);
+	const spec = parseTestSpec(await readSpecFile(featureName, specName));
+	const setupScripts = await loadSetupScripts(spec.setups);
+	if (setupScripts.length > 0) meta("setups", setupScripts.map((s) => s.name).join(", "));
+	blank();
+	const cleanedActions = await cleanupActions$1(actions);
+	if (cleanedActions.length !== actions.length) meta("cleaned", cleanedActions.length);
+	const scriptPath = await saveTestScript(featureName, specName, actionsToScript(cleanedActions, spec.title, setupScripts.length > 0 ? setupScripts : void 0));
+	meta("saved", scriptPath);
+	blank();
+	let { exitCode, output, currentScript } = await runVitest$1(scriptPath);
+	if (exitCode === 0) {
+		hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+		return;
+	}
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		info(`auto-fix attempt ${attempt}/${maxRetries}...`);
+		blank();
+		const fixed = await autoFixWithLLM$1(currentScript, output);
+		if (!fixed) {
+			warn("could not determine fix from failure log");
+			break;
+		}
+		await writeFile(scriptPath, fixed, "utf-8");
+		meta("saved", scriptPath);
+		blank();
+		({exitCode, output, currentScript} = await runVitest$1(scriptPath));
+		if (exitCode === 0) {
+			hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+			return;
+		}
+	}
+	warn("auto-fix exhausted — test still failing");
+	process.exit(1);
+}
+/**
+* Load setup test scripts, extract test body, and replace {{placeholders}} with params values.
+*/
+async function loadSetupScripts(setups) {
+	if (!setups?.length) return [];
+	const result = [];
+	for (const ref of setups) {
+		const scriptPath = join(getSetupDir(ref.name), "test.spec.ts");
+		const resolved = replacePlaceholders(extractTestBody(await readFile(scriptPath, "utf-8").catch(() => {
+			throw new Error(`Setup test script not found: ${scriptPath}. Run \`ccqa generate-setup ${ref.name}\` first.`);
+		})), ref.params ?? {});
+		result.push({
+			name: ref.name,
+			body: resolved
+		});
+	}
+	return result;
+}
+/**
+* Extract the test body (lines inside the first test() block) from a setup test script.
+*/
+function extractTestBody(script) {
+	const lines = script.split("\n");
+	const startIdx = lines.findIndex((l) => /^\s*test\(/.test(l));
+	if (startIdx === -1) return "";
+	const bodyLines = [];
+	for (let i = startIdx + 1; i < lines.length; i++) {
+		if (/^\s*\}[\s,);]/.test(lines[i])) break;
+		bodyLines.push(lines[i]);
+	}
+	return bodyLines.join("\n");
+}
+function replacePlaceholders(body, params) {
+	let result = body;
+	for (const [key, value] of Object.entries(params)) result = result.replaceAll(`{{${key}}}`, value);
+	return result;
+}
+async function autoFixWithLLM$1(script, failureLog) {
+	try {
+		const { result, isError } = await invokeClaudeStreaming({
+			prompt: buildAutoFixPrompt(script, failureLog),
+			disableBuiltinTools: true,
+			maxTurns: 1
+		}, () => {});
+		if (isError || !result) return null;
+		const json = result.trim().replace(/^```(?:json)?\n?([\s\S]*?)\n?```$/, "$1").trim();
+		const fixes = JSON.parse(json);
+		if (!Array.isArray(fixes) || fixes.length === 0) return null;
+		return applySleepFixes$1(script, fixes);
+	} catch {
+		return null;
+	}
+}
+function applySleepFixes$1(script, fixes) {
+	const lines = script.split("\n");
+	for (const fix of fixes) if ("increase_to" in fix) {
+		const idx = fix.line - 1;
+		if (idx >= 0 && idx < lines.length) lines[idx] = lines[idx].replace(/spawnSync\("sleep",\s*\["\d+"\]/, `spawnSync("sleep", ["${fix.increase_to}"]`);
+	}
+	const inserts = fixes.filter((f) => "seconds" in f && !("increase_to" in f)).sort((a, b) => b.line - a.line);
+	for (const fix of inserts) {
+		const idx = fix.line - 1;
+		if (idx >= 0 && idx <= lines.length) lines.splice(idx, 0, `  spawnSync("sleep", ["${fix.seconds}"], { stdio: "inherit" });`);
+	}
+	return lines.join("\n");
+}
+async function runVitest$1(scriptPath) {
+	const { exitCode, stdout, stderr } = await spawnVitestCaptured([
+		"run",
+		"--config",
+		bundledVitestConfigPath(),
+		scriptPath
+	]);
+	const currentScript = await readFile(scriptPath, "utf8");
+	process.stdout.write(stdout);
+	if (stderr) process.stderr.write(stderr);
+	return {
+		exitCode,
+		output: stdout + stderr,
+		currentScript
+	};
+}
+async function cleanupActions$1(actions) {
+	try {
+		const { result, isError } = await invokeClaudeStreaming({
+			prompt: buildCleanupPrompt(actions),
+			disableBuiltinTools: true,
+			maxTurns: 1
+		}, () => {});
+		if (isError || !result) return actions;
+		const json = result.trim().replace(/^```(?:json)?\n?([\s\S]*?)\n?```$/, "$1").trim();
+		const parsed = JSON.parse(json);
+		if (Array.isArray(parsed) && parsed.length > 0) return parsed;
+	} catch {}
+	return actions;
+}
+//#endregion
+//#region src/cli/run.ts
+const USER_VITEST_CONFIG = resolve(".ccqa/vitest.config.ts");
+async function resolveVitestConfig() {
+	try {
+		await access(USER_VITEST_CONFIG);
+		return USER_VITEST_CONFIG;
+	} catch {
+		return bundledVitestConfigPath();
+	}
+}
+const runCommand = new Command("run").argument("[target]", "Spec to run: '<feature>/<spec>', '<feature>', or omit for all").description("Run generated agent-browser test scripts").action(async (target) => {
+	await runTests(target);
+});
+async function runTests(target) {
+	header("run", target);
+	const specs = await resolveSpecs(target);
+	if (specs.length === 0) {
+		error("no test scripts found");
+		hint("run 'ccqa generate <feature>/<spec>' first to generate tests");
+		process.exit(1);
+	}
+	const tmpDir = await mkdtemp(join(tmpdir(), "ccqa-run-"));
+	const summaries = [];
+	let overallExitCode = 0;
+	const vitestConfig = await resolveVitestConfig();
+	try {
+		for (let i = 0; i < specs.length; i++) {
+			const { featureName, specName } = specs[i];
+			const scriptFile = await getTestScript(featureName, specName);
+			if (!scriptFile) {
+				warn(`${featureName}/${specName}: no test.spec.ts found`);
+				continue;
+			}
+			info(`▶ ${featureName}/${specName}`);
+			meta("test", scriptFile);
+			blank();
+			const reportFile = join(tmpDir, `report-${i}.json`);
+			const proc = spawnVitestStreaming([
+				"run",
+				"--config",
+				vitestConfig,
+				scriptFile,
+				"--reporter=json",
+				`--outputFile.json=${reportFile}`
+			]);
+			await Promise.all([streamFiltered(proc.stdout, process.stdout), streamFiltered(proc.stderr, process.stderr)]);
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) overallExitCode = exitCode;
+			const report = await readReport(reportFile);
+			summaries.push({
+				featureName,
+				specName,
+				scriptFile,
+				report,
+				exitCode
+			});
+			blank();
+		}
+		printSummary(summaries);
+	} finally {
+		await rm(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	process.exit(overallExitCode);
+}
+async function readReport(path) {
+	try {
+		const raw = await readFile(path, "utf8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+const useColor = process.stdout.isTTY && process.env.NO_COLOR == null;
+const C = {
+	reset: useColor ? "\x1B[0m" : "",
+	bold: useColor ? "\x1B[1m" : "",
+	dim: useColor ? "\x1B[2m" : "",
+	green: useColor ? "\x1B[32m" : "",
+	red: useColor ? "\x1B[31m" : "",
+	yellow: useColor ? "\x1B[33m" : "",
+	cyan: useColor ? "\x1B[36m" : "",
+	gray: useColor ? "\x1B[90m" : ""
+};
+function printSummary(summaries) {
+	process.stdout.write(`\n${C.cyan}${C.bold}──────── ccqa summary ────────${C.reset}\n\n`);
+	let totalTests = 0;
+	let totalPassed = 0;
+	let totalFailed = 0;
+	let totalSkipped = 0;
+	for (const s of summaries) {
+		const header = `${C.bold}${s.featureName}/${s.specName}${C.reset}`;
+		if (!s.report) {
+			const icon = s.exitCode === 0 ? `${C.green}✔${C.reset}` : `${C.red}✖${C.reset}`;
+			process.stdout.write(`${icon} ${header} ${C.dim}(no report)${C.reset}\n`);
+			continue;
+		}
+		totalTests += s.report.numTotalTests;
+		totalPassed += s.report.numPassedTests;
+		totalFailed += s.report.numFailedTests;
+		totalSkipped += s.report.numPendingTests;
+		const ok = s.report.success;
+		const icon = ok ? `${C.green}✔${C.reset}` : `${C.red}✖${C.reset}`;
+		const countColor = ok ? C.green : C.red;
+		process.stdout.write(`${icon} ${header}  ${countColor}${s.report.numPassedTests}/${s.report.numTotalTests}${C.reset} ${C.dim}passed${C.reset}\n`);
+		for (const file of s.report.testResults) for (const a of file.assertionResults) {
+			const aIcon = assertionIcon(a.status);
+			const dur = a.duration != null ? ` ${C.gray}${formatDuration(a.duration)}${C.reset}` : "";
+			process.stdout.write(`    ${aIcon} ${a.fullName}${dur}\n`);
+			if (a.status === "failed" && a.failureMessages?.length) for (const msg of a.failureMessages) {
+				const firstLine = msg.split("\n")[0] ?? msg;
+				process.stdout.write(`        ${C.red}${firstLine}${C.reset}\n`);
+			}
+		}
+	}
+	const specsPassed = summaries.filter((s) => s.exitCode === 0).length;
+	const specsFailed = summaries.filter((s) => s.exitCode !== 0).length;
+	process.stdout.write("\n");
+	process.stdout.write(`  ${C.bold}Specs${C.reset}   ${summaries.length}  (${C.green}${specsPassed} passed${C.reset}, ${specsFailed > 0 ? C.red : C.dim}${specsFailed} failed${C.reset})\n`);
+	process.stdout.write(`  ${C.bold}Tests${C.reset}   ${totalTests}  (${C.green}${totalPassed} passed${C.reset}, ${totalFailed > 0 ? C.red : C.dim}${totalFailed} failed${C.reset}, ${C.yellow}${totalSkipped} skipped${C.reset})\n`);
+	process.stdout.write("\n");
+}
+function assertionIcon(status) {
+	switch (status) {
+		case "passed": return `${C.green}✔${C.reset}`;
+		case "failed": return `${C.red}✖${C.reset}`;
+		case "skipped":
+		case "pending":
+		case "todo": return `${C.yellow}◌${C.reset}`;
+	}
+}
+function formatDuration(ms) {
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	return `${(ms / 1e3).toFixed(2)}s`;
+}
+const NOISE_LINE_PATTERNS = [/^JSON report written to /];
+async function streamFiltered(source, sink) {
+	source.setEncoding("utf8");
+	let buffer = "";
+	for await (const chunk of source) {
+		buffer += chunk;
+		let nl = buffer.indexOf("\n");
+		while (nl !== -1) {
+			const line = buffer.slice(0, nl);
+			buffer = buffer.slice(nl + 1);
+			if (!NOISE_LINE_PATTERNS.some((p) => p.test(line))) sink.write(line + "\n");
+			nl = buffer.indexOf("\n");
+		}
+	}
+	if (buffer.length > 0 && !NOISE_LINE_PATTERNS.some((p) => p.test(buffer))) sink.write(buffer);
+}
+async function resolveSpecs(target) {
+	if (!target) return listAllSpecs();
+	if (target.includes("/")) {
+		const { featureName, specName } = parseSpecPath(target);
+		return [{
+			featureName,
+			specName
+		}];
+	}
+	return (await listSpecsForFeature(target)).map((specName) => ({
+		featureName: target,
+		specName
+	}));
+}
+//#endregion
+//#region src/cli/trace-setup.ts
+const traceSetupCommand = new Command("trace-setup").argument("<name>", "Setup name to trace (e.g. login)").description("Trace a setup procedure using dummy placeholder values").action(async (name) => {
+	await runTraceSetup(name);
+});
+async function runTraceSetup(name) {
+	header("trace-setup", name);
+	await ensureCcqaDir();
+	const spec = parseSetupSpec(await readSetupSpecFile(name));
+	const resolvedSpec = replacePlaceholdersWithDummies(spec);
+	meta("setup", spec.title);
+	meta("steps", spec.steps.length);
+	if (spec.placeholders) meta("placeholders", Object.keys(spec.placeholders).join(", "));
+	blank();
+	const systemPrompt = buildSetupTraceSystemPrompt(resolvedSpec);
+	const prompt = buildSetupTracePrompt(resolvedSpec);
+	info("Running agent-browser session...");
+	blank();
+	const routeSteps = [];
+	let overallStatus = "passed";
+	const traceActions = [];
+	const { isError } = await invokeClaudeStreaming({
+		prompt,
+		systemPrompt,
+		allowedTools: [
+			"Bash(*)",
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		onAbAction: (abAction) => {
+			const action = parseAbAction(abAction);
+			if (action) traceActions.push(action);
+		},
+		onAbActionFailed: () => {
+			traceActions.pop();
+		}
+	}, (msg) => {
+		if (msg.type !== "assistant") return;
+		for (const block of msg.message.content ?? []) {
+			if (block.type !== "text" || !block.text) continue;
+			const text = block.text;
+			const statusLine = parseStatusLine(text);
+			if (statusLine) step(statusLine.type, statusLine.stepId, statusLine.detail);
+			for (const line of text.split("\n")) {
+				const trimmed = line.trim();
+				if (trimmed.startsWith("ROUTE_STEP|")) {
+					const routeStep = parseRouteStep(trimmed);
+					if (routeStep) {
+						routeSteps.push(routeStep);
+						if (routeStep.status === "FAILED") overallStatus = "failed";
+					}
+				} else if (trimmed.startsWith("AB_ACTION|snapshot|") || trimmed.startsWith("AB_ACTION|assert|")) {
+					const action = parseAbAction(trimmed);
+					if (action) traceActions.push(action);
+				}
+			}
+		}
+	});
+	if (isError) overallStatus = "failed";
+	const route = {
+		specName: name,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		status: overallStatus,
+		steps: routeSteps
+	};
+	const [routePath, actionsPath] = await Promise.all([saveSetupRoute(name, route), saveSetupActions(name, traceActions)]);
+	blank();
+	meta("route", routePath);
+	meta("saved", actionsPath);
+	meta("actions", traceActions.length);
+	meta("status", overallStatus.toUpperCase());
+	hint(`run 'ccqa generate-setup ${name}' to generate and validate the setup`);
+}
+function replacePlaceholdersWithDummies(spec) {
+	if (!spec.placeholders) return spec;
+	const dummies = spec.placeholders;
+	const resolve = (text) => {
+		let result = text;
+		for (const [key, def] of Object.entries(dummies)) result = result.replaceAll(`{{${key}}}`, def.dummy);
+		return result;
+	};
+	return {
+		...spec,
+		steps: spec.steps.map((step) => ({
+			...step,
+			instruction: resolve(step.instruction),
+			expected: resolve(step.expected)
+		}))
+	};
+}
+//#endregion
+//#region src/cli/generate-setup.ts
+const generateSetupCommand = new Command("generate-setup").argument("<name>", "Setup name to generate (e.g. login)").description("Clean up, validate, and templatize setup actions").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--from-dummy", "Resume from existing test.dummy.spec.ts (after manual fix)").action(async (name, opts) => {
+	await runGenerateSetup(name, parseInt(opts.maxRetries, 10), opts.fromDummy ?? false);
+});
+async function runGenerateSetup(name, maxRetries, fromDummy) {
+	header("generate-setup", name);
+	await ensureCcqaDir();
+	const spec = parseSetupSpec(await readSetupSpecFile(name));
+	const dummyPath = join(getSetupDir(name), "test.dummy.spec.ts");
+	const finalPath = join(getSetupDir(name), "test.spec.ts");
+	if (fromDummy) {
+		if (!await stat(dummyPath).then(() => true).catch(() => false)) {
+			warn(`test.dummy.spec.ts not found. Run without --from-dummy first.`);
+			process.exit(1);
+		}
+		info("Resuming from existing test.dummy.spec.ts");
+	} else {
+		const { actions } = await getSetupActions(name);
+		meta("setup", spec.title);
+		meta("actions", actions.length);
+		blank();
+		const cleanedActions = await cleanupActions(actions);
+		if (cleanedActions.length !== actions.length) meta("cleaned", cleanedActions.length);
+		await writeFile(dummyPath, actionsToScript(cleanedActions, spec.title), "utf-8");
+		meta("saved", dummyPath);
+	}
+	blank();
+	let { exitCode, output, currentScript } = await runVitest(dummyPath);
+	if (exitCode !== 0) {
+		for (let attempt = 1; attempt <= maxRetries; attempt++) {
+			info(`auto-fix attempt ${attempt}/${maxRetries}...`);
+			blank();
+			const fixed = await autoFixWithLLM(currentScript, output);
+			if (!fixed) {
+				warn("could not determine fix from failure log");
+				break;
+			}
+			await writeFile(dummyPath, fixed, "utf-8");
+			meta("saved", dummyPath);
+			blank();
+			({exitCode, output, currentScript} = await runVitest(dummyPath));
+			if (exitCode === 0) break;
+		}
+		if (exitCode !== 0) {
+			warn("auto-fix exhausted — setup test still failing");
+			hint(`edit ${dummyPath} manually, then run: ccqa generate-setup ${name} --from-dummy`);
+			process.exit(1);
+		}
+	}
+	await writeFile(finalPath, reversePlaceholdersInScript(currentScript, spec.placeholders), "utf-8");
+	await unlink(dummyPath).catch(() => {});
+	blank();
+	meta("saved", finalPath);
+	hint(`setup '${name}' is ready — reference it in test-spec.md with setups: [{name: ${name}, params: {...}}]`);
+}
+/**
+* Replace dummy values with {{placeholder}} directly in the test script text.
+* Longer dummy values are replaced first to avoid partial matches.
+*/
+function reversePlaceholdersInScript(script, placeholders) {
+	if (!placeholders) return script;
+	const entries = Object.entries(placeholders).sort((a, b) => b[1].dummy.length - a[1].dummy.length);
+	let result = script;
+	for (const [key, def] of entries) result = result.replaceAll(def.dummy, `{{${key}}}`);
+	return result;
+}
+async function autoFixWithLLM(script, failureLog) {
+	try {
+		const { result, isError } = await invokeClaudeStreaming({
+			prompt: buildAutoFixPrompt(script, failureLog),
+			disableBuiltinTools: true,
+			maxTurns: 1
+		}, () => {});
+		if (isError || !result) return null;
+		const json = result.trim().replace(/^```(?:json)?\n?([\s\S]*?)\n?```$/, "$1").trim();
+		const fixes = JSON.parse(json);
+		if (!Array.isArray(fixes) || fixes.length === 0) return null;
+		return applySleepFixes(script, fixes);
+	} catch {
+		return null;
+	}
+}
+function applySleepFixes(script, fixes) {
+	const lines = script.split("\n");
+	for (const fix of fixes) if ("increase_to" in fix) {
+		const idx = fix.line - 1;
+		if (idx >= 0 && idx < lines.length) lines[idx] = lines[idx].replace(/spawnSync\("sleep",\s*\["\d+"\]/, `spawnSync("sleep", ["${fix.increase_to}"]`);
+	}
+	const inserts = fixes.filter((f) => "seconds" in f && !("increase_to" in f)).sort((a, b) => b.line - a.line);
+	for (const fix of inserts) {
+		const idx = fix.line - 1;
+		if (idx >= 0 && idx <= lines.length) lines.splice(idx, 0, `  spawnSync("sleep", ["${fix.seconds}"], { stdio: "inherit" });`);
+	}
+	return lines.join("\n");
+}
+async function runVitest(scriptPath) {
+	const { exitCode, stdout, stderr } = await spawnVitestCaptured([
+		"run",
+		"--config",
+		bundledVitestConfigPath(),
+		scriptPath
+	]);
+	const currentScript = await readFile(scriptPath, "utf8");
+	process.stdout.write(stdout);
+	if (stderr) process.stderr.write(stderr);
+	return {
+		exitCode,
+		output: stdout + stderr,
+		currentScript
+	};
+}
+async function cleanupActions(actions) {
+	try {
+		const { result, isError } = await invokeClaudeStreaming({
+			prompt: buildCleanupPrompt(actions),
+			disableBuiltinTools: true,
+			maxTurns: 1
+		}, () => {});
+		if (isError || !result) return actions;
+		const json = result.trim().replace(/^```(?:json)?\n?([\s\S]*?)\n?```$/, "$1").trim();
+		const parsed = JSON.parse(json);
+		if (Array.isArray(parsed) && parsed.length > 0) return parsed;
+	} catch {}
+	return actions;
+}
+//#endregion
+//#region src/cli/index.ts
+const packageJsonPath = resolvePackageJson();
+const { version } = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+function resolvePackageJson() {
+	const distCandidate = fileURLToPath(new URL("../package.json", import.meta.url));
+	const srcCandidate = fileURLToPath(new URL("../../package.json", import.meta.url));
+	try {
+		readFileSync(distCandidate);
+		return distCandidate;
+	} catch {
+		return srcCandidate;
+	}
+}
+const program = new Command();
+program.name("ccqa").description("E2E test CLI using Claude Code + agent-browser").version(version);
+program.addCommand(traceCommand);
+program.addCommand(generateCommand);
+program.addCommand(runCommand);
+program.addCommand(traceSetupCommand);
+program.addCommand(generateSetupCommand);
+program.parse();
+//#endregion
+export {};