auto-feedback 0.1.0

package/build/interaction/selectors.js

@@ -0,0 +1,84 @@
+/**
+ * Selector resolution and page discovery
+ * Converts string selectors to Playwright Locators and discovers active pages
+ */
+/**
+ * Convert a selector string to a Playwright Locator.
+ *
+ * Supported formats:
+ * - CSS selectors: #id, .class, div > span (passed directly to Playwright)
+ * - Text: text=Click me (Playwright native)
+ * - Role: role=button[name='Submit'] (Playwright native)
+ * - XPath: xpath=//div[@id='main'] (Playwright native)
+ * - Test ID: testid=my-btn (resolved via getByTestId)
+ */
+export function resolveSelector(page, selector) {
+    // testid= is the one prefix Playwright doesn't handle natively
+    if (selector.startsWith("testid=")) {
+        const testId = selector.slice("testid=".length);
+        return page.getByTestId(testId);
+    }
+    // All other selectors: CSS, text=, role=, xpath= — Playwright handles natively
+    return page.locator(selector);
+}
+/**
+ * Find the active page for interaction in a session.
+ *
+ * - If pageIdentifier is provided, looks up that specific page
+ * - If omitted and session has exactly one page, auto-selects it
+ * - If omitted and session has 0 or >1 pages, returns actionable error
+ */
+export function getActivePage(sessionManager, sessionId, pageIdentifier) {
+    // Validate session exists
+    const session = sessionManager.get(sessionId);
+    if (!session) {
+        return {
+            success: false,
+            error: `Session not found: ${sessionId}`,
+        };
+    }
+    if (pageIdentifier) {
+        // Look up specific page by identifier
+        const ref = sessionManager.getPageRef(sessionId, pageIdentifier);
+        if (!ref) {
+            const refs = sessionManager.getPageRefs(sessionId);
+            const available = refs.map((r) => r.type === "electron" ? "electron" : r.url ?? "unknown");
+            return {
+                success: false,
+                error: `Page not found: ${pageIdentifier}`,
+                availablePages: available.length > 0 ? available : undefined,
+            };
+        }
+        return {
+            success: true,
+            page: ref.page,
+            identifier: pageIdentifier,
+            type: ref.type,
+        };
+    }
+    // Auto-discover: no pageIdentifier provided
+    const refs = sessionManager.getPageRefs(sessionId);
+    if (refs.length === 0) {
+        return {
+            success: false,
+            error: "No pages available in this session. Launch an app first with launch_web_server, launch_electron, or screenshot_web.",
+        };
+    }
+    if (refs.length === 1) {
+        const ref = refs[0];
+        const identifier = ref.type === "electron" ? "electron" : ref.url ?? "unknown";
+        return {
+            success: true,
+            page: ref.page,
+            identifier,
+            type: ref.type,
+        };
+    }
+    // Multiple pages — require explicit selection
+    const available = refs.map((r) => r.type === "electron" ? "electron" : r.url ?? "unknown");
+    return {
+        success: false,
+        error: `Multiple pages found (${refs.length}). Specify pageIdentifier to target a specific page.`,
+        availablePages: available,
+    };
+}

package/build/interaction/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Interaction-specific type definitions
+ * Used by click_element, type_text, and navigation tools
+ */
+import type { Page } from "playwright";
+/** Options for click_element tool */
+export interface ClickOptions {
+    button?: "left" | "right" | "middle";
+    clickCount?: number;
+    position?: {
+        x: number;
+        y: number;
+    };
+    force?: boolean;
+    timeout?: number;
+}
+/** Options for type_text tool */
+export interface TypeOptions {
+    pressSequentially?: boolean;
+    delay?: number;
+    clear?: boolean;
+    timeout?: number;
+}
+/** Navigate tool actions */
+export type NavigateAction = "goto" | "back" | "forward";
+/** Result of finding the active page for interaction */
+export type PageDiscoveryResult = {
+    success: true;
+    page: Page;
+    identifier: string;
+    type: "web" | "electron";
+} | {
+    success: false;
+    error: string;
+    availablePages?: string[];
+};
+/** State values for locator.waitFor() */
+export type WaitForState = "visible" | "hidden" | "attached" | "detached";
+/** Shape of the get_element_state tool response */
+export interface ElementStateResult {
+    selector: string;
+    visible: boolean;
+    enabled: boolean;
+    editable: boolean;
+    checked: boolean | null;
+    textContent: string | null;
+    innerText: string;
+    inputValue: string | null;
+    attributes: Record<string, string | null>;
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}

