@hover-dev/core 0.16.0 → 0.17.0

package/dist/specs/replayGrounded.js

@@ -0,0 +1,155 @@
+import { chromium } from 'playwright-core';
+const ACTUATION_TOOLS = new Set(['click_control', 'fill_control', 'select_control', 'check_control', 'assert_visible']);
+const ACTION_TIMEOUT = 8000;
+function bare(tool) {
+    if (!tool)
+        return '';
+    const p = tool.split('__');
+    return p[0] === 'mcp' && p.length >= 3 ? p.slice(2).join('__') : tool;
+}
+function errLine(e) {
+    return e instanceof Error ? e.message.split('\n')[0] : String(e);
+}
+function originOf(u) {
+    try {
+        return new URL(u).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function describe(g) {
+    if (g.role && g.name)
+        return `${g.role} "${g.name}"`;
+    if (g.testId)
+        return `testId "${g.testId}"`;
+    if (g.text)
+        return `text "${g.text}"`;
+    return '(no target)';
+}
+// Mirrors mcp/actuateServer.ts `locate` — role+name → testId → text, optionally
+// scoped to a `within` container. See file header. Exported so non-extension
+// consumers (the replayer here, the standalone `hover-mcp`) share ONE grounded
+// resolver without touching the load-bearing actuateServer.
+export function groundedLocate(page, g) {
+    const base = g.within?.role && g.within?.name
+        ? page.getByRole(g.within.role, { name: g.within.name, exact: true })
+        : page;
+    if (g.role && g.name)
+        return base.getByRole(g.role, { name: g.name, exact: true });
+    if (g.testId)
+        return base.getByTestId(g.testId);
+    if (g.text)
+        return base.getByText(g.text).first();
+    return null;
+}
+/** Replay ONE grounded step on a page. Returns 'skipped' for non-actuation
+ *  steps; throws on a failed locate / action (the caller records it). */
+export async function applyGroundedStep(page, step) {
+    const tool = bare(step.tool);
+    if (!ACTUATION_TOOLS.has(tool))
+        return 'skipped';
+    const input = (step.input ?? {});
+    const loc = groundedLocate(page, input);
+    if (!loc)
+        throw new Error(`could not locate ${describe(input)}`);
+    switch (tool) {
+        case 'click_control':
+            await loc.click({ timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'fill_control':
+            await loc.fill(String(input.value ?? ''), { timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'select_control':
+            await loc.selectOption(String(input.value ?? ''), { timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'check_control':
+            if (input.checked === false)
+                await loc.uncheck({ timeout: ACTION_TIMEOUT });
+            else
+                await loc.check({ timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'assert_visible': {
+            const visible = await loc.first().isVisible();
+            if (!visible)
+                throw new Error(`${describe(input)} not visible`);
+            return 'ok';
+        }
+        default:
+            return 'skipped';
+    }
+}
+/** Replay a flow's grounded steps on a given page (injected, so it's testable
+ *  without a real browser). Navigates to `devUrl` first for a consistent start,
+ *  then runs each grounded action, stopping at the first failure. */
+export async function replayOnPage(page, devUrl, steps) {
+    const failures = [];
+    let ran = 0;
+    const total = steps.filter((s) => ACTUATION_TOOLS.has(bare(s.tool))).length;
+    try {
+        await page.goto(devUrl, { waitUntil: 'domcontentloaded', timeout: 15000 });
+    }
+    catch {
+        // SPA / already on the origin — replay anyway.
+    }
+    for (let i = 0; i < steps.length; i++) {
+        if (!ACTUATION_TOOLS.has(bare(steps[i].tool)))
+            continue;
+        try {
+            if ((await applyGroundedStep(page, steps[i])) === 'ok')
+                ran++;
+        }
+        catch (e) {
+            failures.push({ index: i, tool: bare(steps[i].tool), target: describe((steps[i].input ?? {})), error: errLine(e) });
+            break; // a broken step breaks the flow — stop here
+        }
+    }
+    return { ok: failures.length === 0, ran, total, failures };
+}
+/** Pick the page on the dev origin, else the foreground page. */
+async function pickPage(browser, devUrl) {
+    const wantOrigin = originOf(devUrl);
+    const pages = browser.contexts().flatMap((c) => c.pages());
+    if (pages.length === 0)
+        return null;
+    const matches = wantOrigin ? pages.filter((p) => originOf(p.url()) === wantOrigin) : [];
+    const candidates = matches.length ? matches : pages;
+    let chosen = candidates[candidates.length - 1];
+    for (const p of candidates) {
+        try {
+            if (await p.evaluate(() => document.visibilityState === 'visible')) {
+                chosen = p;
+                break;
+            }
+        }
+        catch {
+            /* busy/closed */
+        }
+    }
+    return chosen;
+}
+/** Connect to the debug Chrome over CDP and replay a flow's grounded steps. */
+export async function replayGroundedSteps(opts) {
+    let browser;
+    try {
+        browser = await chromium.connectOverCDP(opts.cdpUrl, { timeout: 5000 });
+    }
+    catch (e) {
+        return { ok: false, ran: 0, total: 0, failures: [{ index: -1, tool: 'connect', target: opts.cdpUrl, error: errLine(e) }] };
+    }
+    try {
+        const page = await pickPage(browser, opts.devUrl);
+        if (!page) {
+            return { ok: false, ran: 0, total: 0, failures: [{ index: -1, tool: 'page', target: opts.devUrl, error: 'no page on the dev origin' }] };
+        }
+        return await replayOnPage(page, opts.devUrl, opts.steps);
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* disconnect only — never kill the user's debug Chrome */
+        }
+    }
+}

package/dist/specs/runFailures.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Self-heal Stage 1 — the failure → heal-hint bridge.
+ *
+ * Playwright's JSON reporter records pass/fail but not *which locator* failed.
+ * Self-healing needs that to know what to re-locate. The locator IS in the error
+ * message (e.g. `waiting for getByRole('button', { name: 'Submit' })`), so this
+ * module parses the run JSON's failed tests and pulls out, per failure, the
+ * `getBy…` expression + the action that failed — the hint the heal session
+ * (Stage 2) drives the agent with.
+ *
+ * Pure + total: bad/partial JSON yields []. No FS, no agent — just parsing.
+ */
+export interface RunFailure {
+    /** Spec file as Playwright reports it (path or basename). */
+    specFile: string;
+    /** Test title. */
+    title: string;
+    /** First line of the error message (the human-readable failure). */
+    error: string;
+    /** The `getBy…` locator expression parsed from the error — the thing to
+     *  re-locate — or undefined if the failure wasn't a locator miss. */
+    failingLocator?: string;
+    /** The Playwright action that failed: 'click' / 'fill' / 'assert' / … */
+    failingAction?: string;
+}
+/** The `getBy…` expression in an error message, if any. */
+export declare function extractLocator(message: string): string | undefined;
+/** The failing action (click / fill / assert / …) inferred from the message. */
+export declare function extractAction(message: string): string | undefined;
+/** Parse a Playwright JSON-reporter run into its failures (with the failing
+ *  locator + action pulled from each error). Accepts the parsed object or a
+ *  JSON string; anything malformed yields []. */
+export declare function parseRunFailures(json: unknown): RunFailure[];
+//# sourceMappingURL=runFailures.d.ts.map

package/dist/specs/runFailures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runFailures.d.ts","sourceRoot":"","sources":["../../src/specs/runFailures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd;yEACqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgBD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGlE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOjE;AAoCD;;iDAEiD;AACjD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,EAAE,CAY5D"}

package/dist/specs/runFailures.js

@@ -0,0 +1,93 @@
+/**
+ * Self-heal Stage 1 — the failure → heal-hint bridge.
+ *
+ * Playwright's JSON reporter records pass/fail but not *which locator* failed.
+ * Self-healing needs that to know what to re-locate. The locator IS in the error
+ * message (e.g. `waiting for getByRole('button', { name: 'Submit' })`), so this
+ * module parses the run JSON's failed tests and pulls out, per failure, the
+ * `getBy…` expression + the action that failed — the hint the heal session
+ * (Stage 2) drives the agent with.
+ *
+ * Pure + total: bad/partial JSON yields []. No FS, no agent — just parsing.
+ */
+/** A `getBy…(...)` call with an optional `.first()/.last()/.nth()` tail. The
+ *  inner `(?:[^()]|\([^()]*\))*` tolerates one level of nested parens so
+ *  `getByRole('button', { name: 'x' })` matches whole. */
+const LOCATOR_RE = /getBy\w+\((?:[^()]|\([^()]*\))*\)(?:\.(?:first|last|nth)\([^)]*\))?/;
+/** A KNOWN Playwright interaction at the head of an error (`locator.click: …`),
+ *  restricted to real actions so a generic `Error:` / `Some:` prefix is NOT
+ *  mistaken for one. */
+const ACTION_RE = /^(?:locator\.)?(click|dblclick|fill|type|press|check|uncheck|selectOption|setInputFiles|hover|tap|focus|clear)\b/;
+const ASSERT_RE = /\b(?:toBeVisible|toHaveText|toContainText|toHaveCount|toHaveValue|toBeChecked|toBeEnabled)\b|^expect\(/;
+function firstLine(s) {
+    return (s.split('\n').find(l => l.trim()) ?? '').trim();
+}
+/** The `getBy…` expression in an error message, if any. */
+export function extractLocator(message) {
+    const m = message.match(LOCATOR_RE);
+    return m ? m[0] : undefined;
+}
+/** The failing action (click / fill / assert / …) inferred from the message. */
+export function extractAction(message) {
+    const head = firstLine(message);
+    // Assert first — an `Error: expect(...)` line leads with "Error:", which a
+    // generic action match would wrongly read as the action.
+    if (ASSERT_RE.test(head) || ASSERT_RE.test(message))
+        return 'assert';
+    const m = head.match(ACTION_RE);
+    return m ? m[1].toLowerCase() : undefined;
+}
+/** The error message of the first failed/timed-out result on a spec, if any. */
+function failedMessage(spec) {
+    for (const t of spec.tests ?? []) {
+        for (const r of t.results ?? []) {
+            if (r.status === 'failed' || r.status === 'timedOut' || r.status === 'interrupted') {
+                return r.error?.message || r.errors?.find(e => e.message)?.message || 'Test failed (no error message).';
+            }
+        }
+    }
+    return undefined;
+}
+function walk(suite, fileFallback, out) {
+    const file = suite.file || fileFallback;
+    for (const spec of suite.specs ?? []) {
+        if (spec.ok === true)
+            continue;
+        const message = failedMessage(spec);
+        if (!message)
+            continue; // not a failure (ok may be undefined but no failed result)
+        out.push({
+            specFile: spec.file || file,
+            title: spec.title || '(untitled)',
+            error: firstLine(message),
+            failingLocator: extractLocator(message),
+            failingAction: extractAction(message),
+        });
+    }
+    for (const child of suite.suites ?? [])
+        walk(child, file, out);
+}
+/** Parse a Playwright JSON-reporter run into its failures (with the failing
+ *  locator + action pulled from each error). Accepts the parsed object or a
+ *  JSON string; anything malformed yields []. */
+export function parseRunFailures(json) {
+    let root;
+    if (typeof json === 'string') {
+        try {
+            root = JSON.parse(json);
+        }
+        catch {
+            return [];
+        }
+    }
+    else if (json && typeof json === 'object') {
+        root = json;
+    }
+    else {
+        return [];
+    }
+    const out = [];
+    for (const suite of root.suites ?? [])
+        walk(suite, suite.file || '', out);
+    return out;
+}

package/dist/specs/seeds.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Translation seeds: human-written worked examples that teach the optimization
+ * pass (F7) a multi-step Playwright pattern by few-shot — NOT by deterministic
+ * match+template. A seed is a rough `signature` (tool names, used only to pick
+ * relevant seeds) + a concrete `example` (input steps → output code) the LLM
+ * generalizes from.
+ *
+ * These ship inlined as the `BUILTIN_SEEDS` constant below. They used to be
+ * JSON files under `packages/core/seeds/optimization/` plus a `.hover/rules/`
+ * "author your own seed" mechanism and a `.hover/seeds.json` opt-out — all
+ * removed: that user-facing surface added burden for a small curated catalogue
+ * that feeds an optional, manually-invoked pass. To add a pattern, append a
+ * `SeedRule` here.
+ */
 export interface SeedRule {
     /** Identifier, e.g. `download`. */
     name: string;
@@ -13,23 +27,10 @@ export interface SeedRule {
     };
 }
 /**
- * Built-in seeds ship with core and feed EVERY project's optimization pass, so
- * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
- * certain* optimization — a fixed, app-agnostic translation whose output is
- * deterministic and can't mislead (e.g. download → waitForEvent pairing).
- *
- * Deliberately NOT built-in:
- *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
- *     assert) — those are already standing instructions in buildOptimizePrompt,
- *     and a bad generalization would pollute every user's spec.
- *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
- * Project-specific or speculative patterns live in <root>/.hover/rules/, where
- * the bar is the user's own call.
+ * Built-in optimization seeds, inlined. They feed EVERY project's optimization
+ * pass (the prompt builder and the relevance filter consume this directly).
  */
 export declare const BUILTIN_SEEDS: SeedRule[];
-/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
- *  are skipped rather than failing the whole read. */
-export declare function readSeeds(projectRoot: string): Promise<SeedRule[]>;
 /** Pick seeds whose signature's base tool appears in the spec — a cheap
  *  relevance filter so the prompt only carries plausibly-applicable examples. */
 export declare function relevantSeeds(seeds: SeedRule[], specTools: Set<string>, cap?: number): SeedRule[];

package/dist/specs/seeds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/specs/seeds.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;qEACiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,EAenC,CAAC;AAEF;sDACsD;AACtD,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiBxE;AAED;iFACiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAI,GAAG,QAAQ,EAAE,CAG5F"}
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/specs/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;qEACiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,EAiFnC,CAAC;AAEF;iFACiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAI,GAAG,QAAQ,EAAE,CAG5F"}

package/dist/specs/seeds.js

@@ -1,71 +1,103 @@
 /**
- * Community translation seeds (Stage 6, approach A): human-written worked
- * examples that teach the optimization pass (F7) new patterns by few-shot,
- * NOT by deterministic match+template. A seed is a rough `signature` (tool
- * names, used only to pick relevant seeds) + a concrete `example`
- * (input steps → output code) the LLM generalizes from.
+ * Translation seeds: human-written worked examples that teach the optimization
+ * pass (F7) a multi-step Playwright pattern by few-shot — NOT by deterministic
+ * match+template. A seed is a rough `signature` (tool names, used only to pick
+ * relevant seeds) + a concrete `example` (input steps → output code) the LLM
+ * generalizes from.
  *
- * Sources: a small built-in set + the project's <projectRoot>/.hover/rules/.
- * Adding a pattern = dropping an example JSON in .hover/rules/ — no core change.
- *
- * Built-in seeds deliberately cover patterns the deterministic translator does
- * NOT hardcode (popup is already hardcoded in writeSpec, so it's not here).
+ * These ship inlined as the `BUILTIN_SEEDS` constant below. They used to be
+ * JSON files under `packages/core/seeds/optimization/` plus a `.hover/rules/`
+ * "author your own seed" mechanism and a `.hover/seeds.json` opt-out — all
+ * removed: that user-facing surface added burden for a small curated catalogue
+ * that feeds an optional, manually-invoked pass. To add a pattern, append a
+ * `SeedRule` here.
  */
-import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
 /**
- * Built-in seeds ship with core and feed EVERY project's optimization pass, so
- * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
- * certain* optimization — a fixed, app-agnostic translation whose output is
- * deterministic and can't mislead (e.g. download → waitForEvent pairing).
- *
- * Deliberately NOT built-in:
- *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
- *     assert) — those are already standing instructions in buildOptimizePrompt,
- *     and a bad generalization would pollute every user's spec.
- *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
- * Project-specific or speculative patterns live in <root>/.hover/rules/, where
- * the bar is the user's own call.
+ * Built-in optimization seeds, inlined. They feed EVERY project's optimization
+ * pass (the prompt builder and the relevance filter consume this directly).
  */
 export const BUILTIN_SEEDS = [
     {
         name: 'download',
         signature: ['browser_click'],
-        note: 'a click that triggers a file download → pair with waitForEvent("download")',
+        note: 'A click that triggers a file download — pair it with waitForEvent(\'download\') so the listener is registered before the click fires.',
         example: {
             steps: [{ tool: 'browser_click', element: 'Export CSV button' }],
-            code: "const [download] = await Promise.all([\n" +
-                "  page.waitForEvent('download'),\n" +
-                "  page.getByRole('button', { name: 'Export CSV' }).click(),\n" +
-                "]);\n" +
-                "expect(await download.suggestedFilename()).toContain('.csv');",
+            code: `const [download] = await Promise.all([
+  page.waitForEvent('download'),
+  page.getByRole('button', { name: 'Export CSV' }).click(),
+]);
+expect(await download.suggestedFilename()).toContain('.csv');`,
+        },
+    },
+    {
+        name: 'file-upload',
+        signature: ['browser_file_upload'],
+        note: 'Set a file on a (often hidden) <input type=file>. The file chooser opens synchronously on click, so register waitForEvent(\'filechooser\') before the click — same race as download.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Upload avatar button' },
+                { tool: 'browser_file_upload', paths: ['avatar.png'] },
+            ],
+            code: `const [chooser] = await Promise.all([
+  page.waitForEvent('filechooser'),
+  page.getByRole('button', { name: 'Upload avatar' }).click(),
+]);
+await chooser.setFiles('tests/fixtures/avatar.png');
+await expect(page.getByText('avatar.png')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'dialog',
+        signature: ['browser_handle_dialog'],
+        note: 'A click that triggers a native dialog (alert/confirm/prompt). Register the page \'dialog\' handler BEFORE the click that fires it — otherwise Playwright auto-dismisses it and the assertion is wrong.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Delete account button' },
+                { tool: 'browser_handle_dialog', action: 'accept' },
+            ],
+            code: `page.once('dialog', dialog => dialog.accept());
+await page.getByRole('button', { name: 'Delete account' }).click();
+await expect(page.getByText('Account deleted')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'oauth-popup',
+        signature: ['browser_click', 'browser_tabs:select'],
+        note: 'Sign in through a provider popup that opens a new tab. Pair the opener click with context.waitForEvent(\'page\'), then drive the returned popup page.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Sign in with Google button' },
+                { tool: 'browser_tabs', action: 'select', idx: 1 },
+            ],
+            code: `const [popup] = await Promise.all([
+  context.waitForEvent('page'),
+  page.getByRole('button', { name: 'Sign in with Google' }).click(),
+]);
+await popup.getByLabel('Email').fill('user@example.com');
+await popup.getByRole('button', { name: 'Next' }).click();
+await popup.waitForEvent('close');
+await expect(page.getByText('Signed in')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'network-gated-assertion',
+        signature: ['browser_click', 'browser_wait_for'],
+        note: 'A click fires an XHR/fetch and the result is asserted. Pair the click with page.waitForResponse so the test waits for the real request to settle, instead of a guessed timeout or a race.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Place order button' },
+                { tool: 'browser_wait_for', text: 'Order confirmed' },
+            ],
+            code: `const [res] = await Promise.all([
+  page.waitForResponse(r => r.url().includes('/api/orders') && r.request().method() === 'POST'),
+  page.getByRole('button', { name: 'Place order' }).click(),
+]);
+expect(res.ok()).toBeTruthy();
+await expect(page.getByText('Order confirmed')).toBeVisible();`,
         },
     },
 ];
-/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
- *  are skipped rather than failing the whole read. */
-export async function readSeeds(projectRoot) {
-    const out = [...BUILTIN_SEEDS];
-    try {
-        const dir = join(projectRoot, '.hover', 'rules');
-        for (const f of await readdir(dir)) {
-            if (!f.endsWith('.json'))
-                continue;
-            try {
-                const s = JSON.parse(await readFile(join(dir, f), 'utf-8'));
-                if (s && s.name && Array.isArray(s.signature) && s.example?.code)
-                    out.push(s);
-            }
-            catch {
-                /* skip malformed seed file */
-            }
-        }
-    }
-    catch {
-        /* no .hover/rules/ directory */
-    }
-    return out;
-}
 /** Pick seeds whose signature's base tool appears in the spec — a cheap
  *  relevance filter so the prompt only carries plausibly-applicable examples. */
 export function relevantSeeds(seeds, specTools, cap = 6) {

package/dist/specs/sidecar.d.ts

@@ -1,4 +1,4 @@
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 import type { SpecAssertion } from './writeSpec.js';
 /** Current sidecar schema version. Bump when the shape changes so readers
  *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
@@ -15,11 +15,39 @@ export interface SpecSidecar {
     /** Alt-click assertions captured alongside the session. */
     assertions: SpecAssertion[];
 }
-/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
- *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+/** Project-root `.hover/` directory — the single home for Hover-derived data
+ *  (sidecars, runs, rules, conventions). */
+export declare function hoverDir(devRoot: string): string;
+/** Sanitize an id segment for use as a directory name (conversation / run id). */
+export declare function safeSeg(s: string): string;
+/** Per-run home: `<devRoot>/.hover/conversations/<conversationId>/<runId>/`.
+ *  Everything a single agent run produces — meta.json (the ledger record),
+ *  report.md (QA), screenshots/ — lives here, grouped under its conversation so
+ *  deleting a conversation is one `rm -rf .hover/conversations/<conversationId>`.
+ *  (Distinct from `.hover/runs/`, which is the Playwright spec-run-results
+ *  ledger written by ▶ Run.) */
+export declare function conversationsDir(devRoot: string): string;
+export declare function conversationDir(devRoot: string, conversationId: string): string;
+export declare function runDir(devRoot: string, conversationId: string, runId: string): string;
+/** Sidecar directory: `<devRoot>/.hover/sidecars`. Outside `__vibe_tests__/`,
+ *  so Playwright's default `*.spec.ts` glob trivially never reaches it. */
 export declare function sidecarDir(devRoot: string): string;
-/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
- *  the data minus the stamped fields (`version`, `createdAt`), which this
- *  function fills. Returns the absolute path written. */
+/** Pre-relocation sidecar home (`__vibe_tests__/.hover/`). Read-only fallback;
+ *  nothing writes here anymore. */
+export declare function legacySidecarDir(devRoot: string): string;
+/** Write the structured-session sidecar at `.hover/sidecars/<slug>.json`.
+ *  Caller passes the data minus the stamped fields (`version`, `createdAt`),
+ *  which this function fills. Returns the absolute path written. */
 export declare function writeSidecar(devRoot: string, data: Omit<SpecSidecar, 'version' | 'createdAt'>): Promise<string>;
+/**
+ * Read one sidecar by slug, with legacy fallback + lazy copy-forward: when a
+ * sidecar only exists at the pre-relocation `__vibe_tests__/.hover/` path it
+ * is parsed from there and best-effort re-written into `.hover/sidecars/` so
+ * the next read hits the new home. Returns `null` when absent or malformed.
+ */
+export declare function readSidecar(devRoot: string, slug: string): Promise<SpecSidecar | null>;
+/** Parse one sidecar file, or `null` when absent / not JSON. Deliberately
+ *  lenient on shape (an empty `{}` still counts as "a sidecar exists") —
+ *  consumers that need `steps`/`slug` filter for themselves. */
+export declare function parseSidecarFile(path: string): Promise<SpecSidecar | null>;
 //# sourceMappingURL=sidecar.d.ts.map

package/dist/specs/sidecar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;6EAC6E;AAC7E,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB;yCACqC;IACrC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;0EAC0E;AAC1E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;yDAEyD;AACzD,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB"}
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;6EAC6E;AAC7E,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB;yCACqC;IACrC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;4CAC4C;AAC5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;gCAKgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;oEAEoE;AACpE,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB5F;AAED;;gEAEgE;AAChE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOhF"}