retestkit 1.4.1

package/src/workspace/index.ts

@@ -0,0 +1,945 @@
+import { mkdir, writeFile, access, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { Logger } from "../logger.js";
+import type { Config } from "../schemas/config.js";
+import type {
+  WorkspaceIndex,
+  CrawlIndex,
+  CrawlCheckpoint,
+  PageReference,
+  ActionRecord,
+  TestRunIndex,
+  TestStepResult,
+  Feature,
+  FlowsReference,
+} from "./types.js";
+import {
+  writeMarkdownWithFrontmatter,
+  readMarkdownFrontmatter,
+  formatAccessibilityTree,
+  extractInteractiveElements,
+  formatDate,
+  formatTime,
+  type AccessibilityNode,
+} from "./markdown.js";
+
+export * from "./types.js";
+export * from "./markdown.js";
+
+export interface WorkspaceManager {
+  createWorkspace(params: {
+    url: string;
+    focus?: string;
+    limits: {
+      maxSteps: number;
+      maxMinutes: number;
+      maxPages: number;
+    };
+  }): Promise<{ analysisId: string; workspacePath: string }>;
+
+  getWorkspacePath(analysisId: string): string;
+  workspaceExists(analysisId: string): Promise<boolean>;
+  readWorkspaceIndex(analysisId: string): Promise<WorkspaceIndex>;
+  updateWorkspaceIndex(
+    analysisId: string,
+    update: Partial<WorkspaceIndex>
+  ): Promise<void>;
+
+  createCrawl(
+    analysisId: string,
+    params: { goal: string; strategy: string; limits: WorkspaceIndex["limits"] }
+  ): Promise<{ crawlId: string; crawlPath: string }>;
+  getCrawlPath(analysisId: string, crawlId: string): string;
+  readCrawlIndex(analysisId: string, crawlId: string): Promise<CrawlIndex>;
+  updateCrawlIndex(
+    analysisId: string,
+    crawlId: string,
+    update: Partial<CrawlIndex>
+  ): Promise<void>;
+
+  savePage(
+    analysisId: string,
+    crawlId: string,
+    page: {
+      url: string;
+      title: string;
+      snapshot: string;
+      screenshot: { data: string; mimeType: string };
+      dom: string;
+    }
+  ): Promise<PageReference>;
+
+  saveCheckpoint(
+    analysisId: string,
+    crawlId: string,
+    checkpoint: CrawlCheckpoint
+  ): Promise<void>;
+  loadCheckpoint(
+    analysisId: string,
+    crawlId: string
+  ): Promise<CrawlCheckpoint | null>;
+
+  recordAction(
+    analysisId: string,
+    crawlId: string,
+    action: ActionRecord
+  ): Promise<void>;
+
+  saveFeatures(
+    analysisId: string,
+    features: { markdown: string; frontmatter: { features: Feature[] } }
+  ): Promise<{
+    featuresFilePath: string;
+    featuresUri: string;
+    featureCount: number;
+  }>;
+
+  saveFlows(
+    analysisId: string,
+    featureSlug: string,
+    flows: { markdown: string; frontmatter: unknown }
+  ): Promise<{
+    flowsFilePath: string;
+    flowsUri: string;
+    flowCount: number;
+  }>;
+
+  getFeaturePath(analysisId: string, featureSlug: string): string;
+
+  saveTests(
+    analysisId: string,
+    tests: { markdown: string; frontmatter: unknown }
+  ): Promise<{
+    testsFilePath: string;
+    testsUri: string;
+    testCount: number;
+  }>;
+
+  createTestRun(
+    analysisId: string,
+    params: { testCaseId: string; testName: string }
+  ): Promise<{ runId: string; runPath: string }>;
+  getTestRunPath(analysisId: string, runId: string): string;
+  readTestRunIndex(analysisId: string, runId: string): Promise<TestRunIndex>;
+  updateTestRunIndex(
+    analysisId: string,
+    runId: string,
+    update: Partial<TestRunIndex>
+  ): Promise<void>;
+
+  saveTestStepEvidence(
+    analysisId: string,
+    runId: string,
+    stepNumber: number,
+    evidence: {
+      screenshot?: { data: string; mimeType: string };
+      snapshot?: string;
+    }
+  ): Promise<{
+    screenshotFilePath?: string;
+    screenshotUri?: string;
+    snapshotFilePath?: string;
+    snapshotUri?: string;
+  }>;
+
+  listWorkspaces(): Promise<string[]>;
+}
+
+export function createWorkspaceManager(
+  config: Config,
+  logger: Logger
+): WorkspaceManager {
+  const baseDir = resolve(config.workspaceDir);
+
+  function getWorkspacePath(analysisId: string): string {
+    return join(baseDir, analysisId);
+  }
+
+  function getCrawlPath(analysisId: string, crawlId: string): string {
+    return join(getWorkspacePath(analysisId), "crawls", crawlId);
+  }
+
+  function getTestRunPath(analysisId: string, runId: string): string {
+    return join(getWorkspacePath(analysisId), "runs", runId);
+  }
+
+  async function ensureDir(path: string): Promise<void> {
+    await mkdir(path, { recursive: true });
+  }
+
+  async function fileExists(path: string): Promise<boolean> {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Helper to generate workspace markdown content
+  function generateWorkspaceMarkdown(index: WorkspaceIndex): string {
+    const lines: string[] = [];
+    lines.push(`# Analysis Workspace`);
+    lines.push("");
+    lines.push(`**Target**: ${index.url}`);
+    if (index.focus) {
+      lines.push(`**Focus**: ${index.focus}`);
+    }
+    lines.push(`**Status**: ${index.status}`);
+    lines.push(`**Created**: ${formatDate(index.createdAt)}`);
+    lines.push("");
+    lines.push("## Configuration");
+    lines.push("");
+    lines.push("| Setting | Value |");
+    lines.push("|---------|-------|");
+    lines.push(`| Max Steps | ${index.limits.maxSteps} |`);
+    lines.push(`| Max Pages | ${index.limits.maxPages} |`);
+    lines.push(`| Max Minutes | ${index.limits.maxMinutes} |`);
+    lines.push("");
+
+    if (index.crawls.length > 0) {
+      lines.push("## Crawls");
+      lines.push("");
+      for (const crawl of index.crawls) {
+        lines.push(`### ${crawl.crawlId.slice(0, 8)}`);
+        lines.push(`- **Goal**: ${crawl.goal}`);
+        lines.push(`- **Status**: ${crawl.status}`);
+        lines.push(`- **Pages**: ${crawl.pagesVisited} discovered`);
+        lines.push(`- **Steps**: ${crawl.stepsExecuted} executed`);
+        lines.push(`- **Started**: ${formatTime(crawl.startedAt)}`);
+        if (crawl.completedAt) {
+          lines.push(`- **Completed**: ${formatTime(crawl.completedAt)}`);
+        }
+        lines.push("");
+      }
+    }
+
+    if (index.features) {
+      lines.push("## Features");
+      lines.push("");
+      lines.push(`${index.features.featureCount} features discovered at ${formatTime(index.features.createdAt)}.`);
+      lines.push(`- [View Features](./features.md)`);
+      lines.push("");
+      if (index.featureFlows && index.featureFlows.length > 0) {
+        lines.push("### Feature Flows");
+        lines.push("");
+        for (const flow of index.featureFlows) {
+          lines.push(`- [${flow.featureSlug}](./features/${flow.featureSlug}/flows.md) - ${flow.flowCount} flows`);
+        }
+        lines.push("");
+      }
+    }
+
+
+    if (index.tests) {
+      lines.push("## Tests");
+      lines.push("");
+      lines.push(`${index.tests.testCount} test cases generated at ${formatTime(index.tests.createdAt)}.`);
+      lines.push(`- [View Test Cases](./tests/tests.md)`);
+      lines.push("");
+    }
+
+    if (index.runs.length > 0) {
+      lines.push("## Test Runs");
+      lines.push("");
+      lines.push("| Run | Test | Status | Started |");
+      lines.push("|-----|------|--------|---------|");
+      for (const run of index.runs) {
+        const status = run.status === "passed" ? "Passed" : run.status === "failed" ? "Failed" : run.status;
+        lines.push(`| ${run.runId.slice(0, 8)} | ${run.testCaseId} | ${status} | ${formatTime(run.startedAt)} |`);
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  // Helper to generate crawl markdown content
+  function generateCrawlMarkdown(index: CrawlIndex): string {
+    const lines: string[] = [];
+    lines.push(`# Crawl Report`);
+    lines.push("");
+    lines.push(`**Goal**: ${index.goal}`);
+    lines.push(`**Strategy**: ${index.strategy}`);
+    lines.push(`**Status**: ${index.status}`);
+    lines.push(`**Started**: ${formatDate(index.startedAt)}`);
+    if (index.completedAt) {
+      lines.push(`**Completed**: ${formatDate(index.completedAt)}`);
+    }
+    lines.push("");
+    lines.push("## Budget Usage");
+    lines.push("");
+    lines.push("| Metric | Used | Limit | % |");
+    lines.push("|--------|------|-------|---|");
+    const stepsPercent = Math.round((index.budget.stepsUsed / index.budget.maxSteps) * 100);
+    const pagesPercent = Math.round((index.budget.pagesVisited / index.budget.maxPages) * 100);
+    lines.push(`| Steps | ${index.budget.stepsUsed} | ${index.budget.maxSteps} | ${stepsPercent}% |`);
+    lines.push(`| Pages | ${index.budget.pagesVisited} | ${index.budget.maxPages} | ${pagesPercent}% |`);
+    lines.push("");
+
+    if (index.pages.length > 0) {
+      lines.push("## Pages Discovered");
+      lines.push("");
+      lines.push("| # | Page | URL | Captured |");
+      lines.push("|---|------|-----|----------|");
+      for (let i = 0; i < index.pages.length; i++) {
+        const page = index.pages[i];
+        lines.push(`| ${i + 1} | ${page.title || "Untitled"} | ${page.url} | ${formatTime(page.capturedAt)} |`);
+      }
+      lines.push("");
+    }
+
+    if (index.actionHistory.length > 0) {
+      lines.push("## Action History");
+      lines.push("");
+      const recentActions = index.actionHistory.slice(-20); // Show last 20 actions
+      for (const action of recentActions) {
+        const status = action.result === "success" ? "Success" : "Error";
+        lines.push(`${action.step}. **${action.tool}** → ${status}`);
+        if (action.reasoning) {
+          lines.push(`   - ${action.reasoning}`);
+        }
+        if (action.error) {
+          lines.push(`   - Error: ${action.error}`);
+        }
+      }
+      if (index.actionHistory.length > 20) {
+        lines.push(`\n*...and ${index.actionHistory.length - 20} more actions*`);
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  // Helper to generate checkpoint markdown content
+  function generateCheckpointMarkdown(checkpoint: CrawlCheckpoint): string {
+    const lines: string[] = [];
+    lines.push(`# Crawl Checkpoint`);
+    lines.push("");
+    lines.push(`**Step**: ${checkpoint.step}`);
+    lines.push(`**Saved**: ${formatDate(checkpoint.timestamp)}`);
+    lines.push(`**Current URL**: ${checkpoint.currentUrl}`);
+    lines.push(`**Can Resume**: ${checkpoint.canResume ? "Yes" : "No"}`);
+    lines.push("");
+    lines.push("## Progress");
+    lines.push("");
+    lines.push(checkpoint.goalProgress);
+    lines.push("");
+    lines.push("## Visited URLs");
+    lines.push("");
+    for (const url of checkpoint.visitedUrls) {
+      lines.push(`- ${url}`);
+    }
+    lines.push("");
+
+    if (checkpoint.loopDetection) {
+      lines.push("## Loop Detection State");
+      lines.push("");
+      if (checkpoint.loopDetection.urlVisits.length > 0) {
+        lines.push("### URL Visit Counts");
+        for (const [url, count] of checkpoint.loopDetection.urlVisits) {
+          if (count > 1) {
+            lines.push(`- \`${url}\`: ${count} visits`);
+          }
+        }
+        lines.push("");
+      }
+      lines.push(`- Recent action signatures tracked: ${checkpoint.loopDetection.recentActions.length}`);
+      lines.push(`- DOM signatures in window: ${checkpoint.loopDetection.domSignatures.length}`);
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  // Helper to generate page snapshot markdown content
+  function generateSnapshotMarkdown(
+    pageId: string,
+    url: string,
+    title: string,
+    capturedAt: string,
+    snapshotData: AccessibilityNode
+  ): string {
+    const lines: string[] = [];
+    lines.push(`# Page Snapshot: ${title || "Untitled"}`);
+    lines.push("");
+    lines.push(`**URL**: ${url}`);
+    lines.push(`**Captured**: ${formatTime(capturedAt)}`);
+    lines.push("");
+    lines.push("## Accessibility Tree");
+    lines.push("");
+    lines.push("```");
+    lines.push(formatAccessibilityTree(snapshotData));
+    lines.push("```");
+    lines.push("");
+
+    const interactiveElements = extractInteractiveElements(snapshotData);
+    if (interactiveElements.length > 0) {
+      lines.push("## Interactive Elements");
+      lines.push("");
+      lines.push("| Element | Type | Ref |");
+      lines.push("|---------|------|-----|");
+      for (const el of interactiveElements.slice(0, 50)) { // Limit to 50
+        lines.push(`| ${el.element} | ${el.type} | ${el.ref || "-"} |`);
+      }
+      if (interactiveElements.length > 50) {
+        lines.push(`\n*...and ${interactiveElements.length - 50} more elements*`);
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  // Helper to generate test run report markdown content
+  function generateTestRunMarkdown(index: TestRunIndex): string {
+    const lines: string[] = [];
+    const statusEmoji = index.status === "passed" ? "PASSED" : index.status === "failed" ? "FAILED" : index.status.toUpperCase();
+
+    lines.push(`# Test Run Report`);
+    lines.push("");
+    lines.push(`**Test**: ${index.testName} (${index.testCaseId})`);
+    lines.push(`**Status**: ${statusEmoji}`);
+    lines.push(`**Started**: ${formatDate(index.startedAt)}`);
+    if (index.completedAt) {
+      lines.push(`**Completed**: ${formatDate(index.completedAt)}`);
+    }
+    lines.push(`**Run ID**: ${index.runId}`);
+    lines.push("");
+
+    if (index.steps.length > 0) {
+      const passedSteps = index.steps.filter(s => s.status === "passed").length;
+      const failedSteps = index.steps.filter(s => s.status === "failed").length;
+      const errorSteps = index.steps.filter(s => s.status === "error").length;
+
+      lines.push("## Summary");
+      lines.push("");
+      lines.push("| Metric | Value |");
+      lines.push("|--------|-------|");
+      lines.push(`| Total Steps | ${index.steps.length} |`);
+      lines.push(`| Passed | ${passedSteps} |`);
+      lines.push(`| Failed | ${failedSteps} |`);
+      lines.push(`| Errors | ${errorSteps} |`);
+      const successRate = Math.round((passedSteps / index.steps.length) * 100);
+      lines.push(`| Success Rate | ${successRate}% |`);
+      lines.push("");
+
+      lines.push("## Step Results");
+      lines.push("");
+
+      for (const step of index.steps) {
+        const stepStatus = step.status === "passed" ? "PASSED" : step.status === "failed" ? "FAILED" : step.status.toUpperCase();
+        lines.push(`### Step ${step.stepNumber}: ${stepStatus}`);
+        lines.push("");
+        lines.push(`**Executed**: ${formatTime(step.executedAt)}`);
+        if (step.actualResult) {
+          lines.push(`**Result**: ${step.actualResult}`);
+        }
+        if (step.errorMessage) {
+          lines.push(`**Error**: ${step.errorMessage}`);
+        }
+        lines.push("");
+
+        if (step.evidence.screenshotUri || step.evidence.snapshotUri) {
+          lines.push("**Evidence**:");
+          if (step.evidence.screenshotUri) {
+            lines.push(`- [Screenshot](./steps/${step.stepNumber}/screenshot.png)`);
+          }
+          if (step.evidence.snapshotUri) {
+            lines.push(`- [Snapshot](./steps/${step.stepNumber}/snapshot.md)`);
+          }
+          lines.push("");
+        }
+        lines.push("---");
+        lines.push("");
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  // Generate a date-time based folder name: YYYY-MM-DD_HH-mm
+  function generateWorkspaceFolderName(): string {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    const hours = String(now.getHours()).padStart(2, "0");
+    const minutes = String(now.getMinutes()).padStart(2, "0");
+    return `${year}-${month}-${day}_${hours}-${minutes}`;
+  }
+
+  // Generate a date-time based folder name with seconds: YYYY-MM-DD_HH-mm-ss
+  function generateCrawlFolderName(): string {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    const hours = String(now.getHours()).padStart(2, "0");
+    const minutes = String(now.getMinutes()).padStart(2, "0");
+    const seconds = String(now.getSeconds()).padStart(2, "0");
+    return `${year}-${month}-${day}_${hours}-${minutes}-${seconds}`;
+  }
+
+  return {
+    async createWorkspace(params) {
+      const analysisId = generateWorkspaceFolderName();
+      const workspacePath = getWorkspacePath(analysisId);
+
+      logger.info("Creating workspace", { analysisId, url: params.url });
+
+      await ensureDir(workspacePath);
+      await ensureDir(join(workspacePath, "crawls"));
+      await ensureDir(join(workspacePath, "features"));
+      await ensureDir(join(workspacePath, "tests"));
+      await ensureDir(join(workspacePath, "runs"));
+
+      const domain = new URL(params.url).hostname;
+
+      const index: WorkspaceIndex = {
+        analysisId,
+        url: params.url,
+        domain,
+        focus: params.focus,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        status: "active",
+        limits: params.limits,
+        crawls: [],
+        featureFlows: [],
+        runs: [],
+      };
+
+      const markdown = generateWorkspaceMarkdown(index);
+      await writeMarkdownWithFrontmatter(join(workspacePath, "index.md"), index, markdown);
+
+      logger.info("Workspace created", { analysisId, workspacePath });
+
+      return { analysisId, workspacePath };
+    },
+
+    getWorkspacePath,
+
+    async workspaceExists(analysisId) {
+      return fileExists(join(getWorkspacePath(analysisId), "index.md"));
+    },
+
+    async readWorkspaceIndex(analysisId) {
+      return readMarkdownFrontmatter<WorkspaceIndex>(
+        join(getWorkspacePath(analysisId), "index.md")
+      );
+    },
+
+    async updateWorkspaceIndex(analysisId, update) {
+      const indexPath = join(getWorkspacePath(analysisId), "index.md");
+      const current = await readMarkdownFrontmatter<WorkspaceIndex>(indexPath);
+      const updated: WorkspaceIndex = {
+        ...current,
+        ...update,
+        updatedAt: new Date().toISOString(),
+      };
+      const markdown = generateWorkspaceMarkdown(updated);
+      await writeMarkdownWithFrontmatter(indexPath, updated, markdown);
+    },
+
+    async createCrawl(analysisId, params) {
+      const crawlId = generateCrawlFolderName();
+      const crawlPath = getCrawlPath(analysisId, crawlId);
+
+      logger.info("Creating crawl", { analysisId, crawlId, goal: params.goal });
+
+      await ensureDir(crawlPath);
+      await ensureDir(join(crawlPath, "pages"));
+
+      const index: CrawlIndex = {
+        crawlId,
+        analysisId,
+        goal: params.goal,
+        strategy: params.strategy,
+        status: "in_progress",
+        startedAt: new Date().toISOString(),
+        budget: {
+          ...params.limits,
+          stepsUsed: 0,
+          pagesVisited: 0,
+        },
+        pages: [],
+        actionHistory: [],
+        loopDetection: {
+          domSignatures: {},
+          urlVisits: {},
+          recentActions: [],
+        },
+      };
+
+      const markdown = generateCrawlMarkdown(index);
+      await writeMarkdownWithFrontmatter(join(crawlPath, "index.md"), index, markdown);
+
+      // Update workspace index
+      const workspace = await this.readWorkspaceIndex(analysisId);
+      workspace.crawls.push({
+        crawlId,
+        goal: params.goal,
+        status: "in_progress",
+        startedAt: index.startedAt,
+        pagesVisited: 0,
+        stepsExecuted: 0,
+      });
+      await this.updateWorkspaceIndex(analysisId, { crawls: workspace.crawls });
+
+      return { crawlId, crawlPath };
+    },
+
+    getCrawlPath,
+
+    async readCrawlIndex(analysisId, crawlId) {
+      return readMarkdownFrontmatter<CrawlIndex>(
+        join(getCrawlPath(analysisId, crawlId), "index.md")
+      );
+    },
+
+    async updateCrawlIndex(analysisId, crawlId, update) {
+      const indexPath = join(getCrawlPath(analysisId, crawlId), "index.md");
+      const current = await readMarkdownFrontmatter<CrawlIndex>(indexPath);
+      const updated: CrawlIndex = { ...current, ...update };
+      const markdown = generateCrawlMarkdown(updated);
+      await writeMarkdownWithFrontmatter(indexPath, updated, markdown);
+    },
+
+    async savePage(analysisId, crawlId, page) {
+      const pageId = randomUUID();
+      const pagesDir = join(getCrawlPath(analysisId, crawlId), "pages", pageId);
+      const capturedAt = new Date().toISOString();
+
+      await ensureDir(pagesDir);
+
+      // Parse snapshot JSON to create markdown
+      let snapshotData: AccessibilityNode;
+      try {
+        snapshotData = JSON.parse(page.snapshot) as AccessibilityNode;
+      } catch {
+        snapshotData = { role: "document", name: "Parse error" };
+      }
+
+      // Save snapshot as markdown with frontmatter
+      const snapshotFilePath = join(pagesDir, "snapshot.md");
+      const snapshotFrontmatter = {
+        pageId,
+        url: page.url,
+        title: page.title,
+        capturedAt,
+        snapshot: snapshotData,
+      };
+      const snapshotMarkdown = generateSnapshotMarkdown(pageId, page.url, page.title, capturedAt, snapshotData);
+      await writeMarkdownWithFrontmatter(snapshotFilePath, snapshotFrontmatter, snapshotMarkdown);
+
+      // Save screenshot
+      const ext = page.screenshot.mimeType.includes("png") ? "png" : "jpg";
+      const screenshotFilePath = join(pagesDir, `screenshot.${ext}`);
+      const screenshotBuffer = Buffer.from(page.screenshot.data, "base64");
+      await writeFile(screenshotFilePath, screenshotBuffer);
+
+      // Save DOM
+      const domFilePath = join(pagesDir, "dom.html");
+      await writeFile(domFilePath, page.dom, "utf-8");
+
+      const pageRef: PageReference = {
+        pageId,
+        url: page.url,
+        title: page.title,
+        capturedAt,
+        snapshotFilePath,
+        snapshotUri: `webtest://${analysisId}/crawls/${crawlId}/pages/${pageId}/snapshot.md`,
+        screenshotFilePath,
+        screenshotUri: `webtest://${analysisId}/crawls/${crawlId}/pages/${pageId}/screenshot.${ext}`,
+        domFilePath,
+        domUri: `webtest://${analysisId}/crawls/${crawlId}/pages/${pageId}/dom.html`,
+      };
+
+      // Update crawl index
+      const crawlIndex = await this.readCrawlIndex(analysisId, crawlId);
+      crawlIndex.pages.push(pageRef);
+      crawlIndex.budget.pagesVisited = crawlIndex.pages.length;
+      await this.updateCrawlIndex(analysisId, crawlId, {
+        pages: crawlIndex.pages,
+        budget: crawlIndex.budget,
+      });
+
+      logger.debug("Page saved", { analysisId, crawlId, pageId, url: page.url });
+
+      return pageRef;
+    },
+
+    async saveCheckpoint(analysisId, crawlId, checkpoint) {
+      const crawlPath = getCrawlPath(analysisId, crawlId);
+      const markdown = generateCheckpointMarkdown(checkpoint);
+      await writeMarkdownWithFrontmatter(join(crawlPath, "checkpoint.md"), checkpoint, markdown);
+
+      await this.updateCrawlIndex(analysisId, crawlId, { checkpoint });
+
+      logger.info("Checkpoint saved", {
+        analysisId,
+        crawlId,
+        step: checkpoint.step,
+      });
+    },
+
+    async loadCheckpoint(analysisId, crawlId) {
+      const checkpointPath = join(
+        getCrawlPath(analysisId, crawlId),
+        "checkpoint.md"
+      );
+
+      if (await fileExists(checkpointPath)) {
+        return readMarkdownFrontmatter<CrawlCheckpoint>(checkpointPath);
+      }
+
+      return null;
+    },
+
+    async recordAction(analysisId, crawlId, action) {
+      const crawlIndex = await this.readCrawlIndex(analysisId, crawlId);
+      crawlIndex.actionHistory.push(action);
+      crawlIndex.budget.stepsUsed = crawlIndex.actionHistory.length;
+
+      // Update loop detection
+      const actionKey = `${action.tool}:${JSON.stringify(action.args)}`;
+      crawlIndex.loopDetection.recentActions.push(actionKey);
+      if (crawlIndex.loopDetection.recentActions.length > 10) {
+        crawlIndex.loopDetection.recentActions.shift();
+      }
+
+      await this.updateCrawlIndex(analysisId, crawlId, {
+        actionHistory: crawlIndex.actionHistory,
+        budget: crawlIndex.budget,
+        loopDetection: crawlIndex.loopDetection,
+      });
+    },
+
+    getFeaturePath(analysisId: string, featureSlug: string): string {
+      return join(getWorkspacePath(analysisId), "features", featureSlug);
+    },
+
+    async saveFeatures(analysisId, features) {
+      const workspacePath = getWorkspacePath(analysisId);
+
+      // Save features.md at workspace root
+      const featuresFilePath = join(workspacePath, "features.md");
+      await writeMarkdownWithFrontmatter(
+        featuresFilePath,
+        features.frontmatter,
+        features.markdown
+      );
+
+      const featuresUri = `webtest://${analysisId}/features.md`;
+      const featureCount = features.frontmatter.features?.length || 0;
+
+      await this.updateWorkspaceIndex(analysisId, {
+        features: {
+          createdAt: new Date().toISOString(),
+          featuresFilePath,
+          featuresUri,
+          featureCount,
+          features: features.frontmatter.features || [],
+        },
+      });
+
+      logger.info("Features saved", { analysisId, featureCount });
+
+      return { featuresFilePath, featuresUri, featureCount };
+    },
+
+    async saveFlows(analysisId, featureSlug, flows) {
+      const featureDir = join(getWorkspacePath(analysisId), "features", featureSlug);
+      await ensureDir(featureDir);
+
+      // Save flows.md under features/<slug>/
+      const flowsFilePath = join(featureDir, "flows.md");
+      await writeMarkdownWithFrontmatter(
+        flowsFilePath,
+        flows.frontmatter as object,
+        flows.markdown
+      );
+
+      const flowsUri = `webtest://${analysisId}/features/${featureSlug}/flows.md`;
+      const flowsData = flows.frontmatter as { flows?: unknown[] };
+      const flowCount = flowsData.flows?.length || 0;
+
+      // Update workspace featureFlows array
+      const workspace = await this.readWorkspaceIndex(analysisId);
+      const featureFlows = workspace.featureFlows || [];
+
+      // Remove existing entry for this feature if present
+      const existingIdx = featureFlows.findIndex(f => f.featureSlug === featureSlug);
+      if (existingIdx >= 0) {
+        featureFlows.splice(existingIdx, 1);
+      }
+
+      featureFlows.push({
+        featureSlug,
+        createdAt: new Date().toISOString(),
+        flowsFilePath,
+        flowsUri,
+        flowCount,
+      });
+
+      await this.updateWorkspaceIndex(analysisId, { featureFlows });
+
+      logger.info("Flows saved", { analysisId, featureSlug, flowCount });
+
+      return { flowsFilePath, flowsUri, flowCount };
+    },
+
+    async saveTests(analysisId, tests) {
+      const testsDir = join(getWorkspacePath(analysisId), "tests");
+
+      // Save tests as single markdown file with frontmatter
+      const testsFilePath = join(testsDir, "tests.md");
+      await writeMarkdownWithFrontmatter(
+        testsFilePath,
+        tests.frontmatter as object,
+        tests.markdown
+      );
+
+      const testsUri = `webtest://${analysisId}/tests/tests.md`;
+      const testArray = tests.frontmatter as { tests?: unknown[] };
+      const testCount = testArray.tests?.length || 0;
+
+      await this.updateWorkspaceIndex(analysisId, {
+        tests: {
+          createdAt: new Date().toISOString(),
+          testsFilePath,
+          testsUri,
+          testCount,
+        },
+      });
+
+      logger.info("Tests saved", { analysisId, testCount });
+
+      return { testsFilePath, testsUri, testCount };
+    },
+
+    async createTestRun(analysisId, params) {
+      const runId = randomUUID();
+      const runPath = getTestRunPath(analysisId, runId);
+
+      await ensureDir(runPath);
+      await ensureDir(join(runPath, "steps"));
+
+      const index: TestRunIndex = {
+        runId,
+        analysisId,
+        testCaseId: params.testCaseId,
+        testName: params.testName,
+        status: "in_progress",
+        startedAt: new Date().toISOString(),
+        steps: [],
+      };
+
+      const markdown = generateTestRunMarkdown(index);
+      await writeMarkdownWithFrontmatter(join(runPath, "report.md"), index, markdown);
+
+      // Update workspace index
+      const workspace = await this.readWorkspaceIndex(analysisId);
+      workspace.runs.push({
+        runId,
+        testCaseId: params.testCaseId,
+        status: "in_progress",
+        startedAt: index.startedAt,
+      });
+      await this.updateWorkspaceIndex(analysisId, { runs: workspace.runs });
+
+      logger.info("Test run created", { analysisId, runId, testCaseId: params.testCaseId });
+
+      return { runId, runPath };
+    },
+
+    getTestRunPath,
+
+    async readTestRunIndex(analysisId, runId) {
+      return readMarkdownFrontmatter<TestRunIndex>(
+        join(getTestRunPath(analysisId, runId), "report.md")
+      );
+    },
+
+    async updateTestRunIndex(analysisId, runId, update) {
+      const indexPath = join(getTestRunPath(analysisId, runId), "report.md");
+      const current = await readMarkdownFrontmatter<TestRunIndex>(indexPath);
+      const updated: TestRunIndex = { ...current, ...update };
+      const markdown = generateTestRunMarkdown(updated);
+      await writeMarkdownWithFrontmatter(indexPath, updated, markdown);
+    },
+
+    async saveTestStepEvidence(analysisId, runId, stepNumber, evidence) {
+      const stepDir = join(
+        getTestRunPath(analysisId, runId),
+        "steps",
+        String(stepNumber)
+      );
+      await ensureDir(stepDir);
+
+      const result: {
+        screenshotFilePath?: string;
+        screenshotUri?: string;
+        snapshotFilePath?: string;
+        snapshotUri?: string;
+      } = {};
+
+      if (evidence.screenshot) {
+        const ext = evidence.screenshot.mimeType.includes("png") ? "png" : "jpg";
+        const screenshotBuffer = Buffer.from(
+          evidence.screenshot.data,
+          "base64"
+        );
+        const screenshotFilePath = join(stepDir, `screenshot.${ext}`);
+        await writeFile(screenshotFilePath, screenshotBuffer);
+        result.screenshotFilePath = screenshotFilePath;
+        result.screenshotUri = `webtest://${analysisId}/runs/${runId}/steps/${stepNumber}/screenshot.${ext}`;
+      }
+
+      if (evidence.snapshot) {
+        // Parse snapshot JSON to create markdown
+        let snapshotData: AccessibilityNode;
+        try {
+          snapshotData = JSON.parse(evidence.snapshot) as AccessibilityNode;
+        } catch {
+          snapshotData = { role: "document", name: "Parse error" };
+        }
+
+        const snapshotFilePath = join(stepDir, "snapshot.md");
+        const snapshotFrontmatter = {
+          stepNumber,
+          runId,
+          analysisId,
+          capturedAt: new Date().toISOString(),
+          snapshot: snapshotData,
+        };
+        const snapshotMarkdown = generateSnapshotMarkdown(
+          `step-${stepNumber}`,
+          "",
+          `Step ${stepNumber} Snapshot`,
+          snapshotFrontmatter.capturedAt,
+          snapshotData
+        );
+        await writeMarkdownWithFrontmatter(snapshotFilePath, snapshotFrontmatter, snapshotMarkdown);
+        result.snapshotFilePath = snapshotFilePath;
+        result.snapshotUri = `webtest://${analysisId}/runs/${runId}/steps/${stepNumber}/snapshot.md`;
+      }
+
+      return result;
+    },
+
+    async listWorkspaces() {
+      try {
+        const entries = await readdir(baseDir, { withFileTypes: true });
+        return entries
+          .filter((e) => e.isDirectory())
+          .map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
+  };
+}