@hover-dev/core 0.16.0 → 0.18.0

package/dist/memory/businessMemory.js

@@ -0,0 +1,125 @@
+/**
+ * Business memory — the per-app knowledge QA / API modes accumulate so they stop
+ * re-asking the same business questions every run. Lives at `<devRoot>/.hover/
+ * memory/`, mirroring Claude's own memory layout (an index + one fact per file):
+ *
+ *   .hover/memory/
+ *     MEMORY.md        ← index: one `- [title](file.md) — hook` line per fact
+ *     checkout-tax.md  ← frontmatter (name / description / type) + the fact body
+ *     ...
+ *
+ * Loop: load at run start → inject as agent context ("Known business rules…");
+ * after the user answers a business clarification (trigger-B, a later QA stage),
+ * write the learned fact. The more an app is tested, the fewer popups — see the
+ * QA-tester-mode design + project-moat-strategy.
+ *
+ * CONTRACT: business RULES only, NEVER secrets / PII / credentials (extends the
+ * standing "never read env / secrets" rule). Writes are best-effort — a memory
+ * failure must NEVER break a run (same rule as the session ledger). Used by QA +
+ * API modes only; Flow / Pentest don't read or write it.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hoverDir } from '../specs/sidecar.js';
+export function memoryDir(devRoot) {
+    return join(hoverDir(devRoot), 'memory');
+}
+/** kebab-case a title into a safe filename stem. */
+export function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'fact';
+}
+/** Parse a fact file's `---` frontmatter + body. Minimal + total — a malformed
+ *  file yields nulls and is skipped by the caller. Only the three known keys are
+ *  read; everything after the closing `---` is the body. */
+function parseFact(slug, raw) {
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!m)
+        return null;
+    const fm = m[1];
+    const body = m[2].trim();
+    const field = (k) => {
+        const f = fm.match(new RegExp(`^${k}\\s*:\\s*(.+)$`, 'm'));
+        return f ? f[1].trim().replace(/^["']|["']$/g, '') : '';
+    };
+    const description = field('description');
+    const rawType = field('type');
+    const types = ['business-rule', 'expected-behavior', 'validation', 'access-policy'];
+    const type = types.includes(rawType) ? rawType : 'business-rule';
+    if (!body)
+        return null;
+    return { name: field('name') || slug, description, type, body };
+}
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export async function loadMemory(devRoot) {
+    try {
+        const dir = memoryDir(devRoot);
+        const entries = (await readdir(dir)).filter((e) => e.endsWith('.md') && e.toLowerCase() !== 'memory.md');
+        const facts = [];
+        for (const entry of entries.sort()) {
+            try {
+                const raw = await readFile(join(dir, entry), 'utf-8');
+                const fact = parseFact(entry.replace(/\.md$/, ''), raw);
+                if (fact)
+                    facts.push(fact);
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+        return facts;
+    }
+    catch {
+        return [];
+    }
+}
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export function formatMemoryForPrompt(facts) {
+    if (!facts.length)
+        return '';
+    const lines = facts.map((f) => `- ${f.description ? f.description + ' — ' : ''}${f.body.replace(/\s+/g, ' ').trim()}`);
+    return ('KNOWN BUSINESS KNOWLEDGE FOR THIS APP (learned from earlier runs — treat as ' +
+        'ground truth; do NOT re-ask what these already answer):\n' +
+        lines.join('\n'));
+}
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export async function writeFact(devRoot, fact) {
+    try {
+        const dir = memoryDir(devRoot);
+        await mkdir(dir, { recursive: true });
+        const slug = slugify(fact.name);
+        const file = `${slug}.md`;
+        const content = `---\nname: ${slug}\ndescription: ${fact.description}\ntype: ${fact.type}\n---\n\n${fact.body.trim()}\n`;
+        await writeFile(join(dir, file), content, 'utf-8');
+        await upsertIndex(dir, slug, fact);
+        return { path: join(dir, file) };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Add/replace this fact's line in MEMORY.md (`- [title](file.md) — hook`),
+ *  keyed by the file link so re-writing a fact updates rather than duplicates. */
+async function upsertIndex(dir, slug, fact) {
+    const indexPath = join(dir, 'MEMORY.md');
+    const link = `(${slug}.md)`;
+    const line = `- [${fact.name}](${slug}.md) — ${fact.description || fact.type}`;
+    let existing = '';
+    try {
+        existing = await readFile(indexPath, 'utf-8');
+    }
+    catch {
+        existing = '# Business memory\n\nWhat Hover has learned about this app. One fact per file.\n';
+    }
+    const kept = existing
+        .split('\n')
+        .filter((l) => !(l.startsWith('- [') && l.includes(link)));
+    await writeFile(indexPath, `${kept.join('\n').replace(/\n+$/, '')}\n${line}\n`, 'utf-8');
+}

package/dist/playwright/launchChrome.d.ts

@@ -21,6 +21,17 @@ export interface LaunchOptions {
         /** Base64 SHA-256 of the MITM CA's SubjectPublicKeyInfo. */
         spki: string;
     };
+    /** Launch Chrome headless (`--headless=new`) — no visible window. Still
+     *  CDP-drivable and still uses the persistent profile, so login state set in
+     *  a prior headed launch carries over. Used by the VSCode extension's silent
+     *  mode. Default false (visible window). */
+    headless?: boolean;
+    /** Close any existing debug Chrome on this port FIRST, then launch fresh.
+     *  The plain launch is idempotent (returns the running instance), so it can't
+     *  switch headless↔visible or recover a window that's there-but-not-showing —
+     *  `force` makes the headless/visible toggle and the "reopen browser" action
+     *  actually relaunch. Default false. */
+    force?: boolean;
 }
 export type LaunchResult = {
     ok: true;
@@ -32,6 +43,13 @@ export type LaunchResult = {
     reason: string;
 };
 export declare function findChromeBinary(): string | null;
+/**
+ * Close a debug Chrome on `port` by sending CDP `Browser.close` over its
+ * DevTools WebSocket (from /json/version). Works without a child-process handle
+ * — Hover spawns Chrome detached — so it's the only way to relaunch in a
+ * different mode. Resolves once closed (or the timeout lapses); never throws.
+ */
+export declare function closeDebugChrome(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Start (or detect) a debug Chrome listening on the given CDP port. Detaches
  * the child process so the calling script can exit cleanly while Chrome keeps

package/dist/playwright/launchChrome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launchChrome.d.ts","sourceRoot":"","sources":["../../src/playwright/launchChrome.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;wEAKoE;IACpE,KAAK,CAAC,EAAE;QACN,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlC,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CA0ChD;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8DvF"}
+{"version":3,"file":"launchChrome.d.ts","sourceRoot":"","sources":["../../src/playwright/launchChrome.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;wEAKoE;IACpE,KAAK,CAAC,EAAE;QACN,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;gDAG4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;4CAIwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlC,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CA0ChD;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBvF;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuEvF"}

package/dist/playwright/launchChrome.js

@@ -1,9 +1,8 @@
 /**
  * Cross-platform launcher for an isolated debug Chrome on a known CDP port.
  *
- * Idempotent — if the port already responds, returns immediately. Used by:
- *   - `pnpm smoke:chrome` (monorepo) via src/scripts/start-chrome.ts
- *   - `pnpm exec hover-chrome` (npm consumers) via vite-plugin-hover's bin
+ * Idempotent — if the port already responds, returns immediately. The VS Code
+ * extension calls this on demand (first ✨ click) to bring up the debug Chrome.
  *
  * The user-data-dir is isolated under tmpdir so we never touch the user's
  * primary Chrome profile.
@@ -12,6 +11,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, unlinkSync } from 'node:fs';
 import { platform, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { WebSocket } from 'ws';
 const DEFAULT_PORT = 9222;
 const DEFAULT_READY_TIMEOUT_MS = 9000;
 const DEFAULT_POLL_MS = 300;
@@ -53,6 +53,39 @@ export function findChromeBinary() {
     }
     return null;
 }
+/**
+ * Close a debug Chrome on `port` by sending CDP `Browser.close` over its
+ * DevTools WebSocket (from /json/version). Works without a child-process handle
+ * — Hover spawns Chrome detached — so it's the only way to relaunch in a
+ * different mode. Resolves once closed (or the timeout lapses); never throws.
+ */
+export async function closeDebugChrome(port, timeoutMs = 4000) {
+    let wsUrl;
+    try {
+        const res = await fetch(`http://localhost:${port}/json/version`, { signal: AbortSignal.timeout(1500) });
+        if (!res.ok)
+            return false;
+        wsUrl = (await res.json()).webSocketDebuggerUrl ?? '';
+    }
+    catch {
+        return false;
+    }
+    if (!wsUrl)
+        return false;
+    return await new Promise((resolve) => {
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; try {
+            sock.close();
+        }
+        catch { /* ignore */ } resolve(ok); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        const sock = new WebSocket(wsUrl);
+        sock.on('open', () => sock.send(JSON.stringify({ id: 1, method: 'Browser.close' })));
+        sock.on('message', () => { clearTimeout(timer); finish(true); });
+        sock.on('error', () => { clearTimeout(timer); finish(false); });
+    });
+}
 async function isCdpAlive(port) {
     try {
         const res = await fetch(`http://localhost:${port}/json/version`, {
@@ -95,6 +128,14 @@ export async function launchDebugChrome(opts = {}) {
     const url = opts.url ?? 'about:blank';
     const readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
     const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    // force: close any existing instance first so a headless↔visible switch (or
+    // a "reopen browser" click) actually relaunches instead of no-opping.
+    if (opts.force && (await isCdpAlive(port))) {
+        await closeDebugChrome(port);
+        // Give the port a moment to free up before relaunch.
+        for (let i = 0; i < 20 && (await isCdpAlive(port)); i++)
+            await new Promise((r) => setTimeout(r, 150));
+    }
     if (await isCdpAlive(port)) {
         return { ok: true, alreadyRunning: true, userDataDir, port };
     }
@@ -112,6 +153,8 @@ export async function launchDebugChrome(opts = {}) {
         '--no-first-run',
         '--no-default-browser-check',
     ];
+    if (opts.headless)
+        args.push('--headless=new');
     if (opts.proxy) {
         args.push(`--proxy-server=127.0.0.1:${opts.proxy.port}`, `--ignore-certificate-errors-spki-list=${opts.proxy.spki}`);
     }

package/dist/qa/candidates.d.ts

@@ -0,0 +1,32 @@
+/**
+ * QA candidate-flow finalization.
+ *
+ * During a QA run the agent calls `record_candidate(name)` right after it
+ * completes a coherent flow; the hover-control MCP captures the actual grounded
+ * actuation steps since the previous marker and sends them along — so a
+ * candidate already carries its real, replayable SkillSteps (no fragile
+ * step-number citing). This module just validates + de-dupes them before they
+ * become one-click "Crystallize" cards.
+ *
+ * Pure + side-effect-free so it can be unit-tested without a live run.
+ */
+import type { SkillStep } from '../specs/specStep.js';
+/** What the agent recorded: a flow name + the real steps Hover captured for it. */
+export interface RecordedCandidate {
+    name: string;
+    description?: string;
+    steps: SkillStep[];
+}
+/** A candidate ready to crystallize. */
+export interface ResolvedCandidate {
+    name: string;
+    description?: string;
+    steps: SkillStep[];
+    stepCount: number;
+}
+/**
+ * Validate + de-dupe recorded candidates: drop ones with no name or no steps,
+ * collapse identical repeats (same name + same step count), and stamp stepCount.
+ */
+export declare function finalizeCandidates(candidates: readonly RecordedCandidate[]): ResolvedCandidate[];
+//# sourceMappingURL=candidates.d.ts.map

package/dist/qa/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../src/qa/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAahG"}

package/dist/qa/candidates.js

@@ -0,0 +1,20 @@
+/**
+ * Validate + de-dupe recorded candidates: drop ones with no name or no steps,
+ * collapse identical repeats (same name + same step count), and stamp stepCount.
+ */
+export function finalizeCandidates(candidates) {
+    const out = [];
+    const seen = new Set();
+    for (const c of candidates) {
+        const name = c.name?.trim();
+        const steps = Array.isArray(c.steps) ? c.steps.filter((s) => s && s.kind === 'step') : [];
+        if (!name || !steps.length)
+            continue;
+        const key = `${name}|${steps.length}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ name, description: c.description?.trim() || undefined, steps, stepCount: steps.length });
+    }
+    return out;
+}

package/dist/qa/intensity.d.ts

@@ -0,0 +1,33 @@
+/**
+ * QA run intensity presets — how hard a QA exploration tries, bounded by a hard
+ * STEP ceiling so "explore the whole app" can't run away on time/cost.
+ *
+ * Each preset maps to a `maxSteps` (agent turns ≈ steps). It's enforced two ways:
+ *   1. the prompt (qaBudgetDirective) tells the agent its step budget so it paces
+ *      itself and writes the findings report BEFORE running out — the graceful
+ *      path, and it works for every agent;
+ *   2. a hard `--max-turns` backstop (claude) so a misbehaving agent is still
+ *      bounded. Steps are what the user reasons in, so the budget is in steps,
+ *      not dollars.
+ * Only applies in QA mode.
+ */
+export type QaIntensity = 'quick' | 'standard' | 'deep';
+export interface QaIntensitySpec {
+    label: string;
+    /** Hard ceiling on agent turns (~steps): the prompt paces against it and
+     *  `--max-turns` enforces it as a backstop. */
+    maxSteps: number;
+    /** One-line description (with the rough step range) — used in the prompt + UI. */
+    blurb: string;
+}
+export declare const QA_INTENSITY: Record<QaIntensity, QaIntensitySpec>;
+export declare const DEFAULT_QA_INTENSITY: QaIntensity;
+/** Coerce arbitrary input (from the run payload) to a valid intensity. */
+export declare function asQaIntensity(v: unknown): QaIntensity;
+/**
+ * Prompt directive: tell the agent its STEP budget so it paces and ALWAYS wraps
+ * up with a report before the ceiling. The `--max-turns` backstop is the hard
+ * limit; this prose is what guarantees a report.
+ */
+export declare function qaBudgetDirective(intensity: QaIntensity): string;
+//# sourceMappingURL=intensity.d.ts.map

package/dist/qa/intensity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intensity.d.ts","sourceRoot":"","sources":["../../src/qa/intensity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;mDAC+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,eAAe,CAI7D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,WAAwB,CAAC;AAE5D,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,CAErD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,WAAW,GAAG,MAAM,CAWhE"}

package/dist/qa/intensity.js

@@ -0,0 +1,25 @@
+export const QA_INTENSITY = {
+    quick: { label: 'Quick', maxSteps: 45, blurb: 'a fast pass over the main flows — breadth over depth (~20–45 steps)' },
+    standard: { label: 'Standard', maxSteps: 150, blurb: 'the main flows plus key negative tests (~45–150 steps)' },
+    deep: { label: 'Deep', maxSteps: 500, blurb: 'exhaustive — every reachable control and state (~150–500 steps)' },
+};
+export const DEFAULT_QA_INTENSITY = 'standard';
+/** Coerce arbitrary input (from the run payload) to a valid intensity. */
+export function asQaIntensity(v) {
+    return v === 'quick' || v === 'deep' || v === 'standard' ? v : DEFAULT_QA_INTENSITY;
+}
+/**
+ * Prompt directive: tell the agent its STEP budget so it paces and ALWAYS wraps
+ * up with a report before the ceiling. The `--max-turns` backstop is the hard
+ * limit; this prose is what guarantees a report.
+ */
+export function qaBudgetDirective(intensity) {
+    const spec = QA_INTENSITY[intensity];
+    const wrapAt = Math.max(5, spec.maxSteps - Math.ceil(spec.maxSteps * 0.1));
+    return (`RUN BUDGET — ${spec.label}: ${spec.blurb}. You have about ${spec.maxSteps} steps ` +
+        `(tool actions) this run, enforced. Pace yourself to fit: cover the most ` +
+        `important flows FIRST. By roughly step ${wrapAt}, STOP exploring and ` +
+        `immediately WRITE YOUR FINDINGS REPORT (and record any clean candidate flows) ` +
+        `while you still can — never end a run without a report. On Quick, be decisive ` +
+        `and favour breadth; on Deep, be exhaustive.`);
+}

package/dist/qa/qaReport.d.ts

@@ -0,0 +1,19 @@
+import type { SessionFinding } from '../sessions/sessions.js';
+export interface QaReportInput {
+    prompt: string;
+    summary: string;
+    findings: SessionFinding[];
+    endedAt: string;
+    targetUrl?: string;
+}
+/** Render the report Markdown (pure — exported for testing). */
+export declare function renderQaReport(input: QaReportInput): string;
+/** Write the QA report into the run's folder as `report.md`. Each run (incl.
+ *  each phase of a two-pass run) has its own folder, so there's no name
+ *  collision. NEVER throws; returns the path or an error string. */
+export declare function writeQaReport(runDirPath: string, input: QaReportInput): Promise<{
+    path: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=qaReport.d.ts.map

package/dist/qa/qaReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qaReport.d.ts","sourceRoot":"","sources":["../../src/qa/qaReport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAkB3D;AAED;;oEAEoE;AACpE,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAS/C"}

package/dist/qa/qaReport.js

@@ -0,0 +1,50 @@
+/**
+ * QA report artifact — the durable, human-readable output of a QA Testing run.
+ *
+ * QA is report-first: a run produces findings (rendered live in the chat's
+ * Findings card via the normal parseFindings pipeline) AND this persistent
+ * Markdown report under `<devRoot>/.hover/qa-reports/<slug>.md`, mirroring
+ * pentest's report file. Latest-run-wins per prompt slug (the session ledger
+ * keeps the full history; this is the readable artifact).
+ *
+ * Best-effort by contract: a report-write failure must NEVER break a run or the
+ * ledger (same rule as the session ledger + business memory).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Render the report Markdown (pure — exported for testing). */
+export function renderQaReport(input) {
+    const { prompt, summary, findings, endedAt, targetUrl } = input;
+    const meta = [endedAt, targetUrl, `${findings.length} finding${findings.length === 1 ? '' : 's'}`]
+        .filter(Boolean)
+        .join(' · ');
+    const body = [`# QA report — ${prompt.trim()}`, '', `_${meta}_`];
+    if (summary.trim())
+        body.push('', summary.trim());
+    body.push('', '## Findings');
+    if (findings.length) {
+        for (const f of findings) {
+            const sev = (f.severity || 'note').trim();
+            const head = f.title && f.title !== f.text ? `${f.title} — ` : '';
+            body.push(`- **${sev}** — ${head}${f.text.trim()}`);
+        }
+    }
+    else {
+        body.push('_No issues found._');
+    }
+    return body.join('\n') + '\n';
+}
+/** Write the QA report into the run's folder as `report.md`. Each run (incl.
+ *  each phase of a two-pass run) has its own folder, so there's no name
+ *  collision. NEVER throws; returns the path or an error string. */
+export async function writeQaReport(runDirPath, input) {
+    try {
+        await mkdir(runDirPath, { recursive: true });
+        const path = join(runDirPath, 'report.md');
+        await writeFile(path, renderQaReport(input), 'utf-8');
+        return { path };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/sessions/sessions.d.ts

@@ -0,0 +1,125 @@
+export declare const SESSION_RECORD_VERSION = 2;
+/** One agent-reported finding (the ## Findings block), persisted so the
+ *  ledger becomes a reusable findings log — not just a run-history list.
+ *  Severity is the raw marker the agent emitted (Bug / Minor / Info / …);
+ *  readers normalise it for display. */
+export interface SessionFinding {
+    severity: string;
+    text: string;
+    /** Optional short headline (from the structured JSON findings block). */
+    title?: string;
+    /** Endpoint / method when the finding is about an API call — used to
+     *  crystallize a request-based regression later. */
+    endpoint?: string;
+    method?: string;
+}
+export interface SessionRecord {
+    /** Bumped to 2 when the reproducibility + outcome fields below were added.
+     *  Readers must tolerate v1 records (every new field is optional). */
+    version: number;
+    /** `<sanitized-startedAt>-<rand>` — the runId, generated at run start; names
+     *  the run folder `.hover/runs/<conversationId>/<id>/` and is the meta.json id. */
+    id: string;
+    /** The chat conversation this run belongs to — the folder it's grouped under,
+     *  so deleting a conversation removes all its runs. */
+    conversationId?: string;
+    startedAt: string;
+    endedAt: string;
+    /** Real wall-clock of the agent run (endedAt − startedAt in ms). The bare
+     *  timestamps can collapse to ~0 for an instant failure; this is explicit. */
+    durationMs?: number;
+    agent: string;
+    model?: string;
+    /** Active mode: null/absent = normal authoring, else 'api-test' / 'pentest'.
+     *  A pentest record is a different artifact from a normal one. */
+    mode?: string | null;
+    prompt: string;
+    outcome: 'saved' | 'completed' | 'error' | 'aborted';
+    /** Why an error/aborted run ended — engine message, preflight failure,
+     *  budget cutoff, user cancel. Makes a failed record diagnostic. */
+    errorReason?: string;
+    /** The agent's final verification prose (the Result card body), minus the
+     *  Findings block. Searchable history + context, not just the prompt. */
+    summary?: string;
+    /** Parsed ## Findings — the run's actual product output. */
+    findings?: SessionFinding[];
+    /** Per-tool call counts (browser_snapshot → 12, browser_click → 8). Explains
+     *  cost and feeds optimization targeting. */
+    toolCounts?: Record<string, number>;
+    /** What this run drove. envId/envName come from the editor's environment
+     *  store (Local vs a remote target); url is the active dev tab. The Cloud
+     *  run layer keys flakiness + scheduling off these. */
+    target?: {
+        url?: string;
+        envId?: string;
+        envName?: string;
+    };
+    /** @account labels this run logged in with — LABELS ONLY, never the
+     *  username/password (same contract as spec redaction). */
+    accountLabels?: string[];
+    /** Tag of the `.hover/screenshots/<tag>` dir this run wrote to, so the UI
+     *  can open the run's artifacts. (Distinct from `id` because the screenshot
+     *  dir is named at MCP-launch time, before the record id exists.) */
+    screenshotTag?: string;
+    /** Chaining hook (reserved for Cloud): the prior turn's session id when this
+     *  was a `--resume` follow-up, so a multi-turn conversation links as one. */
+    resumeOf?: string;
+    /** Set when the session was crystallized into a spec. */
+    specSlug?: string;
+    turns?: number;
+    costUsd?: number;
+    /** Total tokens consumed (input + output + cache) — the raw-usage counterpart
+     *  to costUsd, surfaced by the widget/dashboard for users who track tokens
+     *  rather than dollars. */
+    tokensUsed?: number;
+    stepCount: number;
+}
+/**
+ * Strip leaked function-call syntax a model sometimes emits as TEXT instead of
+ * actually invoking the tool — e.g. a final summary that ends with
+ * `call\n<invoke name="mcp__playwright__browser_wait_for">…</invoke>`. The model
+ * "writes out" the call (a known tool-calling glitch, common at end-of-turn /
+ * budget cap) and the parser renders it verbatim into the report + Done card.
+ * This keeps user-facing prose about the APP, not Hover's tooling
+ * (REPORTING_DIRECTIVE). Defensive + total: any agent can trip this.
+ */
+export declare function stripToolCallNoise(text: string): string;
+/** Markdown-forced: the agent emits a plain-markdown report (REPORTING_DIRECTIVE)
+ *  — ONE outcome line, `- ` bullets, and an optional `## Findings` section with
+ *  `- **severity** — text` items. Parse the summary + findings from that markdown
+ *  only; a stray ```json block (a non-compliant agent) is stripped, never parsed
+ *  for findings and never leaked. Pure + total — no Findings block yields none. */
+export declare function parseFindings(summary: string): {
+    summary: string;
+    findings: SessionFinding[];
+};
+/** Count tool_use steps by tool name for the `toolCounts` field. */
+export declare function tallyTools(steps: {
+    kind: string;
+    tool?: string;
+}[]): Record<string, number>;
+/** Write one session record as `<runDir>/meta.json`. The id (runId) + the
+ *  conversation are decided by the caller at run start (so screenshots + report
+ *  share the folder). NEVER throws; returns the path or an error string. */
+export declare function writeSessionRecord(devRoot: string, conversationId: string, runId: string, rec: Omit<SessionRecord, 'version' | 'id' | 'conversationId'>): Promise<{
+    path: string;
+    id: string;
+} | {
+    error: string;
+}>;
+/** List every run's meta.json across all conversations: `.hover/runs/<conv>/<run>/meta.json`.
+ *  Best-effort; returns [] if no runs yet. */
+export declare function listSessionRecords(devRoot: string): Promise<{
+    path: string;
+    rec: SessionRecord;
+}[]>;
+/**
+ * Mark the session that produced `promptText` as crystallized: find the most
+ * recent record matching the prompt that has no `specSlug` yet, set
+ * `outcome: 'saved'` + the slug. Save-as-spec arrives as a separate WS message
+ * after the run record was already written, so this is a patch, keyed on the
+ * prompt (the `user` seed step) — tolerant by design; a miss is a no-op.
+ * NEVER throws.
+ */
+export declare function markSessionSaved(devRoot: string, promptText: string, specSlug: string): Promise<void>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/sessions/sessions.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;wCAGwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;wDACoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;0EACsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB;uFACmF;IACnF,EAAE,EAAE,MAAM,CAAC;IACX;2DACuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;kFAC8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;sEACkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;IACrD;wEACoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6EACyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B;iDAC6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;2DAEuD;IACvD,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D;+DAC2D;IAC3D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;yEAEqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;+BAE2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASvD;AAED;;;;mFAImF;AACnF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,EAAE,CAAA;CAAE,CAwB9F;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3F;AAED;;4EAE4E;AAC5E,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,IAAI,GAAG,gBAAgB,CAAC,GAC5D,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAW3D;AAED;8CAC8C;AAC9C,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,aAAa,CAAA;CAAE,EAAE,CAAC,CA0BjD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef"}