@ia-qa/self-healing 1.6.7 → 1.6.8

package/dist/ui/registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The list of projects this machine's console may switch between —
+ * `~/.ia-qa/projects.json`.
+ *
+ * A single console that can reach several projects is a bigger thing than one
+ * bound to a directory: its token now unlocks the contracts of *every* app in
+ * the list, and its actions can edit test files in any of them. That is a real
+ * widening, and it is contained by exactly one rule, which the rest of this
+ * file exists to enforce:
+ *
+ *   **A project is reachable only if the user opened a console in it.**
+ *
+ * Nothing scans the disk, nothing walks parent directories, nothing accepts a
+ * path from an HTTP request. The registry is append-on-launch: running
+ * `ia-qa-heal ui` in a folder is the act of consent, and `--forget` is how it is
+ * withdrawn. So the console can reach precisely the set of projects the user
+ * already had consoles for — the switcher removes the walking between them, not
+ * a boundary.
+ *
+ * Entries are verified on read: an entry whose `.ia-qa/config.json` is gone is
+ * dropped rather than offered, so a deleted or moved project cannot linger as a
+ * reachable path.
+ */
+export interface ProjectEntry {
+    /** Absolute, normalized. The identity of a project — there is no other id. */
+    dir: string;
+    /** Last known baseUrl, shown in the switcher so two localhost projects are distinguishable. */
+    baseUrl?: string;
+    lastOpened: string;
+}
+/**
+ * `IAQA_HOME` relocates the registry. It exists so the console's own tests can
+ * exercise the real code path — including the HTTP endpoint, which takes no
+ * home argument — without writing to the machine's actual project list. It is
+ * also the lever for a shared or throwaway machine.
+ */
+export declare function registryDir(home?: string): string;
+export declare function registryPath(home?: string): string;
+/** Does this directory actually hold a project? The only thing that makes one. */
+export declare function isProjectDir(dir: string): boolean;
+/**
+ * Every registered project that still exists, most recently opened first.
+ *
+ * The existence check is not tidiness — it is the second half of the allowlist.
+ * A stale entry is a path the console would otherwise still be willing to read.
+ */
+export declare function listProjects(home?: string): ProjectEntry[];
+/** Record that a console was opened here. The one act that grants reachability. */
+export declare function rememberProject(dir: string, baseUrl?: string, home?: string): void;
+/** Withdraw consent — `ia-qa-heal ui --forget [dir]`. */
+export declare function forgetProject(dir: string | null, home?: string): number;
+/**
+ * Resolve a directory the *client* asked for.
+ *
+ * This is the security boundary of the whole feature, so it is deliberately
+ * dull: the candidate must match a registered entry exactly after
+ * normalization. It never joins, never resolves relative to anything, and never
+ * falls back to "close enough" — a request cannot name a directory that is not
+ * already in the list, which makes path traversal not a thing to defend against
+ * but a thing that cannot be expressed.
+ */
+export declare function resolveRequestedProject(requested: unknown, home?: string): string | null;

package/dist/ui/registry.js