package/build/interaction/types.js

@@ -0,0 +1,5 @@
+/**
+ * Interaction-specific type definitions
+ * Used by click_element, type_text, and navigation tools
+ */
+export {};

package/build/process/cleanup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Process tree cleanup utility
+ * Wraps tree-kill with timeout for best-effort process termination
+ */
+import { ChildProcess } from "child_process";
+import { Resource } from "../types/index.js";
+import { ProcessType } from "./types.js";
+/**
+ * Kill a process and all its children (best-effort)
+ * Always resolves -- cleanup should never block shutdown
+ *
+ * @param pid - OS process ID to kill
+ * @param timeoutMs - Maximum time to wait for kill (default 5000ms)
+ */
+export declare function killProcessTree(pid: number, timeoutMs?: number): Promise<void>;
+/**
+ * Create a Resource that cleans up a child process on disposal
+ * Integrates with SessionManager's resource tracking
+ *
+ * @param childProcess - The spawned child process
+ * @param _type - Process type (for future use in type-specific cleanup)
+ */
+export declare function createProcessResource(childProcess: ChildProcess, _type: ProcessType): Resource;

package/build/process/cleanup.js

@@ -0,0 +1,50 @@
+/**
+ * Process tree cleanup utility
+ * Wraps tree-kill with timeout for best-effort process termination
+ */
+import treeKill from "tree-kill";
+/**
+ * Kill a process and all its children (best-effort)
+ * Always resolves -- cleanup should never block shutdown
+ *
+ * @param pid - OS process ID to kill
+ * @param timeoutMs - Maximum time to wait for kill (default 5000ms)
+ */
+export function killProcessTree(pid, timeoutMs = 5000) {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            console.error(`[Process] Tree-kill timeout after ${timeoutMs}ms for PID ${pid}, continuing anyway`);
+            resolve();
+        }, timeoutMs);
+        treeKill(pid, "SIGTERM", (error) => {
+            clearTimeout(timeout);
+            if (error) {
+                console.error(`[Process] Tree-kill error for PID ${pid}: ${error.message} (process may already be dead)`);
+            }
+            else {
+                console.error(`[Process] Killed process tree for PID ${pid}`);
+            }
+            resolve();
+        });
+    });
+}
+/**
+ * Create a Resource that cleans up a child process on disposal
+ * Integrates with SessionManager's resource tracking
+ *
+ * @param childProcess - The spawned child process
+ * @param _type - Process type (for future use in type-specific cleanup)
+ */
+export function createProcessResource(childProcess, _type) {
+    return {
+        cleanup: async () => {
+            // Process already exited -- nothing to clean up
+            if (childProcess.exitCode !== null) {
+                return;
+            }
+            if (childProcess.pid !== undefined) {
+                await killProcessTree(childProcess.pid);
+            }
+        },
+    };
+}

package/build/process/launcher.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cross-platform process spawning utility
+ * Handles Windows quirks (cmd scripts, npm wrappers) transparently
+ */
+import { ChildProcess, SpawnOptions } from "child_process";
+/**
+ * Spawn a process with cross-platform compatibility
+ * Automatically enables shell mode on Windows for npm/npx and .cmd/.bat files
+ *
+ * @param command - Command to execute
+ * @param args - Arguments for the command
+ * @param options - Additional spawn options
+ */
+export declare function spawnCrossPlatform(command: string, args: string[], options?: SpawnOptions): ChildProcess;
+/**
+ * Attach logging listeners to a child process
+ * All output is routed to console.error to avoid corrupting stdio transport
+ *
+ * @param child - The child process to monitor
+ * @param label - Label for log messages (e.g., "web-server")
+ */
+export declare function attachProcessListeners(child: ChildProcess, label: string): void;

package/build/process/launcher.js

