auto-feedback 0.1.0

package/build/workflow/executor.js

@@ -0,0 +1,269 @@
+/**
+ * Workflow step executor
+ * Sequentially runs actions against a Playwright page with per-step
+ * screenshot capture and console/error log delta tracking.
+ *
+ * Stop-on-error semantics: failed steps still capture screenshot and
+ * log deltas for debugging context, then execution halts.
+ */
+import { resolveSelector } from "../interaction/selectors.js";
+import { capturePlaywrightPage } from "../screenshot/capture.js";
+import { optimizeScreenshot } from "../screenshot/optimize.js";
+import { evaluateAssertion } from "./assertions.js";
+/**
+ * Validate a workflow step has all required fields for its action type.
+ *
+ * @param step - The workflow step to validate
+ * @param index - Zero-based step index (for error messages)
+ * @returns null if valid, or a descriptive error string
+ */
+export function validateStep(step, index) {
+    switch (step.action) {
+        case "click":
+            if (!step.selector) {
+                return `Step ${index}: 'click' requires a 'selector' field`;
+            }
+            break;
+        case "type":
+            if (!step.selector) {
+                return `Step ${index}: 'type' requires a 'selector' field`;
+            }
+            if (step.text === undefined || step.text === null) {
+                return `Step ${index}: 'type' requires a 'text' field`;
+            }
+            break;
+        case "navigate":
+            if (!step.url) {
+                return `Step ${index}: 'navigate' requires a 'url' field`;
+            }
+            break;
+        case "wait":
+            if (!step.selector) {
+                return `Step ${index}: 'wait' requires a 'selector' field`;
+            }
+            break;
+        case "screenshot":
+            // No required fields
+            break;
+        case "assert": {
+            if (!step.selector) {
+                return `Step ${index}: 'assert' requires a 'selector' field`;
+            }
+            if (!step.assertType) {
+                return `Step ${index}: 'assert' requires an 'assertType' field`;
+            }
+            const needsExpected = ["text-equals", "text-contains", "value-equals", "attribute-equals"];
+            if (needsExpected.includes(step.assertType) && step.expected === undefined) {
+                return `Step ${index}: '${step.assertType}' assertion requires an 'expected' field`;
+            }
+            const needsAttribute = ["has-attribute", "attribute-equals"];
+            if (needsAttribute.includes(step.assertType) && !step.attribute) {
+                return `Step ${index}: '${step.assertType}' assertion requires an 'attribute' field`;
+            }
+            break;
+        }
+        default:
+            return `Step ${index}: unknown action '${step.action}'`;
+    }
+    return null;
+}
+/**
+ * Execute a workflow — sequential steps against a Playwright page.
+ *
+ * Each step: validate -> execute action -> capture screenshot -> capture log deltas.
+ * On error: capture screenshot + log deltas for debugging, then stop.
+ *
+ * @returns WorkflowResult with per-step results, counts, and optional failedStep index
+ */
+export async function executeWorkflow(params) {
+    const { page, steps, sessionManager, sessionId } = params;
+    let pageIdentifier = params.pageIdentifier;
+    const results = [];
+    let lastConsoleCount = 0;
+    let lastErrorCount = 0;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const result = {
+            stepIndex: i,
+            action: step.action,
+            success: false,
+            timestamp: new Date().toISOString(),
+            consoleDelta: [],
+            errorDelta: [],
+        };
+        // Validate step before execution
+        const validationError = validateStep(step, i);
+        if (validationError) {
+            result.error = validationError;
+            results.push(result);
+            break;
+        }
+        try {
+            // Execute action via switch dispatch
+            switch (step.action) {
+                case "click": {
+                    const locator = resolveSelector(page, step.selector);
+                    await locator.click({
+                        button: step.button ?? undefined,
+                        clickCount: step.clickCount ?? undefined,
+                        timeout: step.timeout ?? 30000,
+                    });
+                    // Post-click stability wait (matches click-element.ts pattern)
+                    await Promise.race([
+                        page.waitForLoadState("load").catch(() => { }),
+                        new Promise((resolve) => setTimeout(resolve, 2000)),
+                    ]);
+                    break;
+                }
+                case "type": {
+                    const locator = resolveSelector(page, step.selector);
+                    const effectiveTimeout = step.timeout ?? 30000;
+                    if (step.pressSequentially) {
+                        // Clear first, then type char-by-char
+                        await locator.fill("", { timeout: effectiveTimeout });
+                        await locator.pressSequentially(step.text, {
+                            delay: 50,
+                            timeout: effectiveTimeout,
+                        });
+                    }
+                    else if (step.clear === false) {
+                        // Append mode: click to focus, then insertText
+                        await locator.click({ timeout: effectiveTimeout });
+                        await page.keyboard.insertText(step.text);
+                    }
+                    else {
+                        // Default: fill() clears and types in one step
+                        await locator.fill(step.text, { timeout: effectiveTimeout });
+                    }
+                    break;
+                }
+                case "navigate": {
+                    await page.goto(step.url, {
+                        waitUntil: "load",
+                        timeout: step.timeout ?? 30000,
+                    });
+                    // Update PageReference URL (matches navigate.ts lines 120-128)
+                    const oldRef = sessionManager.getPageRef(sessionId, pageIdentifier);
+                    if (oldRef) {
+                        sessionManager.removePageRef(sessionId, pageIdentifier);
+                        sessionManager.setPageRef(sessionId, step.url, {
+                            ...oldRef,
+                            url: step.url,
+                        });
+                    }
+                    // Update local identifier for subsequent steps
+                    pageIdentifier = step.url;
+                    break;
+                }
+                case "screenshot": {
+                    // No-op: screenshot is captured in the post-step phase below
+                    break;
+                }
+                case "wait": {
+                    const locator = resolveSelector(page, step.selector);
+                    await locator.waitFor({
+                        state: step.state ?? "visible",
+                        timeout: step.timeout ?? 30000,
+                    });
+                    break;
+                }
+                case "assert": {
+                    const effectiveTimeout = step.timeout ?? 30000;
+                    const assertionResult = await evaluateAssertion(page, step, effectiveTimeout);
+                    result.assertion = assertionResult;
+                    if (!assertionResult.passed) {
+                        // Failed assertion: capture screenshot + log deltas, then stop workflow
+                        const rawBuffer = await capturePlaywrightPage(page, { fullPage: step.fullPage ?? false });
+                        const optimized = await optimizeScreenshot(rawBuffer, { maxWidth: 1024, quality: 60 });
+                        result.screenshotBase64 = optimized.data.toString("base64");
+                        result.screenshotMimeType = optimized.mimeType;
+                        // Capture log deltas
+                        const allConsole = sessionManager.getConsoleCollectors(sessionId).flatMap((c) => [...c.getEntries()]);
+                        const allErrors = sessionManager.getErrorCollectors(sessionId).flatMap((c) => [...c.getEntries()]);
+                        result.consoleDelta = allConsole.slice(lastConsoleCount);
+                        result.errorDelta = allErrors.slice(lastErrorCount);
+                        lastConsoleCount = allConsole.length;
+                        lastErrorCount = allErrors.length;
+                        results.push(result);
+                        break; // Break out of switch
+                    }
+                    break; // Switch break for passed assertions (falls through to normal screenshot/log capture)
+                }
+            }
+            // Stop-on-error for failed assertions
+            if (step.action === "assert" && result.assertion && !result.assertion.passed) {
+                break; // Break the for loop
+            }
+            // Capture screenshot (aggressive optimization for workflows)
+            const rawBuffer = await capturePlaywrightPage(page, {
+                fullPage: step.fullPage ?? false,
+            });
+            const optimized = await optimizeScreenshot(rawBuffer, {
+                maxWidth: 1024,
+                quality: 60,
+            });
+            result.screenshotBase64 = optimized.data.toString("base64");
+            result.screenshotMimeType = optimized.mimeType;
+            // Capture log deltas (spread copy for mutation safety)
+            const allConsole = sessionManager
+                .getConsoleCollectors(sessionId)
+                .flatMap((c) => [...c.getEntries()]);
+            const allErrors = sessionManager
+                .getErrorCollectors(sessionId)
+                .flatMap((c) => [...c.getEntries()]);
+            result.consoleDelta = allConsole.slice(lastConsoleCount);
+            result.errorDelta = allErrors.slice(lastErrorCount);
+            lastConsoleCount = allConsole.length;
+            lastErrorCount = allErrors.length;
+            result.success = true;
+            results.push(result);
+        }
+        catch (error) {
+            // Set error message
+            result.error =
+                error instanceof Error ? error.message : String(error);
+            // Best-effort screenshot capture on failure
+            try {
+                const rawBuffer = await capturePlaywrightPage(page, {
+                    fullPage: step.fullPage ?? false,
+                });
+                const optimized = await optimizeScreenshot(rawBuffer, {
+                    maxWidth: 1024,
+                    quality: 60,
+                });
+                result.screenshotBase64 = optimized.data.toString("base64");
+                result.screenshotMimeType = optimized.mimeType;
+            }
+            catch {
+                // Silently skip if screenshot capture fails
+            }
+            // Still capture log deltas for debugging context
+            try {
+                const allConsole = sessionManager
+                    .getConsoleCollectors(sessionId)
+                    .flatMap((c) => [...c.getEntries()]);
+                const allErrors = sessionManager
+                    .getErrorCollectors(sessionId)
+                    .flatMap((c) => [...c.getEntries()]);
+                result.consoleDelta = allConsole.slice(lastConsoleCount);
+                result.errorDelta = allErrors.slice(lastErrorCount);
+                lastConsoleCount = allConsole.length;
+                lastErrorCount = allErrors.length;
+            }
+            catch {
+                // Silently skip if log capture fails
+            }
+            results.push(result);
+            break; // Stop-on-error: halt after first failure
+        }
+    }
+    // Build workflow result
+    const completedSteps = results.filter((r) => r.success).length;
+    const failedResult = results.find((r) => !r.success);
+    return {
+        steps: results,
+        totalSteps: steps.length,
+        completedSteps,
+        failedStep: failedResult ? failedResult.stepIndex : undefined,
+    };
+}

