superghost 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superghost",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Plain English test cases with AI execution and instant cached replay for CI/CD",
   "type": "module",
   "bin": {
@@ -14,8 +14,10 @@
   "scripts": {
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check --write .",
     "build:binary": "bun run scripts/build-binaries.ts",
-    "prepublishOnly": "bun test && bunx tsc --noEmit",
+    "prepublishOnly": "bun run lint && bun test && bunx tsc --noEmit",
     "e2e": "bun run e2e/run-e2e.ts",
     "e2e:smoke": "bun run e2e/run-e2e.ts smoke",
     "e2e:browser": "bun run e2e/run-e2e.ts browser",
@@ -69,6 +71,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.4.6",
     "@types/bun": "^1.3.10",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/src/agent/agent-runner.ts

@@ -1,10 +1,11 @@
 import { generateText, Output, stepCountIs } from "ai";
 import { z } from "zod";
+
 import { StepRecorder } from "../cache/step-recorder.ts";
-import type { AgentExecutionResult } from "./types.ts";
-import { buildSystemPrompt } from "./prompt.ts";
 import { describeToolCall } from "../output/tool-name-map.ts";
-import type { OnStepProgress } from "../output/types.ts";
+import { type OnStepProgress } from "../output/types.ts";
+import { buildSystemPrompt } from "./prompt.ts";
+import { type AgentExecutionResult } from "./types.ts";
 
 /**
  * Schema for structured agent output.
@@ -12,9 +13,7 @@ import type { OnStepProgress } from "../output/types.ts";
  */
 const TestResultSchema = z.object({
   passed: z.boolean().describe("Whether the test case passed"),
-  message: z
-    .string()
-    .describe("Brief diagnostic: what happened and what the page showed"),
+  message: z.string().describe("Brief diagnostic: what happened and what the page showed"),
 });
 
 /**
@@ -40,12 +39,7 @@ export async function executeAgent(config: {
   const recorder = new StepRecorder();
   const wrappedTools = recorder.wrapTools(config.tools);
 
-  const systemPrompt = buildSystemPrompt(
-    config.testCase,
-    config.baseUrl,
-    config.globalContext,
-    config.testContext,
-  );
+  const systemPrompt = buildSystemPrompt(config.testCase, config.baseUrl, config.globalContext, config.testContext);
 
   let stepCounter = 0;
 
@@ -60,11 +54,8 @@ export async function executeAgent(config: {
       ? (event: any) => {
           if (event.success) {
             stepCounter++;
-            const input = (event.toolCall.input ?? {}) as Record<
-              string,
-              unknown
-            >;
-            config.onStepProgress!({
+            const input = (event.toolCall.input ?? {}) as Record<string, unknown>;
+            config.onStepProgress?.({
               stepNumber: stepCounter,
               toolName: event.toolCall.toolName,
               input,

package/src/agent/mcp-manager.ts

@@ -1,6 +1,7 @@
 import { createMCPClient } from "@ai-sdk/mcp";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import type { Config } from "../config/types.ts";
+
+import { type Config } from "../config/types.ts";
 import { getMcpCommand } from "../dist/paths.ts";
 
 /**
@@ -12,8 +13,7 @@ import { getMcpCommand } from "../dist/paths.ts";
  * regardless of test type.
  */
 export class McpManager {
-  private playwrightClient: Awaited<ReturnType<typeof createMCPClient>> | null =
-    null;
+  private playwrightClient: Awaited<ReturnType<typeof createMCPClient>> | null = null;
   private curlClient: Awaited<ReturnType<typeof createMCPClient>> | null = null;
 
   constructor(private readonly config: Pick<Config, "browser" | "headless">) {}
@@ -27,11 +27,7 @@ export class McpManager {
     const playwrightCmd = getMcpCommand("@playwright/mcp");
     const curlCmd = getMcpCommand("@calibress/curl-mcp");
 
-    const playwrightArgs = [
-      ...playwrightCmd.args,
-      "--isolated",
-      `--browser=${this.config.browser}`,
-    ];
+    const playwrightArgs = [...playwrightCmd.args, "--isolated", `--browser=${this.config.browser}`];
 
     if (this.config.headless) {
       playwrightArgs.splice(playwrightCmd.args.length, 0, "--headless");
@@ -57,8 +53,8 @@ export class McpManager {
    * Provides ALL tools to the agent regardless of test type.
    */
   async getTools(): Promise<Record<string, any>> {
-    const playwrightTools = await this.playwrightClient!.tools();
-    const curlTools = await this.curlClient!.tools();
+    const playwrightTools = await this.playwrightClient?.tools();
+    const curlTools = await this.curlClient?.tools();
     return { ...playwrightTools, ...curlTools };
   }
 
@@ -68,10 +64,7 @@ export class McpManager {
    * even if one fails to close.
    */
   async close(): Promise<void> {
-    await Promise.allSettled([
-      this.playwrightClient?.close(),
-      this.curlClient?.close(),
-    ]);
+    await Promise.allSettled([this.playwrightClient?.close(), this.curlClient?.close()]);
     this.playwrightClient = null;
     this.curlClient = null;
   }

package/src/agent/model-factory.ts

@@ -1,6 +1,6 @@
 import { anthropic } from "@ai-sdk/anthropic";
-import { openai } from "@ai-sdk/openai";
 import { google } from "@ai-sdk/google";
+import { openai } from "@ai-sdk/openai";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 
 /** Supported LLM provider names */

package/src/agent/types.ts

@@ -1,4 +1,4 @@
-import type { CachedStep } from "../cache/types.ts";
+import { type CachedStep } from "../cache/types.ts";
 
 /** Result of a single AI agent execution */
 export interface AgentExecutionResult {

package/src/cache/cache-manager.ts

@@ -1,6 +1,7 @@
+import { mkdir, readdir, rename } from "node:fs/promises";
 import { join } from "node:path";
-import { mkdir, rename, readdir } from "node:fs/promises";
-import type { CacheEntry, CachedStep } from "./types.ts";
+
+import { type CachedStep, type CacheEntry } from "./types.ts";
 
 /**
  * Manages file-based cache entries for test step recordings.
@@ -103,7 +104,7 @@ export class CacheManager {
     const filePath = join(this.cacheDir, `${hash}.json`);
 
     try {
-      return await Bun.file(filePath).json() as CacheEntry;
+      return (await Bun.file(filePath).json()) as CacheEntry;
     } catch {
       return null;
     }

package/src/cache/step-recorder.ts

@@ -1,4 +1,4 @@
-import type { CachedStep } from "./types.ts";
+import { type CachedStep } from "./types.ts";
 
 /**
  * Records MCP tool calls as CachedStep entries.

package/src/cache/step-replayer.ts

@@ -1,12 +1,9 @@
-import type { CachedStep } from "./types.ts";
-import type { OnStepProgress } from "../output/types.ts";
 import { describeToolCall } from "../output/tool-name-map.ts";
+import { type OnStepProgress } from "../output/types.ts";
+import { type CachedStep } from "./types.ts";
 
 /** Function signature for executing a tool by name with given input */
-export type ToolExecutor = (
-  toolName: string,
-  toolInput: Record<string, unknown>,
-) => Promise<string>;
+export type ToolExecutor = (toolName: string, toolInput: Record<string, unknown>) => Promise<string>;
 
 /** Result of replaying cached steps */
 export interface ReplayResult {

package/src/cli.ts

@@ -2,31 +2,31 @@
 
 import { Command } from "commander";
 import pc from "picocolors";
-import { loadConfig, ConfigLoadError } from "./config/loader.ts";
-import { TestRunner } from "./runner/test-runner.ts";
-import type { ExecuteFn } from "./runner/test-runner.ts";
-import { ConsoleReporter, writeStderr } from "./output/reporter.ts";
-import { ProcessManager } from "./infra/process-manager.ts";
-import { setupSignalHandlers } from "./infra/signals.ts";
+import picomatch from "picomatch";
+
+import pkg from "../package.json";
+import { executeAgent } from "./agent/agent-runner.ts";
 import { McpManager } from "./agent/mcp-manager.ts";
+import { createModel, inferProvider, type ProviderName, validateApiKey } from "./agent/model-factory.ts";
 import { CacheManager } from "./cache/cache-manager.ts";
-import { StepReplayer } from "./cache/step-replayer.ts";
-import type { ToolExecutor } from "./cache/step-replayer.ts";
-import { TestExecutor } from "./runner/test-executor.ts";
-import {
-  inferProvider,
-  validateApiKey,
-  createModel,
-} from "./agent/model-factory.ts";
-import type { ProviderName } from "./agent/model-factory.ts";
-import { executeAgent } from "./agent/agent-runner.ts";
-import type { OnStepProgress } from "./output/types.ts";
-import picomatch from "picomatch";
-import { checkBaseUrlReachable } from "./infra/preflight.ts";
+import { StepReplayer, type ToolExecutor } from "./cache/step-replayer.ts";
+import { ConfigLoadError, loadConfig } from "./config/loader.ts";
 import { isStandaloneBinary } from "./dist/paths.ts";
 import { ensureMcpDependencies } from "./dist/setup.ts";
+import { checkBaseUrlReachable } from "./infra/preflight.ts";
+import { ProcessManager } from "./infra/process-manager.ts";
+import { setupSignalHandlers } from "./infra/signals.ts";
 import { animateBanner } from "./output/banner.ts";
-import pkg from "../package.json";
+import {
+  formatJsonDryRun,
+  formatJsonError,
+  formatJsonOutput,
+  type JsonOutputMetadata,
+} from "./output/json-formatter.ts";
+import { ConsoleReporter, writeStderr } from "./output/reporter.ts";
+import { type OnStepProgress } from "./output/types.ts";
+import { TestExecutor } from "./runner/test-executor.ts";
+import { type ExecuteFn, TestRunner } from "./runner/test-runner.ts";
 
 /** Print the run header and any stacked annotations to stderr */
 function printRunHeader(testCount: number, totalTestCount: number | undefined, annotations: string[]): void {
@@ -48,6 +48,11 @@ function printRunHeader(testCount: number, totalTestCount: number | undefined, a
 
 const program = new Command();
 
+program.configureOutput({
+  writeOut: (str) => writeStderr(str.trimEnd()),
+  writeErr: (str) => writeStderr(str.trimEnd()),
+});
+
 program
   .name("superghost")
   .description("AI-powered end-to-end browser and API testing")
@@ -58,6 +63,7 @@ program
   .option("--no-cache", "Bypass cache reads (still writes on success)")
   .option("--dry-run", "List tests and validate config without executing")
   .option("--verbose", "Show per-step tool call output during execution")
+  .option("--output <format>", "Output format (json)")
   .exitOverride((err) => {
     // Commander writes its own error message to stderr.
     // Re-exit with code 2 for config-class errors (missing required option, unknown option).
@@ -65,167 +71,234 @@ program
       process.exit(2);
     }
   })
-  .action(async (options: { config: string; headed?: boolean; only?: string; cache: boolean; dryRun?: boolean; verbose?: boolean }) => {
-    const pm = new ProcessManager();
-    setupSignalHandlers(pm);
-
-    // Auto-install MCP dependencies for standalone binary on first run
-    if (isStandaloneBinary()) {
-      await ensureMcpDependencies();
-    }
+  .action(
+    async (options: {
+      config: string;
+      headed?: boolean;
+      only?: string;
+      cache: boolean;
+      dryRun?: boolean;
+      verbose?: boolean;
+      output?: string;
+    }) => {
+      const pm = new ProcessManager();
+      setupSignalHandlers(pm);
 
-    let mcpManager: McpManager | null = null;
+      // Validate --output format early
+      if (options.output && options.output !== "json") {
+        writeStderr(`${pc.red("Error:")} Unknown output format '${options.output}'. Supported: json`);
+        setTimeout(() => process.exit(2), 100);
+        return;
+      }
 
-    try {
-      const config = await loadConfig(options.config);
-      if (options.headed) {
-        config.headless = false;
+      // Auto-install MCP dependencies for standalone binary on first run
+      if (isStandaloneBinary()) {
+        await ensureMcpDependencies();
       }
-      const reporter = new ConsoleReporter(options.verbose ?? false);
-
-      // Infer provider: use explicit modelProvider unless it matches default and model suggests otherwise
-      const provider =
-        config.modelProvider === "anthropic"
-          ? inferProvider(config.model)
-          : (config.modelProvider as ProviderName);
-
-      // Validate API key at startup before any tests run
-      validateApiKey(provider);
-
-      // Apply --only filter before any expensive operations
-      const totalTestCount = config.tests.length;
-      if (options.only) {
-        const allTestNames = config.tests.map((t) => t.name);
-        const isMatch = picomatch(options.only, { nocase: true });
-        config.tests = config.tests.filter((t) => isMatch(t.name));
-
-        if (config.tests.length === 0) {
-          const names = allTestNames.map((n) => `  - ${n}`).join("\n");
-          writeStderr(`${pc.red("Error:")} No tests match pattern "${options.only}"\n\nAvailable tests:\n${names}`);
-          setTimeout(() => process.exit(2), 100);
+
+      let mcpManager: McpManager | null = null;
+
+      try {
+        const config = await loadConfig(options.config);
+        if (options.headed) {
+          config.headless = false;
+        }
+        const reporter = new ConsoleReporter(options.verbose ?? false);
+
+        // Infer provider: use explicit modelProvider unless it matches default and model suggests otherwise
+        const provider =
+          config.modelProvider === "anthropic" ? inferProvider(config.model) : (config.modelProvider as ProviderName);
+
+        // Validate API key at startup before any tests run
+        validateApiKey(provider);
+
+        // Apply --only filter before any expensive operations
+        const totalTestCount = config.tests.length;
+        if (options.only) {
+          const allTestNames = config.tests.map((t) => t.name);
+          const isMatch = picomatch(options.only, { nocase: true });
+          config.tests = config.tests.filter((t) => isMatch(t.name));
+
+          if (config.tests.length === 0) {
+            const names = allTestNames.map((n) => `  - ${n}`).join("\n");
+            writeStderr(`${pc.red("Error:")} No tests match pattern "${options.only}"\n\nAvailable tests:\n${names}`);
+            setTimeout(() => process.exit(2), 100);
+            return;
+          }
+        }
+
+        // Dry-run: list tests with cache/AI source labels, then exit
+        if (options.dryRun) {
+          const cacheManager = new CacheManager(config.cacheDir);
+
+          // Print header with annotations
+          const dryRunAnnotations = ["(dry-run)"];
+          if (options.only) dryRunAnnotations.push(`(filtered by --only "${options.only}")`);
+          printRunHeader(config.tests.length, options.only ? totalTestCount : undefined, dryRunAnnotations);
+
+          // Determine max test name length for padding
+          const maxNameLen = Math.max(...config.tests.map((t) => t.name.length));
+          let cachedCount = 0;
+          const dryRunTests: Array<{ name: string; case: string; source: "cache" | "ai" }> = [];
+
+          for (let i = 0; i < config.tests.length; i++) {
+            const test = config.tests[i];
+            const baseUrl = test.baseUrl ?? config.baseUrl ?? "";
+            const entry = await cacheManager.load(test.case, baseUrl);
+            const source: "cache" | "ai" = entry ? "cache" : "ai";
+            if (entry) cachedCount++;
+            dryRunTests.push({ name: test.name, case: test.case, source });
+
+            const paddedName = test.name.padEnd(maxNameLen);
+            writeStderr(`  ${i + 1}. ${paddedName}  (${source})`);
+          }
+
+          writeStderr("");
+          writeStderr(`${config.tests.length} tests, ${cachedCount} cached`);
+
+          // Write JSON to stdout when --output json is active
+          if (options.output === "json") {
+            const metadata: JsonOutputMetadata = {
+              model: config.model,
+              provider,
+              configFile: options.config,
+              baseUrl: config.baseUrl,
+              timestamp: new Date().toISOString(),
+              ...(options.only
+                ? { filter: { pattern: options.only, matched: config.tests.length, total: totalTestCount } }
+                : {}),
+            };
+            const testList = dryRunTests.map((t) => ({
+              name: t.name,
+              case: t.case,
+              source: t.source,
+            }));
+            const json = formatJsonDryRun(testList, metadata, pkg.version);
+            process.stdout.write(`${json}\n`);
+          }
+
+          setTimeout(() => process.exit(0), 100);
           return;
         }
-      }
 
-      // Dry-run: list tests with cache/AI source labels, then exit
-      if (options.dryRun) {
+        // Preflight: check baseUrl reachability (only if global baseUrl configured)
+        if (config.baseUrl) {
+          try {
+            await checkBaseUrlReachable(config.baseUrl);
+          } catch {
+            writeStderr(`${pc.red("Error:")} baseUrl unreachable: ${config.baseUrl}`);
+            writeStderr(`  Check that the server is running and the URL is correct.`);
+            setTimeout(() => process.exit(2), 100);
+            return;
+          }
+        }
+
+        // Create AI model
+        const model = createModel(config.model, provider);
+
+        // Initialize MCP servers (shared across test suite, not per-test)
+        mcpManager = new McpManager({
+          browser: config.browser,
+          headless: config.headless,
+        });
+        await mcpManager.initialize();
+        const tools = await mcpManager.getTools();
+
+        // Create cache subsystem
         const cacheManager = new CacheManager(config.cacheDir);
+        await cacheManager.migrateV1Cache();
+        const toolExecutor: ToolExecutor = async (toolName, toolInput) => {
+          const tool = tools[toolName];
+          if (!tool) throw new Error(`Tool not found: ${toolName}`);
+          return await tool.execute(toolInput);
+        };
+        const replayer = new StepReplayer(toolExecutor);
 
-        // Print header with annotations
-        const dryRunAnnotations = ["(dry-run)"];
-        if (options.only) dryRunAnnotations.push(`(filtered by --only "${options.only}")`);
-        printRunHeader(config.tests.length, options.only ? totalTestCount : undefined, dryRunAnnotations);
+        // Create onStepProgress callback bound to reporter
+        const onStepProgress: OnStepProgress = (step) => reporter.onStepProgress(step);
 
-        // Determine max test name length for padding
-        const maxNameLen = Math.max(...config.tests.map(t => t.name.length));
-        let cachedCount = 0;
+        // Create TestExecutor with cache-first strategy
+        const executor = new TestExecutor({
+          cacheManager,
+          replayer,
+          executeAgentFn: executeAgent,
+          model,
+          tools,
+          config,
+          globalContext: config.context,
+          noCache: !options.cache,
+          onStepProgress,
+        });
 
-        for (let i = 0; i < config.tests.length; i++) {
-          const test = config.tests[i];
-          const baseUrl = test.baseUrl ?? config.baseUrl ?? "";
-          const entry = await cacheManager.load(test.case, baseUrl);
-          const source = entry ? "cache" : "ai";
-          if (entry) cachedCount++;
+        // Wire execute function for TestRunner
+        const executeFn: ExecuteFn = async (testCase, baseUrl, testContext?) =>
+          executor.execute(testCase, baseUrl, testContext);
 
-          const paddedName = test.name.padEnd(maxNameLen);
-          writeStderr(`  ${i + 1}. ${paddedName}  (${source})`);
-        }
+        const runAnnotations: string[] = [];
+        if (options.only) runAnnotations.push(`(filtered by --only "${options.only}")`);
+        if (!options.cache) runAnnotations.push("(cache disabled)");
+        if (options.verbose) runAnnotations.push("(verbose)");
+        printRunHeader(config.tests.length, options.only ? totalTestCount : undefined, runAnnotations);
 
-        writeStderr("");
-        writeStderr(`${config.tests.length} tests, ${cachedCount} cached`);
+        const runner = new TestRunner(config, reporter, executeFn);
+        const result = await runner.run();
+        result.skipped = options.only ? totalTestCount - config.tests.length : 0;
 
-        setTimeout(() => process.exit(0), 100);
-        return;
-      }
+        await mcpManager.close();
+        await pm.killAll();
+        const code = result.failed > 0 ? 1 : 0;
 
-      // Preflight: check baseUrl reachability (only if global baseUrl configured)
-      if (config.baseUrl) {
-        try {
-          await checkBaseUrlReachable(config.baseUrl);
-        } catch {
-          writeStderr(`${pc.red("Error:")} baseUrl unreachable: ${config.baseUrl}`);
-          writeStderr(`  Check that the server is running and the URL is correct.`);
-          setTimeout(() => process.exit(2), 100);
-          return;
+        // Write JSON to stdout when --output json is active
+        if (options.output === "json") {
+          const metadata: JsonOutputMetadata = {
+            model: config.model,
+            provider,
+            configFile: options.config,
+            baseUrl: config.baseUrl,
+            timestamp: new Date().toISOString(),
+            ...(options.only
+              ? { filter: { pattern: options.only, matched: config.tests.length, total: totalTestCount } }
+              : {}),
+          };
+          const json = formatJsonOutput(result, metadata, pkg.version, code);
+          process.stdout.write(`${json}\n`);
         }
-      }
 
-      // Create AI model
-      const model = createModel(config.model, provider);
-
-      // Initialize MCP servers (shared across test suite, not per-test)
-      mcpManager = new McpManager({
-        browser: config.browser,
-        headless: config.headless,
-      });
-      await mcpManager.initialize();
-      const tools = await mcpManager.getTools();
-
-      // Create cache subsystem
-      const cacheManager = new CacheManager(config.cacheDir);
-      await cacheManager.migrateV1Cache();
-      const toolExecutor: ToolExecutor = async (toolName, toolInput) => {
-        const tool = tools[toolName];
-        if (!tool) throw new Error(`Tool not found: ${toolName}`);
-        return await tool.execute(toolInput);
-      };
-      const replayer = new StepReplayer(toolExecutor);
-
-      // Create onStepProgress callback bound to reporter
-      const onStepProgress: OnStepProgress = (step) => reporter.onStepProgress(step);
-
-      // Create TestExecutor with cache-first strategy
-      const executor = new TestExecutor({
-        cacheManager,
-        replayer,
-        executeAgentFn: executeAgent,
-        model,
-        tools,
-        config,
-        globalContext: config.context,
-        noCache: !options.cache,
-        onStepProgress,
-      });
-
-      // Wire execute function for TestRunner
-      const executeFn: ExecuteFn = async (testCase, baseUrl, testContext?) =>
-        executor.execute(testCase, baseUrl, testContext);
-
-      const runAnnotations: string[] = [];
-      if (options.only) runAnnotations.push(`(filtered by --only "${options.only}")`);
-      if (!options.cache) runAnnotations.push("(cache disabled)");
-      if (options.verbose) runAnnotations.push("(verbose)");
-      printRunHeader(config.tests.length, options.only ? totalTestCount : undefined, runAnnotations);
-
-      const runner = new TestRunner(config, reporter, executeFn);
-      const result = await runner.run();
-      result.skipped = options.only ? totalTestCount - config.tests.length : 0;
-
-      await mcpManager.close();
-      await pm.killAll();
-      const code = result.failed > 0 ? 1 : 0;
-      setTimeout(() => process.exit(code), 100);
-    } catch (error) {
-      if (mcpManager) {
-        await mcpManager.close().catch(() => {});
-      }
-      await pm.killAll();
+        setTimeout(() => process.exit(code), 100);
+      } catch (error) {
+        if (mcpManager) {
+          await mcpManager.close().catch(() => {});
+        }
+        await pm.killAll();
 
-      if (error instanceof ConfigLoadError) {
-        writeStderr(`${pc.red("Error:")} ${error.message}`);
-        setTimeout(() => process.exit(2), 100);
-        return;
-      }
-      if (error instanceof Error && error.message.startsWith("Missing API key")) {
-        writeStderr(`${pc.red("Error:")} ${error.message}`);
+        if (error instanceof ConfigLoadError) {
+          writeStderr(`${pc.red("Error:")} ${error.message}`);
+          if (options.output === "json") {
+            const json = formatJsonError(error.message, pkg.version, { configFile: options.config });
+            process.stdout.write(`${json}\n`);
+          }
+          setTimeout(() => process.exit(2), 100);
+          return;
+        }
+        if (error instanceof Error && error.message.startsWith("Missing API key")) {
+          writeStderr(`${pc.red("Error:")} ${error.message}`);
+          if (options.output === "json") {
+            const json = formatJsonError(error.message, pkg.version, { configFile: options.config });
+            process.stdout.write(`${json}\n`);
+          }
+          setTimeout(() => process.exit(2), 100);
+          return;
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        writeStderr(`${pc.red("Unexpected error:")} ${msg}`);
+        if (options.output === "json") {
+          const json = formatJsonError(msg, pkg.version, { configFile: options.config });
+          process.stdout.write(`${json}\n`);
+        }
         setTimeout(() => process.exit(2), 100);
-        return;
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      writeStderr(`${pc.red("Unexpected error:")} ${msg}`);
-      setTimeout(() => process.exit(2), 100);
-    }
-  });
+    },
+  );
 
 (async () => {
   const isHelpRequest = process.argv.includes("--help") || process.argv.includes("-h");

package/src/config/loader.ts

@@ -1,6 +1,7 @@
 import { YAML } from "bun";
+
 import { ConfigSchema } from "./schema.ts";
-import type { Config } from "./types.ts";
+import { type Config } from "./types.ts";
 
 /** Error thrown when config loading or validation fails */
 export class ConfigLoadError extends Error {
@@ -39,8 +40,7 @@ export async function loadConfig(filePath: string): Promise<Config> {
       );
     }
     throw new ConfigLoadError(
-      `Cannot read config file: ${filePath}\n` +
-        `  ${error instanceof Error ? error.message : String(error)}`,
+      `Cannot read config file: ${filePath}\n` + `  ${error instanceof Error ? error.message : String(error)}`,
       error,
     );
   }
@@ -50,10 +50,7 @@ export async function loadConfig(filePath: string): Promise<Config> {
   try {
     raw = YAML.parse(content);
   } catch (error) {
-    throw new ConfigLoadError(
-      `Invalid YAML syntax: ${error instanceof Error ? error.message : String(error)}`,
-      error,
-    );
+    throw new ConfigLoadError(`Invalid YAML syntax: ${error instanceof Error ? error.message : String(error)}`, error);
   }
 
   // Layer 3: Zod validation
@@ -61,15 +58,10 @@ export async function loadConfig(filePath: string): Promise<Config> {
   const result = ConfigSchema.safeParse(raw);
   if (!result.success) {
     const issues = result.error.issues
-      .map(
-        (issue, i) =>
-          `  ${i + 1}. ${issue.path.join(".")}: ${issue.message}`,
-      )
+      .map((issue, i) => `  ${i + 1}. ${issue.path.join(".")}: ${issue.message}`)
       .join("\n");
     const count = result.error.issues.length;
-    throw new ConfigLoadError(
-      `Invalid config (${count} issue${count > 1 ? "s" : ""})\n${issues}`,
-    );
+    throw new ConfigLoadError(`Invalid config (${count} issue${count > 1 ? "s" : ""})\n${issues}`);
   }
 
   return result.data;

package/src/config/types.ts

@@ -1,5 +1,6 @@
-import type { z } from "zod";
-import type { ConfigSchema, TestCaseSchema } from "./schema.ts";
+import { type z } from "zod";
+
+import { type ConfigSchema, type TestCaseSchema } from "./schema.ts";
 
 /** A single test case parsed from the config YAML */
 export type TestCase = z.infer<typeof TestCaseSchema>;

package/src/infra/process-manager.ts

@@ -1,4 +1,4 @@
-import type { Subprocess } from "bun";
+import { type Subprocess } from "bun";
 
 /**
  * Tracks spawned subprocesses and ensures cleanup on shutdown.
@@ -25,7 +25,11 @@ export class ProcessManager {
             proc.kill("SIGKILL");
           }
         }, 5000);
-        try { await proc.exited; } finally { clearTimeout(timeout); }
+        try {
+          await proc.exited;
+        } finally {
+          clearTimeout(timeout);
+        }
       }
     });
     await Promise.allSettled(kills);

package/src/infra/signals.ts

@@ -1,4 +1,4 @@
-import type { ProcessManager } from "./process-manager.ts";
+import { type ProcessManager } from "./process-manager.ts";
 
 /**
  * Register SIGINT and SIGTERM handlers that clean up all tracked subprocesses.

package/src/output/banner.ts

@@ -21,11 +21,7 @@ function rainbowLine(text: string, hueOffset: number): string {
 }
 
 const TITLE = "  Super Ghost  ";
-const BANNER_LINES = [
-  `   👻${TITLE}👻`,
-  `  ─────────────────────`,
-  `  AI-powered E2E testing`,
-];
+const BANNER_LINES = [`   👻${TITLE}👻`, `  ─────────────────────`, `  AI-powered E2E testing`];
 
 function renderBanner(hueOffset: number): string[] {
   return [
@@ -40,31 +36,31 @@ const FRAME_MS = 60;
 const HUE_STEP = 24;
 
 export async function animateBanner(): Promise<void> {
-  const isTTY = process.stdout.isTTY === true;
+  const isTTY = process.stderr.isTTY === true;
 
   if (!isTTY) {
     const lines = BANNER_LINES;
-    process.stdout.write(lines.join("\n") + "\n\n");
+    process.stderr.write(`${lines.join("\n")}\n\n`);
     return;
   }
 
-  process.stdout.write("\x1b[?25l"); // hide cursor
+  process.stderr.write("\x1b[?25l"); // hide cursor
 
   try {
     for (let frame = 0; frame < FRAMES; frame++) {
       const lines = renderBanner(frame * HUE_STEP);
       if (frame > 0) {
         // Move cursor up N lines to overwrite previous frame
-        process.stdout.write(`\x1b[${lines.length}A`);
+        process.stderr.write(`\x1b[${lines.length}A`);
       }
-      process.stdout.write(lines.join("\n") + "\n");
+      process.stderr.write(`${lines.join("\n")}\n`);
 
       if (frame < FRAMES - 1) {
         await new Promise<void>((resolve) => setTimeout(resolve, FRAME_MS));
       }
     }
-    process.stdout.write("\n");
+    process.stderr.write("\n");
   } finally {
-    process.stdout.write("\x1b[?25h"); // restore cursor
+    process.stderr.write("\x1b[?25h"); // restore cursor
   }
 }

package/src/output/json-formatter.ts

@@ -0,0 +1,150 @@
+import { type RunResult } from "../runner/types.ts";
+
+/** Metadata about the test run environment and configuration */
+export interface JsonOutputMetadata {
+  model: string;
+  provider: string;
+  configFile: string;
+  baseUrl: string | undefined;
+  timestamp: string;
+  filter?: {
+    pattern: string;
+    matched: number;
+    total: number;
+  };
+}
+
+/** Top-level JSON output structure for all output modes */
+export interface JsonOutput {
+  version: string;
+  success: boolean;
+  exitCode: number;
+  dryRun?: boolean;
+  error?: string;
+  metadata: JsonOutputMetadata;
+  summary: {
+    passed: number;
+    failed: number;
+    cached: number;
+    skipped: number;
+    total?: number;
+    totalDurationMs?: number;
+  };
+  tests: Array<{
+    testName: string;
+    testCase: string;
+    status?: string;
+    source: string;
+    durationMs?: number;
+    selfHealed?: boolean;
+    error?: string;
+  }>;
+}
+
+/**
+ * Format a completed run result as JSON.
+ * Only includes selfHealed when true, only includes error when present.
+ */
+export function formatJsonOutput(
+  runResult: RunResult,
+  metadata: JsonOutputMetadata,
+  version: string,
+  exitCode: number,
+): string {
+  const output: JsonOutput = {
+    version,
+    success: exitCode === 0,
+    exitCode,
+    metadata,
+    summary: {
+      passed: runResult.passed,
+      failed: runResult.failed,
+      cached: runResult.cached,
+      skipped: runResult.skipped,
+      totalDurationMs: runResult.totalDurationMs,
+    },
+    tests: runResult.results.map((r) => {
+      const entry: Record<string, unknown> = {
+        testName: r.testName,
+        testCase: r.testCase,
+        status: r.status,
+        source: r.source,
+        durationMs: r.durationMs,
+      };
+      if (r.selfHealed === true) {
+        entry.selfHealed = true;
+      }
+      if (r.error !== undefined) {
+        entry.error = r.error;
+      }
+      return entry as JsonOutput["tests"][number];
+    }),
+  };
+
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Format a dry-run test listing as JSON.
+ * Produces dryRun: true, exitCode: 0, success: true.
+ */
+export function formatJsonDryRun(
+  tests: Array<{ name: string; case: string; source: "cache" | "ai" }>,
+  metadata: JsonOutputMetadata,
+  version: string,
+): string {
+  const cachedCount = tests.filter((t) => t.source === "cache").length;
+
+  const output: JsonOutput = {
+    version,
+    success: true,
+    exitCode: 0,
+    dryRun: true,
+    metadata,
+    summary: {
+      passed: 0,
+      failed: 0,
+      cached: cachedCount,
+      skipped: 0,
+      total: tests.length,
+    },
+    tests: tests.map((t) => ({
+      testName: t.name,
+      testCase: t.case,
+      source: t.source,
+    })),
+  };
+
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Format an error condition as JSON.
+ * Produces success: false, exitCode: 2, with the error message.
+ */
+export function formatJsonError(errorMessage: string, version: string, metadata: Partial<JsonOutputMetadata>): string {
+  const fullMetadata: JsonOutputMetadata = {
+    model: metadata.model ?? "",
+    provider: metadata.provider ?? "",
+    configFile: metadata.configFile ?? "",
+    baseUrl: metadata.baseUrl,
+    timestamp: metadata.timestamp ?? new Date().toISOString(),
+  };
+
+  const output: JsonOutput = {
+    version,
+    success: false,
+    exitCode: 2,
+    error: errorMessage,
+    metadata: fullMetadata,
+    summary: {
+      passed: 0,
+      failed: 0,
+      cached: 0,
+      skipped: 0,
+    },
+    tests: [],
+  };
+
+  return JSON.stringify(output, null, 2);
+}

package/src/output/reporter.ts

@@ -1,7 +1,8 @@
-import pc from "picocolors";
 import { createSpinner } from "nanospinner";
-import type { Reporter, StepInfo } from "./types.ts";
-import type { TestResult, RunResult } from "../runner/types.ts";
+import pc from "picocolors";
+
+import { type RunResult, type TestResult } from "../runner/types.ts";
+import { type Reporter, type StepInfo } from "./types.ts";
 
 /**
  * Format milliseconds as a human-readable duration string.
@@ -16,7 +17,7 @@ export function formatDuration(ms: number): string {
 
 /** Write a line of text to stderr */
 export function writeStderr(text: string): void {
-  Bun.write(Bun.stderr, text + "\n");
+  Bun.write(Bun.stderr, `${text}\n`);
 }
 
 /**
@@ -64,7 +65,7 @@ export class ConsoleReporter implements Reporter {
     } else if (this.spinner) {
       let spinnerText = `${this.currentTestName} \u2014 ${step.description.full}`;
       if (spinnerText.length > 60) {
-        spinnerText = spinnerText.slice(0, 57) + "...";
+        spinnerText = `${spinnerText.slice(0, 57)}...`;
       }
       this.spinner.update(spinnerText);
     }
@@ -79,9 +80,7 @@ export class ConsoleReporter implements Reporter {
     writeStderr(`  ${bar}`);
     writeStderr(`    Total:   ${data.results.length}`);
     writeStderr(`    Passed:  ${pc.green(String(data.passed))}`);
-    writeStderr(
-      `    Failed:  ${data.failed > 0 ? pc.red(String(data.failed)) : String(data.failed)}`,
-    );
+    writeStderr(`    Failed:  ${data.failed > 0 ? pc.red(String(data.failed)) : String(data.failed)}`);
     if (data.skipped > 0) {
       writeStderr(`    Skipped: ${data.skipped}`);
     }

package/src/output/tool-name-map.ts

@@ -1,4 +1,4 @@
-import type { StepDescription } from "./types.ts";
+import { type StepDescription } from "./types.ts";
 
 /** Maps raw MCP tool names to human-readable action names */
 const PREFIX_MAP: Record<string, string> = {
@@ -46,24 +46,15 @@ const KEY_ARG_MAP: Record<string, string> = {
  * Unknown tools fall back to: strip underscores, capitalize first letter.
  * Key arguments are extracted based on tool type (e.g., "url" for navigate).
  */
-export function describeToolCall(
-  toolName: string,
-  input: Record<string, unknown>,
-): StepDescription {
+export function describeToolCall(toolName: string, input: Record<string, unknown>): StepDescription {
   // Look up human name, or derive from raw name as fallback
-  const action =
-    PREFIX_MAP[toolName] ??
-    toolName
-      .replace(/_/g, " ")
-      .replace(/^\w/, (c) => c.toUpperCase());
+  const action = PREFIX_MAP[toolName] ?? toolName.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase());
 
   // Look up which input field is the key argument for this tool
   const keyArgField = KEY_ARG_MAP[toolName];
   const rawKeyArg = keyArgField ? input[keyArgField] : undefined;
   const keyArg =
-    rawKeyArg !== undefined && rawKeyArg !== null && String(rawKeyArg) !== ""
-      ? String(rawKeyArg)
-      : undefined;
+    rawKeyArg !== undefined && rawKeyArg !== null && String(rawKeyArg) !== "" ? String(rawKeyArg) : undefined;
 
   const full = keyArg ? `${action} \u2192 ${keyArg}` : action;
 

package/src/output/types.ts

@@ -1,4 +1,4 @@
-import type { RunResult, TestResult } from "../runner/types.ts";
+import { type RunResult, type TestResult } from "../runner/types.ts";
 
 /** Describes a tool call in human-readable form */
 export interface StepDescription {

package/src/runner/test-executor.ts

@@ -1,9 +1,9 @@
-import type { CacheManager } from "../cache/cache-manager.ts";
-import type { StepReplayer } from "../cache/step-replayer.ts";
-import type { AgentExecutionResult } from "../agent/types.ts";
-import type { Config } from "../config/types.ts";
-import type { TestResult } from "./types.ts";
-import type { OnStepProgress } from "../output/types.ts";
+import { type AgentExecutionResult } from "../agent/types.ts";
+import { type CacheManager } from "../cache/cache-manager.ts";
+import { type StepReplayer } from "../cache/step-replayer.ts";
+import { type Config } from "../config/types.ts";
+import { type OnStepProgress } from "../output/types.ts";
+import { type TestResult } from "./types.ts";
 
 /** Function signature for executing a test via the AI agent */
 type ExecuteAgentFn = (config: {
@@ -29,10 +29,9 @@ export class TestExecutor {
   private readonly executeAgentFn: ExecuteAgentFn;
   private readonly model: any;
   private readonly tools: Record<string, any>;
-  private readonly config: Pick<
-    Config,
-    "maxAttempts" | "recursionLimit" | "model" | "modelProvider"
-  > & { context?: string };
+  private readonly config: Pick<Config, "maxAttempts" | "recursionLimit" | "model" | "modelProvider"> & {
+    context?: string;
+  };
   private readonly globalContext?: string;
   private readonly noCache: boolean;
   private readonly onStepProgress?: OnStepProgress;
@@ -43,10 +42,7 @@ export class TestExecutor {
     executeAgentFn: ExecuteAgentFn;
     model?: any;
     tools?: Record<string, any>;
-    config: Pick<
-      Config,
-      "maxAttempts" | "recursionLimit" | "model" | "modelProvider"
-    > & { context?: string };
+    config: Pick<Config, "maxAttempts" | "recursionLimit" | "model" | "modelProvider"> & { context?: string };
     globalContext?: string;
     noCache?: boolean;
     onStepProgress?: OnStepProgress;
@@ -63,11 +59,7 @@ export class TestExecutor {
   }
 
   /** Execute a single test case with cache-first strategy */
-  async execute(
-    testCase: string,
-    baseUrl: string,
-    testContext?: string,
-  ): Promise<TestResult> {
+  async execute(testCase: string, baseUrl: string, testContext?: string): Promise<TestResult> {
     const start = Date.now();
 
     // Phase 1: Try cache replay (unless noCache)

package/src/runner/test-runner.ts

@@ -1,13 +1,9 @@
-import type { Config } from "../config/types.ts";
-import type { Reporter } from "../output/types.ts";
-import type { TestResult, RunResult } from "./types.ts";
+import { type Config } from "../config/types.ts";
+import { type Reporter } from "../output/types.ts";
+import { type RunResult, type TestResult } from "./types.ts";
 
 /** Function signature for executing a single test case */
-export type ExecuteFn = (
-  testCase: string,
-  baseUrl: string,
-  testContext?: string,
-) => Promise<TestResult>;
+export type ExecuteFn = (testCase: string, baseUrl: string, testContext?: string) => Promise<TestResult>;
 
 /**
  * Orchestrates sequential execution of all test cases.
@@ -50,18 +46,13 @@ export class TestRunner {
 }
 
 /** Aggregate individual test results into a run summary */
-function aggregateResults(
-  results: TestResult[],
-  totalDurationMs: number,
-): RunResult {
+function aggregateResults(results: TestResult[], totalDurationMs: number): RunResult {
   return {
     results,
     totalDurationMs,
     passed: results.filter((r) => r.status === "passed").length,
     failed: results.filter((r) => r.status === "failed").length,
-    cached: results.filter(
-      (r) => r.source === "cache" && r.status === "passed",
-    ).length,
+    cached: results.filter((r) => r.source === "cache" && r.status === "passed").length,
     skipped: 0,
   };
 }