electron-verify-mcp 0.0.1

package/dist/core/signals/mainProcess.js

@@ -0,0 +1,61 @@
+const DEFAULT_TAIL = 8_000;
+/**
+ * Capture main-process stderr into a rolling tail and watch for exit.
+ * If the main process throws on boot this is the key diagnosis signal.
+ */
+export class MainProcessCollector {
+    chunks = [];
+    totalLen = 0;
+    exited = false;
+    exitCode = null;
+    attached = false;
+    maxTail;
+    constructor(maxTail = DEFAULT_TAIL) {
+        this.maxTail = maxTail;
+    }
+    attach(app) {
+        if (this.attached)
+            return;
+        this.attached = true;
+        const proc = app.process();
+        if (!proc)
+            return;
+        const onData = (buf) => {
+            const s = typeof buf === "string" ? buf : buf.toString("utf8");
+            this.chunks.push(s);
+            this.totalLen += s.length;
+            // Trim from the front when over budget.
+            while (this.totalLen > this.maxTail && this.chunks.length > 1) {
+                const dropped = this.chunks.shift();
+                this.totalLen -= dropped.length;
+            }
+            if (this.totalLen > this.maxTail && this.chunks.length === 1) {
+                const only = this.chunks[0];
+                this.chunks[0] = only.slice(only.length - this.maxTail);
+                this.totalLen = this.chunks[0].length;
+            }
+        };
+        proc.stderr?.on("data", onData);
+        // Some Electron builds also dump diagnostics to stdout.
+        proc.stdout?.on("data", (buf) => {
+            // Keep stdout quieter: only store if it looks like an error line.
+            const s = typeof buf === "string" ? buf : buf.toString("utf8");
+            if (/error|exception|fatal|throw/i.test(s))
+                onData(s);
+        });
+        proc.on("exit", (code, _signal) => {
+            this.exited = true;
+            this.exitCode = typeof code === "number" ? code : null;
+        });
+        proc.on("error", (err) => {
+            onData(`process error: ${err.message}\n`);
+        });
+    }
+    snapshot() {
+        return {
+            exited: this.exited,
+            exitCode: this.exitCode,
+            stderrTail: this.chunks.join("").slice(-this.maxTail),
+        };
+    }
+}

package/dist/core/signals/resources.d.ts

@@ -0,0 +1,24 @@
+import type { Page } from "playwright-core";
+import type { ResourceSignal } from "../types.js";
+/**
+ * Network + image resource collector. Failures are tagged per page and
+ * windowed per-verify (same marker pattern as console).
+ */
+export declare class ResourcesCollector {
+    private failed;
+    private attachedPages;
+    private pageIds;
+    private nextPageId;
+    private verifyMarker;
+    private readonly maxEntries;
+    pageId(page: Page): number;
+    attachPage(page: Page): void;
+    attachApp(app: {
+        on: (ev: "window", cb: (p: Page) => void) => void;
+        windows: () => Page[];
+    }): void;
+    /** Call after each verify so the next pass only sees subsequent failures. */
+    markVerifyStart(): void;
+    snapshot(page: Page): Promise<ResourceSignal>;
+    private push;
+}

package/dist/core/signals/resources.js

