ghost-qa 0.0.0-stage → 1.3.0

package/dist/src/engine/server-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/engine/server-lifecycle.ts"],"names":[],"mappings":"AAIA,gFAAgF;AAChF,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,SAAS,SAAS,EAClB,cAAc,SAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,MAAM,CAAM;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;gBAEnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;IAK/D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,GAAG,IAAI,MAAM,GAAG,SAAS,CAE5B;IAED,kFAAkF;IAClF,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,KAAK,IAAI,IAAI;IAmBb,4FAA4F;IACtF,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBpE,wEAAwE;IAClE,IAAI,CAAC,OAAO,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1C,OAAO,CAAC,UAAU;CAgBnB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,oBAAoB,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/src/engine/server-lifecycle.js

@@ -0,0 +1,154 @@
+import { spawn } from 'node:child_process';
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+/** Polls a URL until it answers with any HTTP status (even 404 = server up). */
+export function waitForUrl(url, timeoutMs = 30_000, pollIntervalMs = 400) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolvePromise, rejectPromise) => {
+        const attempt = () => {
+            const getter = url.startsWith('https:') ? httpsGet : httpGet;
+            const request = getter(url, (response) => {
+                response.resume();
+                resolvePromise();
+            });
+            request.setTimeout(2_000, () => request.destroy(new Error('poll timeout')));
+            request.on('error', () => {
+                if (Date.now() >= deadline) {
+                    rejectPromise(new Error(`Timed out after ${timeoutMs}ms waiting for ${url} to respond.`));
+                }
+                else {
+                    setTimeout(attempt, pollIntervalMs);
+                }
+            });
+        };
+        attempt();
+    });
+}
+/**
+ * Owns a spawned dev-server process tree: `start()` spawns it through the
+ * platform shell in its own process group, `waitUntilReady()` polls the
+ * target URL, and `stop()` terminates the whole tree (SIGTERM, then SIGKILL)
+ * so no orphaned dev servers survive a ghost-qa run.
+ */
+export class ManagedDevServer {
+    child = null;
+    output = '';
+    command;
+    options;
+    constructor(command, options = {}) {
+        this.command = command;
+        this.options = options;
+    }
+    get isRunning() {
+        return this.child !== null && !this.child.killed && this.child.exitCode === null;
+    }
+    get pid() {
+        return this.child?.pid;
+    }
+    /** Last chunk of captured stdout+stderr (for "server failed to start" errors). */
+    get outputTail() {
+        return this.output.slice(-2_000);
+    }
+    start() {
+        if (this.child)
+            throw new Error(`Dev server already started: ${this.command}`);
+        const bufferLimit = this.options.outputBufferChars ?? 20_000;
+        this.child = spawn(this.command, {
+            cwd: this.options.cwd ?? process.cwd(),
+            env: { ...process.env, ...(this.options.env ?? {}) },
+            shell: true,
+            // Own process group on POSIX so stop() can kill the whole tree
+            // (shell -> npm -> node) instead of just the shell wrapper.
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const capture = (chunk) => {
+            this.output = (this.output + chunk.toString()).slice(-bufferLimit);
+        };
+        this.child.stdout?.on('data', capture);
+        this.child.stderr?.on('data', capture);
+    }
+    /** Resolves once the URL responds; rejects with the server output on timeout/early exit. */
+    async waitUntilReady(url, timeoutMs = 30_000) {
+        if (!this.child)
+            this.start();
+        let exited = null;
+        const onExit = (code) => {
+            exited = new Error(`Dev server exited before ${url} became ready (exit code ${code ?? 'unknown'}).\n` +
+                `Command: ${this.command}\n--- server output ---\n${this.outputTail || '(no output captured)'}`);
+        };
+        this.child.once('exit', onExit);
+        try {
+            await waitForUrl(url, timeoutMs);
+            if (exited)
+                throw exited;
+        }
+        catch (error) {
+            if (exited)
+                throw exited;
+            throw new Error(`${error instanceof Error ? error.message : String(error)}\n` +
+                `Command: ${this.command}\n--- server output ---\n${this.outputTail || '(no output captured)'}`);
+        }
+        finally {
+            this.child?.removeListener('exit', onExit);
+        }
+    }
+    /** Terminates the spawned process tree. Safe to call multiple times. */
+    async stop(graceMs = 3_000) {
+        const child = this.child;
+        if (!child || child.exitCode !== null) {
+            this.child = null;
+            return;
+        }
+        const exited = new Promise((resolvePromise) => {
+            child.once('exit', () => resolvePromise());
+        });
+        this.signalTree(child, 'SIGTERM');
+        const graceful = await Promise.race([
+            exited.then(() => true),
+            new Promise((resolvePromise) => setTimeout(() => resolvePromise(false), graceMs)),
+        ]);
+        if (!graceful) {
+            this.signalTree(child, 'SIGKILL');
+            await Promise.race([
+                exited,
+                new Promise((resolvePromise) => setTimeout(resolvePromise, 2_000)),
+            ]);
+        }
+        this.child = null;
+    }
+    signalTree(child, signal) {
+        try {
+            if (process.platform !== 'win32' && child.pid) {
+                // Negative pid = the whole process group created by `detached: true`.
+                process.kill(-child.pid, signal);
+                return;
+            }
+        }
+        catch {
+            /* group already gone — fall through to direct kill */
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            /* already exited */
+        }
+    }
+}
+/**
+ * Convenience wrapper: spawn `command`, wait for `url`, run `fn`, and always
+ * tear the server down afterwards — even when `fn` throws.
+ */
+export async function withManagedDevServer(command, url, fn, options = {}) {
+    const server = new ManagedDevServer(command, options);
+    server.start();
+    try {
+        await server.waitUntilReady(url, options.readyTimeoutMs ?? 30_000);
+        return await fn();
+    }
+    finally {
+        await server.stop();
+    }
+}
+//# sourceMappingURL=server-lifecycle.js.map

package/dist/src/engine/server-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-lifecycle.js","sourceRoot":"","sources":["../../../src/engine/server-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types.js';
+export * from './traps/console-trap.js';
+export * from './traps/network-trap.js';
+export * from './traps/layout-trap.js';
+export * from './traps/a11y-trap.js';
+export * from './traps/perf-trap.js';
+export * from './engine/browser-session.js';
+export * from './engine/route-crawler.js';
+export * from './engine/interaction-runner.js';
+export * from './engine/audit-runner.js';
+export * from './engine/server-lifecycle.js';
+export * from './reporter/terminal-summary.js';
+export * from './reporter/agent-diagnostic.js';
+export * from './reporter/html-report.js';
+export * from './mcp/server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,16 @@
+export * from './types.js';
+export * from './traps/console-trap.js';
+export * from './traps/network-trap.js';
+export * from './traps/layout-trap.js';
+export * from './traps/a11y-trap.js';
+export * from './traps/perf-trap.js';
+export * from './engine/browser-session.js';
+export * from './engine/route-crawler.js';
+export * from './engine/interaction-runner.js';
+export * from './engine/audit-runner.js';
+export * from './engine/server-lifecycle.js';
+export * from './reporter/terminal-summary.js';
+export * from './reporter/agent-diagnostic.js';
+export * from './reporter/html-report.js';
+export * from './mcp/server.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC"}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,111 @@
+import { type GhostQAOptions, type GhostQAReport } from '../types.js';
+/**
+ * Native MCP (Model Context Protocol) server for ghost-qa.
+ *
+ * Standard JSON-RPC 2.0 over stdio, implemented with zero external SDKs:
+ * newline-delimited JSON in, newline-delimited JSON out, diagnostics on
+ * stderr only (stdout is the protocol channel). Compatible with Claude Code,
+ * Claude Desktop, Cursor, Codex and any other MCP host:
+ *
+ *   { "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "github:avivgerz-hue/ghost-qa", "mcp"] } } }
+ */
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+export declare const MCP_SERVER_INFO: {
+    readonly name: "ghost-qa";
+    readonly version: "1.3.0";
+};
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare const JSON_RPC_ERRORS: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+};
+export interface DoctorResult {
+    ready: boolean;
+    node: string;
+    nodeOk: boolean;
+    chromiumPath: string;
+    chromiumFound: boolean;
+    smokeTest: string;
+}
+export declare function runDoctorCheck(): Promise<DoctorResult>;
+export declare const MCP_TOOLS: readonly [{
+    readonly name: "ghost_qa_audit_url";
+    readonly description: "Run the full ghost-qa headless browser audit against a running localhost app: crawls internal routes on Desktop 1440x900 and Mobile 390x844, safely exercises interactive controls, and traps console/hydration errors, failed network requests, layout overflow, accessibility bugs and performance problems. Returns the Self-Healing Bug Report — fix every critical/major issue it reports before declaring the task done.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: "Target URL of the running app, e.g. http://localhost:3000";
+            };
+            readonly maxDepth: {
+                readonly type: "number";
+                readonly description: "Link-following depth (default 2)";
+            };
+            readonly maxRoutes: {
+                readonly type: "number";
+                readonly description: "Maximum routes to visit (default 25)";
+            };
+            readonly viewport: {
+                readonly type: "string";
+                readonly enum: readonly ["both", "desktop", "mobile"];
+                readonly description: "Viewports to test (default both)";
+            };
+        };
+        readonly required: readonly ["url"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "ghost_qa_doctor";
+    readonly description: "Verify ghost-qa environment readiness: Node.js version, Chromium binary availability, and a live headless-browser smoke test. Run this first when an audit fails to start.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+}];
+export type McpToolName = (typeof MCP_TOOLS)[number]['name'];
+export interface McpHandlers {
+    audit: (target: string, options: GhostQAOptions) => Promise<GhostQAReport>;
+    doctor: () => Promise<DoctorResult>;
+}
+export declare const defaultHandlers: McpHandlers;
+/**
+ * Pure JSON-RPC dispatcher — one parsed request in, one response object (or
+ * `null` for notifications) out. Fully unit-testable without stdio or a
+ * browser when handlers are injected.
+ */
+export declare function handleJsonRpcRequest(request: JsonRpcRequest, handlers?: McpHandlers): Promise<JsonRpcResponse | null>;
+/** Parses one raw line of stdio input into a response line (or null). */
+export declare function handleJsonRpcLine(line: string, handlers?: McpHandlers): Promise<string | null>;
+/** The ready-to-paste MCP host configuration installed by `ghost-qa init`. */
+export declare function mcpServerConfig(): {
+    mcpServers: Record<string, {
+        command: string;
+        args: string[];
+    }>;
+};
+/**
+ * Serves MCP over stdio until stdin closes. All human diagnostics go to
+ * stderr — stdout carries protocol frames only.
+ */
+export declare function startMcpServer(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream, handlers?: McpHandlers): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;GASG;AAEH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,eAAe;;;CAA2D,CAAC;AAExF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3D;AAED,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC,CAmB5D;AAUD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BZ,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3E,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,eAAe,EAAE,WAG7B,CAAC;AAqFF;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,WAA6B,GACtC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAmDjC;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,WAA6B,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBxB;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAMrG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,GAAE,MAAM,CAAC,cAA8B,EAC5C,MAAM,GAAE,MAAM,CAAC,cAA+B,EAC9C,QAAQ,GAAE,WAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/src/mcp/server.js

@@ -0,0 +1,267 @@
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { chromium } from 'playwright';
+import { runGhostQAAudit, GHOST_QA_VERSION } from '../engine/audit-runner.js';
+import { smokeTestBrowser } from '../engine/browser-session.js';
+import { formatAgentDiagnostic } from '../reporter/agent-diagnostic.js';
+import { DEFAULT_OPTIONS } from '../types.js';
+/**
+ * Native MCP (Model Context Protocol) server for ghost-qa.
+ *
+ * Standard JSON-RPC 2.0 over stdio, implemented with zero external SDKs:
+ * newline-delimited JSON in, newline-delimited JSON out, diagnostics on
+ * stderr only (stdout is the protocol channel). Compatible with Claude Code,
+ * Claude Desktop, Cursor, Codex and any other MCP host:
+ *
+ *   { "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "github:avivgerz-hue/ghost-qa", "mcp"] } } }
+ */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+export const MCP_SERVER_INFO = { name: 'ghost-qa', version: GHOST_QA_VERSION };
+export const JSON_RPC_ERRORS = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};
+export async function runDoctorCheck() {
+    const nodeMajor = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    const chromiumPath = process.env.GHOST_QA_CHROMIUM_PATH ?? safeExecutablePath();
+    const chromiumFound = chromiumPath !== '' && existsSync(chromiumPath);
+    let smokeTest = 'not run (Chromium binary not found)';
+    let smokeOk = false;
+    if (chromiumFound) {
+        const smoke = await smokeTestBrowser();
+        smokeOk = smoke.ok;
+        smokeTest = smoke.detail.replace(/\s+/g, ' ').slice(0, 400);
+    }
+    return {
+        ready: nodeMajor >= 20 && chromiumFound && smokeOk,
+        node: process.versions.node,
+        nodeOk: nodeMajor >= 20,
+        chromiumPath,
+        chromiumFound,
+        smokeTest,
+    };
+}
+function safeExecutablePath() {
+    try {
+        return chromium.executablePath();
+    }
+    catch {
+        return '';
+    }
+}
+export const MCP_TOOLS = [
+    {
+        name: 'ghost_qa_audit_url',
+        description: 'Run the full ghost-qa headless browser audit against a running localhost app: crawls internal routes on Desktop 1440x900 and Mobile 390x844, safely exercises interactive controls, and traps console/hydration errors, failed network requests, layout overflow, accessibility bugs and performance problems. Returns the Self-Healing Bug Report — fix every critical/major issue it reports before declaring the task done.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Target URL of the running app, e.g. http://localhost:3000',
+                },
+                maxDepth: { type: 'number', description: 'Link-following depth (default 2)' },
+                maxRoutes: { type: 'number', description: 'Maximum routes to visit (default 25)' },
+                viewport: {
+                    type: 'string',
+                    enum: ['both', 'desktop', 'mobile'],
+                    description: 'Viewports to test (default both)',
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'ghost_qa_doctor',
+        description: 'Verify ghost-qa environment readiness: Node.js version, Chromium binary availability, and a live headless-browser smoke test. Run this first when an audit fails to start.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+];
+export const defaultHandlers = {
+    audit: (target, options) => runGhostQAAudit(target, options),
+    doctor: () => runDoctorCheck(),
+};
+function toolResult(text, structured, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(structured ? { structuredContent: structured } : {}),
+        isError,
+    };
+}
+function optionsFromArgs(args) {
+    const options = { ...DEFAULT_OPTIONS, viewports: [...DEFAULT_OPTIONS.viewports] };
+    if (typeof args.maxDepth === 'number' && Number.isFinite(args.maxDepth) && args.maxDepth >= 0) {
+        options.maxDepth = Math.floor(args.maxDepth);
+    }
+    if (typeof args.maxRoutes === 'number' && Number.isFinite(args.maxRoutes) && args.maxRoutes > 0) {
+        options.maxRoutes = Math.floor(args.maxRoutes);
+    }
+    if (args.viewport === 'desktop' || args.viewport === 'mobile') {
+        options.viewports = [args.viewport];
+    }
+    else if (args.viewport === 'both') {
+        options.viewports = ['desktop', 'mobile'];
+    }
+    return options;
+}
+async function callTool(name, args, handlers) {
+    switch (name) {
+        case 'ghost_qa_audit_url': {
+            const url = args.url;
+            if (typeof url !== 'string' || !/^https?:\/\//i.test(url)) {
+                return toolResult('Invalid argument: "url" must be an http(s) URL of a running app, e.g. http://localhost:3000', undefined, true);
+            }
+            try {
+                const report = await handlers.audit(url, optionsFromArgs(args));
+                return toolResult(formatAgentDiagnostic(report), {
+                    passed: report.passed,
+                    targetUrl: report.targetUrl,
+                    routesCrawled: report.summary.routesCrawled,
+                    interactionsTested: report.summary.interactionsTested,
+                    totalIssues: report.summary.totalIssues,
+                    bySeverity: report.summary.bySeverity,
+                    byCategory: report.summary.byCategory,
+                    issues: report.issues.map((issue) => ({
+                        id: issue.id,
+                        severity: issue.severity,
+                        category: issue.category,
+                        type: issue.type,
+                        route: issue.route,
+                        viewport: issue.viewport,
+                        message: issue.message,
+                    })),
+                });
+            }
+            catch (error) {
+                return toolResult(`ghost-qa audit failed to run: ${error instanceof Error ? error.message : String(error)}\n` +
+                    'Check that the dev server is running and Chromium is installed (npx playwright install chromium), or call ghost_qa_doctor.', undefined, true);
+            }
+        }
+        case 'ghost_qa_doctor': {
+            const result = await handlers.doctor();
+            const lines = [
+                `ghost-qa doctor — ${result.ready ? 'READY ✔' : 'NOT READY ✖'}`,
+                `Node.js: ${result.node} ${result.nodeOk ? '(ok)' : '(requires >= 20)'}`,
+                `Chromium: ${result.chromiumFound ? result.chromiumPath : 'not found — run: npx playwright install chromium'}`,
+                `Smoke test: ${result.smokeTest}`,
+            ];
+            return toolResult(lines.join('\n'), { ...result });
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Pure JSON-RPC dispatcher — one parsed request in, one response object (or
+ * `null` for notifications) out. Fully unit-testable without stdio or a
+ * browser when handlers are injected.
+ */
+export async function handleJsonRpcRequest(request, handlers = defaultHandlers) {
+    const id = request.id ?? null;
+    const isNotification = request.id === undefined;
+    const respond = (result) => isNotification ? null : { jsonrpc: '2.0', id, result };
+    const fail = (code, message) => isNotification ? null : { jsonrpc: '2.0', id, error: { code, message } };
+    if (!request || typeof request.method !== 'string') {
+        return fail(JSON_RPC_ERRORS.invalidRequest, 'Invalid Request: "method" must be a string.');
+    }
+    switch (request.method) {
+        case 'initialize': {
+            const requested = request.params?.protocolVersion;
+            return respond({
+                protocolVersion: typeof requested === 'string' && requested ? requested : MCP_PROTOCOL_VERSION,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { ...MCP_SERVER_INFO },
+                instructions: 'Use ghost_qa_audit_url to verify any frontend change in a real browser before reporting a task complete. Fix every critical/major issue it returns and re-run until it passes.',
+            });
+        }
+        case 'ping':
+            return respond({});
+        case 'tools/list':
+            return respond({ tools: MCP_TOOLS });
+        case 'tools/call': {
+            const name = request.params?.name;
+            const args = (request.params?.arguments ?? {});
+            if (typeof name !== 'string') {
+                return fail(JSON_RPC_ERRORS.invalidParams, 'tools/call requires params.name (string).');
+            }
+            const result = await callTool(name, args, handlers);
+            if (result === null) {
+                return fail(JSON_RPC_ERRORS.invalidParams, `Unknown tool: ${name}`);
+            }
+            return respond(result);
+        }
+        case 'resources/list':
+            return respond({ resources: [] });
+        case 'prompts/list':
+            return respond({ prompts: [] });
+        default:
+            // Notifications (notifications/initialized, notifications/cancelled…)
+            // never get a response; unknown requests get Method Not Found.
+            if (isNotification)
+                return null;
+            return fail(JSON_RPC_ERRORS.methodNotFound, `Method not found: ${request.method}`);
+    }
+}
+/** Parses one raw line of stdio input into a response line (or null). */
+export async function handleJsonRpcLine(line, handlers = defaultHandlers) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: JSON_RPC_ERRORS.parseError, message: 'Parse error: invalid JSON.' },
+        });
+    }
+    // Batch requests are answered as a batch, per JSON-RPC 2.0.
+    if (Array.isArray(parsed)) {
+        const responses = [];
+        for (const item of parsed) {
+            const response = await handleJsonRpcRequest(item, handlers);
+            if (response)
+                responses.push(response);
+        }
+        return responses.length > 0 ? JSON.stringify(responses) : null;
+    }
+    const response = await handleJsonRpcRequest(parsed, handlers);
+    return response ? JSON.stringify(response) : null;
+}
+/** The ready-to-paste MCP host configuration installed by `ghost-qa init`. */
+export function mcpServerConfig() {
+    return {
+        mcpServers: {
+            'ghost-qa': { command: 'npx', args: ['-y', 'github:avivgerz-hue/ghost-qa', 'mcp'] },
+        },
+    };
+}
+/**
+ * Serves MCP over stdio until stdin closes. All human diagnostics go to
+ * stderr — stdout carries protocol frames only.
+ */
+export function startMcpServer(input = process.stdin, output = process.stdout, handlers = defaultHandlers) {
+    process.stderr.write(`ghost-qa MCP server v${GHOST_QA_VERSION} listening on stdio\n`);
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    return new Promise((resolvePromise) => {
+        rl.on('line', (line) => {
+            void handleJsonRpcLine(line, handlers)
+                .then((responseLine) => {
+                if (responseLine)
+                    output.write(`${responseLine}\n`);
+            })
+                .catch((error) => {
+                process.stderr.write(`ghost-qa MCP handler error: ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+        });
+        rl.on('close', () => resolvePromise());
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/src/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/src/reporter/agent-diagnostic.d.ts

@@ -0,0 +1,17 @@
+import type { GhostQAReport, IssueCategory } from '../types.js';
+/**
+ * Token-efficient fix guidance per category. The agent reading the diagnostic
+ * should be able to act without re-discovering first principles each run.
+ */
+export declare const FIX_PLAYBOOK: Record<IssueCategory, string>;
+/**
+ * The Self-Healing Bug Report: deliberately compact Markdown an agent can
+ * paste into its own context — verdict first, issues grouped by route, one
+ * fix playbook line per category, then the re-verify command.
+ */
+export declare function formatAgentDiagnostic(report: GhostQAReport): string;
+/** Structured JSON for CI gates and programmatic agent tooling. */
+export declare function formatAgentDiagnosticJson(report: GhostQAReport): string;
+export type DiagnosticFormat = 'markdown' | 'json';
+export declare function formatDiagnostic(report: GhostQAReport, format: DiagnosticFormat): string;
+//# sourceMappingURL=agent-diagnostic.d.ts.map

package/dist/src/reporter/agent-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-diagnostic.d.ts","sourceRoot":"","sources":["../../../src/reporter/agent-diagnostic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAW,MAAM,aAAa,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAetD,CAAC;AAsBF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA2CnE;AAED,mEAAmE;AACnE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAExF"}