ccqa 0.1.0

package/src/claude/invoke.ts

@@ -0,0 +1,238 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKMessage, Options, HookInput } from "@anthropic-ai/claude-agent-sdk";
+import * as log from "../cli/logger.ts";
+
+export interface ClaudeInvokeOptions {
+  prompt: string;
+  systemPrompt?: string;
+  allowedTools?: string[];
+  disableBuiltinTools?: boolean;
+  mcpConfigPath?: string;
+  maxTurns?: number;
+  env?: Record<string, string>;
+  /** Called when an agent-browser command is intercepted; receives the AB_ACTION line. */
+  onAbAction?: (abAction: string) => void;
+  /** Called when an agent-browser command fails (exit non-zero); allows rolling back the last AB_ACTION. */
+  onAbActionFailed?: () => void;
+}
+
+export async function invokeClaudeStreaming(
+  options: ClaudeInvokeOptions,
+  onEvent: (msg: SDKMessage) => void,
+): Promise<{ result: string; isError: boolean }> {
+  const {
+    prompt,
+    systemPrompt,
+    allowedTools,
+    disableBuiltinTools = false,
+    maxTurns,
+    env,
+    onAbAction,
+    onAbActionFailed,
+  } = options;
+
+  // Track the last agent-browser tool_use_id so PostToolUseFailure can roll back
+  let lastAbToolUseId: string | null = null;
+
+  const sdkOptions: Options = {
+    systemPrompt,
+    maxTurns,
+    allowedTools: allowedTools ?? ["Bash(*)"],
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
+    ...(env ? { env: { ...process.env, ...env } as Record<string, string | undefined> } : {}),
+    ...(disableBuiltinTools ? { tools: [] } : {}),
+    hooks:
+      onAbAction || onAbActionFailed
+        ? {
+            PreToolUse: [
+              {
+                hooks: [
+                  async (input: HookInput) => {
+                    if (input.hook_event_name !== "PreToolUse") return {};
+                    if (input.tool_name !== "Bash") return {};
+                    const cmd = (input.tool_input as Record<string, unknown>)?.["command"];
+                    if (typeof cmd !== "string") return {};
+
+                    // Block eval/js/find/etc — they bypass structured action recording
+                    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.",
+                      };
+                    }
+
+                    // Block @ref selectors — they are session-specific and not replayable
+                    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: HookInput) => {
+                    if (input.hook_event_name !== "PostToolUseFailure") return {};
+                    if (input.tool_name !== "Bash") return {};
+                    // If the failed Bash command was the one that emitted an AB_ACTION, roll it back
+                    if (input.tool_use_id === lastAbToolUseId && onAbActionFailed) {
+                      onAbActionFailed();
+                      lastAbToolUseId = null;
+                    }
+                    return {};
+                  },
+                ],
+              },
+            ],
+          }
+        : undefined,
+  };
+
+  let result = "";
+  let isError = false;
+
+  const q = query({ prompt, options: 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 as Record<string, unknown>)?.["command"];
+          if (typeof cmd === "string") log.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"]
+ */
+export function shellTokenize(s: string): string[] {
+  const tokens: string[] = [];
+  let cur = "";
+  let quote: '"' | "'" | null = 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 === "\t") {
+      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. */
+export function extractAbSubcommand(cmd: string): string | null {
+  const abIdx = cmd.indexOf("agent-browser");
+  if (abIdx === -1) return null;
+  const rest = cmd.slice(abIdx + "agent-browser".length).trim();
+  const parts = shellTokenize(rest);
+  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). */
+export function isBlockedAbSubcommand(cmd: string): boolean {
+  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). */
+export function hasRefSelector(cmd: string): boolean {
+  const abIdx = cmd.indexOf("agent-browser");
+  if (abIdx === -1) return false;
+  const rest = cmd.slice(abIdx + "agent-browser".length).trim();
+  const parts = shellTokenize(rest);
+  // Skip flags and subcommand, check remaining args
+  let i = 0;
+  while (i < parts.length && parts[i]!.startsWith("-")) { i += 2; }
+  i++; // skip subcommand
+  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.
+ */
+export function extractAbActionFromBashCommand(cmd: string): string | null {
+  const subCmd = extractAbSubcommand(cmd);
+  if (!subCmd) return null;
+
+  // Extract everything after "agent-browser" to get args (shell-aware tokenization)
+  const abIdx = cmd.indexOf("agent-browser");
+  const rest = cmd.slice(abIdx + "agent-browser".length).trim();
+  // Filter out shell redirects/pipes (2>&1, >&1, |, >file) that are not agent-browser args
+  const parts = shellTokenize(rest).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":
+      // snapshot AB_ACTION is emitted by LLM with its own observation
+      return null;
+    default:
+      return null;
+  }
+}
+

package/src/cli/generate-setup.ts

@@ -0,0 +1,215 @@
+import { readFile, writeFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Command } from "commander";
+import {
+  ensureCcqaDir,
+  readSetupSpecFile,
+  getSetupActions,
+  getSetupDir,
+  saveSetupTestScript,
+} from "../store/index.ts";
+import { actionsToScript } from "../codegen/actions-to-script.ts";
+import { buildCleanupPrompt, buildAutoFixPrompt } from "../prompts/codegen.ts";
+import { invokeClaudeStreaming } from "../claude/invoke.ts";
+import { parseSetupSpec } from "../spec/parser.ts";
+import type { TraceAction } from "../types.ts";
+import * as log from "./logger.ts";
+
+export 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: string, opts: { maxRetries: string; fromDummy?: boolean }) => {
+    await runGenerateSetup(name, parseInt(opts.maxRetries, 10), opts.fromDummy ?? false);
+  });
+
+async function runGenerateSetup(name: string, maxRetries: number, fromDummy: boolean): Promise<void> {
+  log.header("generate-setup", name);
+
+  await ensureCcqaDir();
+
+  const specContent = await readSetupSpecFile(name);
+  const spec = parseSetupSpec(specContent);
+  const dummyPath = join(getSetupDir(name), "test.dummy.spec.ts");
+  const finalPath = join(getSetupDir(name), "test.spec.ts");
+
+  // Phase 1: Generate or reuse test.dummy.spec.ts
+  if (fromDummy) {
+    // --from-dummy: use existing test.dummy.spec.ts
+    const exists = await stat(dummyPath).then(() => true).catch(() => false);
+    if (!exists) {
+      log.warn(`test.dummy.spec.ts not found. Run without --from-dummy first.`);
+      process.exit(1);
+    }
+    log.info("Resuming from existing test.dummy.spec.ts");
+  } else {
+    // Normal: generate from actions.json
+    const { actions } = await getSetupActions(name);
+    log.meta("setup", spec.title);
+    log.meta("actions", actions.length);
+    log.blank();
+
+    const cleanedActions = await cleanupActions(actions);
+    if (cleanedActions.length !== actions.length) {
+      log.meta("cleaned", cleanedActions.length);
+    }
+
+    const script = actionsToScript(cleanedActions, spec.title);
+    await writeFile(dummyPath, script, "utf-8");
+    log.meta("saved", dummyPath);
+  }
+  log.blank();
+
+  // Phase 2: Run vitest on test.dummy.spec.ts with auto-fix
+  let { exitCode, output, currentScript } = await runVitest(dummyPath);
+
+  if (exitCode !== 0) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      log.info(`auto-fix attempt ${attempt}/${maxRetries}...`);
+      log.blank();
+
+      const fixed = await autoFixWithLLM(currentScript, output);
+      if (!fixed) {
+        log.warn("could not determine fix from failure log");
+        break;
+      }
+
+      await writeFile(dummyPath, fixed, "utf-8");
+      log.meta("saved", dummyPath);
+      log.blank();
+
+      ({ exitCode, output, currentScript } = await runVitest(dummyPath));
+      if (exitCode === 0) break;
+    }
+
+    if (exitCode !== 0) {
+      log.warn("auto-fix exhausted — setup test still failing");
+      log.hint(`edit ${dummyPath} manually, then run: ccqa generate-setup ${name} --from-dummy`);
+      process.exit(1);
+    }
+  }
+
+  // Phase 3: Reverse-replace dummy values → {{placeholders}}, save as test.spec.ts
+  const templatizedScript = reversePlaceholdersInScript(
+    currentScript,
+    spec.placeholders as Record<string, { dummy: string; description?: string }> | undefined,
+  );
+
+  await writeFile(finalPath, templatizedScript, "utf-8");
+  await unlink(dummyPath).catch(() => {});
+
+  log.blank();
+  log.meta("saved", finalPath);
+  log.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: string,
+  placeholders?: Record<string, { dummy: string; description?: string }>,
+): string {
+  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;
+}
+
+// --- Shared utilities ---
+
+interface SleepInsert { line: number; seconds: number; reason: string }
+interface SleepIncrease { line: number; increase_to: number; reason: string }
+type AutoFixAction = SleepInsert | SleepIncrease;
+
+async function autoFixWithLLM(script: string, failureLog: string): Promise<string | null> {
+  try {
+    const prompt = buildAutoFixPrompt(script, failureLog);
+    const { result, isError } = await invokeClaudeStreaming(
+      { prompt, 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) as AutoFixAction[];
+    if (!Array.isArray(fixes) || fixes.length === 0) return null;
+
+    return applySleepFixes(script, fixes);
+  } catch {
+    return null;
+  }
+}
+
+function applySleepFixes(script: string, fixes: AutoFixAction[]): string {
+  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): f is SleepInsert => "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: string): Promise<{ exitCode: number; output: string; currentScript: string }> {
+  const proc = Bun.spawn(["bunx", "vitest", "run", scriptPath], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdoutText, stderrText, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  const currentScript = await Bun.file(scriptPath).text();
+
+  process.stdout.write(stdoutText);
+  if (stderrText) process.stderr.write(stderrText);
+  return { exitCode, output: stdoutText + stderrText, currentScript };
+}
+
+async function cleanupActions(actions: TraceAction[]): Promise<TraceAction[]> {
+  try {
+    const prompt = buildCleanupPrompt(actions);
+    const { result, isError } = await invokeClaudeStreaming(
+      { prompt, 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) as TraceAction[];
+    if (Array.isArray(parsed) && parsed.length > 0) return parsed;
+  } catch {
+    // Fall through
+  }
+  return actions;
+}

package/src/cli/generate.ts

@@ -0,0 +1,224 @@
+import { writeFile } from "node:fs/promises";
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  ensureCcqaDir,
+  parseSpecPath,
+  getTraceActions,
+  getSetupDir,
+  readSpecFile,
+  saveTestScript,
+} from "../store/index.ts";
+import { actionsToScript } from "../codegen/actions-to-script.ts";
+import type { SetupScript } from "../codegen/actions-to-script.ts";
+import { buildCleanupPrompt, buildAutoFixPrompt } from "../prompts/codegen.ts";
+import { invokeClaudeStreaming } from "../claude/invoke.ts";
+import { parseTestSpec } from "../spec/parser.ts";
+import type { TraceAction } from "../types.ts";
+import * as log from "./logger.ts";
+
+export 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: string, opts: { maxRetries: string }) => {
+    const { featureName, specName } = parseSpecPath(specPath);
+    await runGenerate(featureName, specName, parseInt(opts.maxRetries, 10));
+  });
+
+async function runGenerate(featureName: string, specName: string, maxRetries: number): Promise<void> {
+  log.header("generate", `${featureName}/${specName}`);
+
+  await ensureCcqaDir();
+
+  const { path: actionsPath, actions } = await getTraceActions(featureName, specName);
+
+  log.meta("trace", actionsPath);
+  log.meta("actions", actions.length);
+
+  // Load setup actions if test-spec references setups
+  const specContent = await readSpecFile(featureName, specName);
+  const spec = parseTestSpec(specContent);
+  const setupScripts = await loadSetupScripts(
+    spec.setups as Array<{ name: string; params?: Record<string, string> }> | undefined,
+  );
+  if (setupScripts.length > 0) {
+    log.meta("setups", setupScripts.map((s) => s.name).join(", "));
+  }
+  log.blank();
+
+  const cleanedActions = await cleanupActions(actions);
+  if (cleanedActions.length !== actions.length) {
+    log.meta("cleaned", cleanedActions.length);
+  }
+
+  const script = actionsToScript(cleanedActions, spec.title, setupScripts.length > 0 ? setupScripts : undefined);
+  const scriptPath = await saveTestScript(featureName, specName, script);
+  log.meta("saved", scriptPath);
+  log.blank();
+
+  let { exitCode, output, currentScript } = await runVitest(scriptPath);
+  if (exitCode === 0) {
+    log.hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+    return;
+  }
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    log.info(`auto-fix attempt ${attempt}/${maxRetries}...`);
+    log.blank();
+
+    const fixed = await autoFixWithLLM(currentScript, output);
+    if (!fixed) {
+      log.warn("could not determine fix from failure log");
+      break;
+    }
+
+    await writeFile(scriptPath, fixed, "utf-8");
+    log.meta("saved", scriptPath);
+    log.blank();
+
+    ({ exitCode, output, currentScript } = await runVitest(scriptPath));
+    if (exitCode === 0) {
+      log.hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+      return;
+    }
+  }
+
+  log.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?: Array<{ name: string; params?: Record<string, string> }>,
+): Promise<SetupScript[]> {
+  if (!setups?.length) return [];
+
+  const result: SetupScript[] = [];
+  for (const ref of setups) {
+    const scriptPath = join(getSetupDir(ref.name), "test.spec.ts");
+    const script = await readFile(scriptPath, "utf-8").catch(() => {
+      throw new Error(`Setup test script not found: ${scriptPath}. Run \`ccqa generate-setup ${ref.name}\` first.`);
+    });
+    const body = extractTestBody(script);
+    const resolved = replacePlaceholders(body, 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: string): string {
+  const lines = script.split("\n");
+  const startIdx = lines.findIndex((l) => /^\s*test\(/.test(l));
+  if (startIdx === -1) return "";
+  const bodyLines: string[] = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    // Match closing line: "}, N * 60 * 1000);" or "})" at the end of a test block
+    if (/^\s*\}[\s,);]/.test(lines[i]!)) break;
+    bodyLines.push(lines[i]!);
+  }
+  return bodyLines.join("\n");
+}
+
+function replacePlaceholders(body: string, params: Record<string, string>): string {
+  let result = body;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}
+
+// --- Auto-fix ---
+
+interface SleepInsert { line: number; seconds: number; reason: string }
+interface SleepIncrease { line: number; increase_to: number; reason: string }
+type AutoFixAction = SleepInsert | SleepIncrease;
+
+async function autoFixWithLLM(script: string, failureLog: string): Promise<string | null> {
+  try {
+    const prompt = buildAutoFixPrompt(script, failureLog);
+    const { result, isError } = await invokeClaudeStreaming(
+      { prompt, 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) as AutoFixAction[];
+    if (!Array.isArray(fixes) || fixes.length === 0) return null;
+
+    return applySleepFixes(script, fixes);
+  } catch {
+    return null;
+  }
+}
+
+function applySleepFixes(script: string, fixes: AutoFixAction[]): string {
+  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): f is SleepInsert => "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: string): Promise<{ exitCode: number; output: string; currentScript: string }> {
+  const proc = Bun.spawn(["bunx", "vitest", "run", scriptPath], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdoutText, stderrText, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  const currentScript = await Bun.file(scriptPath).text();
+
+  process.stdout.write(stdoutText);
+  if (stderrText) process.stderr.write(stderrText);
+  return { exitCode, output: stdoutText + stderrText, currentScript };
+}
+
+async function cleanupActions(actions: TraceAction[]): Promise<TraceAction[]> {
+  try {
+    const prompt = buildCleanupPrompt(actions);
+    const { result, isError } = await invokeClaudeStreaming(
+      { prompt, 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) as TraceAction[];
+    if (Array.isArray(parsed) && parsed.length > 0) return parsed;
+  } catch {
+    // Fall through
+  }
+  return actions;
+}

package/src/cli/index.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import { traceCommand } from "./trace.ts";
+import { generateCommand } from "./generate.ts";
+import { runCommand } from "./run.ts";
+import { traceSetupCommand } from "./trace-setup.ts";
+import { generateSetupCommand } from "./generate-setup.ts";
+
+const program = new Command();
+
+program
+  .name("ccqa")
+  .description("E2E test CLI using Claude Code + agent-browser")
+  .version("0.1.0");
+
+program.addCommand(traceCommand);
+program.addCommand(generateCommand);
+program.addCommand(runCommand);
+program.addCommand(traceSetupCommand);
+program.addCommand(generateSetupCommand);
+
+program.parse();