@@ -0,0 +1,91 @@
+/**
+ * Network + image resource collector. Failures are tagged per page and
+ * windowed per-verify (same marker pattern as console).
+ */
+export class ResourcesCollector {
+    failed = [];
+    attachedPages = new WeakSet();
+    pageIds = new WeakMap();
+    nextPageId = 1;
+    verifyMarker = 0;
+    maxEntries = 100;
+    pageId(page) {
+        let id = this.pageIds.get(page);
+        if (id === undefined) {
+            id = this.nextPageId++;
+            this.pageIds.set(page, id);
+        }
+        return id;
+    }
+    attachPage(page) {
+        if (this.attachedPages.has(page))
+            return;
+        this.attachedPages.add(page);
+        const pid = this.pageId(page);
+        page.on("response", (res) => {
+            const status = res.status();
+            if (status >= 400) {
+                this.push(`${shortUrl(res.url())} ${status}`, pid);
+            }
+        });
+        page.on("requestfailed", (req) => {
+            const failure = req.failure();
+            const err = failure?.errorText ?? "requestfailed";
+            // Abort is often intentional (navigation); skip pure aborts.
+            if (/ERR_ABORTED|net::ERR_ABORTED/i.test(err))
+                return;
+            this.push(`${shortUrl(req.url())} ${err}`, pid);
+        });
+    }
+    attachApp(app) {
+        app.on("window", (page) => this.attachPage(page));
+        for (const page of app.windows()) {
+            this.attachPage(page);
+        }
+    }
+    /** Call after each verify so the next pass only sees subsequent failures. */
+    markVerifyStart() {
+        this.verifyMarker = this.failed.length;
+    }
+    async snapshot(page) {
+        let brokenImages = 0;
+        try {
+            brokenImages = await page.evaluate(() => {
+                const imgs = Array.from(document.images ?? []);
+                return imgs.filter((img) => {
+                    return img.complete && img.naturalWidth === 0 && !!img.src;
+                }).length;
+            });
+        }
+        catch {
+            brokenImages = 0;
+        }
+        const pid = this.pageId(page);
+        const newSlice = this.failed
+            .slice(this.verifyMarker)
+            .filter((f) => f.pageId === pid)
+            .map((f) => f.entry);
+        return {
+            brokenImages,
+            failedRequests: newSlice.slice(-this.maxEntries),
+        };
+    }
+    push(entry, pageId) {
+        this.failed.push({ entry: entry.slice(0, 500), pageId });
+        if (this.failed.length > this.maxEntries * 2) {
+            this.failed = this.failed.slice(-this.maxEntries);
+        }
+    }
+}
+function shortUrl(url) {
+    if (url.startsWith("data:"))
+        return "data:…";
+    try {
+        const u = new URL(url);
+        const path = u.pathname.length > 60 ? u.pathname.slice(0, 57) + "…" : u.pathname;
+        return `${u.origin}${path}`;
+    }
+    catch {
+        return url.slice(0, 120);
+    }
+}

package/dist/core/signals/staleBuild.d.ts

@@ -0,0 +1,18 @@
+import type { StaleBuildSignal } from "../types.js";
+export interface StaleBuildOptions {
+    /** Working directory for globs (app cwd). */
+    cwd: string;
+    /** Epoch ms when the session launched. */
+    launchedAt: number;
+    /**
+     * Source globs relative to cwd. If empty/undefined, skip (stale=false).
+     * Supports a minimal subset: recursive **, single-dir *, and directory prefixes.
+     */
+    srcGlobs?: string[];
+}
+/**
+ * Compare newest mtime under configured source globs vs the launch timestamp.
+ * If source is newer than launch, the running app may be a stale build.
+ * Default: skip (not stale) when globs are not configured.
+ */
+export declare function detectStaleBuild(opts: StaleBuildOptions): StaleBuildSignal;

