@hover-dev/core 0.14.1 → 0.16.0

package/dist/specs/writeSpec.js

@@ -19,7 +19,26 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { humanSteps } from './humanSteps.js';
+import { humanSteps, humanStep } from './humanSteps.js';
+import { writeSidecar } from './sidecar.js';
+import { readPageObjectManifest, } from './pageObjectManifest.js';
+import { stepSignature } from './detectSharedFlows.js';
+import { slugify, firstSentence } from './text.js';
+/**
+ * Marker the deterministic translator leaves where a captured action is a real
+ * interaction but has no single-step Playwright translation (e.g. file upload,
+ * drag, a dialog handler) — a shape that needs a multi-step pattern. It is a
+ * structured signal, not a `// TODO`: the optimization pass (F7) and the
+ * "seeds could complete this — review?" suggestion grep for it, and
+ * `countOptimizableMarkers` reads it back off a saved spec.
+ */
+export const OPTIMIZABLE_MARKER = '// hover:optimizable';
+/** How many `// hover:optimizable` markers a generated spec carries. Used to
+ *  surface "this spec has an interaction the deterministic pass couldn't fully
+ *  translate — the optimization pass can complete it". */
+export function countOptimizableMarkers(source) {
+    return source.split('\n').filter(l => l.trimStart().startsWith(OPTIMIZABLE_MARKER)).length;
+}
 export class SpecExistsError extends Error {
     slug;
     path;
@@ -43,17 +62,25 @@ export async function writeSpec(opts) {
         throw new SpecExistsError(slug, path);
     }
     await mkdir(dir, { recursive: true });
-    const source = renderSpec(slug, opts.name, opts.description ?? '', opts.steps, opts.assertions ?? []);
+    // Stage 3c: if a prior extraction left a Page Object whose flow prefixes
+    // this spec, consume it (await loginPage.login(…)) instead of re-emitting
+    // the steps inline. No manifest (extraction never ran) → plain spec.
+    const manifest = await readPageObjectManifest(opts.devRoot);
+    const match = manifest ? matchPageObject(opts.steps, manifest) : null;
+    const source = renderSpec(slug, opts.name, opts.description ?? '', opts.steps, opts.assertions ?? [], match);
     await writeFile(path, source, 'utf-8');
+    // Persist the structured session next to the spec so cross-session
+    // extraction (F4) and the optimization pass (F7) read real SpecStep[]
+    // instead of parsing the generated code. Lands in .hover/, which
+    // Playwright's *.spec.ts glob never collects.
+    await writeSidecar(opts.devRoot, {
+        slug,
+        name: opts.name,
+        steps: opts.steps,
+        assertions: opts.assertions ?? [],
+    });
     return { path, slug };
 }
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 // Escape sequences that would prematurely terminate the JSDoc block.
 // (Backtick literal of close-comment sequence omitted on purpose — see how
 // the regex below is built — to avoid recursively poisoning *this* file.)
@@ -75,12 +102,11 @@ function collectExpected(assertions, doneSummary) {
     }
     if (doneSummary && doneSummary.trim()) {
         // Take the first sentence only — agents sometimes ramble.
-        const first = doneSummary.split(/(?<=[.!?])\s+/)[0] ?? doneSummary;
-        return [first.trim()];
+        return [firstSentence(doneSummary)];
     }
     return [];
 }
