@ia-qa/self-healing 1.6.6 → 1.6.8

package/dist/ui/shortcut.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A desktop shortcut that opens this project's console — `ia-qa-heal ui --shortcut`.
+ *
+ * The console already opens a browser by itself, so the only thing standing
+ * between a manual QA and their drift report is a terminal they have no reason
+ * to own. This removes it: double-click an icon, the console starts in the
+ * right project directory and the browser opens on it. No URL is ever typed,
+ * copied, or seen — which is also what keeps the session token out of the way
+ * instead of making it something a person has to handle.
+ *
+ * Nothing about the icon is cosmetic-only: an unlabelled `.cmd` on a desktop is
+ * a file people are right to be wary of double-clicking.
+ *
+ * **Per platform, and the honest limits.**
+ *
+ * - **Windows** — a real `.lnk`, which is the only shape that can carry a custom
+ *   icon. It is created by shelling out to PowerShell's `WScript.Shell` (present
+ *   on every supported Windows, and not a dependency), and it targets a `.cmd`
+ *   kept *inside* the project rather than a second file on the desktop. If
+ *   PowerShell refuses, the `.cmd` is placed on the desktop instead and the
+ *   caller says so — a working shortcut with the default icon beats none.
+ * - **Linux** — a `.desktop` entry, whose `Icon=` takes the PNG directly.
+ * - **macOS** — a `.command`, with the **system's default icon**. Setting a
+ *   custom one needs a resource fork via `Rez`/`fileicon` or Finder scripting;
+ *   both are fragile and neither is worth a silent failure. Stated, not hidden.
+ */
+export type Platform = 'win32' | 'darwin' | 'linux';
+export interface ShortcutFile {
+    file: string;
+    contents: string;
+    mode?: number;
+}
+/** A Windows `.lnk`, which cannot be written as text — see `installShortcut`. */
+export interface LnkPlan {
+    file: string;
+    target: string;
+    workingDir: string;
+    iconPath: string;
+    description: string;
+}
+export interface ShortcutPlan {
+    /** Plain-text files to write, in order. */
+    files: ShortcutFile[];
+    /** Present on Windows only. */
+    lnk?: LnkPlan;
+    /** Where the .ico has to be written for the lnk to find it. */
+    icoPath?: string;
+    /** True when this platform gets the system's default icon. */
+    defaultIconOnly?: boolean;
+}
+/**
+ * The desktop name. It carries the site because this icon sits on the desktop
+ * of every QA who uses the tool, which makes it the cheapest honest place to
+ * say where it comes from — and because "console" alone, months later, names
+ * nothing.
+ */
+export declare const SHORTCUT_NAME = "ia-qa-heal console (ia-qa.com)";
+/**
+ * What would be written, without writing it. Split out so the shape of every
+ * platform's launcher is testable on any platform — the one thing that would
+ * otherwise only ever be exercised on the maintainer's own OS.
+ */
+export declare function planShortcut(opts: {
+    platform: Platform;
+    desktop: string;
+    projectDir: string;
+    configDir: string;
+    nodePath: string;
+    cliEntry: string;
+    logoPath: string;
+    name?: string;
+}): ShortcutPlan;
+/**
+ * Create the Windows `.lnk`. PowerShell's COM shell object is the only way to
+ * write one without either a native module or hand-assembling the binary Shell
+ * Link format. Returns false rather than throwing: the caller has a working
+ * fallback and a shortcut is not worth failing a command over.
+ *
+ * Every value is passed as an environment variable, never interpolated into the
+ * script text — a project path containing a quote would otherwise end up being
+ * executed as PowerShell.
+ */
+export declare function createWindowsLnk(lnk: LnkPlan): boolean;
+/**
+ * Where the desktop is. `XDG_DESKTOP_DIR` and localized folder names exist and
+ * are not resolvable without reading user config, so a missing `Desktop` falls
+ * back to the home directory rather than guessing wrong and writing an icon
+ * nobody finds.
+ */
+export declare function desktopDir(home?: string): string;

package/dist/ui/shortcut.js

