superghost 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superghost",
-  "version": "0.1.1",
+  "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",
@@ -60,13 +62,16 @@
     "@ai-sdk/openai": "^3.0.41",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@openrouter/ai-sdk-provider": "^2.2.5",
+    "@types/picomatch": "^4.0.2",
     "ai": "^6.0.116",
     "commander": "^14.0.3",
     "nanospinner": "^1.2.2",
     "picocolors": "^1.1.1",
+    "picomatch": "^4.0.3",
     "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,8 +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 { describeToolCall } from "../output/tool-name-map.ts";
+import { type OnStepProgress } from "../output/types.ts";
 import { buildSystemPrompt } from "./prompt.ts";
+import { type AgentExecutionResult } from "./types.ts";
 
 /**
  * Schema for structured agent output.
@@ -10,9 +13,7 @@ import { buildSystemPrompt } from "./prompt.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"),
 });
 
 /**
@@ -33,16 +34,14 @@ export async function executeAgent(config: {
   recursionLimit: number;
   globalContext?: string;
   testContext?: string;
+  onStepProgress?: OnStepProgress;
 }): Promise<AgentExecutionResult> {
   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;
 
   const { output } = await generateText({
     model: config.model,
@@ -51,6 +50,20 @@ export async function executeAgent(config: {
     prompt: `Execute the test case: "${config.testCase}"`,
     stopWhen: stepCountIs(config.recursionLimit),
     output: Output.object({ schema: TestResultSchema }),
+    experimental_onToolCallFinish: config.onStepProgress
+      ? (event: any) => {
+          if (event.success) {
+            stepCounter++;
+            const input = (event.toolCall.input ?? {}) as Record<string, unknown>;
+            config.onStepProgress?.({
+              stepNumber: stepCounter,
+              toolName: event.toolCall.toolName,
+              input,
+              description: describeToolCall(event.toolCall.toolName, input),
+            });
+          }
+        }
+      : undefined,
   });
 
   if (output === null) {

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,5 +1,4 @@
-import type { CachedStep } from "../cache/types.ts";
-import type { ProviderName } from "./model-factory.ts";
+import { type CachedStep } from "../cache/types.ts";
 
 /** Result of a single AI agent execution */
 export interface AgentExecutionResult {
@@ -10,19 +9,3 @@ export interface AgentExecutionResult {
   /** Recorded tool call steps for caching */
   steps: CachedStep[];
 }
-
-/** Configuration for a single agent run */
-export interface AgentConfig {
-  /** Model identifier (e.g., "claude-sonnet-4-6", "gpt-4o") */
-  model: string;
-  /** LLM provider */
-  provider: ProviderName;
-  /** Maximum number of agent steps */
-  recursionLimit: number;
-  /** Plain English test case description */
-  testCase: string;
-  /** Base URL for the application under test */
-  baseUrl: string;
-  /** Optional per-test context appended to system prompt */
-  context?: string;
-}

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 } 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.
@@ -17,9 +18,30 @@ export class CacheManager {
   /**
    * Generate a deterministic 16-char hex hash key.
    * Uses Bun-native CryptoHasher for SHA-256 hashing.
+   *
+   * Normalization pipeline (v2):
+   * 1. Unicode NFC normalization + whitespace collapse (case-preserving)
+   * 2. URL normalization (lowercase hostname, strip trailing slash)
+   * 3. Version-prefixed input string ("v2|...")
    */
   static hashKey(testCase: string, baseUrl: string): string {
-    const input = `${testCase}|${baseUrl}`;
+    // Step 1: Unicode NFC + whitespace collapse (case-preserving per user decision)
+    const normalizedCase = testCase.normalize("NFC").replace(/\s+/g, " ").trim();
+
+    // Step 2: URL normalization (lowercase hostname, strip trailing slash)
+    let normalizedUrl: string;
+    try {
+      const url = new URL(baseUrl);
+      // new URL() lowercases hostname and strips default ports
+      // Manually strip trailing slash(es)
+      normalizedUrl = url.href.replace(/\/+$/, "");
+    } catch {
+      // Fallback for non-URL values (defensive)
+      normalizedUrl = baseUrl.replace(/\/+$/, "").toLowerCase();
+    }
+
+    // Step 3: Version-prefixed input
+    const input = `v2|${normalizedCase}|${normalizedUrl}`;
     const hasher = new Bun.CryptoHasher("sha256");
     hasher.update(input);
     return hasher.digest("hex").slice(0, 16);
@@ -52,7 +74,7 @@ export class CacheManager {
     const existing = await this.load(testCase, baseUrl);
 
     const entry: CacheEntry = {
-      version: 1,
+      version: 2,
       testCase,
       baseUrl,
       steps,
@@ -82,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;
     }
@@ -102,4 +124,29 @@ export class CacheManager {
       // No-op if file doesn't exist
     }
   }
+
+  /**
+   * Migrate v1 cache entries by deleting them.
+   * Scans the cache directory for JSON files with version 1 and removes them.
+   * v2 entries are preserved. Handles missing/empty cache directories gracefully.
+   */
+  async migrateV1Cache(): Promise<void> {
+    try {
+      const files = await readdir(this.cacheDir);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        try {
+          const filePath = join(this.cacheDir, file);
+          const entry = await Bun.file(filePath).json();
+          if (entry?.version === 1) {
+            await Bun.file(filePath).delete();
+          }
+        } catch {
+          // Skip corrupted files silently
+        }
+      }
+    } catch {
+      // Cache dir doesn't exist yet -- nothing to migrate
+    }
+  }
 }

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,10 +1,9 @@
-import type { CachedStep } from "./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 {
@@ -30,13 +29,19 @@ export class StepReplayer {
    * @param steps - The cached steps to replay
    * @returns Result indicating success or failure with details
    */
-  async replay(steps: CachedStep[]): Promise<ReplayResult> {
+  async replay(steps: CachedStep[], onStepProgress?: OnStepProgress): Promise<ReplayResult> {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       if (!step) continue;
 
       try {
         await this.executor(step.toolName, step.toolInput);
+        onStepProgress?.({
+          stepNumber: i + 1,
+          toolName: step.toolName,
+          input: step.toolInput,
+          description: describeToolCall(step.toolName, step.toolInput),
+        });
       } catch (error) {
         return {
           success: false,

package/src/cache/types.ts

@@ -6,7 +6,7 @@ export interface CachedStep {
 
 /** A complete cache entry with diagnostic metadata */
 export interface CacheEntry {
-  version: 1;
+  version: 1 | 2;
   testCase: string;
   baseUrl: string;
   steps: CachedStep[];