auto-feedback 0.1.0

package/build/utils/errors.js

@@ -0,0 +1,62 @@
+/**
+ * Structured error formatting for tool results
+ */
+/**
+ * Create a tool error response with structured information
+ * @param message Error message
+ * @param context Optional context about what was being attempted
+ * @param suggestedFix Optional suggestion for how to fix the issue
+ * @returns ToolResult with isError: true
+ */
+export function createToolError(message, context, suggestedFix) {
+    let text = `Error: ${message}`;
+    if (context) {
+        text += `\nContext: ${context}`;
+    }
+    if (suggestedFix) {
+        text += `\nSuggested fix: ${suggestedFix}`;
+    }
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+/**
+ * Create a successful tool result
+ * @param data Data to serialize as JSON
+ * @returns ToolResult with isError: false
+ */
+export function createToolResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        isError: false,
+    };
+}
+/**
+ * Create a screenshot tool result with text metadata and image content
+ * @param metadata Metadata to include as JSON text
+ * @param imageBase64 Base64-encoded image data
+ * @param mimeType Image MIME type (default: 'image/webp')
+ * @returns ToolResult with text + image content
+ */
+export function createScreenshotResult(metadata, imageBase64, mimeType = "image/webp") {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(metadata, null, 2),
+            },
+            {
+                type: "image",
+                data: imageBase64,
+                mimeType,
+            },
+        ],
+        isError: false,
+    };
+}

package/build/utils/shutdown.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Graceful shutdown coordinator with cleanup handler registry
+ */
+export declare class ShutdownManager {
+    private cleanupHandlers;
+    private isShuttingDown;
+    /**
+     * Register a cleanup handler to run during shutdown
+     */
+    register(handler: () => Promise<void>): void;
+    /**
+     * Execute all cleanup handlers and exit process
+     * Safe to call multiple times - subsequent calls are ignored
+     */
+    cleanup(): Promise<void>;
+}

package/build/utils/shutdown.js

@@ -0,0 +1,34 @@
+/**
+ * Graceful shutdown coordinator with cleanup handler registry
+ */
+export class ShutdownManager {
+    cleanupHandlers = [];
+    isShuttingDown = false;
+    /**
+     * Register a cleanup handler to run during shutdown
+     */
+    register(handler) {
+        this.cleanupHandlers.push(handler);
+    }
+    /**
+     * Execute all cleanup handlers and exit process
+     * Safe to call multiple times - subsequent calls are ignored
+     */
+    async cleanup() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        console.error("Shutting down...");
+        // Run all handlers in parallel with individual try/catch
+        const results = await Promise.allSettled(this.cleanupHandlers.map((handler) => handler()));
+        // Log any handler failures
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                console.error(`Cleanup handler ${index} failed:`, result.reason);
+            }
+        });
+        console.error("Shutdown complete");
+        process.exit(0);
+    }
+}

package/build/workflow/assertions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Assertion evaluation for workflow assert steps.
+ * Queries element state via Playwright locator methods and returns
+ * structured pass/fail results.
+ */
+import type { Page } from "playwright";
+import type { WorkflowStep } from "./types.js";
+/**
+ * Structured result of an assertion evaluation.
+ */
+export interface AssertionResult {
+    passed: boolean;
+    assertType: string;
+    selector: string;
+    expected: string | null;
+    actual: string | null;
+    message: string;
+}
+/**
+ * Evaluate an assertion step against a Playwright page.
+ *
+ * Assertion failures produce { passed: false } results, NOT thrown exceptions.
+ * Only unexpected errors (page crash, browser disconnect) propagate as throws.
+ */
+export declare function evaluateAssertion(page: Page, step: WorkflowStep, timeout: number): Promise<AssertionResult>;

package/build/workflow/assertions.js

