@ia-qa/self-healing 1.6.16 → 1.7.0

package/dist/mcp/server.d.ts

@@ -1,2 +1,371 @@
 #!/usr/bin/env node
-export {};
+declare const TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            url: {
+                type: string;
+                description: string;
+            };
+            page_name: {
+                type: string;
+                description: string;
+            };
+            out_dir: {
+                type: string;
+                description: string;
+            };
+            wait_for_selector: {
+                type: string;
+                description: string;
+            };
+            wait_until: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            browser_channel: {
+                type: string;
+                description: string;
+            };
+            browser_path: {
+                type: string;
+                description: string;
+            };
+            locale: {
+                type: string;
+                description: string;
+            };
+            before_path?: undefined;
+            after_path?: undefined;
+            before_json?: undefined;
+            after_json?: undefined;
+            test_paths?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            before_path: {
+                type: string;
+                description: string;
+            };
+            after_path: {
+                type: string;
+                description: string;
+            };
+            before_json: {
+                type: string;
+                description: string;
+            };
+            after_json: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            test_paths?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            before_path: {
+                type: string;
+                description: string;
+            };
+            after_path: {
+                type: string;
+                description: string;
+            };
+            before_json: {
+                type: string;
+                description: string;
+            };
+            after_json: {
+                type: string;
+                description: string;
+            };
+            test_paths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            dry_run: {
+                type: string;
+                description: string;
+            };
+            use_locators: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            before_path: {
+                type: string;
+                description: string;
+            };
+            after_path: {
+                type: string;
+                description: string;
+            };
+            before_json: {
+                type: string;
+                description: string;
+            };
+            after_json: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            model: {
+                type: string;
+                description: string;
+            };
+            api_key_env: {
+                type: string;
+                description: string;
+            };
+            min_confidence: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            test_paths?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            test_paths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            write: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            before_path?: undefined;
+            after_path?: undefined;
+            before_json?: undefined;
+            after_json?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            test_paths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            before_path?: undefined;
+            after_path?: undefined;
+            before_json?: undefined;
+            after_json?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+            limit?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            offline: {
+                type: string;
+                description: string;
+            };
+            concurrency: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            before_path?: undefined;
+            after_path?: undefined;
+            before_json?: undefined;
+            after_json?: undefined;
+            test_paths?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            limit?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            limit: {
+                type: string;
+                description: string;
+            };
+            url?: undefined;
+            page_name?: undefined;
+            out_dir?: undefined;
+            wait_for_selector?: undefined;
+            wait_until?: undefined;
+            browser_channel?: undefined;
+            browser_path?: undefined;
+            locale?: undefined;
+            before_path?: undefined;
+            after_path?: undefined;
+            before_json?: undefined;
+            after_json?: undefined;
+            test_paths?: undefined;
+            dry_run?: undefined;
+            use_locators?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            api_key_env?: undefined;
+            min_confidence?: undefined;
+            write?: undefined;
+            offline?: undefined;
+            concurrency?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+export declare function callTool(name: string, args: any): Promise<string>;
+declare function main(): void;
+export { TOOLS, main };

package/dist/mcp/server.js

@@ -34,6 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS = void 0;
+exports.callTool = callTool;
+exports.main = main;
 const fs = __importStar(require("fs"));
 const aom_1 = require("../aom");
 const mapUrl_1 = require("../mapUrl");
@@ -46,17 +49,32 @@ const ingest_1 = require("../ingest");
 const config_1 = require("../config");
 const resolver_1 = require("../ai/resolver");
 const history_1 = require("../history");
