@ia-qa/self-healing 1.0.0 → 1.1.0

package/dist/ai/resolver.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiResolve = aiResolve;
+exports.prefilter = prefilter;
+exports.buildPrompt = buildPrompt;
+exports.parseModelJson = parseModelJson;
+const match_1 = require("../browser/match");
+const DEFAULTS = { minConfidence: 0.7, topN: 15, timeoutMs: 15000, temperature: 0 };
+/**
+ * Resolve a broken `target` to one of the live `candidates`, or null.
+ *
+ * Returns null — defer to the deterministic path / a human — whenever there is
+ * nothing to choose from, the model is not confident enough, the reply is
+ * unparseable, or the network fails. It never throws on any of those.
+ */
+async function aiResolve(target, candidates, opts) {
+    const minConfidence = opts.minConfidence ?? DEFAULTS.minConfidence;
+    const topN = opts.topN ?? DEFAULTS.topN;
+    const shortlist = prefilter(target, candidates, topN);
+    if (shortlist.length === 0)
+        return null;
+    const raw = await callModel(buildPrompt(target, shortlist), opts);
+    if (!raw)
+        return null;
+    const { candidateIndex, confidence, rationale } = raw;
+    if (!Number.isInteger(candidateIndex) || candidateIndex < 0 || candidateIndex >= shortlist.length) {
+        return null;
+    }
+    if (typeof confidence !== 'number' || confidence < minConfidence)
+        return null;
+    const candidate = shortlist[candidateIndex];
+    return { selector: candidate.selector, confidence, rationale: String(rationale ?? ''), candidate };
+}
+/**
+ * Keep only same-role candidates, ranked by name similarity to the target, capped
+ * at `topN`. Reuses the deterministic engine's pure metric so the shortlist the
+ * model sees is the same neighbourhood the heuristic would have searched — the LLM
+ * is asked to break a tie the heuristic couldn't, not to search a different space.
+ *
+ * A target with no accessible name (icon-only) has nothing for Dice to rank on;
+ * every same-role candidate scores 0, so the shortlist is just "same role, first N".
+ * That is the vision case (phase 2), and text-only will usually — correctly — not
+ * clear the confidence floor on it.
+ */
+function prefilter(target, candidates, topN) {
+    const wanted = (0, match_1.normalize)(target.name);
+    return candidates
+        .filter((c) => c.role === target.role)
+        .map((c) => ({ c, score: (0, match_1.diceSimilarity)((0, match_1.normalize)(c.name), wanted) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topN)
+        .map((x) => x.c);
+}
+function describe(el) {
+    const parts = [`role="${el.role}"`, `name=${JSON.stringify(el.name || '')}`];
+    if (el.context)
+        parts.push(`context=${JSON.stringify(el.context)}`);
+    if (el.hint)
+        parts.push(`hint=${JSON.stringify(el.hint)}`);
+    return parts.join(' ');
+}
+function buildPrompt(target, shortlist) {
+    const list = shortlist.map((c, i) => `  ${i}. ${describe(c)}`).join('\n');
+    return (`A UI end-to-end test targeted an element that no longer resolves. The element ` +
+        `was identified by its ARIA role and accessible name. The page changed; below are ` +
+        `the current interactive elements of the same role.\n\n` +
+        `Decide which current element is THE SAME element as the original — same purpose, ` +
+        `likely renamed or restyled — not merely similar. If none is clearly the same, be ` +
+        `unconfident.\n\n` +
+        `ORIGINAL (broken):\n  ${describe(target)}\n\n` +
+        `CURRENT CANDIDATES (choose by index):\n${list}\n\n` +
+        `Reply with ONLY a JSON object, nothing else, in exactly this key order:\n` +
+        `{"rationale": "<one sentence: why this candidate is the same element, or why none is>", ` +
+        `"confidence": <number 0-1>, "candidateIndex": <integer index into the list above>}\n` +
+        `Set confidence to 0 if no candidate is the same element.`);
+}
+/**
+ * One provider round-trip, fully defensive: a strict timeout (LLMs hang), any
+ * non-2xx (429 rate limit, 5xx) or network error, and any unparseable body all
+ * resolve to null instead of throwing. The caller treats null as "no suggestion".
+ */
+async function callModel(prompt, opts) {
+    const fetchFn = opts.fetchFn ?? globalThis.fetch;
+    if (typeof fetchFn !== 'function')
+        return null;
+    const timeoutMs = opts.timeoutMs ?? DEFAULTS.timeoutMs;
+    const temperature = opts.temperature ?? DEFAULTS.temperature;
+    // The newest models reject sampling params entirely: Anthropic Opus 4.8 / Sonnet 5 /
+    // Fable 5 and OpenAI reasoning models (o-series, gpt-5) 400 on `temperature`. Rather
+    // than maintain a per-model capability matrix, send temperature and — only on a 400 —
+    // retry once without it. Any model that rejects sampling still works.
+    let res = await attempt(fetchFn, opts, prompt, temperature, timeoutMs);
+    if (res && res.status === 400) {
+        res = await attempt(fetchFn, opts, prompt, undefined, timeoutMs);
+    }
+    if (!res || !res.ok)
+        return null;
+    let text;
+    try {
+        const data = await res.json();
+        text = extractText(opts.provider, data);
+    }
+    catch {
+        return null;
+    }
+    return parseModelJson(text);
+}
+/** One hardened round-trip. Returns the Response (even non-2xx, so the caller can see 400), or null on network/timeout. */
+async function attempt(fetchFn, opts, prompt, temperature, timeoutMs) {
+    const req = buildRequest(opts.provider, opts.model, opts.apiKey, prompt, temperature);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchFn(req.url, { method: 'POST', headers: req.headers, body: JSON.stringify(req.body), signal: controller.signal });
+    }
+    catch {
+        return null; // network error or aborted timeout
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function buildRequest(provider, model, apiKey, prompt, temperature) {
+    if (provider === 'anthropic') {
+        const body = { model, max_tokens: 512, messages: [{ role: 'user', content: prompt }] };
+        if (temperature !== undefined)
+            body.temperature = temperature;
+        return {
+            url: 'https://api.anthropic.com/v1/messages',
+            headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+            body,
+        };
+    }
+    if (provider === 'google') {
+        const generationConfig = { responseMimeType: 'application/json' };
+        if (temperature !== undefined)
+            generationConfig.temperature = temperature;
+        return {
+            // Key in the query string is Google's documented scheme for the Generative Language API.
+            url: `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`,
+            headers: { 'content-type': 'application/json' },
+            body: { contents: [{ parts: [{ text: prompt }] }], generationConfig },
+        };
+    }
+    const body = { model, messages: [{ role: 'user', content: prompt }] };
+    if (temperature !== undefined)
+        body.temperature = temperature;
+    return {
+        url: 'https://api.openai.com/v1/chat/completions',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+        body,
+    };
+}
+function extractText(provider, data) {
+    if (provider === 'anthropic') {
+        const block = Array.isArray(data?.content) ? data.content.find((b) => b?.type === 'text') : null;
+        return String(block?.text ?? '');
+    }
+    if (provider === 'google') {
+        const parts = data?.candidates?.[0]?.content?.parts;
+        return Array.isArray(parts) ? parts.map((p) => p?.text ?? '').join('') : '';
+    }
+    return String(data?.choices?.[0]?.message?.content ?? '');
+}
+/**
+ * Parse the model's reply. Models drool Markdown fences and prose around JSON, so
+ * we take the outermost `{…}` and parse that. Any failure → null.
+ */
+function parseModelJson(text) {
+    const match = text.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(match[0]);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    if (typeof obj.confidence !== 'number' || !Number.isInteger(obj.candidateIndex))
+        return null;
+    return {
+        rationale: typeof obj.rationale === 'string' ? obj.rationale : '',
+        confidence: obj.confidence,
+        candidateIndex: obj.candidateIndex,
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/ai/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/ai/resolver.ts"],"names":[],"mappings":";;AA2EA,8BAsBC;AAaD,8BAYC;AASD,kCAgBC;AAwGD,wCAgBC;AA1QD,4CAA6D;AAiE7D,MAAM,QAAQ,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAEpF;;;;;;GAMG;AACI,KAAK,UAAU,SAAS,CAC7B,MAAqB,EACrB,UAA2B,EAC3B,IAAsB;IAEtB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC;IACnE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;IAExC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IACtD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;IAClE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,IAAI,cAAc,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QAClG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,aAAa;QAAE,OAAO,IAAI,CAAC;IAE9E,MAAM,SAAS,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;IAC5C,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC;AACrG,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,SAAS,CACvB,MAAqB,EACrB,UAA2B,EAC3B,IAAY;IAEZ,MAAM,MAAM,GAAG,IAAA,iBAAS,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,UAAU;SACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC;SACrC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,IAAA,sBAAc,EAAC,IAAA,iBAAS,EAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;SACrE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,QAAQ,CAAC,EAAiB;IACjC,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,GAAG,EAAE,QAAQ,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7E,IAAI,EAAE,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpE,IAAI,EAAE,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAgB,WAAW,CAAC,MAAqB,EAAE,SAA0B;IAC3E,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1E,OAAO,CACL,gFAAgF;QAChF,mFAAmF;QACnF,wDAAwD;QACxD,mFAAmF;QACnF,mFAAmF;QACnF,kBAAkB;QAClB,yBAAyB,QAAQ,CAAC,MAAM,CAAC,MAAM;QAC/C,0CAA0C,IAAI,MAAM;QACpD,2EAA2E;QAC3E,0FAA0F;QAC1F,sFAAsF;QACtF,0DAA0D,CAC3D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,IAAsB;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC;IACjD,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC;IAE7D,qFAAqF;IACrF,qFAAqF;IACrF,sFAAsF;IACtF,sEAAsE;IACtE,IAAI,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IACvE,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC9B,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAQ,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,2HAA2H;AAC3H,KAAK,UAAU,OAAO,CACpB,OAAqB,EACrB,IAAsB,EACtB,MAAc,EACd,WAA+B,EAC/B,SAAiB;IAEjB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IACrI,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,mCAAmC;IAClD,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CACnB,QAAoB,EACpB,KAAa,EACb,MAAc,EACd,MAAc,EACd,WAA+B;IAE/B,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC5F,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC9D,OAAO;YACL,GAAG,EAAE,uCAAuC;YAC5C,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE,mBAAmB,EAAE,YAAY,EAAE;YACvG,IAAI;SACL,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,gBAAgB,GAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;QACvE,IAAI,WAAW,KAAK,SAAS;YAAE,gBAAgB,CAAC,WAAW,GAAG,WAAW,CAAC;QAC1E,OAAO;YACL,yFAAyF;YACzF,GAAG,EAAE,2DAA2D,kBAAkB,CAAC,KAAK,CAAC,wBAAwB,kBAAkB,CAAC,MAAM,CAAC,EAAE;YAC7I,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE;SACtE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC3E,IAAI,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAC9D,OAAO;QACL,GAAG,EAAE,4CAA4C;QACjD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;QAClF,IAAI;KACL,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,QAAoB,EAAE,IAAS;IAClD,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACtG,OAAO,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;QACpD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7F,OAAO;QACL,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;QACjE,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,cAAc,EAAE,GAAG,CAAC,cAAc;KACnC,CAAC;AACJ,CAAC"}

package/dist/cli-ai/index.d.ts

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

package/dist/cli-ai/index.js

@@ -0,0 +1,474 @@
+#!/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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const match_1 = require("../browser/match");
+const fixEngine_1 = require("../fixEngine");
+const ingest_1 = require("../ingest");
+const config_1 = require("../config");
+const resolver_1 = require("../ai/resolver");
+const models_1 = require("../ai/models");
+const PROVIDERS = ['anthropic', 'openai', 'google'];
+/**
+ * `ia-qa-heal-ai` — the OPTIONAL, BYOK AI add-on to the deterministic healer.
+ *
+ * A third binary (beside `ia-qa-heal` and `ia-qa-heal-mcp`) in the same package —
+ * its own command and `--help`, one install, zero drift. It is NOT a standalone
+ * tool: it consumes the page contract + the diff the deterministic engine
+ * produces, and only speaks for the rows that engine gives up on (`lost` /
+ * `ambiguous`). Everything it proposes is a SUGGESTION a human confirms — never a
+ * CI auto-fix. The deterministic `ia-qa-heal` works fully without it.
+ */
+const HELP = `ia-qa-heal-ai — optional AI add-on to the deterministic healer (BYOK)
+
+  Deterministic healing (\`ia-qa-heal\`) refuses to guess: a semantic rename it
+  cannot see ("Submit" → "Confirm order") comes back as \`lost\`. This add-on hands
+  ONLY those \`lost\`/\`ambiguous\` rows to your own LLM (BYOK) and proposes a match.
+  It is a SUGGESTION, confirmed by you — never a CI gate. Most useful right after
+  \`ia-qa-heal diff\`.
+
+  Setup — the easy way: run \`ia-qa-heal-ai init\` and pick your provider + model from
+  a list; it writes the "ai" block to .ia-qa/config.json for you. Providers: OpenAI
+  (GPT-4/5), Anthropic (Claude), Google (Gemini) — bring your own key.
+
+Usage:
+  ia-qa-heal-ai init                            Interactive: pick provider + model → writes .ia-qa/config.json
+  ia-qa-heal-ai models                          List supported providers + models (any custom id also works)
+  ia-qa-heal-ai suggest                         Suggest for baseline/ vs mapping/ (all pages)
+  ia-qa-heal-ai suggest <before.json> <after.json> [tests…]
+                                                Suggest for one mapping pair
+  ia-qa-heal-ai suggest --dir <base-dir> <cur-dir> [tests…]
+                                                Suggest across all matching pairs
+    --apply     after review, rewrite the suggested selectors in your test files.
+                Interactive confirmation required — REFUSES without a TTY (never in CI).
+    --json      machine-readable output (no writes)
+  ia-qa-heal-ai help                            Show this help
+`;
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    switch (command) {
+        case 'init':
+            await runInit();
+            break;
+        case 'models':
+            console.log('\n' + (0, models_1.renderModelList)());
+            break;
+        case 'suggest':
+            await runSuggest(rest);
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            console.log(HELP);
+            break;
+        default:
+            console.error(`Unknown command "${command}".\n\n${HELP}`);
+            process.exit(1);
+    }
+}
+async function runInit() {
+    // The AI block is an add-on to an existing config (baseUrl + pages).
+    let config;
+    try {
+        config = (0, config_1.loadConfig)();
+    }
+    catch (e) {
+        console.error(`❌ ${e instanceof Error ? e.message : String(e)}\n\n` +
+            '   `ia-qa-heal-ai init` only adds the "ai" block to an existing config. Run `ia-qa-heal init` first.');
+        process.exitCode = 2;
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error('❌ `init` is interactive and needs a terminal. In a non-TTY, add the block by hand:\n' +
+            '     "ai": { "provider": "openai", "model": "gpt-4o-mini",\n' +
+            '             "apiKey": { "source": "env", "key": "OPENAI_API_KEY" } }\n' +
+            '   Run `ia-qa-heal-ai models` for the full list of providers and models.');
+        process.exitCode = 2;
+        return;
+    }
+    const providerAns = await (0, prompts_1.default)({
+        type: 'select',
+        name: 'provider',
+        message: 'AI provider (bring your own key)?',
+        choices: models_1.AI_PROVIDERS.map((p) => ({ title: `${p.label}  (key env: ${p.keyEnv})`, value: p.id })),
+    });
+    const provider = providerAns.provider;
+    if (!provider)
+        return void console.log('   Aborted — nothing written.');
+    const info = (0, models_1.findProvider)(provider);
+    const modelAns = await (0, prompts_1.default)({
+        type: 'select',
+        name: 'model',
+        message: `${info.label} model?`,
+        choices: [
+            ...info.models.map((m) => ({ title: `${m.id}${m.note ? `   — ${m.note}` : ''}`, value: m.id })),
+            { title: 'Custom…  (type any model id your provider accepts)', value: '__custom__' },
+        ],
+    });
+    let model = modelAns.model;
+    if (!model)
+        return void console.log('   Aborted — nothing written.');
+    if (model === '__custom__') {
+        const custom = await (0, prompts_1.default)({ type: 'text', name: 'model', message: 'Model id:' });
+        model = custom.model;
+        if (!model)
+            return void console.log('   Aborted — nothing written.');
+    }
+    const keyAns = await (0, prompts_1.default)({
+        type: 'text',
+        name: 'keyEnv',
+        message: 'Env var that will hold your API key:',
+        initial: info.keyEnv,
+    });
+    const keyEnv = keyAns.keyEnv;
+    if (!keyEnv)
+        return void console.log('   Aborted — nothing written.');
+    config.ai = { provider, model, apiKey: { source: 'env', key: keyEnv } };
+    const file = (0, config_1.saveConfig)(config);
+    console.log(`\n✅ Wrote the AI add-on config → ${rel(file)}`);
+    console.log(`   provider ${provider} · model ${model} · key from $${keyEnv} (read at runtime, never on disk)\n`);
+    console.log(`   Next:  export ${keyEnv}=…   then   ia-qa-heal diff   and   ia-qa-heal-ai suggest\n`);
+}
+async function runSuggest(args) {
+    const apply = args.includes('--apply');
+    const json = args.includes('--json');
+    const dirMode = args.includes('--dir');
+    const rest = args.filter((a) => !a.startsWith('--'));
+    const opts = await resolveAiOptions();
+    if (!opts)
+        return; // resolveAiOptions already printed guidance + set exit code
+    const { pairs, testPaths } = collectPairs(rest, dirMode);
+    if (pairs.length === 0) {
+        // collectPairs printed the reason + set the exit code
+        return;
+    }
+    if (!json) {
+        console.log(`\n🤖 ia-qa-heal-ai — AI suggestions for what deterministic healing gave up on`);
+        console.log(`   provider ${opts.provider} · model ${opts.model} · confidence ≥ ${opts.minConfidence}\n`);
+    }
+    const suggestions = [];
+    const unresolved = [];
+    for (const { name, before, after } of pairs) {
+        const report = (0, match_1.diffMappings)(before, after);
+        const targets = report.rows.filter((r) => r.status === 'lost' || r.status === 'ambiguous');
+        for (const row of targets) {
+            const target = {
+                role: row.role,
+                name: row.name,
+                selector: row.selector,
+                context: row.context,
+                hint: row.hint,
+            };
+            if (!json)
+                process.stderr.write(`   … asking about ${label(target)} on ${name}\n`);
+            const resolution = await (0, resolver_1.aiResolve)(target, after.elements, opts);
+            if (resolution) {
+                suggestions.push({ page: name, target, status: row.status, reboundTo: row.reboundTo, resolution });
+            }
+            else {
+                unresolved.push({ page: name, target, status: row.status });
+            }
+        }
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            suggestions: suggestions.map((s) => ({
+                page: s.page,
+                status: s.status,
+                role: s.target.role,
+                name: s.target.name,
+                selector: s.target.selector,
+                suggested_selector: s.resolution.selector,
+                suggested_name: s.resolution.candidate.name,
+                confidence: s.resolution.confidence,
+                rationale: s.resolution.rationale,
+                rebound_to: s.reboundTo,
+            })),
+            unresolved: unresolved.map((u) => ({ page: u.page, status: u.status, role: u.target.role, name: u.target.name, selector: u.target.selector })),
+        }, null, 2));
+        process.exitCode = 0;
+        return;
+    }
+    printSuggestions(suggestions, unresolved);
+    if (!apply) {
+        if (suggestions.length > 0) {
+            console.log('   Review the above. Re-run with --apply to rewrite the accepted ones in your tests (interactive).\n');
+        }
+        process.exitCode = 0;
+        return;
+    }
+    await runApply(suggestions, testPaths);
+}
+/**
+ * Build the resolver options from `.ia-qa/config.json`'s optional `ai` block,
+ * resolving the BYOK key at runtime (never read from disk). Returns null and sets
+ * the exit code with guidance when the block or the key is missing.
+ */
+async function resolveAiOptions() {
+    let ai;
+    try {
+        ai = (0, config_1.loadConfig)().ai;
+    }
+    catch (e) {
+        console.error(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 2;
+        return null;
+    }
+    if (!ai) {
+        console.error('❌ No "ai" block in .ia-qa/config.json — this add-on is opt-in.\n\n' +
+            '   Add one (the key is a SecretRef, resolved at runtime, never written to disk):\n' +
+            '     "ai": { "provider": "anthropic", "model": "claude-...",\n' +
+            '             "apiKey": { "source": "env", "key": "ANTHROPIC_API_KEY" } }\n\n' +
+            '   The deterministic `ia-qa-heal` works fully without this.');
+        process.exitCode = 2;
+        return null;
+    }
+    if (!PROVIDERS.includes(ai.provider)) {
+        console.error(`❌ Unknown ai.provider "${ai.provider}". Use one of: ${PROVIDERS.join(', ')}.\n` +
+            '   Run `ia-qa-heal-ai init` to pick from a list, or `ia-qa-heal-ai models` to see them.');
+        process.exitCode = 2;
+        return null;
+    }
+    let apiKey;
+    try {
+        // Same SecretRef resolution as every other secret in the package: value pulled
+        // from env / aws-ssm at runtime, never read from disk (invariant 7).
+        apiKey = await (0, config_1.resolveSecret)(ai.apiKey);
+    }
+    catch (e) {
+        console.error(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 2;
+        return null;
+    }
+    const minConfidence = ai.minConfidence ?? 0.7;
+    return { provider: ai.provider, model: ai.model, apiKey, minConfidence };
+}
+/**
+ * Resolve the CLI positionals into a list of before/after mapping pairs + the test
+ * paths for `--apply`. Mirrors `ia-qa-heal fix`'s shapes so the two feel like one
+ * tool: no args → baseline/ vs mapping/ (every page); two files → one pair;
+ * `--dir a b` → every matching filename in the two dirs.
+ */
+function collectPairs(rest, dirMode) {
+    if (dirMode) {
+        const [baseDir, curDir, ...given] = rest;
+        if (!baseDir || !curDir) {
+            console.error('Usage: ia-qa-heal-ai suggest --dir <baseline-dir> <current-dir> [tests…]');
+            process.exitCode = 2;
+            return { pairs: [], testPaths: [] };
+        }
+        return { pairs: pairDirs(baseDir, curDir), testPaths: given.length > 0 ? given : defaultTestPaths() };
+    }
+    if (rest.length === 0) {
+        const base = (0, config_1.baselineDir)();
+        if (!fs.existsSync(base)) {
+            console.error(`❌ No baseline at ${rel(base)} to compare against. Run \`ia-qa-heal map\` then \`ia-qa-heal baseline\` first,\n` +
+                `   or pass two mapping files: ia-qa-heal-ai suggest <before.json> <after.json>`);
+            process.exitCode = 2;
+            return { pairs: [], testPaths: [] };
+        }
+        return { pairs: pairDirs(base, (0, config_1.mappingDir)()), testPaths: defaultTestPaths() };
+    }
+    const [beforeFile, afterFile, ...given] = rest;
+    if (!beforeFile || !afterFile) {
+        console.error('Usage: ia-qa-heal-ai suggest <before.json> <after.json> [tests…]');
+        process.exitCode = 2;
+        return { pairs: [], testPaths: [] };
+    }
+    const before = readMapping(beforeFile);
+    const after = readMapping(afterFile);
+    const name = path.basename(afterFile).replace(/\.json$/, '');
+    return { pairs: [{ name, before, after }], testPaths: given.length > 0 ? given : defaultTestPaths() };
+}
+/** Pair mapping files by filename across two directories (pages only; layouts skipped — nameless drift is not the AI's job). */
+function pairDirs(baseDir, curDir) {
+    if (!fs.existsSync(baseDir) || !fs.statSync(baseDir).isDirectory()) {
+        console.error(`❌ "${baseDir}" is not a directory.`);
+        process.exitCode = 2;
+        return [];
+    }
+    if (!fs.existsSync(curDir) || !fs.statSync(curDir).isDirectory()) {
+        console.error(`❌ "${curDir}" is not a directory.`);
+        process.exitCode = 2;
+        return [];
+    }
+    const pairs = [];
+    const files = fs.readdirSync(baseDir).filter((f) => f.endsWith('.json') && !f.startsWith('.') && !f.startsWith('_'));
+    for (const file of files) {
+        const curFile = path.join(curDir, file);
+        if (!fs.existsSync(curFile))
+            continue;
+        try {
+            pairs.push({
+                name: file.replace(/\.json$/, ''),
+                before: readMapping(path.join(baseDir, file)),
+                after: readMapping(curFile),
+            });
+        }
+        catch (e) {
+            console.error(`⚠ Skipping ${file}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return pairs;
+}
+async function runApply(suggestions, testPaths) {
+    if (suggestions.length === 0) {
+        console.log('   Nothing to apply — no confident suggestion.\n');
+        process.exitCode = 0;
+        return;
+    }
+    // Invariant: an AI suggestion is only ever written after a human says yes, at a
+    // real terminal. No TTY ⇒ this is CI or a pipe ⇒ refuse. This is what keeps the
+    // AI out of the gate.
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error('\n❌ --apply needs an interactive terminal to confirm each rewrite — refusing in a non-TTY\n' +
+            '   (CI/pipe). An AI suggestion must never be applied unattended. Run it locally, or use the\n' +
+            '   deterministic `ia-qa-heal fix` in CI.');
+        process.exitCode = 2;
+        return;
+    }
+    if (testPaths.length === 0) {
+        console.error('\n❌ No test paths to rewrite. Pass them after the mappings, or run `ia-qa-heal ingest` first.');
+        process.exitCode = 2;
+        return;
+    }
+    const { go } = await (0, prompts_1.default)({
+        type: 'confirm',
+        name: 'go',
+        message: `Apply ${suggestions.length} AI suggestion${suggestions.length === 1 ? '' : 's'} to your test files? (review above)`,
+        initial: false,
+    });
+    if (!go) {
+        console.log('   Aborted — nothing written.\n');
+        process.exitCode = 0;
+        return;
+    }
+    const rewrites = new Map();
+    for (const s of suggestions) {
+        if (s.resolution.selector !== s.target.selector && !rewrites.has(s.target.selector)) {
+            rewrites.set(s.target.selector, s.resolution.selector);
+        }
+    }
+    const files = (0, fixEngine_1.collectFiles)(testPaths, (p) => console.error(`⚠ Skipping "${p}" — not found.`));
+    if (files.length === 0) {
+        console.error(`No test files found under: ${testPaths.join(', ')}`);
+        process.exitCode = 2;
+        return;
+    }
+    const result = (0, fixEngine_1.applyRewrites)(files, rewrites, false);
+    for (const edit of result.edits) {
+        console.log(`   ✎ edited  ${path.relative(process.cwd(), edit.file)}`);
+        for (const r of edit.replacements) {
+            const lines = r.lines && r.lines.length > 0 ? `  (line${r.lines.length === 1 ? '' : 's'} ${r.lines.join(', ')})` : '';
+            console.log(`               ${r.count}× ${r.from} → ${r.to}${lines}`);
+        }
+    }
+    console.log(`\n   Applied ${result.totalReplacements} replacement${result.totalReplacements === 1 ? '' : 's'} in ${result.edits.length} file${result.edits.length === 1 ? '' : 's'}.`);
+    console.log('   These are AI suggestions — review with `git diff` before you commit. Nothing was committed.\n');
+    process.exitCode = 0;
+}
+function printSuggestions(suggestions, unresolved) {
+    if (suggestions.length === 0 && unresolved.length === 0) {
+        console.log('   ✅ Nothing for the AI to do — deterministic healing left no lost/ambiguous rows.\n');
+        return;
+    }
+    for (const s of suggestions) {
+        const pct = Math.round(s.resolution.confidence * 100);
+        console.log(`   💡 ${s.status.padEnd(9)} ${label(s.target)}  (${s.page})`);
+        console.log(`               ${s.target.selector}  →  ${s.resolution.selector}`);
+        console.log(`               proposes ${s.resolution.candidate.role} "${s.resolution.candidate.name}"  ·  confidence ${pct}%`);
+        console.log(`               ↳ ${s.resolution.rationale}`);
+        if (s.reboundTo) {
+            console.log(`               ⚠️  the old selector currently resolves onto "${s.reboundTo}" — green today, clicking the wrong element.`);
+        }
+        console.log('');
+    }
+    for (const u of unresolved) {
+        console.log(`   🚫 ${u.status.padEnd(9)} ${label(u.target)}  (${u.page})  ·  no confident AI match — stays for a human.`);
+    }
+    if (unresolved.length > 0)
+        console.log('');
+}
+function label(el) {
+    if (el.name)
+        return `${el.role} "${el.name}"`;
+    if (el.hint)
+        return `${el.role} ⋯${el.hint}`;
+    return `${el.role} "(no name)"`;
+}
+function defaultTestPaths() {
+    const usage = (0, ingest_1.loadUsage)();
+    if (!usage)
+        return [];
+    return (0, ingest_1.usageFiles)(usage);
+}
+function rel(p) {
+    return path.relative(process.cwd(), p) || p;
+}
+function readMapping(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        console.error(`❌ Cannot read "${file}".`);
+        process.exit(2);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(`❌ "${file}" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(2);
+    }
+    if (!parsed || !Array.isArray(parsed.elements)) {
+        console.error(`❌ "${file}" has no "elements" array — is it a mapping file?`);
+        process.exit(2);
+    }
+    return parsed;
+}
+main().catch((err) => {
+    console.error(`\n❌ ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map