package/dist/core/signals/staleBuild.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Compare newest mtime under configured source globs vs the launch timestamp.
+ * If source is newer than launch, the running app may be a stale build.
+ * Default: skip (not stale) when globs are not configured.
+ */
+export function detectStaleBuild(opts) {
+    const globs = opts.srcGlobs ?? [];
+    if (globs.length === 0) {
+        return { stale: false };
+    }
+    let newest = 0;
+    for (const pattern of globs) {
+        for (const file of expandGlob(opts.cwd, pattern)) {
+            try {
+                const st = fs.statSync(file);
+                if (st.isFile() && st.mtimeMs > newest)
+                    newest = st.mtimeMs;
+            }
+            catch {
+                /* ignore missing */
+            }
+        }
+    }
+    if (newest === 0)
+        return { stale: false };
+    // Small grace: files touched during the same second as launch aren't "stale".
+    return { stale: newest > opts.launchedAt + 1_000 };
+}
+/**
+ * Minimal glob expander without adding a dependency.
+ * Supports literal relative paths, recursive **, and single-dir wildcards (e.g. *.ts).
+ */
+function expandGlob(cwd, pattern) {
+    const norm = pattern.replace(/\\/g, "/");
+    const abs = path.resolve(cwd, norm);
+    // Recursive **
+    if (norm.includes("**")) {
+        const [prefix] = norm.split("**");
+        const root = path.resolve(cwd, prefix || ".");
+        return walkFiles(root);
+    }
+    // Single-dir wildcard: foo/*.ts
+    if (norm.includes("*")) {
+        const dir = path.dirname(abs);
+        const filePat = path.basename(norm);
+        const re = wildcardToRegExp(filePat);
+        try {
+            return fs
+                .readdirSync(dir)
+                .filter((n) => re.test(n))
+                .map((n) => path.join(dir, n))
+                .filter((p) => {
+                try {
+                    return fs.statSync(p).isFile();
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    // Literal path (file or directory).
+    try {
+        const st = fs.statSync(abs);
+        if (st.isFile())
+            return [abs];
+        if (st.isDirectory())
+            return walkFiles(abs);
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function walkFiles(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name === "node_modules" || e.name === ".git" || e.name === "dist")
+                continue;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile())
+                out.push(full);
+        }
+    }
+    return out;
+}
+function wildcardToRegExp(pat) {
+    const escaped = pat
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`, "i");
+}

package/dist/core/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared signal / verdict types for electron-verify-mcp.
+ * structuredContent shape (PNG is never embedded here — only in the image content block).
+ */
+export type Verdict = "PASS" | "WARN" | "FAIL";
+/** How the human-facing screenshot was produced. */
+export type CaptureModeUsed = "window" | "content" | "content-fallback" | "os-window" | "os-window-fallback:window";
+/** Requested capture mode for screenshot / verify. */
+export type CaptureMode = "content" | "window" | "os-window" | "both";
+export interface ReadinessSignal {
+    stable: boolean;
+    waitedMs: number;
+    timedOut: boolean;
+}
+export interface ConsoleMessage {
+    type: string;
+    text: string;
+    /** Epoch ms when captured. */
+    ts: number;
+}
+export interface ConsoleSignal {
+    /** Non-ignored hard/soft errors since the last verify marker (selected page). */
+    newErrors: number;
+    /** pageerror / crash count since marker (selected page). */
+    newHardErrors: number;
+    /** console.error count since marker (selected page). */
+    newConsoleErrors: number;
+    /** unhandledrejection count since marker (selected page). */
+    newUnhandledRejections: number;
+    /** Non-ignored errors across the whole session (selected page). */
+    sessionErrors: number;
+    /** Messages dropped by the ignore-list. */
+    ignored: number;
+    /** Non-ignored error / pageerror messages (recent, selected page). */
+    messages: ConsoleMessage[];
+    rendererCrashed: boolean;
+}
+export interface MainProcessSignal {
+    exited: boolean;
+    exitCode: number | null;
+    stderrTail: string;
+}
+export interface BlankScreenSignal {
+    isBlank: boolean;
+    reason: string | null;
+}
+export interface LayoutSignal {
+    documentOverflow: boolean;
+    criticalMissing: string[];
+}
+export interface ResourceSignal {
+    brokenImages: number;
+    failedRequests: string[];
+}
+export interface StaleBuildSignal {
+    stale: boolean;
+}
+export interface Signals {
+    readiness: ReadinessSignal;
+    console: ConsoleSignal;
+    mainProcess: MainProcessSignal;
+    blankScreen: BlankScreenSignal;
+    layout: LayoutSignal;
+    resources: ResourceSignal;
+    staleBuild: StaleBuildSignal;
+}
+export interface VerdictResult {
+    verdict: Verdict;
+    hardFails: string[];
+    warns: string[];
+    signals: Signals;
+    /** Echo of the caller's intent string, if provided. */
+    expect?: string;
+}
+export interface HoleRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared signal / verdict types for electron-verify-mcp.
+ * structuredContent shape (PNG is never embedded here — only in the image content block).
+ */
+export {};

package/dist/core/verdict.d.ts

@@ -0,0 +1,23 @@
+import type { Signals, VerdictResult } from "./types.js";
+export interface VerdictOptions {
+    expect?: string;
+    /**
+     * When true, bare console.error (type=error) is a hard-FAIL.
+     * Default false: console.error → WARN; pageerror/crash remain FAIL.
+     */
+    strictConsole?: boolean;
+}
+/**
+ * Map collected signals → PASS | WARN | FAIL.
+ *
+ * hard-FAIL (high precision only):
+ *   rendererCrashed · uncaught pageerror · mainProcess.exited
+ *   · blankScreen.isBlank
+ *   · console.error when strictConsole
+ *
+ * WARN:
+ *   bare console.error (default) · unhandledrejection
+ *   · console.staleErrors (session still has prior errors)
+ *   · layout / resources / staleBuild / readiness
+ */
+export declare function computeVerdict(signals: Signals, expectOrOpts?: string | VerdictOptions): VerdictResult;

package/dist/core/verdict.js

@@ -0,0 +1,87 @@
+/**
+ * Map collected signals → PASS | WARN | FAIL.
+ *
+ * hard-FAIL (high precision only):
+ *   rendererCrashed · uncaught pageerror · mainProcess.exited
+ *   · blankScreen.isBlank
+ *   · console.error when strictConsole
+ *
+ * WARN:
+ *   bare console.error (default) · unhandledrejection
+ *   · console.staleErrors (session still has prior errors)
+ *   · layout / resources / staleBuild / readiness
+ */
+export function computeVerdict(signals, expectOrOpts) {
+    const opts = typeof expectOrOpts === "string"
+        ? { expect: expectOrOpts }
+        : (expectOrOpts ?? {});
+    const expect = opts.expect;
+    const strictConsole = opts.strictConsole === true;
+    const hardFails = [];
+    const warns = [];
+    if (signals.console.rendererCrashed) {
+        hardFails.push("rendererCrashed");
+    }
+    // Uncaught exceptions in the verify window → hard-FAIL.
+    // newHardErrors covers pageerror (+ crash); crash also sets rendererCrashed.
+    if ((signals.console.newHardErrors ?? 0) > 0) {
+        hardFails.push("pageerror");
+    }
+    if (signals.mainProcess.exited) {
+        hardFails.push("mainProcess.exited");
+    }
+    // Bare console.error: WARN by default; FAIL when strictConsole.
+    if ((signals.console.newConsoleErrors ?? 0) > 0) {
+        if (strictConsole) {
+            hardFails.push("console.newErrors");
+        }
+        else {
+            warns.push("console.errors");
+        }
+    }
+    // unhandledrejection → WARN (distinct from pageerror).
+    if ((signals.console.newUnhandledRejections ?? 0) > 0) {
+        warns.push("console.unhandledrejection");
+    }
+    if (signals.blankScreen.isBlank) {
+        hardFails.push("blankScreen.isBlank");
+    }
+    // Persistent state: prior errors still exist even if this window is clean.
+    if (signals.console.sessionErrors > signals.console.newErrors) {
+        warns.push("console.staleErrors");
+    }
+    if (signals.layout.documentOverflow) {
+        warns.push("layout.documentOverflow");
+    }
+    if (signals.layout.criticalMissing.length > 0) {
+        warns.push("layout.criticalMissing");
+    }
+    if (signals.resources.brokenImages > 0) {
+        warns.push("resources.brokenImages");
+    }
+    if (signals.resources.failedRequests.length > 0) {
+        warns.push("resources.failedRequests");
+    }
+    if (signals.staleBuild.stale) {
+        warns.push("staleBuild.stale");
+    }
+    if (signals.readiness.timedOut) {
+        warns.push("readiness.timedOut");
+    }
+    const hard = [...new Set(hardFails)];
+    const soft = [...new Set(warns)];
+    let verdict;
+    if (hard.length > 0)
+        verdict = "FAIL";
+    else if (soft.length > 0)
+        verdict = "WARN";
+    else
+        verdict = "PASS";
+    return {
+        verdict,
+        hardFails: hard,
+        warns: soft,
+        signals,
+        ...(expect !== undefined ? { expect } : {}),
+    };
+}

package/dist/core/verify.d.ts

@@ -0,0 +1,52 @@
+import type { AppSession } from "./session.js";
+import type { CaptureMode, CaptureModeUsed, HoleRect, VerdictResult } from "./types.js";
+export interface VerifyOptions {
+    expect?: string;
+    windowUrlMatch?: string;
+    criticalSelectors?: string[];
+    srcGlobs?: string[];
+    readinessTimeoutMs?: number;
+    maxScreenshotWidth?: number;
+    blankCoverage?: number;
+    changeThreshold?: number;
+    strictConsole?: boolean;
+    /**
+     * When true, install the persistent renderer error buffer and reload so
+     * load-time sync throws are captured. When omitted:
+     * - if no interaction since last verify → true (re-check unchanged app)
+     * - if interaction happened → false (preserve click/type state)
+     */
+    freshLoad?: boolean;
+    /**
+     * Human-facing capture: "window" (default) | "content" | "os-window" | "both".
+     * Signal analysis ALWAYS uses content (page.screenshot).
+     */
+    captureMode?: CaptureMode;
+}
+export interface VerifyResult {
+    verdict: VerdictResult["verdict"];
+    hardFails: string[];
+    warns: string[];
+    signals: VerdictResult["signals"];
+    expect?: string;
+    /** Primary human-facing screenshot (window or content-fallback or content). */
+    screenshot: Buffer;
+    /** Optional second image when captureMode === "both" (window capture). */
+    windowScreenshot?: Buffer;
+    /** Content-only annotated image when captureMode === "both". */
+    contentScreenshot?: Buffer;
+    captureMode: CaptureModeUsed;
+    captureNote?: string;
+    /** Window selection diagnostics. */
+    windowStrategy?: string;
+    windowWarning?: string;
+    holes: HoleRect[];
+}
+/**
+ * Orchestrate one verification pass:
+ * select window → (optional freshLoad) → readiness → drain error buffer →
+ * capture content (for signals) + optional window capture → collect → verdict.
+ */
+export declare function verify(session: AppSession, opts?: VerifyOptions): Promise<VerifyResult>;
+/** Multiply DIP hole rects by devicePixelRatio for physical-pixel screenshot space. */
+export declare function scaleHolesToPhysical(holes: HoleRect[], dpr: number): HoleRect[];