auto-feedback 0.1.0

package/build/screenshot/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Screenshot-specific type definitions
+ */
+import type { Page, Browser, BrowserContext, ElectronApplication } from "playwright";
+/**
+ * Options for taking a screenshot
+ */
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    maxWidth?: number;
+    quality?: number;
+}
+/**
+ * Result of a captured and optimized screenshot
+ */
+export interface ScreenshotResult {
+    data: string;
+    mimeType: string;
+    width: number;
+    height: number;
+    originalSize: number;
+    optimizedSize: number;
+}
+/**
+ * Stored reference to a Playwright Page for screenshot access
+ */
+export interface PageReference {
+    type: "web" | "electron";
+    page: Page;
+    browser?: Browser;
+    browserContext?: BrowserContext;
+    electronApp?: ElectronApplication;
+    url?: string;
+}
+/**
+ * Data stored from an auto-capture event
+ */
+export interface AutoCaptureData {
+    imageBase64: string;
+    mimeType: string;
+    url: string;
+    capturedAt: Date;
+}

package/build/screenshot/types.js

@@ -0,0 +1,4 @@
+/**
+ * Screenshot-specific type definitions
+ */
+export {};

package/build/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP server factory
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "./session-manager.js";
+/**
+ * Create and configure the Feedback MCP server
+ * Does not connect transport - that's the caller's responsibility
+ */
+export declare function createServer(sessionManager: SessionManager): McpServer;

package/build/server.js

@@ -0,0 +1,18 @@
+/**
+ * MCP server factory
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools/index.js";
+/**
+ * Create and configure the Feedback MCP server
+ * Does not connect transport - that's the caller's responsibility
+ */
+export function createServer(sessionManager) {
+    const server = new McpServer({
+        name: "feedback",
+        version: "0.1.0",
+    });
+    // Register MCP tools
+    registerTools(server, sessionManager);
+    return server;
+}

package/build/session-manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Session lifecycle management
+ * Tracks multiple concurrent sessions with unique UUIDs
+ */
+import { Session, Resource } from "./types/index.js";
+import { PageReference, AutoCaptureData } from "./screenshot/types.js";
+import { Collector, ConsoleEntry, ErrorEntry, NetworkEntry, ProcessOutputEntry } from "./capture/types.js";
+export declare class SessionManager {
+    private sessions;
+    private pageRefs;
+    private autoCaptures;
+    private consoleCollectors;
+    private errorCollectors;
+    private networkCollectors;
+    private processCollectors;
+    /**
+     * Create a new session with a unique UUID
+     * @returns Session ID
+     */
+    create(): string;
+    /**
+     * Get a session by ID
+     * @returns Session or undefined if not found
+     */
+    get(id: string): Session | undefined;
+    /**
+     * List all active session IDs
+     * @returns Array of session IDs
+     */
+    list(): string[];
+    /**
+     * Add a resource to a session
+     * @throws Error if session not found
+     */
+    addResource(sessionId: string, resource: Resource): void;
+    /**
+     * Store a typed Playwright Page reference for a session
+     * Key format: ${sessionId}:${identifier} where identifier is URL or 'electron'
+     */
+    setPageRef(sessionId: string, identifier: string, ref: PageReference): void;
+    /**
+     * Get a specific page reference by session and identifier
+     */
+    getPageRef(sessionId: string, identifier: string): PageReference | undefined;
+    /**
+     * Get all page references for a session
+     */
+    getPageRefs(sessionId: string): PageReference[];
+    /**
+     * Remove a specific page reference
+     */
+    removePageRef(sessionId: string, identifier: string): void;
+    /**
+     * Store the latest auto-captured screenshot for a session
+     */
+    setAutoCapture(sessionId: string, data: AutoCaptureData): void;
+    /**
+     * Get the latest auto-captured screenshot for a session
+     */
+    getAutoCapture(sessionId: string): AutoCaptureData | undefined;
+    /**
+     * Store a console collector for a session
+     */
+    setConsoleCollector(sessionId: string, identifier: string, collector: Collector<ConsoleEntry>): void;
+    /**
+     * Get a specific console collector by session and identifier
+     */
+    getConsoleCollector(sessionId: string, identifier: string): Collector<ConsoleEntry> | undefined;
+    /**
+     * Get all console collectors for a session
+     */
+    getConsoleCollectors(sessionId: string): Collector<ConsoleEntry>[];
+    /**
+     * Store an error collector for a session
+     */
+    setErrorCollector(sessionId: string, identifier: string, collector: Collector<ErrorEntry>): void;
+    /**
+     * Get a specific error collector by session and identifier
+     */
+    getErrorCollector(sessionId: string, identifier: string): Collector<ErrorEntry> | undefined;
+    /**
+     * Get all error collectors for a session
+     */
+    getErrorCollectors(sessionId: string): Collector<ErrorEntry>[];
+    /**
+     * Store a network collector for a session
+     */
+    setNetworkCollector(sessionId: string, identifier: string, collector: Collector<NetworkEntry>): void;
+    /**
+     * Get a specific network collector by session and identifier
+     */
+    getNetworkCollector(sessionId: string, identifier: string): Collector<NetworkEntry> | undefined;
+    /**
+     * Get all network collectors for a session
+     */
+    getNetworkCollectors(sessionId: string): Collector<NetworkEntry>[];
+    /**
+     * Store a process output collector for a session
+     */
+    setProcessCollector(sessionId: string, identifier: string, collector: Collector<ProcessOutputEntry>): void;
+    /**
+     * Get a specific process collector by session and identifier
+     */
+    getProcessCollector(sessionId: string, identifier: string): Collector<ProcessOutputEntry> | undefined;
+    /**
+     * Get all process collectors for a session
+     */
+    getProcessCollectors(sessionId: string): Collector<ProcessOutputEntry>[];
+    /**
+     * Destroy a session and clean up all its resources
+     * Logs cleanup errors but doesn't throw
+     * No-op if session doesn't exist
+     */
+    destroy(sessionId: string): Promise<void>;
+    /**
+     * Destroy all sessions (for shutdown cleanup)
+     */
+    destroyAll(): Promise<void>;
+}