@@ -0,0 +1,326 @@
+/**
+ * Assertion evaluation for workflow assert steps.
+ * Queries element state via Playwright locator methods and returns
+ * structured pass/fail results.
+ */
+import { resolveSelector } from "../interaction/selectors.js";
+/**
+ * Evaluate an assertion step against a Playwright page.
+ *
+ * Assertion failures produce { passed: false } results, NOT thrown exceptions.
+ * Only unexpected errors (page crash, browser disconnect) propagate as throws.
+ */
+export async function evaluateAssertion(page, step, timeout) {
+    const base = {
+        assertType: step.assertType,
+        selector: step.selector,
+    };
+    const locator = resolveSelector(page, step.selector);
+    switch (step.assertType) {
+        case "exists": {
+            const count = await locator.count();
+            const passed = count > 0;
+            return {
+                ...base,
+                passed,
+                expected: "element exists in DOM",
+                actual: count > 0 ? `found (${count} match${count > 1 ? "es" : ""})` : "not found",
+                message: passed
+                    ? `PASS: Element "${step.selector}" exists (${count} match${count > 1 ? "es" : ""})`
+                    : `FAIL: Element "${step.selector}" does not exist`,
+            };
+        }
+        case "not-exists": {
+            const count = await locator.count();
+            const passed = count === 0;
+            return {
+                ...base,
+                passed,
+                expected: "element does not exist in DOM",
+                actual: count === 0 ? "not found" : `found (${count} match${count > 1 ? "es" : ""})`,
+                message: passed
+                    ? `PASS: Element "${step.selector}" does not exist`
+                    : `FAIL: Element "${step.selector}" exists (${count} match${count > 1 ? "es" : ""})`,
+            };
+        }
+        case "visible": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: "element is visible",
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM (timeout waiting for attachment)`,
+                };
+            }
+            const visible = await locator.isVisible();
+            return {
+                ...base,
+                passed: visible,
+                expected: "element is visible",
+                actual: visible ? "visible" : "hidden",
+                message: visible
+                    ? `PASS: Element "${step.selector}" is visible`
+                    : `FAIL: Element "${step.selector}" is hidden`,
+            };
+        }
+        case "hidden": {
+            const count = await locator.count();
+            if (count === 0) {
+                return {
+                    ...base,
+                    passed: true,
+                    expected: "element is hidden",
+                    actual: "not in DOM (hidden)",
+                    message: `PASS: Element "${step.selector}" is not in DOM (counts as hidden)`,
+                };
+            }
+            const visible = await locator.isVisible();
+            const passed = !visible;
+            return {
+                ...base,
+                passed,
+                expected: "element is hidden",
+                actual: visible ? "visible" : "hidden",
+                message: passed
+                    ? `PASS: Element "${step.selector}" is hidden`
+                    : `FAIL: Element "${step.selector}" is visible`,
+            };
+        }
+        case "text-equals": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: `text equals "${step.expected}"`,
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const text = (await locator.innerText({ timeout })).trim();
+            const passed = text === step.expected;
+            return {
+                ...base,
+                passed,
+                expected: `text equals "${step.expected}"`,
+                actual: `"${text}"`,
+                message: passed
+                    ? `PASS: Text of "${step.selector}" equals "${step.expected}"`
+                    : `FAIL: Text of "${step.selector}" is "${text}", expected "${step.expected}"`,
+            };
+        }
+        case "text-contains": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: `text contains "${step.expected}"`,
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const text = await locator.innerText({ timeout });
+            const passed = text.includes(step.expected ?? "");
+            return {
+                ...base,
+                passed,
+                expected: `text contains "${step.expected}"`,
+                actual: `"${text}"`,
+                message: passed
+                    ? `PASS: Text of "${step.selector}" contains "${step.expected}"`
+                    : `FAIL: Text of "${step.selector}" is "${text}", does not contain "${step.expected}"`,
+            };
+        }
+        case "has-attribute": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: `has attribute "${step.attribute}"`,
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const value = await locator.getAttribute(step.attribute, { timeout });
+            const passed = value !== null;
+            return {
+                ...base,
+                passed,
+                expected: `has attribute "${step.attribute}"`,
+                actual: passed ? `attribute "${step.attribute}" present (value: "${value}")` : `attribute "${step.attribute}" not found`,
+                message: passed
+                    ? `PASS: Element "${step.selector}" has attribute "${step.attribute}"`
+                    : `FAIL: Element "${step.selector}" does not have attribute "${step.attribute}"`,
+            };
+        }
+        case "attribute-equals": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: `attribute "${step.attribute}" equals "${step.expected}"`,
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const value = await locator.getAttribute(step.attribute, { timeout });
+            const passed = value === step.expected;
+            return {
+                ...base,
+                passed,
+                expected: `attribute "${step.attribute}" equals "${step.expected}"`,
+                actual: value !== null ? `"${value}"` : "attribute not found",
+                message: passed
+                    ? `PASS: Attribute "${step.attribute}" of "${step.selector}" equals "${step.expected}"`
+                    : `FAIL: Attribute "${step.attribute}" of "${step.selector}" is ${value !== null ? `"${value}"` : "not found"}, expected "${step.expected}"`,
+            };
+        }
+        case "enabled": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: "element is enabled",
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const enabled = await locator.isEnabled({ timeout });
+            return {
+                ...base,
+                passed: enabled,
+                expected: "element is enabled",
+                actual: enabled ? "enabled" : "disabled",
+                message: enabled
+                    ? `PASS: Element "${step.selector}" is enabled`
+                    : `FAIL: Element "${step.selector}" is disabled`,
+            };
+        }
+        case "disabled": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: "element is disabled",
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const enabled = await locator.isEnabled({ timeout });
+            const passed = !enabled;
+            return {
+                ...base,
+                passed,
+                expected: "element is disabled",
+                actual: enabled ? "enabled" : "disabled",
+                message: passed
+                    ? `PASS: Element "${step.selector}" is disabled`
+                    : `FAIL: Element "${step.selector}" is enabled`,
+            };
+        }
+        case "checked": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: "element is checked",
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const checked = await locator.isChecked({ timeout });
+            return {
+                ...base,
+                passed: checked,
+                expected: "element is checked",
+                actual: checked ? "checked" : "not checked",
+                message: checked
+                    ? `PASS: Element "${step.selector}" is checked`
+                    : `FAIL: Element "${step.selector}" is not checked`,
+            };
+        }
+        case "not-checked": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: "element is not checked",
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const checked = await locator.isChecked({ timeout });
+            const passed = !checked;
+            return {
+                ...base,
+                passed,
+                expected: "element is not checked",
+                actual: checked ? "checked" : "not checked",
+                message: passed
+                    ? `PASS: Element "${step.selector}" is not checked`
+                    : `FAIL: Element "${step.selector}" is checked`,
+            };
+        }
+        case "value-equals": {
+            try {
+                await locator.waitFor({ state: "attached", timeout });
+            }
+            catch {
+                return {
+                    ...base,
+                    passed: false,
+                    expected: `value equals "${step.expected}"`,
+                    actual: "element not found in DOM",
+                    message: `FAIL: Element "${step.selector}" not found in DOM`,
+                };
+            }
+            const value = await locator.inputValue({ timeout });
+            const passed = value === step.expected;
+            return {
+                ...base,
+                passed,
+                expected: `value equals "${step.expected}"`,
+                actual: `"${value}"`,
+                message: passed
+                    ? `PASS: Value of "${step.selector}" equals "${step.expected}"`
+                    : `FAIL: Value of "${step.selector}" is "${value}", expected "${step.expected}"`,
+            };
+        }
+        default: {
+            return {
+                ...base,
+                passed: false,
+                expected: null,
+                actual: null,
+                message: `Unknown assertion type: ${step.assertType}`,
+            };
+        }
+    }
+}

package/build/workflow/executor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { Page } from "playwright";
+import type { SessionManager } from "../session-manager.js";
+import type { WorkflowStep, WorkflowResult } from "./types.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 declare function validateStep(step: WorkflowStep, index: number): string | 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 declare function executeWorkflow(params: {
+    page: Page;
+    steps: WorkflowStep[];
+    sessionManager: SessionManager;
+    sessionId: string;
+    pageIdentifier: string;
+}): Promise<WorkflowResult>;