superghost 0.1.1 → 0.3.0

package/src/cli.ts

@@ -2,129 +2,308 @@
 
 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 } 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 { 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 pkg from "../package.json";
+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 {
+  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 {
+  let header = `\n${pc.bold("superghost")} v${pkg.version} / Running ${testCount}`;
+  if (totalTestCount !== undefined) {
+    header += ` of ${totalTestCount}`;
+  }
+  header += ` test(s)...`;
+  writeStderr(header);
+  writeStderr("");
+
+  for (const annotation of annotations) {
+    writeStderr(pc.dim(`  ${annotation}`));
+  }
+  if (annotations.length > 0) {
+    writeStderr("");
+  }
+}
 
 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")
   .version(pkg.version)
   .requiredOption("-c, --config <path>", "Path to YAML config file")
   .option("--headed", "Run browser in headed mode (visible browser window)")
-  .action(async (options: { config: string; headed?: boolean }) => {
-    const pm = new ProcessManager();
-    setupSignalHandlers(pm);
-
-    // Auto-install MCP dependencies for standalone binary on first run
-    if (isStandaloneBinary()) {
-      await ensureMcpDependencies();
+  .option("--only <pattern>", "Run only tests matching glob pattern")
+  .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).
+    if (err.exitCode !== 0) {
+      process.exit(2);
     }
+  })
+  .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;
-
-    try {
-      const config = await loadConfig(options.config);
-      if (options.headed) {
-        config.headless = false;
-      }
-      const reporter = new ConsoleReporter();
-
-      // 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);
-
-      // 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);
-      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 TestExecutor with cache-first strategy
-      const executor = new TestExecutor({
-        cacheManager,
-        replayer,
-        executeAgentFn: executeAgent,
-        model,
-        tools,
-        config,
-        globalContext: config.context,
-      });
-
-      // Wire execute function for TestRunner
-      const executeFn: ExecuteFn = async (testCase, baseUrl, testContext?) =>
-        executor.execute(testCase, baseUrl, testContext);
-
-      console.log(
-        `\n${pc.bold("superghost")} v${pkg.version} / Running ${config.tests.length} test(s)...\n`,
-      );
-
-      const runner = new TestRunner(config, reporter, executeFn);
-      const result = await runner.run();
-
-      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(() => {});
+      // 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;
       }
-      await pm.killAll();
 
-      if (error instanceof ConfigLoadError) {
-        Bun.write(Bun.stderr, `${pc.red("Error:")} ${error.message}\n`);
-        setTimeout(() => process.exit(1), 100);
-        return;
+      // Auto-install MCP dependencies for standalone binary on first run
+      if (isStandaloneBinary()) {
+        await ensureMcpDependencies();
       }
-      if (error instanceof Error && error.message.startsWith("Missing API key")) {
-        Bun.write(Bun.stderr, `${pc.red("Error:")} ${error.message}\n`);
-        setTimeout(() => process.exit(1), 100);
-        return;
+
+      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;
+        }
+
+        // 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);
+
+        // 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;
+
+        // 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`);
+        }
+
+        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}`);
+          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);
       }
-      throw error;
-    }
-  });
+    },
+  );
 
 (async () => {
+  const isHelpRequest = process.argv.includes("--help") || process.argv.includes("-h");
+  if (isHelpRequest) {
+    await animateBanner();
+  }
   await program.parseAsync();
 })();

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/preflight.ts

@@ -0,0 +1,13 @@
+/**
+ * Preflight reachability check for baseUrl.
+ *
+ * Resolves on ANY HTTP response (even 4xx/5xx -- those prove the server is reachable).
+ * Throws on network-level failures: connection refused, DNS failure, timeout.
+ */
+export async function checkBaseUrlReachable(url: string, timeoutMs = 5000): Promise<void> {
+  await fetch(url, {
+    method: "HEAD",
+    signal: AbortSignal.timeout(timeoutMs),
+    redirect: "follow",
+  });
+}

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

@@ -0,0 +1,66 @@
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  s /= 100;
+  l /= 100;
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+}
+
+function colorChar(char: string, hue: number): string {
+  const [r, g, b] = hslToRgb(hue % 360, 100, 60);
+  return `\x1b[38;2;${r};${g};${b}m${char}\x1b[0m`;
+}
+
+function rainbowLine(text: string, hueOffset: number): string {
+  const hueStep = 360 / text.length;
+  return text
+    .split("")
+    .map((char, i) => colorChar(char, (hueOffset + i * hueStep) % 360))
+    .join("");
+}
+
+const TITLE = "  Super Ghost  ";
+const BANNER_LINES = [`   👻${TITLE}👻`, `  ─────────────────────`, `  AI-powered E2E testing`];
+
+function renderBanner(hueOffset: number): string[] {
+  return [
+    `   👻${rainbowLine(TITLE, hueOffset)}👻`,
+    `  \x1b[2m─────────────────────\x1b[0m`,
+    `  \x1b[2mAI-powered E2E testing\x1b[0m`,
+  ];
+}
+
+const FRAMES = 15;
+const FRAME_MS = 60;
+const HUE_STEP = 24;
+
+export async function animateBanner(): Promise<void> {
+  const isTTY = process.stderr.isTTY === true;
+
+  if (!isTTY) {
+    const lines = BANNER_LINES;
+    process.stderr.write(`${lines.join("\n")}\n\n`);
+    return;
+  }
+
+  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.stderr.write(`\x1b[${lines.length}A`);
+      }
+      process.stderr.write(`${lines.join("\n")}\n`);
+
+      if (frame < FRAMES - 1) {
+        await new Promise<void>((resolve) => setTimeout(resolve, FRAME_MS));
+      }
+    }
+    process.stderr.write("\n");
+  } finally {
+    process.stderr.write("\x1b[?25h"); // restore cursor
+  }
+}