package/build/session-manager.js

@@ -0,0 +1,284 @@
+/**
+ * Session lifecycle management
+ * Tracks multiple concurrent sessions with unique UUIDs
+ */
+import { randomUUID } from "crypto";
+export class SessionManager {
+    sessions = new Map();
+    pageRefs = new Map();
+    autoCaptures = new Map();
+    consoleCollectors = new Map();
+    errorCollectors = new Map();
+    networkCollectors = new Map();
+    processCollectors = new Map();
+    /**
+     * Create a new session with a unique UUID
+     * @returns Session ID
+     */
+    create() {
+        const id = randomUUID();
+        const session = {
+            id,
+            createdAt: new Date(),
+            resources: [],
+        };
+        this.sessions.set(id, session);
+        console.error(`Session created: ${id}`);
+        return id;
+    }
+    /**
+     * Get a session by ID
+     * @returns Session or undefined if not found
+     */
+    get(id) {
+        return this.sessions.get(id);
+    }
+    /**
+     * List all active session IDs
+     * @returns Array of session IDs
+     */
+    list() {
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * Add a resource to a session
+     * @throws Error if session not found
+     */
+    addResource(sessionId, resource) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        session.resources.push(resource);
+    }
+    /**
+     * Store a typed Playwright Page reference for a session
+     * Key format: ${sessionId}:${identifier} where identifier is URL or 'electron'
+     */
+    setPageRef(sessionId, identifier, ref) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        this.pageRefs.set(`${sessionId}:${identifier}`, ref);
+    }
+    /**
+     * Get a specific page reference by session and identifier
+     */
+    getPageRef(sessionId, identifier) {
+        return this.pageRefs.get(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Get all page references for a session
+     */
+    getPageRefs(sessionId) {
+        const refs = [];
+        const prefix = `${sessionId}:`;
+        for (const [key, ref] of this.pageRefs) {
+            if (key.startsWith(prefix)) {
+                refs.push(ref);
+            }
+        }
+        return refs;
+    }
+    /**
+     * Remove a specific page reference
+     */
+    removePageRef(sessionId, identifier) {
+        this.pageRefs.delete(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Store the latest auto-captured screenshot for a session
+     */
+    setAutoCapture(sessionId, data) {
+        this.autoCaptures.set(sessionId, data);
+    }
+    /**
+     * Get the latest auto-captured screenshot for a session
+     */
+    getAutoCapture(sessionId) {
+        return this.autoCaptures.get(sessionId);
+    }
+    // --- Console Collectors ---
+    /**
+     * Store a console collector for a session
+     */
+    setConsoleCollector(sessionId, identifier, collector) {
+        this.consoleCollectors.set(`${sessionId}:${identifier}`, collector);
+    }
+    /**
+     * Get a specific console collector by session and identifier
+     */
+    getConsoleCollector(sessionId, identifier) {
+        return this.consoleCollectors.get(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Get all console collectors for a session
+     */
+    getConsoleCollectors(sessionId) {
+        const collectors = [];
+        const prefix = `${sessionId}:`;
+        for (const [key, collector] of this.consoleCollectors) {
+            if (key.startsWith(prefix)) {
+                collectors.push(collector);
+            }
+        }
+        return collectors;
+    }
+    // --- Error Collectors ---
+    /**
+     * Store an error collector for a session
+     */
+    setErrorCollector(sessionId, identifier, collector) {
+        this.errorCollectors.set(`${sessionId}:${identifier}`, collector);
+    }
+    /**
+     * Get a specific error collector by session and identifier
+     */
+    getErrorCollector(sessionId, identifier) {
+        return this.errorCollectors.get(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Get all error collectors for a session
+     */
+    getErrorCollectors(sessionId) {
+        const collectors = [];
+        const prefix = `${sessionId}:`;
+        for (const [key, collector] of this.errorCollectors) {
+            if (key.startsWith(prefix)) {
+                collectors.push(collector);
+            }
+        }
+        return collectors;
+    }
+    // --- Network Collectors ---
+    /**
+     * Store a network collector for a session
+     */
+    setNetworkCollector(sessionId, identifier, collector) {
+        this.networkCollectors.set(`${sessionId}:${identifier}`, collector);
+    }
+    /**
+     * Get a specific network collector by session and identifier
+     */
+    getNetworkCollector(sessionId, identifier) {
+        return this.networkCollectors.get(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Get all network collectors for a session
+     */
+    getNetworkCollectors(sessionId) {
+        const collectors = [];
+        const prefix = `${sessionId}:`;
+        for (const [key, collector] of this.networkCollectors) {
+            if (key.startsWith(prefix)) {
+                collectors.push(collector);
+            }
+        }
+        return collectors;
+    }
+    // --- Process Collectors ---
+    /**
+     * Store a process output collector for a session
+     */
+    setProcessCollector(sessionId, identifier, collector) {
+        this.processCollectors.set(`${sessionId}:${identifier}`, collector);
+    }
+    /**
+     * Get a specific process collector by session and identifier
+     */
+    getProcessCollector(sessionId, identifier) {
+        return this.processCollectors.get(`${sessionId}:${identifier}`);
+    }
+    /**
+     * Get all process collectors for a session
+     */
+    getProcessCollectors(sessionId) {
+        const collectors = [];
+        const prefix = `${sessionId}:`;
+        for (const [key, collector] of this.processCollectors) {
+            if (key.startsWith(prefix)) {
+                collectors.push(collector);
+            }
+        }
+        return collectors;
+    }
+    /**
+     * Destroy a session and clean up all its resources
+     * Logs cleanup errors but doesn't throw
+     * No-op if session doesn't exist
+     */
+    async destroy(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return; // No-op if session doesn't exist
+        }
+        console.error(`Destroying session ${sessionId} (${session.resources.length} resources)`);
+        // Clean up page references for this session
+        const prefix = `${sessionId}:`;
+        for (const [key, ref] of this.pageRefs) {
+            if (key.startsWith(prefix)) {
+                try {
+                    if (ref.browserContext) {
+                        await ref.browserContext.close();
+                    }
+                    if (ref.browser) {
+                        await ref.browser.close();
+                    }
+                }
+                catch (error) {
+                    console.error(`Error cleaning up page ref in session ${sessionId}:`, error);
+                }
+                this.pageRefs.delete(key);
+            }
+        }
+        // Clean up diagnostic collectors for this session
+        for (const [key, collector] of this.consoleCollectors) {
+            if (key.startsWith(prefix)) {
+                collector.detach();
+                this.consoleCollectors.delete(key);
+            }
+        }
+        for (const [key, collector] of this.errorCollectors) {
+            if (key.startsWith(prefix)) {
+                collector.detach();
+                this.errorCollectors.delete(key);
+            }
+        }
+        for (const [key, collector] of this.networkCollectors) {
+            if (key.startsWith(prefix)) {
+                collector.detach();
+                this.networkCollectors.delete(key);
+            }
+        }
+        for (const [key, collector] of this.processCollectors) {
+            if (key.startsWith(prefix)) {
+                collector.detach();
+                this.processCollectors.delete(key);
+            }
+        }
+        // Clean up auto-capture data
+        this.autoCaptures.delete(sessionId);
+        // Clean up each resource individually
+        for (const resource of session.resources) {
+            try {
+                await resource.cleanup();
+            }
+            catch (error) {
+                console.error(`Error cleaning up resource in session ${sessionId}:`, error);
+            }
+        }
+        this.sessions.delete(sessionId);
+        console.error(`Session destroyed: ${sessionId}`);
+    }
+    /**
+     * Destroy all sessions (for shutdown cleanup)
+     */
+    async destroyAll() {
+        const sessionIds = this.list();
+        console.error(`Destroying all sessions (${sessionIds.length} total)`);
+        for (const id of sessionIds) {
+            await this.destroy(id);
+        }
+    }
+}

package/build/tools/check-port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * check_port MCP tool (PROC-04)
+ * Reports whether a TCP port is available and suggests alternatives
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the check_port tool with the MCP server
+ */
+export declare function registerCheckPortTool(server: McpServer, _sessionManager: SessionManager): void;

package/build/tools/check-port.js

@@ -0,0 +1,40 @@
+/**
+ * check_port MCP tool (PROC-04)
+ * Reports whether a TCP port is available and suggests alternatives
+ */
+import { z } from "zod";
+import { createToolError, createToolResult } from "../utils/errors.js";
+import detect from "detect-port";
+/**
+ * Register the check_port tool with the MCP server
+ */
+export function registerCheckPortTool(server, _sessionManager) {
+    server.tool("check_port", "Check if a TCP port is available for use. Use before launching a web server to avoid EADDRINUSE errors.", {
+        port: z
+            .number()
+            .int()
+            .min(1)
+            .max(65535)
+            .describe("Port number to check availability for"),
+    }, async ({ port }) => {
+        try {
+            const availablePort = await detect(port);
+            if (availablePort === port) {
+                return createToolResult({
+                    port,
+                    available: true,
+                });
+            }
+            return createToolResult({
+                port,
+                available: false,
+                suggestedAlternative: availablePort,
+                message: `Port ${port} is in use. Port ${availablePort} is available.`,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return createToolError(`Failed to check port ${port}`, message, "Ensure the port number is valid (1-65535)");
+        }
+    });
+}

package/build/tools/click-element.d.ts

@@ -0,0 +1,13 @@
+/**
+ * click_element MCP tool
+ * Clicks elements on web or Electron pages using Playwright Locator API
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+/**
+ * Register the click_element tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export declare function registerClickElementTool(server: McpServer, sessionManager: SessionManager): void;

package/build/tools/click-element.js

@@ -0,0 +1,118 @@
+/**
+ * click_element MCP tool
+ * Clicks elements on web or Electron pages using Playwright Locator API
+ */
+import { z } from "zod";
+import { createToolError, createScreenshotResult } from "../utils/errors.js";
+import { capturePlaywrightPage } from "../screenshot/capture.js";
+import { optimizeScreenshot } from "../screenshot/optimize.js";
+import { resolveSelector, getActivePage } from "../interaction/selectors.js";
+/**
+ * Register the click_element tool with the MCP server
+ *
+ * @param server - MCP server instance
+ * @param sessionManager - Session manager for resource tracking
+ */
+export function registerClickElementTool(server, sessionManager) {
+    server.tool("click_element", "Click an element on a web or Electron page. Returns a screenshot after clicking. Use CSS selectors, text content, role, or test IDs to target elements.", {
+        sessionId: z
+            .string()
+            .describe("Session ID from create_session"),
+        selector: z
+            .string()
+            .describe("Element selector. CSS: #id, .class, div > span. Text: text=Click me. Role: role=button[name='Submit']. Test ID: testid=my-btn"),
+        pageIdentifier: z
+            .string()
+            .optional()
+            .describe("URL or 'electron' to target a specific page. Omit if session has only one page."),
+        button: z
+            .enum(["left", "right", "middle"])
+            .optional()
+            .describe("Mouse button (default: left)"),
+        clickCount: z
+            .number()
+            .int()
+            .min(1)
+            .max(3)
+            .optional()
+            .describe("Number of clicks (2 for double-click)"),
+        position: z
+            .object({ x: z.number(), y: z.number() })
+            .optional()
+            .describe("Click position within element"),
+        force: z
+            .boolean()
+            .optional()
+            .describe("Bypass actionability checks (use sparingly)"),
+        timeout: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Max wait time in ms (default: 30000)"),
+    }, async ({ sessionId, selector, pageIdentifier, button, clickCount, position, force, timeout, }) => {
+        try {
+            // Validate session exists
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                const availableSessions = sessionManager.list();
+                return createToolError(`Session not found: ${sessionId}`, "The session may have already been ended", availableSessions.length > 0
+                    ? `Available sessions: ${availableSessions.join(", ")}`
+                    : "Create a session first with create_session.");
+            }
+            // Find the active page
+            const pageResult = getActivePage(sessionManager, sessionId, pageIdentifier);
+            if (!pageResult.success) {
+                return createToolError(pageResult.error, `Session: ${sessionId}`, pageResult.availablePages
+                    ? `Available pages: ${pageResult.availablePages.join(", ")}`
+                    : undefined);
+            }
+            const { page } = pageResult;
+            // Resolve selector to Playwright Locator
+            const locator = resolveSelector(page, selector);
+            // Perform the click with provided options
+            await locator.click({
+                button: button ?? undefined,
+                clickCount: clickCount ?? undefined,
+                position: position ?? undefined,
+                force: force ?? undefined,
+                timeout: timeout ?? 30000,
+            });
+            // Wait briefly for any navigation triggered by the click
+            await Promise.race([
+                page.waitForLoadState("load").catch(() => { }),
+                new Promise((resolve) => setTimeout(resolve, 2000)),
+            ]);
+            // Capture post-click screenshot
+            const rawBuffer = await capturePlaywrightPage(page, {
+                fullPage: false,
+            });
+            const optimized = await optimizeScreenshot(rawBuffer, {
+                maxWidth: 1280,
+                quality: 80,
+            });
+            const imageBase64 = optimized.data.toString("base64");
+            return createScreenshotResult({
+                sessionId,
+                action: "click",
+                selector,
+                button: button ?? "left",
+                success: true,
+            }, imageBase64, optimized.mimeType);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Strict mode violation: selector matched multiple elements
+            if (message.includes("strict mode violation")) {
+                return createToolError("Selector matched multiple elements", `Selector "${selector}" matched more than one element (strict mode violation)`, "Use a more specific selector or add :nth-child(), :first-of-type, or similar to target a single element.");
+            }
+            // Timeout: element not found or not actionable within timeout
+            if (message.includes("Timeout") ||
+                message.includes("timeout")) {
+                return createToolError("Element not found within timeout", `Selector "${selector}" did not match any visible element within ${timeout ?? 30000}ms`, "Check the selector is correct, the element is visible, or increase the timeout. Take a screenshot first to verify the page state.");
+            }
+            // Default error
+            return createToolError("Failed to click element", `Selector: "${selector}" — ${message}`, "Take a screenshot to verify the element exists and is visible on the page.");
+        }
+    });
+}

package/build/tools/get-console-logs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Tool 19: get_console_logs
+ * Retrieves browser console logs captured during a session.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "../session-manager.js";
+export declare function registerGetConsoleLogsTool(server: McpServer, sessionManager: SessionManager): void;