-function renderSpec(slug, displayName, description, steps, assertions) {
+function renderSpec(slug, displayName, description, steps, assertions, match) {
     const userMsg = steps.find(s => s.kind === 'user');
     const doneMsg = [...steps].reverse().find(s => s.kind === 'done');
     // Plain-English step + expected blocks for the JSDoc header. QA / PMs
@@ -89,8 +115,77 @@ function renderSpec(slug, displayName, description, steps, assertions) {
     // CSV via writeCaseCsv.
     const proseSteps = humanSteps(steps);
     const expectedLines = collectExpected(assertions, doneMsg?.summary);
+    // ── Walk the steps into the test body first, so we know whether any F6
+    //    popup pairing needs the `context` fixture before we write the
+    //    signature. Each step becomes one `test.step(...)` (Given/When/Then by
+    //    position) so Playwright's HTML report reads as named stages. ──
+    const body = [];
+    let sawInteraction = false;
+    let sigSeen = 0;
+    let emittedPageObject = false;
+    let pageVar = 'page';
+    let popupCount = 0;
+    let usesContext = false;
+    const actions = steps.filter(s => s.kind === 'step' && !!s.tool);
+    for (let i = 0; i < actions.length; i++) {
+        const s = actions[i];
+        const next = actions[i + 1];
+        // Stage 3c: fold the matched login/entry prefix into one Page Object call.
+        if (match && sigSeen < match.consumedSigs && stepSignature(s.tool, s.input) != null) {
+            sigSeen++;
+            if (!emittedPageObject) {
+                pushTestStep(body, `Given · ${match.entry.methodName}`, [`await ${match.entry.fixtureName}.${match.entry.methodName}(${match.args.join(', ')});`]);
+                emittedPageObject = true;
+                sawInteraction = true;
+            }
+            continue;
+        }
+        // F6: a click that opens a new tab, immediately followed by a tab switch →
+        // pair them into Promise.all([context.waitForEvent('page'), …click()]) and
+        // re-target subsequent steps onto the new page. No visibility prelude on
+        // the click — the open must race the waitForEvent, not await visibility.
+        if (isPopupClick(s) && next && isTabSelectNew(next)) {
+            usesContext = true;
+            popupCount += 1;
+            const newVar = popupCount === 1 ? 'newPage' : `newPage${popupCount}`;
+            const clickSel = selectorFromDescription(String(s.input.element ?? ''), pageVar);
+            pushTestStep(body, `When · ${humanStep(s.tool, s.input) ?? s.tool}`, [
+                `const [${newVar}] = await Promise.all([`,
+                `  context.waitForEvent('page'),`,
+                `  ${clickSel}.click(),`,
+                `]);`,
+            ]);
+            pageVar = newVar;
+            sawInteraction = true;
+            i++; // also consume the paired tab-switch step
+            continue;
+        }
+        // A standalone tab switch back to the original tab → re-target to `page`.
+        if (s.tool === 'browser_tabs') {
+            if (isTabSelectOriginal(s))
+                pageVar = 'page';
+            continue; // tab switches don't emit a line of their own
+        }
+        const bodyLines = translateStep(s.tool, s.input, pageVar);
+        if (bodyLines.length === 0)
+            continue; // diagnostic / non-replayable
+        const phase = !sawInteraction && s.tool === 'browser_navigate' ? 'Given' : 'When';
+        pushTestStep(body, `${phase} · ${humanStep(s.tool, s.input) ?? s.tool}`, bodyLines);
+        if (s.tool !== 'browser_navigate')
+            sawInteraction = true;
+    }
+    // Then: Alt-click assertions group under the report's final stage.
+    if (assertions.length > 0 && body.length > 0)
+        body.push('');
+    for (const a of assertions) {
+        pushTestStep(body, `Then · ${a.hint ?? 'assertion'}`, [`await ${a.code};`]);
+    }
+    // ── Assemble: import + JSDoc header + signature (widened to { context } when
+    //    a popup pairing needs it, and the page-object fixture when matched). ──
     const lines = [];
-    lines.push(`import { test, expect } from '@playwright/test';`);
+    lines.push(match
+        ? `import { test, expect } from './fixtures';`
+        : `import { test, expect } from '@playwright/test';`);
     lines.push('');
     lines.push('/**');
     lines.push(` * Generated by Hover on ${new Date().toISOString().slice(0, 10)}.`);
@@ -115,80 +210,150 @@ function renderSpec(slug, displayName, description, steps, assertions) {
     lines.push(' * so the spec survives markup changes that don\'t touch semantics.');
     lines.push(' */');
     const safeTitle = displayName.replace(/'/g, "\\'");
-    lines.push(`test('${safeTitle}', async ({ page }) => {`);
-    let hasAwait = false;
+    const params = ['page'];
+    if (usesContext)
+        params.unshift('context');
+    if (match)
+        params.push(match.entry.fixtureName);
+    lines.push(`test('${safeTitle}', async ({ ${params.join(', ')} }) => {`);
+    if (body.length === 0) {
+        lines.push('  // (no automatable steps were captured)');
+    }
+    else {
+        for (const b of body)
+            lines.push(b);
+    }
+    lines.push('});');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Push one `await test.step('<label>', async () => { … })` block (4-space
+ *  body indent) onto the assembled spec lines. */
+function pushTestStep(out, label, inner) {
+    out.push(`  await test.step(${JSON.stringify(label)}, async () => {`);
+    for (const l of inner)
+        out.push(`    ${l}`);
+    out.push(`  });`);
+}
+/** A click that may open a new tab — the opener half of an F6 popup pairing. */
+function isPopupClick(s) {
+    return s.tool === 'browser_click' || s.tool === 'browser_double_click';
+}
+/** A browser_tabs step that selects a NEW tab (idx > 0) — the switch half of an
+ *  F6 popup pairing. A select back to idx 0 is a return, not a popup open. */
+function isTabSelectNew(s) {
+    const i = (s.input ?? {});
+    return s.tool === 'browser_tabs'
+        && i.action === 'select'
+        && Number(i.idx ?? i.index ?? -1) > 0;
+}
+/** A tab switch back to the original tab (index/idx 0) → re-target to `page`. */
+function isTabSelectOriginal(s) {
+    const i = (s.input ?? {});
+    if (i.action !== 'select')
+        return false;
+    return Number(i.idx ?? i.index ?? -1) === 0;
+}
+/**
+ * Stage 3c: find the longest Page Object whose recorded signature prefix
+ * matches this spec's leading steps, so the spec can call it instead of
+ * re-emitting those steps. Returns null when nothing matches.
+ */
+function matchPageObject(steps, manifest) {
+    const sigSteps = [];
     for (const s of steps) {
         if (s.kind !== 'step' || !s.tool)
             continue;
-        const calls = translateStep(s.tool, s.input);
-        for (const c of calls) {
-            // Each emitted line gets the test-body indent (2 spaces). Lines
-            // inside an emitInteraction block carry an additional 2 spaces of
-            // relative indent embedded in the line itself, so this single
-            // 2-space prefix produces correct 4-space nesting inside `{ … }`.
-            lines.push(`  ${c}`);
-            hasAwait = true;
-        }
+        const sig = stepSignature(s.tool, s.input);
+        if (sig == null)
+            continue;
+        sigSteps.push({ sig, step: s });
     }
-    // `expect` is imported at the top of the generated file regardless of
-    // whether assertions are present — the visibility preludes emitted by
-    // translateStep depend on it for any element-targeting step. (Cheap:
-    // unused imports get tree-shaken out of any future test bundle, and
-    // Playwright's runner doesn't care.)
-    if (assertions.length > 0) {
-        if (hasAwait)
-            lines.push('');
-        lines.push('  // Assertions captured via Alt-click in the Hover widget.');
-        for (const a of assertions) {
-            if (a.hint)
-                lines.push(`  // ${a.hint}`);
-            lines.push(`  await ${a.code};`);
+    const specSigs = sigSteps.map(x => x.sig);
+    let best = null;
+    for (const p of manifest.pages) {
+        if (p.signatures.length === 0 || p.signatures.length > specSigs.length)
+            continue;
+        if (p.signatures.every((sig, i) => sig === specSigs[i])) {
+            if (!best || p.signatures.length > best.signatures.length)
+                best = p;
         }
     }
-    if (!hasAwait && assertions.length === 0) {
-        lines.push('  // (no automatable steps were captured)');
+    if (!best)
+        return null;
+    const consumed = sigSteps.slice(0, best.signatures.length).map(x => x.step);
+    return { entry: best, args: flowArgValues(consumed), consumedSigs: best.signatures.length };
+}
+/**
+ * The data values the Page Object method takes, in declaration order — the
+ * fill / type / select values from the consumed prefix steps. Mirrors the
+ * params generatePageObject lifts out, so the positions line up.
+ */
+function flowArgValues(steps) {
+    const out = [];
+    for (const s of steps) {
+        const i = (s.input ?? {});
+        switch (s.tool) {
+            case 'browser_type':
+                out.push(JSON.stringify(String(i.text ?? '')));
+                break;
+            case 'browser_select_option': {
+                const values = i.values;
+                const val = (values && values.length > 0 ? values[0] : i.value) ?? '';
+                out.push(JSON.stringify(String(val)));
+                break;
+            }
+            case 'browser_fill_form': {
+                const fields = i.fields ?? [];
+                for (const f of fields)
+                    out.push(JSON.stringify(String(f.value ?? '')));
+                break;
+            }
+            default:
+                break;
+        }
     }
-    lines.push('});');
-    lines.push('');
-    return lines.join('\n');
+    return out;
 }
-function translateStep(tool, rawInput) {
+function translateStep(tool, rawInput, pageVar = 'page') {
     const input = (rawInput ?? {});
     switch (tool) {
         case 'browser_navigate': {
             const url = String(input.url ?? '');
             const path = stripBaseUrl(url);
-            return [`await page.goto(${JSON.stringify(path)});`];
+            return [`await ${pageVar}.goto(${JSON.stringify(path)});`];
         }
         case 'browser_click':
-            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'click()');
+            return emitInteraction(selectorFromDescription(String(input.element ?? ''), pageVar), 'click()');
         case 'browser_double_click':
-            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'dblclick()');
+            return emitInteraction(selectorFromDescription(String(input.element ?? ''), pageVar), 'dblclick()');
         case 'browser_hover':
-            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'hover()');
+            return emitInteraction(selectorFromDescription(String(input.element ?? ''), pageVar), 'hover()');
         case 'browser_fill_form': {
             const fields = input.fields ?? [];
             return fields.flatMap(raw => {
                 const f = raw;
                 const value = String(f.value ?? '');
                 const target = f.name ?? f.element ?? '';
-                return emitInteraction(selectorForFormField(target, f.type), `fill(${JSON.stringify(value)})`);
+                // Each field gets its own block scope so the per-field `const el`
+                // declarations don't collide inside the step's shared test.step closure.
+                return blockScope(emitInteraction(selectorForFormField(target, f.type, pageVar), `fill(${JSON.stringify(value)})`));
             });
         }
         case 'browser_type': {
             const text = String(input.text ?? '');
             const target = String(input.element ?? '');
-            return emitInteraction(selectorFromDescription(target), `fill(${JSON.stringify(text)})`);
+            return emitInteraction(selectorFromDescription(target, pageVar), `fill(${JSON.stringify(text)})`);
         }
         case 'browser_select_option': {
             const target = String(input.element ?? '');
             const values = input.values;
             const val = (values && values.length > 0 ? values[0] : input.value) ?? '';
-            return emitInteraction(selectorFromDescription(target), `selectOption(${JSON.stringify(String(val))})`);
+            return emitInteraction(selectorFromDescription(target, pageVar), `selectOption(${JSON.stringify(String(val))})`);
         }
         case 'browser_press_key': {
             const key = String(input.key ?? '');
-            return [`await page.keyboard.press(${JSON.stringify(key)});`];
+            return [`await ${pageVar}.keyboard.press(${JSON.stringify(key)});`];
         }
         case 'browser_wait_for':
             // Skip "wait for" hints — Playwright auto-waits.
@@ -203,81 +368,83 @@ function translateStep(tool, rawInput) {
             // Diagnostic / read-only / non-replayable on a fresh playwright run.
             return [];
         default:
-            return [`// TODO: translate ${tool} (skipped — unknown tool for spec emission)`];
+            // A real action with no single-step translation. Leave a structured
+            // marker (not a TODO) so the optimization pass / seed library can
+            // complete it; the deterministic draft stays runnable around it.
+            return [`${OPTIMIZABLE_MARKER}: ${tool} — no single-step translation; the optimization pass or a .hover/rules/ seed can complete this`];
     }
 }
 /**
- * Wrap an interaction (click / dblclick / hover / fill / selectOption) in a
- * block-scoped visibility prelude. Replaces the prior one-liner emit:
+ * Emit an interaction (click / dblclick / hover / fill / selectOption) as a
+ * visibility-guarded prelude: hoist the locator to `el`, assert it's visible,
+ * then act.
  *
- *    // before
- *    await page.getByRole('button', { name: 'Submit' }).click();
- *
- *    // after
- *    {
- *      const el = page.getByRole('button', { name: 'Submit' });
- *      await expect(el).toBeVisible();
- *      await el.click();
- *    }
+ *    const el = page.getByRole('button', { name: 'Submit' });
+ *    await expect(el).toBeVisible();
+ *    await el.click();
  *
  * Why: `getByRole` is "visible OR attached" by default. A button that drifted
  * behind a closed `<details>` / kebab menu / drawer is still in the role tree,
  * so the locator stays green AND `.click()` may still fire — but the actual
- * user flow has degraded. Asserting visibility before each interaction makes
- * that drift fail loudly with "Locator expected to be visible" instead of
- * silently passing or timing out generically. Issue raised externally;
- * the fix is a 1-emit change here.
+ * user flow has degraded. Asserting visibility first makes that drift fail
+ * loudly with "Locator expected to be visible" instead of silently passing.
  *
- * Block-scoped (`{ … }`) so each step's local `el` doesn't shadow the next.
- * The 4-line shape keeps the diff readable when re-record regenerates a spec.
+ * Scoping: renderSpec wraps each step in its own `test.step(… async () => {})`,
+ * whose closure already scopes `el`, so a single interaction needs no extra
+ * braces. browser_fill_form emits several fields into one step, so it wraps
+ * each field in `blockScope(...)` to keep the per-field `el` from colliding.
  */
-function emitInteraction(selectorExpr, action) {
+export function emitInteraction(selectorExpr, action) {
     return [
-        `{`,
-        `  const el = ${selectorExpr};`,
-        `  await expect(el).toBeVisible();`,
-        `  await el.${action};`,
-        `}`,
+        `const el = ${selectorExpr};`,
+        `await expect(el).toBeVisible();`,
+        `await el.${action};`,
     ];
 }
+/** Wrap lines in a `{ … }` block scope (2-space inner indent). Used by
+ *  browser_fill_form so each field's `const el` lives in its own scope inside
+ *  the shared test.step closure. */
+export function blockScope(lines) {
+    return ['{', ...lines.map(l => `  ${l}`), '}'];
+}
 /**
  * Parse element descriptions like "Submit button" / "+1 button" / "Email
  * textbox" / "Plan radio" into `getByRole(role, { name })` selectors. The
  * trailing role keyword is the convention Playwright MCP uses.
  */
-function selectorFromDescription(desc) {
+export function selectorFromDescription(desc, pageVar = 'page') {
     const trimmed = desc.trim();
     if (!trimmed)
-        return `page.locator('body')`;
+        return `${pageVar}.locator('body')`;
     // Strip a leading "Link" / "Button" article-style prefix sometimes added
     // by the MCP, e.g. "Link \"Learn more\"". We only handle the trailing form.
     const roleMatch = trimmed.match(/^(.+?)\s+(button|link|textbox|checkbox|radio|combobox|switch|menuitem|tab|listitem|heading|dialog|cell|row|columnheader|rowheader|gridcell)$/i);
     if (roleMatch) {
         const name = roleMatch[1].replace(/^"|"$/g, '');
         const role = roleMatch[2].toLowerCase();
-        return `page.getByRole('${role}', { name: ${JSON.stringify(name)} })`;
+        return `${pageVar}.getByRole('${role}', { name: ${JSON.stringify(name)} })`;
     }
     // Quoted label, e.g. \"Submit\" — fall back to getByText.
     const quoted = trimmed.match(/^"(.+)"$/);
     if (quoted)
-        return `page.getByText(${JSON.stringify(quoted[1])})`;
-    return `page.getByText(${JSON.stringify(trimmed)})`;
+        return `${pageVar}.getByText(${JSON.stringify(quoted[1])})`;
+    return `${pageVar}.getByText(${JSON.stringify(trimmed)})`;
 }
 /**
  * Form fields from browser_fill_form have a `name` that's typically the
  * accessible name / label / aria-label. getByLabel is the right primitive.
  * Fall back to getByRole('textbox') if we have a hint.
  */
-function selectorForFormField(name, type) {
+export function selectorForFormField(name, type, pageVar = 'page') {
     const trimmed = name.trim();
     if (!trimmed)
-        return `page.locator('input')`;
+        return `${pageVar}.locator('input')`;
     if (type) {
         const role = mapInputType(type);
         if (role)
-            return `page.getByRole('${role}', { name: ${JSON.stringify(trimmed)} })`;
+            return `${pageVar}.getByRole('${role}', { name: ${JSON.stringify(trimmed)} })`;
     }
-    return `page.getByLabel(${JSON.stringify(trimmed)})`;
+    return `${pageVar}.getByLabel(${JSON.stringify(trimmed)})`;
 }
 function mapInputType(type) {
     switch (type.toLowerCase()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -49,10 +49,13 @@
     "README.md"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@playwright/mcp": "0.0.75",
     "cross-spawn": "^7.0.6",
     "playwright-core": "^1.50.0",
-    "ws": "^8.20.1"
+    "ts-morph": "^28.0.0",
+    "ws": "^8.20.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
@@ -71,7 +74,6 @@
     "smoke:chrome": "tsx src/scripts/start-chrome.ts",
     "detect": "tsx src/scripts/detect-cli.ts",
     "verify-widget": "tsx src/scripts/verify-widget.ts",
-    "verify-skill": "tsx src/scripts/verify-skill.ts",
     "verify-spec": "tsx src/scripts/verify-spec.ts",
     "ws-smoke": "tsx src/scripts/ws-smoke.ts",
     "bench-ttfb": "tsx src/scripts/bench-ttfb.ts",