@@ -0,0 +1,54 @@
+/**
+ * Cross-platform process spawning utility
+ * Handles Windows quirks (cmd scripts, npm wrappers) transparently
+ */
+import { spawn } from "child_process";
+/**
+ * Spawn a process with cross-platform compatibility
+ * Automatically enables shell mode on Windows for npm/npx and .cmd/.bat files
+ *
+ * @param command - Command to execute
+ * @param args - Arguments for the command
+ * @param options - Additional spawn options
+ */
+export function spawnCrossPlatform(command, args, options = {}) {
+    const isWindows = process.platform === "win32";
+    let useShell = options.shell ?? false;
+    if (isWindows) {
+        const lowerCmd = command.toLowerCase();
+        // npm/npx on Windows are .cmd files that require shell
+        if (lowerCmd === "npm" ||
+            lowerCmd === "npx" ||
+            lowerCmd.endsWith(".cmd") ||
+            lowerCmd.endsWith(".bat")) {
+            useShell = true;
+        }
+    }
+    return spawn(command, args, {
+        ...options,
+        shell: useShell,
+        windowsHide: true,
+        stdio: options.stdio || "pipe",
+    });
+}
+/**
+ * Attach logging listeners to a child process
+ * All output is routed to console.error to avoid corrupting stdio transport
+ *
+ * @param child - The child process to monitor
+ * @param label - Label for log messages (e.g., "web-server")
+ */
+export function attachProcessListeners(child, label) {
+    child.stdout?.on("data", (data) => {
+        console.error(`[${label} stdout] ${data.toString().trim()}`);
+    });
+    child.stderr?.on("data", (data) => {
+        console.error(`[${label} stderr] ${data.toString().trim()}`);
+    });
+    child.on("error", (err) => {
+        console.error(`[${label}] Spawn error: ${err.message}`);
+    });
+    child.on("exit", (code, signal) => {
+        console.error(`[${label}] Exited: code=${code}, signal=${signal}`);
+    });
+}

package/build/process/monitor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Server readiness detection
+ * Uses dual strategy: stdout pattern matching + TCP port polling
+ */
+import { ChildProcess } from "child_process";
+/**
+ * Detect when a spawned server is ready to accept connections
+ * Races two strategies: stdout pattern matching and TCP port availability
+ *
+ * @param child - The spawned server process
+ * @param port - Expected port the server will listen on
+ * @param timeoutMs - Maximum time to wait for readiness (default 60000ms)
+ */
+export declare function detectServerReady(child: ChildProcess, port: number, timeoutMs?: number): Promise<void>;

package/build/process/monitor.js

@@ -0,0 +1,67 @@
+/**
+ * Server readiness detection
+ * Uses dual strategy: stdout pattern matching + TCP port polling
+ */
+import waitOn from "wait-on";
+/**
+ * Common server ready patterns across popular dev servers
+ */
+const readyPatterns = [
+    /Local:.*https?:\/\/localhost[:\d]*/i, // Vite
+    /webpack.*compiled/i, // webpack
+    /ready.*started.*server.*on/i, // Next.js
+    /server.*(?:listening|running|started).*:\d+/i, // generic
+    /ready on/i, // Next.js alt
+    /compiled successfully/i, // CRA
+];
+/**
+ * Detect when a spawned server is ready to accept connections
+ * Races two strategies: stdout pattern matching and TCP port availability
+ *
+ * @param child - The spawned server process
+ * @param port - Expected port the server will listen on
+ * @param timeoutMs - Maximum time to wait for readiness (default 60000ms)
+ */
+export function detectServerReady(child, port, timeoutMs = 60000) {
+    // Strategy 1: stdout/stderr pattern matching
+    const stdoutReady = new Promise((resolve, reject) => {
+        const checkOutput = (data) => {
+            const text = data.toString();
+            for (const pattern of readyPatterns) {
+                if (pattern.test(text)) {
+                    cleanup();
+                    resolve();
+                    return;
+                }
+            }
+        };
+        const onExit = (code) => {
+            cleanup();
+            reject(new Error(`Server process exited before becoming ready (exit code: ${code})`));
+        };
+        const cleanup = () => {
+            child.stdout?.removeListener("data", checkOutput);
+            child.stderr?.removeListener("data", checkOutput);
+            child.removeListener("exit", onExit);
+        };
+        child.stdout?.on("data", checkOutput);
+        child.stderr?.on("data", checkOutput);
+        child.on("exit", onExit);
+    });
+    // Strategy 2: TCP port polling via wait-on
+    const portReady = waitOn({
+        resources: [`tcp:localhost:${port}`],
+        timeout: timeoutMs,
+        interval: 500,
+        log: false,
+    });
+    return Promise.race([stdoutReady, portReady]).then(() => {
+        console.error(`[Monitor] Server ready on port ${port}`);
+    }, (error) => {
+        // Provide better error context if the process has already exited
+        if (child.exitCode !== null) {
+            throw new Error(`Server process exited with code ${child.exitCode} before becoming ready on port ${port}`);
+        }
+        throw error;
+    });
+}