package/build/workflow/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Workflow execution types
+ * Defines step schemas, per-step results, and overall workflow results
+ * for the sequential action executor (QA-01/QA-02).
+ */
+import type { ConsoleEntry, ErrorEntry } from "../capture/types.js";
+/**
+ * A single workflow step — flat schema with action-specific optional fields.
+ *
+ * Required fields per action:
+ * - click: selector
+ * - type: selector, text (text can be empty string but must be defined)
+ * - navigate: url
+ * - wait: selector
+ * - screenshot: (no required fields)
+ * - assert: selector, assertType (plus expected/attribute depending on assertType)
+ */
+export interface WorkflowStep {
+    /** Action to perform */
+    action: "click" | "type" | "navigate" | "screenshot" | "wait" | "assert";
+    /** Element selector — required for click, type, wait */
+    selector?: string;
+    /** Text to type — required for type action */
+    text?: string;
+    /** URL to navigate to — required for navigate action */
+    url?: string;
+    /** Mouse button for click (default: left) */
+    button?: "left" | "right" | "middle";
+    /** Number of clicks for click action (1-3, e.g. 2 for double-click) */
+    clickCount?: number;
+    /** Type one character at a time instead of fill/paste (default: false) */
+    pressSequentially?: boolean;
+    /** Clear field before typing (default: true). Set false to append. */
+    clear?: boolean;
+    /** Capture full scrollable page for screenshot step */
+    fullPage?: boolean;
+    /** Wait state for wait action (default: visible) */
+    state?: "visible" | "hidden" | "attached" | "detached";
+    /** Assertion type — required for assert action */
+    assertType?: "exists" | "not-exists" | "visible" | "hidden" | "text-equals" | "text-contains" | "has-attribute" | "attribute-equals" | "enabled" | "disabled" | "checked" | "not-checked" | "value-equals";
+    /** Expected value for text/attribute assertions */
+    expected?: string;
+    /** Attribute name for attribute assertions */
+    attribute?: string;
+    /** Per-step timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Result of a single workflow step execution.
+ * Always includes log deltas for debugging context.
+ * Screenshot is captured even on failure (best-effort).
+ */
+export interface StepResult {
+    /** Zero-based index of this step in the workflow */
+    stepIndex: number;
+    /** Action that was executed */
+    action: string;
+    /** Whether the step completed successfully */
+    success: boolean;
+    /** ISO timestamp when step execution started */
+    timestamp: string;
+    /** Base64-encoded screenshot captured after step (WebP, quality 60, max 1024px wide) */
+    screenshotBase64?: string;
+    /** MIME type of the screenshot (image/webp) */
+    screenshotMimeType?: string;
+    /** Console log entries captured during this step */
+    consoleDelta: ConsoleEntry[];
+    /** Error entries captured during this step */
+    errorDelta: ErrorEntry[];
+    /** Error message if step failed */
+    error?: string;
+    /** Structured assertion result — only present for assert steps */
+    assertion?: {
+        passed: boolean;
+        assertType: string;
+        selector: string;
+        expected: string | null;
+        actual: string | null;
+        message: string;
+    };
+}
+/**
+ * Overall workflow execution result.
+ * Contains all step results and summary counts.
+ */
+export interface WorkflowResult {
+    /** Results for each executed step (may be fewer than totalSteps on failure) */
+    steps: StepResult[];
+    /** Total number of steps in the input workflow */
+    totalSteps: number;
+    /** Number of steps that completed successfully */
+    completedSteps: number;
+    /** Index of the failed step, if any */
+    failedStep?: number;
+}

package/build/workflow/types.js

@@ -0,0 +1,6 @@
+/**
+ * Workflow execution types
+ * Defines step schemas, per-step results, and overall workflow results
+ * for the sequential action executor (QA-01/QA-02).
+ */
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "auto-feedback",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server for GUI testing and feedback - gives Claude Code eyes and hands",
+  "bin": {
+    "auto-feedback": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "detect-port": "^2.1.0",
+    "node-screenshots": "^0.2.1",
+    "playwright": "^1.58.2",
+    "sharp": "^0.34.5",
+    "tree-kill": "^1.2.2",
+    "wait-on": "^9.0.3",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/wait-on": "^5.3.4",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}