@@ -0,0 +1,176 @@
+"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.SHORTCUT_NAME = void 0;
+exports.planShortcut = planShortcut;
+exports.createWindowsLnk = createWindowsLnk;
+exports.desktopDir = desktopDir;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * The desktop name. It carries the site because this icon sits on the desktop
+ * of every QA who uses the tool, which makes it the cheapest honest place to
+ * say where it comes from — and because "console" alone, months later, names
+ * nothing.
+ */
+exports.SHORTCUT_NAME = 'ia-qa-heal console (ia-qa.com)';
+function quoteWin(s) {
+    return `"${s.replace(/"/g, '""')}"`;
+}
+function quotePosix(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * What would be written, without writing it. Split out so the shape of every
+ * platform's launcher is testable on any platform — the one thing that would
+ * otherwise only ever be exercised on the maintainer's own OS.
+ */
+function planShortcut(opts) {
+    const name = opts.name ?? exports.SHORTCUT_NAME;
+    const description = 'Open the local selector-drift console for this project — ia-qa.com';
+    if (opts.platform === 'win32') {
+        // The .cmd lives in the project, not on the desktop: the desktop gets one
+        // icon, not a launcher plus its helper.
+        const cmd = path.join(opts.configDir, 'console.cmd');
+        return {
+            files: [
+                {
+                    file: cmd,
+                    contents: `@echo off\r\n` +
+                        `title ${name}\r\n` +
+                        `cd /d ${quoteWin(opts.projectDir)}\r\n` +
+                        `echo  ia-qa-heal console  -  ia-qa.com\r\n` +
+                        `echo  Starting... your browser will open on its own.\r\n` +
+                        `echo  Close this window to stop it.\r\n` +
+                        `echo.\r\n` +
+                        `${quoteWin(opts.nodePath)} ${quoteWin(opts.cliEntry)} ui\r\n` +
+                        `if errorlevel 1 pause\r\n`,
+                },
+            ],
+            lnk: {
+                file: path.join(opts.desktop, `${name}.lnk`),
+                target: cmd,
+                workingDir: opts.projectDir,
+                iconPath: path.join(opts.configDir, 'console.ico'),
+                description,
+            },
+            icoPath: path.join(opts.configDir, 'console.ico'),
+        };
+    }
+    if (opts.platform === 'darwin') {
+        return {
+            files: [
+                {
+                    file: path.join(opts.desktop, `${name}.command`),
+                    contents: `#!/bin/sh\n` +
+                        `# ${description}\n` +
+                        `cd ${quotePosix(opts.projectDir)} || exit 1\n` +
+                        `echo " ia-qa-heal console  -  ia-qa.com"\n` +
+                        `echo " Starting... your browser will open on its own."\n` +
+                        `echo " Close this window to stop it."\n` +
+                        `exec ${quotePosix(opts.nodePath)} ${quotePosix(opts.cliEntry)} ui\n`,
+                    mode: 0o755,
+                },
+            ],
+            defaultIconOnly: true,
+        };
+    }
+    return {
+        files: [
+            {
+                file: path.join(opts.desktop, `${name}.desktop`),
+                contents: `[Desktop Entry]\n` +
+                    `Type=Application\n` +
+                    `Name=${name}\n` +
+                    `Comment=${description}\n` +
+                    `Icon=${opts.logoPath}\n` +
+                    `Exec=sh -c "cd ${quotePosix(opts.projectDir)} && ${quotePosix(opts.nodePath)} ${quotePosix(opts.cliEntry)} ui"\n` +
+                    `Terminal=true\n` +
+                    `Categories=Development;\n`,
+                mode: 0o755,
+            },
+        ],
+    };
+}
+/**
+ * Create the Windows `.lnk`. PowerShell's COM shell object is the only way to
+ * write one without either a native module or hand-assembling the binary Shell
+ * Link format. Returns false rather than throwing: the caller has a working
+ * fallback and a shortcut is not worth failing a command over.
+ *
+ * Every value is passed as an environment variable, never interpolated into the
+ * script text — a project path containing a quote would otherwise end up being
+ * executed as PowerShell.
+ */
+function createWindowsLnk(lnk) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { execFileSync } = require('child_process');
+    const script = '$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:IAQA_LNK); ' +
+        '$s.TargetPath = $env:IAQA_TARGET; ' +
+        '$s.WorkingDirectory = $env:IAQA_CWD; ' +
+        '$s.Description = $env:IAQA_DESC; ' +
+        'if (Test-Path $env:IAQA_ICON) { $s.IconLocation = $env:IAQA_ICON }; ' +
+        '$s.Save()';
+    try {
+        execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script], {
+            stdio: 'ignore',
+            timeout: 15000,
+            env: {
+                ...process.env,
+                IAQA_LNK: lnk.file,
+                IAQA_TARGET: lnk.target,
+                IAQA_CWD: lnk.workingDir,
+                IAQA_DESC: lnk.description,
+                IAQA_ICON: lnk.iconPath,
+            },
+        });
+        return fs.existsSync(lnk.file);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where the desktop is. `XDG_DESKTOP_DIR` and localized folder names exist and
+ * are not resolvable without reading user config, so a missing `Desktop` falls
+ * back to the home directory rather than guessing wrong and writing an icon
+ * nobody finds.
+ */
+function desktopDir(home = os.homedir()) {
+    const candidate = path.join(home, 'Desktop');
+    return fs.existsSync(candidate) ? candidate : home;
+}
+//# sourceMappingURL=shortcut.js.map

