@ia-qa/self-healing 0.1.0

package/dist/mapUrl.d.ts

@@ -0,0 +1,34 @@
+import { PageMapping } from './aom';
+import { BrowserChoice } from './launcher';
+/**
+ * Config-free single-URL mapping — the primitive behind the MCP `map_app` tool.
+ *
+ * Unlike `ia-qa-heal map` (which reads `.ia-qa/config.json` for auth + a route
+ * list), this takes one URL, launches its own headless Chromium, extracts the
+ * interactive elements, and returns the mapping. It runs on the caller's machine,
+ * so it sees whatever that machine sees — localhost, staging, an app behind a
+ * VPN. Nothing leaves the machine.
+ */
+export interface MapUrlOptions extends BrowserChoice {
+    /** Logical page name → mapping filename. Defaults to a slug of the URL path. */
+    pageName?: string;
+    /** Directory to write `<page>.json` + `<page>.md` into. Omit to skip writing. */
+    outDir?: string;
+    /** Playwright load state to await before extracting. Default 'networkidle'. */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    /** Navigation timeout in ms. Default 30000. */
+    timeout?: number;
+    /** Optional selector to wait for before extracting (helps SPAs settle). */
+    waitForSelector?: string;
+}
+export interface MapUrlResult {
+    mapping: PageMapping;
+    jsonPath?: string;
+    mdPath?: string;
+    /** Which browser was actually used (bundled, system channel, explicit path). */
+    browser: string;
+}
+export declare function pageNameFromUrl(url: string): string;
+export declare function mapUrl(url: string, options?: MapUrlOptions): Promise<MapUrlResult>;
+/** Convenience for logs: a relative path when possible. */
+export declare function rel(p: string): string;

package/dist/mapUrl.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageNameFromUrl = pageNameFromUrl;
+exports.mapUrl = mapUrl;
+exports.rel = rel;
+const path = __importStar(require("path"));
+const aom_1 = require("./aom");
+const markdown_1 = require("./markdown");
+const config_1 = require("./config");
+const launcher_1 = require("./launcher");
+function pageNameFromUrl(url) {
+    let pathname = '/';
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        /* fall through to default */
+    }
+    const slug = pathname.replace(/^\/+|\/+$/g, '').replace(/\//g, '-');
+    return slug || 'home';
+}
+async function mapUrl(url, options = {}) {
+    const pageName = options.pageName || pageNameFromUrl(url);
+    const waitUntil = options.waitUntil || 'networkidle';
+    const timeout = options.timeout ?? 30000;
+    const { browser, using } = await (0, launcher_1.launchBrowser)(options);
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        await page.goto(url, { waitUntil, timeout });
+        if (options.waitForSelector) {
+            await page.waitForSelector(options.waitForSelector, { timeout });
+        }
+        const elements = await (0, aom_1.extractInteractiveElements)(page);
+        const mapping = {
+            page: pageName,
+            url,
+            capturedAt: new Date().toISOString(),
+            elements,
+        };
+        const result = { mapping, browser: using };
+        if (options.outDir !== undefined) {
+            const dir = options.outDir || (0, config_1.mappingDir)();
+            result.jsonPath = (0, aom_1.saveMapping)(mapping, dir);
+            result.mdPath = (0, markdown_1.saveMarkdown)(mapping, dir);
+        }
+        return result;
+    }
+    finally {
+        await browser.close();
+    }
+}
+/** Convenience for logs: a relative path when possible. */
+function rel(p) {
+    return path.relative(process.cwd(), p) || p;
+}
+//# sourceMappingURL=mapUrl.js.map

package/dist/mapUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapUrl.js","sourceRoot":"","sources":["../src/mapUrl.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,0CASC;AAED,wBAgCC;AAGD,kBAEC;AArFD,2CAA6B;AAC7B,+BAA4F;AAC5F,yCAA0C;AAC1C,qCAAsC;AACtC,yCAA0D;AAiC1D,SAAgB,eAAe,CAAC,GAAW;IACzC,IAAI,QAAQ,GAAG,GAAG,CAAC;IACnB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACpE,OAAO,IAAI,IAAI,MAAM,CAAC;AACxB,CAAC;AAEM,KAAK,UAAU,MAAM,CAAC,GAAW,EAAE,UAAyB,EAAE;IACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,aAAa,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;IAEzC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,IAAA,wBAAa,EAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,QAAQ,GAAoB,MAAM,IAAA,gCAA0B,EAAC,IAAI,CAAC,CAAC;QACzE,MAAM,OAAO,GAAgB;YAC3B,IAAI,EAAE,QAAQ;YACd,GAAG;YACH,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,QAAQ;SACT,CAAC;QAEF,MAAM,MAAM,GAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACzD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,IAAA,mBAAU,GAAE,CAAC;YAC3C,MAAM,CAAC,QAAQ,GAAG,IAAA,iBAAW,EAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC5C,MAAM,CAAC,MAAM,GAAG,IAAA,uBAAY,EAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,SAAgB,GAAG,CAAC,CAAS;IAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC"}