+const audit_1 = require("../cli/audit");
+const check_1 = require("../cli/check");
+const checks_1 = require("../checks");
 /**
  * @ia-qa/self-healing — local stdio MCP server.
  *
  * A dependency-free JSON-RPC 2.0 server over stdio (newline-delimited messages,
  * the MCP stdio transport). It runs on the END USER's machine, launches its own
  * headless Chromium via Playwright, and exposes these tools to an agent:
+ *   - ingest_tests  — inventory the locators the suite uses → .ia-qa/usage.json.
+ *                     The ONLY tool here that writes outside a diff, and the one
+ *                     diff_mappings needs to see name drift at all
  *   - map_app       — scan one URL → page contract (json + md)
  *   - diff_mappings — two contracts → PASS/FIX/BLOCK verdict + drift detail
  *   - fix_tests     — apply the deterministic healable rewrites to test files
+ *   - audit_suite   — day one, NO baseline: does the suite still name things that
+ *                     exist? Read-only, advisory — never a gate
+ *   - check_app     — is the mapped app sound at all? dead links · unnamed elements ·
+ *                     role+name collisions · orphan pages. Read-only
  *   - suggest_heal  — OPTIONAL BYOK AI: propose matches for the lost/ambiguous rows
  *                     the deterministic engine gave up on (suggestion only, no writes)
+ *   - heal_history  — the drift trend no single diff can reconstruct
+ *
+ * `audit_suite` and `check_app` are the entry verbs: every other tool compares two
+ * moments, so its value arrives one drift *after* install — an agent meeting a
+ * project for the first time has no baseline and needs a verdict anyway.
  *
  * Because it runs locally, it sees localhost / staging / VPN apps and nothing
  * leaves the machine. stdout carries the protocol; all logs go to stderr.
@@ -136,6 +154,55 @@ const TOOLS = [
             required: ['provider', 'model'],
         },
     },
+    {
+        name: 'ingest_tests',
+        description: "Inventory the locators the test suite ACTUALLY uses — CSS selectors and accessible names — by scanning the test/POM files statically (no execution, no browser). WRITES .ia-qa/usage.json, the file diff_mappings reads to escalate a rename the tests locate by name, and fix_tests reads as its default file list: without it those two tools see only half the drift, and report a *greener* verdict than the truth. Run it once before diffing, and again whenever the suite changes. It overwrites the whole inventory, so scanning a SUBSET of the suite narrows it — the response says so explicitly in `narrowed`. Use write=false to preview without touching the file. Only .ia-qa/usage.json is written; test files are read, never modified.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                test_paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Test files or directories to scan. Omit to use "testPaths" from .ia-qa/config.json. Pass the WHOLE suite — a partial path produces a partial inventory, and every later verdict inherits it.',
+                },
+                write: {
+                    type: 'boolean',
+                    description: 'Write .ia-qa/usage.json. Default true. Set false to see what the scan finds without replacing the current inventory.',
+                },
+            },
+        },
+    },
+    {
+        name: 'audit_suite',
+        description: "DAY ONE, NO BASELINE. Answers 'does my E2E suite still name things that exist?' by cross-referencing the locators the tests use against ONE capture of the app — so it works the first time it is run, unlike diff_mappings which needs two moments. Read-only: never opens a browser, never edits a file, never leaves the machine. ADVISORY BY DESIGN — do NOT gate a pipeline on this verdict: the capture covers the pages in config.pages, and a locator reported as matching nothing may simply live on an unmapped page, or in a state nothing captured (behind a tab, a modal, a mode toggle). Only role-anchored locators (getByRole, getByLabel, By.linkText) are judged; getByText and cy.contains name a string, not an element, and are counted only. Suggestions prove a resemblance, never an identity — a human confirms before any edit.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                test_paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Test files or directories to scan in memory. Omit to use .ia-qa/usage.json (written by `ia-qa-heal ingest`), falling back to "testPaths" in .ia-qa/config.json.',
+                },
+            },
+        },
+    },
+    {
+        name: 'check_app',
+        description: "Is the app you mapped SOUND? — the question a contract diff structurally cannot answer, since a green diff over a page whose every link 404s is still green. Four checks: dead links, interactive elements with no accessible name, role+name collisions (a locator coin flip: drift that has not happened yet), and mapped pages nothing links to. Read-only, edits nothing. NETWORK: unless offline=true, this GETs the links found in the contract — your own configured baseUrl only, same site only, and never a URL that acts (/logout, /delete…); the response states the host and how many were requested. Only a dead link FAILs (a fact the app itself answered); everything else WARNs and is advisory. A 429 is this tool's own request rate, not a defect — those land in unverifiedLinks, which is 'not checked', never 'ok'.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                offline: {
+                    type: 'boolean',
+                    description: 'Skip the link requests entirely — purely local run. The verdict then covers less, and says so in `skipped`. Default false.',
+                },
+                concurrency: {
+                    type: 'number',
+                    description: 'How many links to request at once (1-32, default 6). Lower it for a target with a strict rate limiter; an out-of-range value falls back to the default and says so.',
+                },
+            },
+        },
+    },
     {
         name: 'heal_history',
         description: "Read-only. The drift TREND for this project, which no single diff can answer: how many runs ended PASS/FIX/BLOCK over time, mean page coverage, how many rewrites were applied, and which pages actually churn. Reads .ia-qa/history.jsonl, written by every diff/run — it never opens a browser, never touches the app, and cannot change a verdict. IMPORTANT when reporting this to a human: runs captured differently (a `map` baseline vs a live suite capture) are excluded from the trend and listed in `excluded_reason` — say so rather than presenting the series as complete, because the two read a page differently and mixing them invents a trend out of a capture artifact. An empty history means nothing has been recorded yet, never that nothing drifted.",
@@ -147,6 +214,7 @@ const TOOLS = [
         },
     },
 ];
+exports.TOOLS = TOOLS;
 function loadMappingArg(inlineJson, filePath, label) {
     let mapping = inlineJson;
     if (!mapping && filePath) {
@@ -175,6 +243,123 @@ function assertComparable(before, after) {
         `then let the app change, then capture again.`);
 }
 async function callTool(name, args) {
+    if (name === 'ingest_tests') {
+        const given = Array.isArray(args?.test_paths) ? args.test_paths : [];
+        for (const p of given)
+            (0, sandbox_1.assertInsideProject)(p, 'test_paths');
+        const paths = given.length > 0 ? given : (0, config_1.configuredTestPaths)();
+        if (paths.length === 0) {
+            throw new Error('Nothing to scan: no test_paths given and no "testPaths" in .ia-qa/config.json. ' +
+                'Pass the whole suite — a partial path produces a partial inventory, and diff_mappings inherits it.');
+        }
+        const write = args?.write !== false;
+        const previous = (0, ingest_1.loadUsage)();
+        const { usage, skipped } = (0, ingest_1.ingestPaths)(paths);
+        const report = (0, ingest_1.buildInventoryReport)(usage);
+        // The one hazard this tool has, and it fails in the reassuring direction:
+        // the whole inventory is replaced, so scanning a subset leaves later diffs
+        // seeing less drift and reporting a GREENER verdict. Nothing about the file
+        // afterwards reveals that it got narrower, so it is said here — as a field,
+        // not buried in prose an agent may not relay.
+        const before = previous
+            ? { selectors: Object.keys(previous.selectors).length, names: Object.keys(previous.names ?? {}).length }
+            : null;
+        const after = { selectors: report.selectors.distinct, names: report.names.distinct };
+        const narrowed = before !== null && (after.selectors < before.selectors || after.names < before.names)
+            ? { before, after, why: 'The inventory now covers LESS than it did. If that was not intended, re-run over the whole suite: every later diff_mappings and fix_tests verdict reads this file, and a narrower inventory reports less drift, not more.' }
+            : null;
+        const file = write ? (0, ingest_1.saveUsage)(usage) : null;
+        return JSON.stringify({
+            written: file ? (0, mapUrl_1.rel)(file) : null,
+            scanned_paths: paths,
+            skipped_paths: skipped,
+            narrowed,
+            ...report,
+            note: (write
+                ? 'Inventory replaced. Test files were read, never modified. '
+                : 'PREVIEW — write=false, .ia-qa/usage.json untouched. ') +
+                report.note,
+        }, null, 2);
+    }
+    if (name === 'audit_suite') {
+        const testPaths = Array.isArray(args?.test_paths) ? args.test_paths : [];
+        for (const p of testPaths)
+            (0, sandbox_1.assertInsideProject)(p, 'test_paths');
+        // `strict` is deliberately not an argument. It only ever changes an exit
+        // code, and an MCP tool has none — offering it would let an agent believe it
+        // had turned an advisory answer into a gate.
+        const outcome = (0, audit_1.auditProject)({ testPaths });
+        // A refusal is an ERROR, not a payload. At a terminal `audit` refuses with
+        // exit 2, which is what stops "verdict: null" from reading as a pass; over
+        // MCP there is no exit code, so the refusal has to arrive as isError or the
+        // absence of a check gets reported upstream as the success of one.
+        if (!outcome.ok)
+            throw new Error(`${outcome.reason}: ${outcome.message}`);
+        const r = outcome.report;
+        return JSON.stringify({
+            verdict: r.verdict,
+            advisory: true,
+            pages_mapped: r.pagesMapped,
+            elements: outcome.elements,
+            locators_judged: r.locatorsJudged,
+            locators_not_judged: r.locatorsNotJudged,
+            dead_locators: r.deadLocators.map((d) => ({
+                name: d.name,
+                roles: d.roles,
+                test_sites: d.sites.map((s) => `${s.file}:${s.line}`),
+                closest_live_label: d.suggestion
+                    ? { role: d.suggestion.role, name: d.suggestion.name, score: Number(d.suggestion.score.toFixed(2)), kind: d.suggestion.kind, pages: d.suggestion.pages }
+                    : null,
+            })),
+            unresolved_selectors: r.unresolvedSelectors,
+            note: 'ADVISORY — never gate a pipeline on this. Coverage decides what the verdict is worth: ' +
+                `${r.pagesMapped} page(s) mapped, and a "dead" locator may live on an unmapped page or in an ` +
+                'unmapped state (behind a tab, a modal, a mode toggle). Nothing was edited — `audit` never writes. ' +
+                'A closest_live_label is a resemblance read from ONE capture, not proof of identity: a human confirms.',
+        }, null, 2);
+    }
+    if (name === 'check_app') {
+        const offline = !!args?.offline;
+        let concurrency = check_1.CONCURRENCY_BOUNDS.default;
+        let concurrencyNote;
+        if (args?.concurrency !== undefined) {
+            const n = Number(args.concurrency);
+            if (Number.isInteger(n) && n >= check_1.CONCURRENCY_BOUNDS.min && n <= check_1.CONCURRENCY_BOUNDS.max) {
+                concurrency = n;
+            }
+            else {
+                concurrencyNote = `concurrency ${JSON.stringify(args.concurrency)} is out of range ${check_1.CONCURRENCY_BOUNDS.min}-${check_1.CONCURRENCY_BOUNDS.max} — used ${check_1.CONCURRENCY_BOUNDS.default}.`;
+            }
+        }
+        const outcome = await (0, check_1.checkProject)({ offline, concurrency });
+        if (!outcome.ok)
+            throw new Error(`${outcome.reason}: ${outcome.message}`);
+        const { report: r, verdict, network } = outcome;
+        return JSON.stringify({
+            verdict,
+            headline: (0, checks_1.checkHeadline)(r, verdict),
+            advisory: verdict === 'WARN',
+            pages_checked: r.pagesChecked,
+            elements: r.elements,
+            // Where the requests went, restated in the payload: over stdio there is
+            // no "before the first request" to announce in.
+            network: network
+                ? { host: network.host, links_requested: network.linksRequested, hrefs_left_alone: network.hrefsLeftAlone, rate_limited: network.throttled, method: 'GET', scope: 'configured baseUrl only, action URLs skipped' }
+                : null,
+            dead_links: r.deadLinks.map((d) => ({ url: d.url, status: d.status, error: d.error ?? null, linked_from: d.from })),
+            unverified_links: r.unverifiedLinks.map((u) => ({ url: u.url, reason: u.reason, linked_from: u.from })),
+            ambiguous_names: r.ambiguous,
+            unnamed_elements: r.unnamed,
+            orphan_pages: r.orphans,
+            checks_ran: (0, checks_1.checkCoverage)(r),
+            skipped: r.skipped,
+            note: (concurrencyNote ? `${concurrencyNote} ` : '') +
+                'FAIL means a dead link — a fact the app answered, not a judgement. WARN is advisory: an unnamed ' +
+                'icon button or a deep-link-only page is real but arguable. unverified_links reached NO verdict ' +
+                '(rate-limited or unanswered) — never report them as ok, and never as dead. A PASS speaks only for ' +
+                'the checks in checks_ran; whatever a skipped check would have found is invisible here.',
+        }, null, 2);
+    }
     if (name === 'heal_history') {
         const limit = Number.isFinite(args?.limit) ? Math.max(1, Math.floor(args.limit)) : 100;
         const entries = (0, history_1.readHistory)(limit);
@@ -453,5 +638,15 @@ function main() {
     });
     process.stdin.on('end', () => process.exit(0));
 }
-main();
+/**
+ * Only when this file IS the process.
+ *
+ * `main()` attaches a stdin listener, which keeps the event loop alive forever —
+ * so an unconditional call made this module impossible to import, and therefore
+ * impossible to test. The dispatch in `callTool` is exactly where a CLI/MCP
+ * divergence would hide, so it has to be reachable from a test; as the `bin`
+ * entry point this condition is true and the server behaves as before.
+ */
+if (require.main === module)
+    main();
 //# sourceMappingURL=server.js.map