package/dist/ui/shortcut.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "Local-first self-healing for UI tests: a local MCP server + CLI that map your app's pages to a role/name/selector contract, diff selector drift (PASS/FIX/BLOCK), and apply deterministic fixes to Cypress/Playwright/Selenium tests. Runs on your machine — nothing leaves it.",
   "keywords": [
     "self-healing",
@@ -53,6 +53,7 @@
   "files": [
     "dist",
     "skills",
+    "assets",
     "README.md",
     "TUTORIAL.md",
     "ROADMAP.md"

package/skills/ia-qa-heal/SKILL.md

@@ -38,6 +38,8 @@ Where things live:
 | `.ia-qa/mapping/_layouts/` | elements shared by every page (navbar, footer) — one fix, not N |
 | `.ia-qa/usage.json` | the locators the suite actually uses (produced by `ingest`) |
 | `.ia-qa/mapping/_overview.md`, `_navigation.md`/`.svg` | app index + navigation graph |
+| `.ia-qa/history.jsonl` | one line per `diff`/`run`: verdict, counts, capture source, page coverage |
+| `.ia-qa/mapping/_shots/` | page screenshots + element positions from `map --screenshots` — artefacts, never diffed |
 
 Open a browser only when the contract *cannot* answer: the page is not mapped, or the element
 exists only in a state nothing captured (behind a tab, a modal, a mode toggle).
@@ -54,10 +56,19 @@ exists only in a state nothing captured (behind a tab, a modal, a mode toggle).
 | "give me the app's structure" | `graph --format mermaid\|svg\|json\|markdown` |
 | "apply the rewrites" | `fix` — `--dry-run` first, always |
 | "what do my tests actually use?" | `ingest` |
+| "is this getting better or worse?" | `history` (`--json`) — the trend no single run can reconstruct |
+| "gate my pipeline on it" | `diff --junit <file>` — every major CI charts the trend natively |
+| "let me look at it / decide myself" | tell the human to run `ia-qa-heal ui` — **do not run it yourself** (§4.8) |
 | first-time setup | write `.ia-qa/config.json` directly — `init` is a TTY wizard and **will refuse in your shell** |
 
 Exact flags: `ia-qa-heal <verb> --help`. Do not guess them from this file.
 
+### Machine-readable outputs
+
+`diff`, `run`, `audit`, `check` and `history` all take `--json`. Prefer it over parsing prose.
+Under `run --json`, every human line moves to stderr so stdout stays one parseable document.
+`diff --junit` / `run --junit` additionally write JUnit XML — the format a CI already knows.
+
 ## 3. Reading a verdict
 
 - **PASS** — nothing moved.
@@ -93,9 +104,25 @@ clicking the wrong thing), or a name-drift finding that is not attributable.
 7. **Renames need an inventory.** `diff` can only gate on a changed *label* if `ingest` has
    inventoried what the suite uses. No `usage.json` ⇒ no name escalation — so if their tests
    locate by `getByRole(..., { name })`, run `ingest` before trusting a PASS.
+8. **Never run `ia-qa-heal ui`.** It starts a local web console and **blocks until a human closes
+   the browser tab** — in your shell that is a hung command, not a result. It also refuses to
+   start under CI for the same reason. When the verdict is BLOCK and the human has to choose
+   between candidates, *tell them the command*; they run it. Everything the console shows is
+   available to you as JSON (`diff --json`) — the console adds pictures for a person, not data
+   for you.
+9. **Never read an empty history as "nothing drifted".** `.ia-qa/history.jsonl` is written by
+   `diff` and `run`; absent means *not recorded*, exactly like a missing `usage.json` means *not
+   measured*. And when you report a trend, repeat what it excluded: runs captured a different way
+   (a `map` baseline vs a live suite capture) are deliberately held out, because charting both
+   invents a trend out of a capture artifact. `history --json` and the `heal_history` MCP tool
+   both hand you that exclusion — pass it on rather than presenting the series as complete.
 
 ## 5. What leaves the machine
 
 Nothing, except: requests to the user's **own** `baseUrl` (`check`'s link half, `discover --crawl`
 — GET only, same origin, never a `/logout` or `/delete` URL), and `ia-qa-heal-ai` calling the
 user's own LLM if they opted in. Say that plainly rather than implying more or less.
+
+`ui` does not change that: it binds `127.0.0.1` only, is gated by a per-process token, and serves a
+page with no external asset. If asked whether it "hosts" anything, the answer is no — it is a local
+process that dies with the browser tab.