package/dist/markdown.d.ts

@@ -0,0 +1,10 @@
+import { PageMapping } from './aom';
+import { renderPageContract } from './browser/contract';
+/**
+ * Node-side file I/O for the page contract. The rendering itself lives in
+ * `browser/contract.js` (pure JS) so the CLI and ia-qa.com produce identical
+ * `.md` output from the same mapping.
+ */
+export { renderPageContract };
+export declare function markdownPath(pageName: string, dir?: string): string;
+export declare function saveMarkdown(mapping: PageMapping, dir?: string): string;

package/dist/markdown.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPageContract = void 0;
+exports.markdownPath = markdownPath;
+exports.saveMarkdown = saveMarkdown;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const contract_1 = require("./browser/contract");
+Object.defineProperty(exports, "renderPageContract", { enumerable: true, get: function () { return contract_1.renderPageContract; } });
+function markdownPath(pageName, dir = (0, config_1.mappingDir)()) {
+    const safe = pageName.replace(/[^a-zA-Z0-9._-]/g, '-');
+    return path.join(dir, `${safe}.md`);
+}
+function saveMarkdown(mapping, dir = (0, config_1.mappingDir)()) {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = markdownPath(mapping.page, dir);
+    fs.writeFileSync(file, (0, contract_1.renderPageContract)(mapping), 'utf8');
+    return file;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcA,oCAGC;AAED,oCAKC;AAxBD,uCAAyB;AACzB,2CAA6B;AAE7B,qCAAsC;AACtC,iDAAwD;AAQ/C,mGARA,6BAAkB,OAQA;AAE3B,SAAgB,YAAY,CAAC,QAAgB,EAAE,MAAc,IAAA,mBAAU,GAAE;IACvE,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,SAAgB,YAAY,CAAC,OAAoB,EAAE,MAAc,IAAA,mBAAU,GAAE;IAC3E,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7C,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAA,6BAAkB,EAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const mapUrl_1 = require("../mapUrl");
+const match_1 = require("../browser/match");
+const markdown_1 = require("../markdown");
+const fixEngine_1 = require("../fixEngine");
+/**
+ * @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 three tools to an agent:
+ *   - 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
+ *
+ * Because it runs locally, it sees localhost / staging / VPN apps and nothing
+ * leaves the machine. stdout carries the protocol; all logs go to stderr.
+ */
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = { name: 'ia-qa-self-healing', version: '0.1.0' };
+const TOOLS = [
+    {
+        name: 'map_app',
+        description: "Scan ONE page of a web app and produce its 'page contract': every visible interactive element as {role, accessible name, context, stable selector}. Runs a local headless browser, so it works on localhost, staging, or an app behind a VPN — nothing leaves the machine. Call once per route (navigate + log in first if needed). Returns the contract as Markdown and, if out_dir is set, writes <page>.json + <page>.md.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'The page URL to map (e.g. http://localhost:3000/checkout).' },
+                page_name: { type: 'string', description: 'Logical name for the mapping file. Defaults to a slug of the URL path.' },
+                out_dir: { type: 'string', description: 'Directory to write <page>.json + <page>.md into. Omit to return the contract without writing files.' },
+                wait_for_selector: { type: 'string', description: 'Optional CSS selector to wait for before extracting — helps a lazy SPA settle.' },
+                wait_until: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle', 'commit'], description: "Load state to await. Default 'networkidle'." },
+                browser_channel: { type: 'string', description: "Reuse a browser already installed on the machine instead of the bundled one: 'chrome', 'msedge'. Playwright's browser cache is machine-wide, so the bundled Chromium is usually already present and free to use — set this only to avoid a download on a machine that has Chrome but no Playwright browsers." },
+                browser_path: { type: 'string', description: 'Absolute path to a browser executable to use. Wins over browser_channel.' },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'diff_mappings',
+        description: 'Diff a baseline page contract against a current one and return a CI-style verdict: PASS / FIX / BLOCK, plus per-element drift (ok, renamed, healable, ambiguous, lost, added). Pure and deterministic — no browser. Provide each mapping either as a file path or inline JSON.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                before_path: { type: 'string', description: 'Path to the baseline mapping JSON.' },
+                after_path: { type: 'string', description: 'Path to the current mapping JSON.' },
+                before_json: { type: 'object', description: 'Baseline mapping inline (alternative to before_path).' },
+                after_json: { type: 'object', description: 'Current mapping inline (alternative to after_path).' },
+            },
+        },
+    },
+    {
+        name: 'fix_tests',
+        description: "Apply ONLY the deterministic 'healable' selector rewrites (old→new) from a diff to your test files. Framework/language-agnostic: replaces the selector only where it appears as a quoted string literal, quote-safe for attribute selectors. LOST / AMBIGUOUS / RENAMED are reported but never touched — they need human judgment. Edits the working tree and NEVER commits; review with git diff. Use dry_run to preview.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                before_path: { type: 'string', description: 'Path to the baseline mapping JSON.' },
+                after_path: { type: 'string', description: 'Path to the current mapping JSON.' },
+                before_json: { type: 'object', description: 'Baseline mapping inline (alternative to before_path).' },
+                after_json: { type: 'object', description: 'Current mapping inline (alternative to after_path).' },
+                test_paths: { type: 'array', items: { type: 'string' }, description: 'Test files or directories to rewrite.' },
+                dry_run: { type: 'boolean', description: 'Preview the plan without writing. Default false.' },
+            },
+            required: ['test_paths'],
+        },
+    },
+];
+function loadMappingArg(inlineJson, filePath, label) {
+    let mapping = inlineJson;
+    if (!mapping && filePath) {
+        mapping = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    if (!mapping)
+        throw new Error(`Provide ${label}_path or ${label}_json.`);
+    if (!Array.isArray(mapping.elements))
+        throw new Error(`${label} has no "elements" array — not a mapping.`);
+    return mapping;
+}
+async function callTool(name, args) {
+    if (name === 'map_app') {
+        if (!args?.url)
+            throw new Error('map_app requires "url".');
+        const res = await (0, mapUrl_1.mapUrl)(args.url, {
+            pageName: args.page_name,
+            outDir: args.out_dir,
+            waitForSelector: args.wait_for_selector,
+            waitUntil: args.wait_until,
+            browserChannel: args.browser_channel,
+            browserPath: args.browser_path,
+        });
+        const md = (0, markdown_1.renderPageContract)(res.mapping);
+        const header = `Mapped ${res.mapping.elements.length} interactive elements on "${res.mapping.page}" (${args.url}).` +
+            `\nBrowser: ${res.browser}` +
+            (res.jsonPath ? `\nWrote ${(0, mapUrl_1.rel)(res.jsonPath)} + ${(0, mapUrl_1.rel)(res.mdPath)}` : '\n(No out_dir given — contract returned inline, not written.)');
+        return `${header}\n\n${md}`;
+    }
+    if (name === 'diff_mappings') {
+        const before = loadMappingArg(args?.before_json, args?.before_path, 'before');
+        const after = loadMappingArg(args?.after_json, args?.after_path, 'after');
+        const report = (0, match_1.diffMappings)(before, after);
+        return JSON.stringify(report, null, 2);
+    }
+    if (name === 'fix_tests') {
+        const before = loadMappingArg(args?.before_json, args?.before_path, 'before');
+        const after = loadMappingArg(args?.after_json, args?.after_path, 'after');
+        if (!Array.isArray(args?.test_paths) || args.test_paths.length === 0) {
+            throw new Error('fix_tests requires a non-empty "test_paths" array.');
+        }
+        const report = (0, match_1.diffMappings)(before, after);
+        const rewrites = (0, fixEngine_1.computeRewrites)(report.rows);
+        const skipped = [];
+        const files = (0, fixEngine_1.collectFiles)(args.test_paths, (p) => skipped.push(p));
+        const result = (0, fixEngine_1.applyRewrites)(files, rewrites, !!args.dry_run);
+        const flagged = report.rows
+            .filter((r) => r.status === 'lost' || r.status === 'ambiguous' || r.status === 'renamed')
+            .map((r) => ({ status: r.status, role: r.role, name: r.name, selector: r.selector, newName: r.newName, candidateCount: r.candidateCount }));
+        return JSON.stringify({
+            verdict: report.verdict,
+            counts: report.counts,
+            applied: result.dryRun ? 0 : result.totalReplacements,
+            would_apply: result.totalReplacements,
+            edits: result.edits.map((e) => ({ file: (0, mapUrl_1.rel)(e.file), replacements: e.replacements })),
+            needs_human: flagged,
+            skipped_paths: skipped,
+            note: result.dryRun
+                ? 'Dry run — nothing written.'
+                : 'Working tree edited. NOT committed — review with git diff, then a human decides to push or discard.',
+        }, null, 2);
+    }
+    throw new Error(`Unknown tool "${name}".`);
+}
+// ── JSON-RPC over stdio (newline-delimited) ─────────────────────────────────
+function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + '\n');
+}
+function reply(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+}
+function replyError(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+async function handle(req) {
+    const { id, method, params } = req;
+    const isNotification = id === undefined || id === null;
+    try {
+        if (method === 'initialize') {
+            reply(id, {
+                protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: SERVER_INFO,
+            });
+            return;
+        }
+        if (method === 'notifications/initialized' || method === 'initialized') {
+            return; // notification, no response
+        }
+        if (method === 'ping') {
+            reply(id, {});
+            return;
+        }
+        if (method === 'tools/list') {
+            reply(id, { tools: TOOLS });
+            return;
+        }
+        if (method === 'tools/call') {
+            const toolName = params?.name;
+            try {
+                const text = await callTool(toolName, params?.arguments || {});
+                reply(id, { content: [{ type: 'text', text }] });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                reply(id, { content: [{ type: 'text', text: `Error: ${message}` }], isError: true });
+            }
+            return;
+        }
+        if (!isNotification)
+            replyError(id, -32601, `Method not found: ${method}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!isNotification)
+            replyError(id, -32603, message);
+        else
+            process.stderr.write(`[ia-qa-self-healing] error handling ${method}: ${message}\n`);
+    }
+}
+function main() {
+    process.stderr.write('[ia-qa-self-healing] MCP server ready (stdio)\n');
+    let buffer = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let req;
+            try {
+                req = JSON.parse(line);
+            }
+            catch {
+                process.stderr.write(`[ia-qa-self-healing] non-JSON line ignored: ${line.slice(0, 80)}\n`);
+                continue;
+            }
+            void handle(req);
+        }
+    });
+    process.stdin.on('end', () => process.exit(0));
+}
+main();
+//# sourceMappingURL=server.js.map

package/dist/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/playwright/healer.d.ts

@@ -0,0 +1,39 @@
+import type { Page } from 'playwright';
+import { MappedElement } from '../aom';
+/**
+ * Runtime self-healing helpers for Playwright.
+ *
+ * Usage in a test:
+ *   import { aiClick } from '@ia-qa/self-healing';
+ *   await aiClick(page, 'button#login');
+ *
+ * If the standard action fails (timeout / not found), the helper reads the
+ * page mapping produced by `ia-qa-heal map`, re-scans the live page, and finds
+ * the element that semantically matches the original (same role + closest
+ * accessible name — or a custom LLM resolver if provided). It then retries the
+ * action on the healed selector and logs a loud warning so the developer knows
+ * the test needs updating.
+ */
+export interface HealerOptions {
+    /** Mapping name (`.ia-qa/mapping/<page>.json`). Inferred from the current URL + config.pages if omitted. */
+    page?: string;
+    /** Timeout for the initial attempt AND the healed retry (ms). Default 5000. */
+    timeout?: number;
+    /** Override the mapping directory (defaults to `<cwd>/.ia-qa/mapping`). */
+    mappingDir?: string;
+    /**
+     * Optional semantic resolver — e.g. an LLM call. Receives the original
+     * element and the live candidates; returns the healed selector or null to
+     * fall back to the built-in heuristic. See `llmResolverStub` below.
+     */
+    llmResolver?: (target: MappedElement, candidates: MappedElement[]) => Promise<string | null>;
+}
+export declare function aiClick(page: Page, selector: string, options?: HealerOptions): Promise<void>;
+export declare function aiFill(page: Page, selector: string, value: string, options?: HealerOptions): Promise<void>;
+/**
+ * LLM resolver stub — TO COMPLETE. Wire this to a real model (e.g.
+ * `POST https://www.ia-qa.com/mcp/call` with an embedding/similarity tool, or
+ * your own provider) and pass it via `options.llmResolver`. It must return the
+ * selector of the best candidate, or null to defer to the heuristic.
+ */
+export declare function llmResolverStub(_target: MappedElement, _candidates: MappedElement[]): Promise<string | null>;

package/dist/playwright/healer.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiClick = aiClick;
+exports.aiFill = aiFill;
+exports.llmResolverStub = llmResolverStub;
+const config_1 = require("../config");
+const aom_1 = require("../aom");
+const match_1 = require("../browser/match");
+const DEFAULT_TIMEOUT = 5000;
+async function aiClick(page, selector, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    try {
+        await page.click(selector, { timeout });
+    }
+    catch (error) {
+        const healed = await heal(page, selector, options, error);
+        await page.click(healed, { timeout });
+    }
+}
+async function aiFill(page, selector, value, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    try {
+        await page.fill(selector, value, { timeout });
+    }
+    catch (error) {
+        const healed = await heal(page, selector, options, error);
+        await page.fill(healed, value, { timeout });
+    }
+}
+async function heal(page, selector, options, originalError) {
+    const pageName = options.page ?? inferPageName(page);
+    const dir = options.mappingDir ?? (0, config_1.mappingDir)();
+    const mapping = (0, aom_1.loadMapping)(pageName, dir);
+    const target = mapping.elements.find((e) => e.selector === selector);
+    if (!target) {
+        throw chain(originalError, `Selector "${selector}" is not in the mapping for page "${pageName}" — re-run \`ia-qa-heal map ${pageName}\` so the healer knows what this selector used to point at.`);
+    }
+    const candidates = await (0, aom_1.extractInteractiveElements)(page);
+    let healedSelector = null;
+    if (options.llmResolver) {
+        healedSelector = await options.llmResolver(target, candidates);
+    }
+    if (!healedSelector) {
+        const match = (0, match_1.matchElement)(target, candidates);
+        if (match && 'ambiguous' in match && match.ambiguous) {
+            throw chain(originalError, `Self-healing refused for "${selector}" on page "${pageName}": ${match.count} elements match role="${target.role}" name="${target.name}" and context "${target.context ?? ''}" doesn't disambiguate. Healing the wrong one is worse than failing — fix the selector by hand, or give the element a data-testid.`);
+        }
+        if (match && match.matched)
+            healedSelector = match.selector;
+    }
+    if (!healedSelector || healedSelector === selector) {
+        throw chain(originalError, `Self-healing failed for "${selector}" on page "${pageName}": no live element matches role="${target.role}" name="${target.name}".`);
+    }
+    console.warn(`\n⚠️  [ia-qa self-healing] Selector "${selector}" failed on page "${pageName}".\n` +
+        `    Healed to "${healedSelector}" (matched role="${target.role}", name="${target.name}").\n` +
+        `    Update your test to use the new selector, then re-run \`ia-qa-heal map ${pageName}\`.\n`);
+    return healedSelector;
+}
+/**
+ * LLM resolver stub — TO COMPLETE. Wire this to a real model (e.g.
+ * `POST https://www.ia-qa.com/mcp/call` with an embedding/similarity tool, or
+ * your own provider) and pass it via `options.llmResolver`. It must return the
+ * selector of the best candidate, or null to defer to the heuristic.
+ */
+async function llmResolverStub(_target, _candidates) {
+    return null;
+}
+function inferPageName(page) {
+    const currentPath = new URL(page.url()).pathname.replace(/\/+$/, '') || '/';
+    const config = (0, config_1.loadConfig)();
+    const match = config.pages.find((p) => {
+        const mapped = new URL(p.url, config.baseUrl).pathname.replace(/\/+$/, '') || '/';
+        return mapped === currentPath;
+    });
+    if (!match) {
+        throw new Error(`Cannot infer the mapping name for ${page.url()} — no entry in config.pages matches this path. Pass { page: '<name>' } explicitly.`);
+    }
+    return match.name;
+}
+function chain(originalError, message) {
+    const reason = originalError instanceof Error ? originalError.message : String(originalError);
+    return new Error(`${message}\nOriginal error: ${reason}`);
+}
+//# sourceMappingURL=healer.js.map

package/dist/playwright/healer.js.map

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