@@ -0,0 +1,139 @@
+"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.registryDir = registryDir;
+exports.registryPath = registryPath;
+exports.isProjectDir = isProjectDir;
+exports.listProjects = listProjects;
+exports.rememberProject = rememberProject;
+exports.forgetProject = forgetProject;
+exports.resolveRequestedProject = resolveRequestedProject;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+/**
+ * `IAQA_HOME` relocates the registry. It exists so the console's own tests can
+ * exercise the real code path — including the HTTP endpoint, which takes no
+ * home argument — without writing to the machine's actual project list. It is
+ * also the lever for a shared or throwaway machine.
+ */
+function registryDir(home) {
+    return path.join(home ?? process.env.IAQA_HOME ?? os.homedir(), config_1.CONFIG_DIR);
+}
+function registryPath(home) {
+    return path.join(registryDir(home), 'projects.json');
+}
+function readRaw(home) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(registryPath(home), 'utf8'));
+        return Array.isArray(parsed.projects) ? parsed.projects : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Does this directory actually hold a project? The only thing that makes one. */
+function isProjectDir(dir) {
+    try {
+        return fs.statSync(path.join(dir, config_1.CONFIG_DIR, 'config.json')).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every registered project that still exists, most recently opened first.
+ *
+ * The existence check is not tidiness — it is the second half of the allowlist.
+ * A stale entry is a path the console would otherwise still be willing to read.
+ */
+function listProjects(home) {
+    return readRaw(home)
+        .filter((p) => p && typeof p.dir === 'string' && isProjectDir(p.dir))
+        .sort((a, b) => String(b.lastOpened).localeCompare(String(a.lastOpened)));
+}
+/** Record that a console was opened here. The one act that grants reachability. */
+function rememberProject(dir, baseUrl, home) {
+    const abs = path.resolve(dir);
+    if (!isProjectDir(abs))
+        return;
+    try {
+        const others = readRaw(home).filter((p) => path.resolve(p.dir ?? '') !== abs);
+        const next = [{ dir: abs, baseUrl, lastOpened: new Date().toISOString() }, ...others];
+        fs.mkdirSync(registryDir(home), { recursive: true });
+        fs.writeFileSync(registryPath(home), JSON.stringify({ projects: next }, null, 2) + '\n', {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* an unregisterable project simply cannot be switched to; nothing else breaks */
+    }
+}
+/** Withdraw consent — `ia-qa-heal ui --forget [dir]`. */
+function forgetProject(dir, home) {
+    const before = readRaw(home);
+    const keep = dir === null ? [] : before.filter((p) => path.resolve(p.dir ?? '') !== path.resolve(dir));
+    try {
+        fs.mkdirSync(registryDir(home), { recursive: true });
+        fs.writeFileSync(registryPath(home), JSON.stringify({ projects: keep }, null, 2) + '\n', {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+    }
+    catch {
+        return 0;
+    }
+    return before.length - keep.length;
+}
+/**
+ * Resolve a directory the *client* asked for.
+ *
+ * This is the security boundary of the whole feature, so it is deliberately
+ * dull: the candidate must match a registered entry exactly after
+ * normalization. It never joins, never resolves relative to anything, and never
+ * falls back to "close enough" — a request cannot name a directory that is not
+ * already in the list, which makes path traversal not a thing to defend against
+ * but a thing that cannot be expressed.
+ */
+function resolveRequestedProject(requested, home) {
+    if (typeof requested !== 'string' || requested === '')
+        return null;
+    const want = path.resolve(requested);
+    const hit = listProjects(home).find((p) => path.resolve(p.dir) === want);
+    return hit ? path.resolve(hit.dir) : null;
+}
+//# sourceMappingURL=registry.js.map

package/dist/ui/registry.js.map

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

package/dist/ui/server.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The local console — `ia-qa-heal ui`.
+ *
+ * What it is for: the HTML report is a *read* artefact. It can now show a human
+ * which of five identical buttons the test meant, but the moment they have
+ * decided, the loop leaves the browser — back to a terminal, by hand. The
+ * console closes that: the same evidence, plus the verbs, plus the run history
+ * the CLI has no place to display.
+ *
+ * ## Why a server, and what that costs
+ *
+ * A static file cannot run `fix` and cannot re-diff after the app changed. That
+ * is the entire justification, and it is worth being explicit that a server on a
+ * QA's machine is not free. Four rules hold the line:
+ *
+ * 1. **Loopback only.** Bound to `127.0.0.1`, never `0.0.0.0` — in a container
+ *    or on a shared network the second one is a published port.
+ * 2. **A per-session token.** Without it, *any* page open in that browser could
+ *    `fetch('http://127.0.0.1:7333/api/state')` and read the contracts of the
+ *    user's authenticated app, or POST an action. The token is random per
+ *    process, required on every request, and lives only in the URL we open.
+ * 3. **Host header pinning.** A token in a URL does not stop DNS rebinding, in
+ *    which an attacker's domain resolves to 127.0.0.1 and the browser treats the
+ *    origin as theirs. Requests whose `Host` is not loopback are refused before
+ *    anything is read.
+ * 4. **No new authority.** Actions spawn this package's own CLI with a fixed
+ *    argv from an allowlist — never a string from the request. The console can
+ *    therefore do nothing the user could not do at their shell, and every
+ *    prohibition the CLI enforces (`fix` refusing an `unattributable` locator,
+ *    refusing to guess an `ambiguous` one) holds without being restated here.
+ *    A button that could bypass them would be the worst thing in this package.
+ *
+ * Nothing is uploaded, no telemetry, no external asset: the page is inline HTML,
+ * CSS and JS, and every byte it displays came off this disk. The server dies
+ * with the process.
+ */
+export interface UiOptions {
+    port?: number;
+    open?: boolean;
+    /** Stay up after the browser goes away. Off by default — see `IDLE_*` below. */
+    keepAlive?: boolean;
+}
+/** How often the page says it is still there. Must stay well under `HEARTBEAT_IDLE_MS`. */
+export declare const HEARTBEAT_INTERVAL_MS = 15000;
+export declare function actionCatalogue(): Array<{
+    id: string;
+    label: string;
+    writes: boolean;
+    means: string;
+}>;
+/**
+ * Loopback check on the `Host` header — the defence a token cannot provide.
+ * An IPv6 literal arrives bracketed (`[::1]:7333`), which is why this is not a
+ * bare `startsWith`.
+ */
+export declare function isLoopbackHost(host: string | undefined): boolean;
+export declare function setActiveProject(dir: string): void;
+export declare function getActiveProject(): string;
+export declare function startUi(opts?: UiOptions): Promise<{
+    url: string;
+    close: () => void;
+    onIdle: (fn: () => void) => void;
+}>;
+export declare function interpret(output: string, code: number): {
+    tone: string;
+    headline: string;
+};