retestkit 1.4.1

package/src/workspace/markdown.ts

@@ -0,0 +1,272 @@
+import matter from "gray-matter";
+import { readFile, writeFile } from "node:fs/promises";
+
+/**
+ * Write a markdown file with YAML frontmatter
+ */
+export async function writeMarkdownWithFrontmatter<T extends object>(
+  filePath: string,
+  frontmatter: T,
+  content: string
+): Promise<void> {
+  const file = matter.stringify(content, frontmatter as object);
+  await writeFile(filePath, file, "utf-8");
+}
+
+/**
+ * Read YAML frontmatter from a markdown file
+ */
+export async function readMarkdownFrontmatter<T>(filePath: string): Promise<T> {
+  const fileContent = await readFile(filePath, "utf-8");
+  const { data } = matter(fileContent);
+  return data as T;
+}
+
+/**
+ * Read both frontmatter and content from a markdown file
+ */
+export async function readMarkdownFile<T>(
+  filePath: string
+): Promise<{ data: T; content: string }> {
+  const fileContent = await readFile(filePath, "utf-8");
+  const { data, content } = matter(fileContent);
+  return { data: data as T, content };
+}
+
+/**
+ * Format an accessibility tree snapshot as a human-readable tree
+ */
+export function formatAccessibilityTree(
+  snapshot: AccessibilityNode,
+  indent: number = 0
+): string {
+  const lines: string[] = [];
+  const prefix = indent === 0 ? "" : "│   ".repeat(indent - 1) + "├── ";
+
+  // Format the node
+  let nodeStr = snapshot.role || "unknown";
+  if (snapshot.name) {
+    nodeStr += ` "${snapshot.name}"`;
+  }
+  if (snapshot.ref) {
+    nodeStr += ` [ref: ${snapshot.ref}]`;
+  }
+  if (snapshot.level) {
+    nodeStr += ` (h${snapshot.level})`;
+  }
+  if (snapshot.checked !== undefined) {
+    nodeStr += snapshot.checked ? " [checked]" : " [unchecked]";
+  }
+  if (snapshot.selected !== undefined) {
+    nodeStr += snapshot.selected ? " [selected]" : "";
+  }
+  if (snapshot.disabled) {
+    nodeStr += " [disabled]";
+  }
+  if (snapshot.value) {
+    nodeStr += ` = "${truncate(snapshot.value, 30)}"`;
+  }
+
+  lines.push(prefix + nodeStr);
+
+  // Format children
+  if (snapshot.children && snapshot.children.length > 0) {
+    for (let i = 0; i < snapshot.children.length; i++) {
+      const child = snapshot.children[i];
+      const isLast = i === snapshot.children.length - 1;
+      const childPrefix = indent === 0 ? "" : "│   ".repeat(indent - 1) + (isLast ? "└── " : "├── ");
+      lines.push(
+        ...formatAccessibilityTreeInternal(child, indent + 1, isLast).split("\n")
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatAccessibilityTreeInternal(
+  snapshot: AccessibilityNode,
+  indent: number,
+  isLast: boolean
+): string {
+  const lines: string[] = [];
+  const connector = isLast ? "└── " : "├── ";
+  const childIndent = isLast ? "    " : "│   ";
+  const prefix = "│   ".repeat(Math.max(0, indent - 1)) + connector;
+
+  // Format the node
+  let nodeStr = snapshot.role || "unknown";
+  if (snapshot.name) {
+    nodeStr += ` "${snapshot.name}"`;
+  }
+  if (snapshot.ref) {
+    nodeStr += ` [ref: ${snapshot.ref}]`;
+  }
+  if (snapshot.level) {
+    nodeStr += ` (h${snapshot.level})`;
+  }
+  if (snapshot.checked !== undefined) {
+    nodeStr += snapshot.checked ? " [checked]" : " [unchecked]";
+  }
+  if (snapshot.selected !== undefined) {
+    nodeStr += snapshot.selected ? " [selected]" : "";
+  }
+  if (snapshot.disabled) {
+    nodeStr += " [disabled]";
+  }
+  if (snapshot.value) {
+    nodeStr += ` = "${truncate(snapshot.value, 30)}"`;
+  }
+
+  lines.push(prefix + nodeStr);
+
+  // Format children
+  if (snapshot.children && snapshot.children.length > 0) {
+    for (let i = 0; i < snapshot.children.length; i++) {
+      const child = snapshot.children[i];
+      const childIsLast = i === snapshot.children.length - 1;
+      const baseIndent = "│   ".repeat(Math.max(0, indent - 1)) + childIndent;
+      lines.push(
+        formatAccessibilityTreeWithBase(child, baseIndent, childIsLast)
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatAccessibilityTreeWithBase(
+  snapshot: AccessibilityNode,
+  baseIndent: string,
+  isLast: boolean
+): string {
+  const lines: string[] = [];
+  const connector = isLast ? "└── " : "├── ";
+  const childIndent = isLast ? "    " : "│   ";
+
+  // Format the node
+  let nodeStr = snapshot.role || "unknown";
+  if (snapshot.name) {
+    nodeStr += ` "${snapshot.name}"`;
+  }
+  if (snapshot.ref) {
+    nodeStr += ` [ref: ${snapshot.ref}]`;
+  }
+  if (snapshot.level) {
+    nodeStr += ` (h${snapshot.level})`;
+  }
+  if (snapshot.checked !== undefined) {
+    nodeStr += snapshot.checked ? " [checked]" : " [unchecked]";
+  }
+  if (snapshot.selected !== undefined) {
+    nodeStr += snapshot.selected ? " [selected]" : "";
+  }
+  if (snapshot.disabled) {
+    nodeStr += " [disabled]";
+  }
+  if (snapshot.value) {
+    nodeStr += ` = "${truncate(snapshot.value, 30)}"`;
+  }
+
+  lines.push(baseIndent + connector + nodeStr);
+
+  // Format children
+  if (snapshot.children && snapshot.children.length > 0) {
+    for (let i = 0; i < snapshot.children.length; i++) {
+      const child = snapshot.children[i];
+      const childIsLast = i === snapshot.children.length - 1;
+      lines.push(
+        formatAccessibilityTreeWithBase(child, baseIndent + childIndent, childIsLast)
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Extract interactive elements from an accessibility snapshot
+ */
+export function extractInteractiveElements(
+  snapshot: AccessibilityNode
+): Array<{ element: string; type: string; ref?: string }> {
+  const elements: Array<{ element: string; type: string; ref?: string }> = [];
+  const interactiveRoles = [
+    "link",
+    "button",
+    "textbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "menuitem",
+    "tab",
+    "slider",
+    "spinbutton",
+    "searchbox",
+  ];
+
+  function traverse(node: AccessibilityNode): void {
+    if (node.role && interactiveRoles.includes(node.role)) {
+      elements.push({
+        element: node.name || node.role,
+        type: node.role,
+        ref: node.ref,
+      });
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        traverse(child);
+      }
+    }
+  }
+
+  traverse(snapshot);
+  return elements;
+}
+
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Format a date for human-readable display
+ */
+export function formatDate(isoDate: string): string {
+  const date = new Date(isoDate);
+  return date.toLocaleString("en-US", {
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  });
+}
+
+/**
+ * Format a short time for display
+ */
+export function formatTime(isoDate: string): string {
+  const date = new Date(isoDate);
+  return date.toLocaleTimeString("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  });
+}
+
+/**
+ * Type definition for accessibility tree nodes
+ */
+export interface AccessibilityNode {
+  role?: string;
+  name?: string;
+  ref?: string;
+  level?: number;
+  checked?: boolean;
+  selected?: boolean;
+  disabled?: boolean;
+  value?: string;
+  children?: AccessibilityNode[];
+}

package/src/workspace/types.ts

@@ -0,0 +1,186 @@
+export interface WorkspaceIndex {
+  analysisId: string;
+  url: string;
+  domain: string;
+  focus?: string;
+  createdAt: string;
+  updatedAt: string;
+  status: "active" | "completed" | "failed";
+  limits: {
+    maxSteps: number;
+    maxMinutes: number;
+    maxPages: number;
+  };
+  crawls: CrawlReference[];
+  /** Discovered features from webtest_discover_features */
+  features?: FeaturesReference;
+  /** Discovered flows per feature from webtest_discover_flows */
+  featureFlows?: FlowsReference[];
+  tests?: TestsReference;
+  runs: TestRunReference[];
+}
+
+export interface CrawlReference {
+  crawlId: string;
+  goal: string;
+  status: "in_progress" | "completed" | "failed" | "cancelled";
+  startedAt: string;
+  completedAt?: string;
+  pagesVisited: number;
+  stepsExecuted: number;
+}
+
+export interface Feature {
+  slug: string;
+  name: string;
+  description: string;
+  entities: string[];
+  entryPoints: string[];
+}
+
+export interface FeaturesReference {
+  createdAt: string;
+  featuresFilePath: string;
+  featuresUri: string;
+  featureCount: number;
+  features: Feature[];
+}
+
+export interface FlowsReference {
+  featureSlug: string;
+  createdAt: string;
+  flowsFilePath: string;
+  flowsUri: string;
+  flowCount: number;
+}
+
+export interface TestsReference {
+  createdAt: string;
+  testsFilePath: string;
+  testsUri: string;
+  testCount: number;
+}
+
+export interface TestRunReference {
+  runId: string;
+  testCaseId: string;
+  status: "in_progress" | "passed" | "failed" | "error";
+  startedAt: string;
+  completedAt?: string;
+}
+
+export interface CrawlIndex {
+  crawlId: string;
+  analysisId: string;
+  goal: string;
+  strategy: string;
+  status: "in_progress" | "completed" | "failed" | "cancelled";
+  startedAt: string;
+  completedAt?: string;
+  budget: {
+    maxSteps: number;
+    maxMinutes: number;
+    maxPages: number;
+    stepsUsed: number;
+    pagesVisited: number;
+  };
+  pages: PageReference[];
+  actionHistory: ActionRecord[];
+  checkpoint?: CrawlCheckpoint;
+  loopDetection: {
+    domSignatures: Record<string, number>;
+    urlVisits: Record<string, number>;
+    recentActions: string[];
+  };
+}
+
+export interface PageReference {
+  pageId: string;
+  url: string;
+  title: string;
+  capturedAt: string;
+  snapshotFilePath: string;
+  snapshotUri: string;
+  screenshotFilePath: string;
+  screenshotUri: string;
+  domFilePath: string;
+  domUri: string;
+}
+
+export interface ActionRecord {
+  step: number;
+  timestamp: string;
+  tool: string;
+  args: Record<string, unknown>;
+  result: "success" | "error";
+  reasoning?: string;
+  error?: string;
+}
+
+export interface CrawlCheckpoint {
+  step: number;
+  timestamp: string;
+  visitedUrls: string[];
+  currentUrl: string;
+  goalProgress: string;
+  canResume: boolean;
+  /** Start URL for navigation guard (blocks return to start after initial steps) */
+  startUrl?: string;
+  /** Preserved loop detection state for context continuity across resume */
+  loopDetection?: {
+    /** DOM signature visit counts as [signature, count] entries */
+    domSignatures: Array<[string, number]>;
+    /** URL visit counts as [url, count] entries */
+    urlVisits: Array<[string, number]>;
+    /** Recent action keys for repeat detection */
+    recentActions: string[];
+  };
+}
+
+export interface TestCase {
+  id: string;
+  name: string;
+  purpose: string;
+  category: "happy_path" | "edge_case" | "error_handling" | "boundary";
+  preconditions: string[];
+  steps: TestStep[];
+  expectedOutcomes: string[];
+  tags?: string[];
+}
+
+export interface TestStep {
+  stepNumber: number;
+  action: string;
+  target?: string;
+  value?: string;
+  expected?: string;
+  /** Playwright MCP element description */
+  element?: string;
+  /** Playwright MCP accessibility snapshot ref */
+  ref?: string;
+}
+
+export interface TestRunIndex {
+  runId: string;
+  analysisId: string;
+  testCaseId: string;
+  testName: string;
+  status: "in_progress" | "passed" | "failed" | "error";
+  startedAt: string;
+  completedAt?: string;
+  steps: TestStepResult[];
+}
+
+export interface TestStepResult {
+  stepNumber: number;
+  status: "passed" | "failed" | "error" | "skipped";
+  executedAt: string;
+  evidence: {
+    screenshotFilePath?: string;
+    screenshotUri?: string;
+    snapshotFilePath?: string;
+    snapshotUri?: string;
+  };
+  actualResult?: string;
+  errorMessage?: string;
+}

package/tests/integration/server.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn, type ChildProcess } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(__dirname, "../../src/index.ts");
+
+describe("MCP Server Integration", () => {
+  let client: Client;
+  let transport: StdioClientTransport;
+  let serverProcess: ChildProcess;
+
+  beforeAll(async () => {
+    // Spawn the server using tsx
+    serverProcess = spawn("npx", ["tsx", serverPath], {
+      env: {
+        ...process.env,
+        TRANSPORT: "stdio",
+        LOG_LEVEL: "error", // Minimize log noise during tests
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    // Create transport connected to server's stdin/stdout
+    transport = new StdioClientTransport({
+      command: "npx",
+      args: ["tsx", serverPath],
+      env: {
+        ...process.env,
+        TRANSPORT: "stdio",
+        LOG_LEVEL: "error",
+      },
+    });
+
+    // Create and connect client
+    client = new Client({
+      name: "test-client",
+      version: "1.0.0",
+    });
+
+    await client.connect(transport);
+  }, 15000);
+
+  afterAll(async () => {
+    await client.close();
+    serverProcess?.kill();
+  });
+
+  describe("server identification", () => {
+    it("reports correct server name", async () => {
+      const info = client.getServerVersion();
+      expect(info?.name).toBe("testing-mcp");
+    });
+
+    it("reports server version", async () => {
+      const info = client.getServerVersion();
+      expect(info?.version).toBeDefined();
+    });
+  });
+
+  describe("tool discovery", () => {
+    it("lists available tools", async () => {
+      const result = await client.listTools();
+      expect(result.tools).toBeDefined();
+      expect(result.tools.length).toBeGreaterThan(0);
+    });
+
+    it("includes hello tool", async () => {
+      const result = await client.listTools();
+      const helloTool = result.tools.find((t) => t.name === "hello");
+      expect(helloTool).toBeDefined();
+    });
+
+    it("hello tool has description", async () => {
+      const result = await client.listTools();
+      const helloTool = result.tools.find((t) => t.name === "hello");
+      expect(helloTool?.description).toBeTruthy();
+    });
+
+    it("hello tool has input schema", async () => {
+      const result = await client.listTools();
+      const helloTool = result.tools.find((t) => t.name === "hello");
+      expect(helloTool?.inputSchema).toBeDefined();
+    });
+  });
+});

package/tests/integration/tools.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(__dirname, "../../src/index.ts");
+
+describe("Tool Execution Integration", () => {
+  let client: Client;
+  let transport: StdioClientTransport;
+
+  beforeAll(async () => {
+    transport = new StdioClientTransport({
+      command: "npx",
+      args: ["tsx", serverPath],
+      env: {
+        ...process.env,
+        TRANSPORT: "stdio",
+        LOG_LEVEL: "error",
+      },
+    });
+
+    client = new Client({
+      name: "test-client",
+      version: "1.0.0",
+    });
+
+    await client.connect(transport);
+  }, 15000);
+
+  afterAll(async () => {
+    await client.close();
+  });
+
+  describe("hello tool", () => {
+    it("returns greeting with provided name", async () => {
+      const result = await client.callTool({
+        name: "hello",
+        arguments: { name: "World" },
+      });
+
+      expect(result.content).toBeDefined();
+      expect(result.content.length).toBeGreaterThan(0);
+
+      const textContent = result.content.find(
+        (c): c is { type: "text"; text: string } => c.type === "text"
+      );
+      expect(textContent?.text).toBe("Hello, World!");
+    });
+
+    it("works with different names", async () => {
+      const result = await client.callTool({
+        name: "hello",
+        arguments: { name: "Alice" },
+      });
+
+      const textContent = result.content.find(
+        (c): c is { type: "text"; text: string } => c.type === "text"
+      );
+      expect(textContent?.text).toBe("Hello, Alice!");
+    });
+
+    it("handles special characters in name", async () => {
+      const result = await client.callTool({
+        name: "hello",
+        arguments: { name: "Bob & Jane" },
+      });
+
+      const textContent = result.content.find(
+        (c): c is { type: "text"; text: string } => c.type === "text"
+      );
+      expect(textContent?.text).toBe("Hello, Bob & Jane!");
+    });
+  });
+
+  describe("error handling", () => {
+    it("returns error for missing required argument", async () => {
+      const result = await client.callTool({
+        name: "hello",
+        arguments: {},
+      });
+
+      // SDK validation should reject this
+      expect(result.isError).toBe(true);
+    });
+
+    it("returns error for invalid argument type", async () => {
+      const result = await client.callTool({
+        name: "hello",
+        // @ts-expect-error - intentionally passing wrong type
+        arguments: { name: 123 },
+      });
+
+      expect(result.isError).toBe(true);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "node",
+    globals: false,
+  },
+});

package/vitest.integration.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/integration/**/*.test.ts"],
+    environment: "node",
+    globals: false,
+    testTimeout: 10000,
+  },
+});