package/build/process/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Process management type definitions
+ * Contract for all process resources tracked by the feedback server
+ */
+/**
+ * Types of processes the server can manage
+ */
+export type ProcessType = "web-server" | "electron" | "windows-exe";
+/**
+ * Lifecycle status of a managed process
+ */
+export type ProcessStatus = "launching" | "ready" | "running" | "stopped" | "error";
+/**
+ * Runtime information for a tracked process
+ */
+export interface ProcessInfo {
+    /** Unique identifier (session ID + process type or similar) */
+    id: string;
+    /** The session this process belongs to */
+    sessionId: string;
+    /** Process type */
+    type: ProcessType;
+    /** Current lifecycle status */
+    status: ProcessStatus;
+    /** OS process ID (undefined if not yet spawned) */
+    pid: number | undefined;
+    /** The command that was used to launch */
+    command: string;
+    /** Arguments passed to the command */
+    args: string[];
+    /** Working directory */
+    cwd: string;
+    /** Port number (for web servers) */
+    port?: number;
+    /** When the process was started */
+    startedAt: Date;
+    /** When readiness was detected */
+    readyAt?: Date;
+    /** Exit code if process has stopped */
+    exitCode?: number | null;
+}
+/**
+ * Configuration for launching a web server process
+ */
+export interface LaunchWebServerConfig {
+    /** Session this process belongs to */
+    sessionId: string;
+    /** Command to execute (e.g., "npm", "npx") */
+    command: string;
+    /** Arguments (e.g., ["run", "dev"], ["vite"]) */
+    args: string[];
+    /** Working directory for the project */
+    cwd: string;
+    /** Expected port the server will listen on */
+    port: number;
+    /** Readiness timeout in ms (default 60000) */
+    timeoutMs?: number;
+}
+/**
+ * Configuration for launching an Electron application
+ */
+export interface LaunchElectronConfig {
+    /** Session this process belongs to */
+    sessionId: string;
+    /** Path to Electron main entry file */
+    entryPath: string;
+    /** Optional working directory */
+    cwd?: string;
+    /** Launch timeout in ms (default 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Configuration for launching a Windows executable
+ */
+export interface LaunchWindowsExeConfig {
+    /** Session this process belongs to */
+    sessionId: string;
+    /** Path to the .exe file */
+    exePath: string;
+    /** Optional command line arguments */
+    args?: string[];
+    /** Optional working directory */
+    cwd?: string;
+}

package/build/process/types.js

@@ -0,0 +1,5 @@
+/**
+ * Process management type definitions
+ * Contract for all process resources tracked by the feedback server
+ */
+export {};

package/build/screenshot/auto-capture.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auto-capture module
+ * Listens for Playwright page navigation events and captures screenshots automatically
+ */
+import type { Page } from "playwright";
+import type { SessionManager } from "../session-manager.js";
+/**
+ * Attach auto-capture listener to a Playwright page.
+ * Captures a screenshot after every main-frame navigation.
+ * Stores the optimized screenshot in the session manager.
+ *
+ * @returns Cleanup function to remove the listener
+ */
+export declare function setupAutoCapture(page: Page, sessionId: string, sessionManager: SessionManager): () => void;

package/build/screenshot/auto-capture.js

@@ -0,0 +1,38 @@
+/**
+ * Auto-capture module
+ * Listens for Playwright page navigation events and captures screenshots automatically
+ */
+import { optimizeScreenshot } from "./optimize.js";
+/**
+ * Attach auto-capture listener to a Playwright page.
+ * Captures a screenshot after every main-frame navigation.
+ * Stores the optimized screenshot in the session manager.
+ *
+ * @returns Cleanup function to remove the listener
+ */
+export function setupAutoCapture(page, sessionId, sessionManager) {
+    const handler = async (frame) => {
+        if (frame !== page.mainFrame())
+            return;
+        try {
+            await page.waitForLoadState("load");
+            const rawBuffer = await page.screenshot({ type: "png" });
+            const optimized = await optimizeScreenshot(rawBuffer);
+            sessionManager.setAutoCapture(sessionId, {
+                imageBase64: optimized.data.toString("base64"),
+                mimeType: optimized.mimeType,
+                url: page.url(),
+                capturedAt: new Date(),
+            });
+            console.error(`[auto-capture] Captured ${optimized.width}x${optimized.height} ` +
+                `(${optimized.data.length} bytes) for session ${sessionId}`);
+        }
+        catch (error) {
+            console.error(`[auto-capture] Failed for session ${sessionId}:`, error);
+        }
+    };
+    page.on("framenavigated", handler);
+    return () => {
+        page.off("framenavigated", handler);
+    };
+}

package/build/screenshot/capture.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Core screenshot capture functions
+ * Playwright pages (web/Electron) and Windows desktop windows
+ */
+import type { Page } from "playwright";
+/**
+ * Capture a screenshot from a Playwright Page (web or Electron)
+ * Returns raw PNG buffer for further optimization
+ */
+export declare function capturePlaywrightPage(page: Page, options?: {
+    fullPage?: boolean;
+}): Promise<Buffer>;
+/**
+ * Capture a screenshot of a Windows desktop window by PID.
+ * Uses node-screenshots to enumerate windows and match by process ID.
+ * Returns raw PNG buffer for further optimization.
+ *
+ * Note: node-screenshots Window objects may not expose PID in all versions.
+ * Falls back to matching by window title if PID is unavailable.
+ */
+export declare function captureDesktopWindow(pid: number): Promise<Buffer>;

package/build/screenshot/capture.js

@@ -0,0 +1,48 @@
+/**
+ * Core screenshot capture functions
+ * Playwright pages (web/Electron) and Windows desktop windows
+ */
+/**
+ * Capture a screenshot from a Playwright Page (web or Electron)
+ * Returns raw PNG buffer for further optimization
+ */
+export async function capturePlaywrightPage(page, options) {
+    return await page.screenshot({
+        fullPage: options?.fullPage ?? false,
+        type: "png",
+    });
+}
+/**
+ * Capture a screenshot of a Windows desktop window by PID.
+ * Uses node-screenshots to enumerate windows and match by process ID.
+ * Returns raw PNG buffer for further optimization.
+ *
+ * Note: node-screenshots Window objects may not expose PID in all versions.
+ * Falls back to matching by window title if PID is unavailable.
+ */
+export async function captureDesktopWindow(pid) {
+    // Dynamic import to avoid load-time failures on non-Windows
+    const { Window } = await import("node-screenshots");
+    const windows = Window.all();
+    // node-screenshots Window type doesn't expose pid in current typings,
+    // but some builds include it at runtime. Use any cast for defensive check.
+    const target = windows.find((w) => {
+        const wAny = w;
+        if (typeof wAny.processId === "number")
+            return wAny.processId === pid;
+        if (typeof wAny.pid === "number")
+            return wAny.pid === pid;
+        if (typeof wAny.pid === "function")
+            return wAny.pid() === pid;
+        return false;
+    });
+    if (!target) {
+        throw new Error(`No window found for PID ${pid}. The process may not have a visible window yet.`);
+    }
+    if (target.isMinimized) {
+        throw new Error(`Window for PID ${pid} is minimized. Restore it before capturing.`);
+    }
+    const image = await target.captureImage();
+    const pngData = await image.toPng();
+    return Buffer.from(pngData);
+}

package/build/screenshot/optimize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Screenshot optimization pipeline
+ * Resizes and converts screenshots to WebP for efficient MCP transport
+ */
+/**
+ * Optimize a raw screenshot buffer: resize + WebP conversion
+ * @param buffer - Raw PNG/JPEG buffer from capture
+ * @param options - Optimization options
+ * @returns Optimized buffer with metadata
+ */
+export declare function optimizeScreenshot(buffer: Buffer, options?: {
+    maxWidth?: number;
+    quality?: number;
+}): Promise<{
+    data: Buffer;
+    mimeType: string;
+    width: number;
+    height: number;
+}>;

package/build/screenshot/optimize.js

@@ -0,0 +1,28 @@
+/**
+ * Screenshot optimization pipeline
+ * Resizes and converts screenshots to WebP for efficient MCP transport
+ */
+import sharp from "sharp";
+/**
+ * Optimize a raw screenshot buffer: resize + WebP conversion
+ * @param buffer - Raw PNG/JPEG buffer from capture
+ * @param options - Optimization options
+ * @returns Optimized buffer with metadata
+ */
+export async function optimizeScreenshot(buffer, options) {
+    const maxWidth = options?.maxWidth ?? 1280;
+    const quality = options?.quality ?? 80;
+    const optimized = await sharp(buffer)
+        .resize(maxWidth, undefined, {
+        fit: "inside",
+        withoutEnlargement: true,
+    })
+        .webp({ quality })
+        .toBuffer({ resolveWithObject: true });
+    return {
+        data: optimized.data,
+        mimeType: "image/webp",
+        width: optimized.info.width,
+        height: optimized.info.height,
+    };
+}