@hover-dev/core 0.2.0

package/dist/specs/writeSpec.js

@@ -0,0 +1,265 @@
+/**
+ * Save a completed Hover session as a standard Playwright spec.
+ *
+ * Writes a `.spec.ts` file under `<devRoot>/__vibe_tests__/`. The generated
+ * file imports only `@playwright/test` — no Hover runtime, no agent in the
+ * loop. The dev project's playwright.config.ts is expected to set
+ * `baseURL` so the spec can use relative URLs (matches the dogfood spec).
+ *
+ * Translation strategy is deterministic, not LLM. Each `browser_*` tool call
+ * in the captured session maps to one Playwright call. Element descriptions
+ * coming back from Playwright MCP (e.g. "Submit button", "+1 button") are
+ * parsed for role + accessible name and emitted as `getByRole(role, { name })`
+ * — Hover's official preference because those selectors survive markup
+ * changes that don't touch semantics.
+ *
+ * Assertions (future "Assert This" feature) layer in via the optional
+ * `assertions` field on the input.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { humanSteps } from './humanSteps.js';
+export class SpecExistsError extends Error {
+    slug;
+    path;
+    constructor(slug, path) {
+        super(`Playwright spec "${slug}" already exists at ${path}`);
+        this.slug = slug;
+        this.path = path;
+        this.name = 'SpecExistsError';
+    }
+}
+export async function writeSpec(opts) {
+    const slug = slugify(opts.name);
+    if (!slug)
+        throw new Error('spec name must contain at least one alphanumeric character');
+    if (!opts.steps.some(s => s.kind === 'step')) {
+        throw new Error('spec must contain at least one tool step to replay');
+    }
+    const dir = join(opts.devRoot, '__vibe_tests__');
+    const path = join(dir, `${slug}.spec.ts`);
+    if (!opts.overwrite && existsSync(path)) {
+        throw new SpecExistsError(slug, path);
+    }
+    await mkdir(dir, { recursive: true });
+    const source = renderSpec(slug, opts.name, opts.description ?? '', opts.steps, opts.assertions ?? []);
+    await writeFile(path, source, 'utf-8');
+    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.)
+function jsdocEscape(s) {
+    return s.replace(/\*\//g, '*\\/');
+}
+/**
+ * Turn the captured assertions (Alt-click "Assert This") and the agent's
+ * final summary into bullet lines for the Expected: block.
+ *
+ * Assertions take priority — they're the developer's explicit "this is
+ * what success looks like". When there are none, fall back to the
+ * agent's natural-language done-summary (single first sentence) so the
+ * block still carries something readable for QA.
+ */
+function collectExpected(assertions, doneSummary) {
+    if (assertions.length > 0) {
+        return assertions.map(a => a.hint ?? a.code);
+    }
+    if (doneSummary && doneSummary.trim()) {
+        // Take the first sentence only — agents sometimes ramble.
+        const first = doneSummary.split(/(?<=[.!?])\s+/)[0] ?? doneSummary;
+        return [first.trim()];
+    }
+    return [];
+}
+function renderSpec(slug, displayName, description, steps, assertions) {
+    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
+    // can read these without grokking Playwright API; the same prose also
+    // populates the Step column when the user exports the session to Xray
+    // CSV via writeCaseCsv.
+    const proseSteps = humanSteps(steps);
+    const expectedLines = collectExpected(assertions, doneMsg?.summary);
+    const lines = [];
+    lines.push(`import { test, expect } from '@playwright/test';`);
+    lines.push('');
+    lines.push('/**');
+    lines.push(` * Generated by Hover on ${new Date().toISOString().slice(0, 10)}.`);
+    if (userMsg?.text)
+        lines.push(` * Original prompt: ${jsdocEscape(userMsg.text).slice(0, 240)}`);
+    if (doneMsg?.summary)
+        lines.push(` * Outcome: ${jsdocEscape(doneMsg.summary.split('\n')[0]).slice(0, 240)}`);
+    if (proseSteps.length > 0) {
+        lines.push(' *');
+        lines.push(' * Steps:');
+        proseSteps.forEach((s, i) => lines.push(` *   ${i + 1}. ${jsdocEscape(s)}`));
+    }
+    if (expectedLines.length > 0) {
+        lines.push(' *');
+        lines.push(' * Expected:');
+        for (const e of expectedLines)
+            lines.push(` *   • ${jsdocEscape(e)}`);
+    }
+    lines.push(' *');
+    lines.push(' * Selectors prefer getByRole / getByLabel / getByTestId — generated from');
+    lines.push(' * the agent\'s natural-language element descriptions, not raw CSS ids,');
+    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;
+    for (const s of steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        const calls = translateStep(s.tool, s.input);
+        for (const c of calls) {
+            lines.push(`  ${c}`);
+            hasAwait = true;
+        }
+    }
+    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};`);
+        }
+    }
+    if (!hasAwait && assertions.length === 0) {
+        lines.push('  // (no automatable steps were captured)');
+    }
+    lines.push('});');
+    lines.push('');
+    return lines.join('\n');
+}
+function translateStep(tool, rawInput) {
+    const input = (rawInput ?? {});
+    switch (tool) {
+        case 'browser_navigate': {
+            const url = String(input.url ?? '');
+            const path = stripBaseUrl(url);
+            return [`await page.goto(${JSON.stringify(path)});`];
+        }
+        case 'browser_click':
+            return [`await ${selectorFromDescription(String(input.element ?? ''))}.click();`];
+        case 'browser_double_click':
+            return [`await ${selectorFromDescription(String(input.element ?? ''))}.dblclick();`];
+        case 'browser_hover':
+            return [`await ${selectorFromDescription(String(input.element ?? ''))}.hover();`];
+        case 'browser_fill_form': {
+            const fields = input.fields ?? [];
+            return fields.map(raw => {
+                const f = raw;
+                const value = String(f.value ?? '');
+                const target = f.name ?? f.element ?? '';
+                return `await ${selectorForFormField(target, f.type)}.fill(${JSON.stringify(value)});`;
+            });
+        }
+        case 'browser_type': {
+            const text = String(input.text ?? '');
+            const target = String(input.element ?? '');
+            return [`await ${selectorFromDescription(target)}.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 [`await ${selectorFromDescription(target)}.selectOption(${JSON.stringify(String(val))});`];
+        }
+        case 'browser_press_key': {
+            const key = String(input.key ?? '');
+            return [`await page.keyboard.press(${JSON.stringify(key)});`];
+        }
+        case 'browser_wait_for':
+            // Skip "wait for" hints — Playwright auto-waits.
+            return [];
+        case 'browser_tabs':
+        case 'browser_snapshot':
+        case 'browser_take_screenshot':
+        case 'browser_resize':
+        case 'browser_evaluate':
+        case 'browser_console_messages':
+        case 'browser_network_requests':
+            // Diagnostic / read-only / non-replayable on a fresh playwright run.
+            return [];
+        default:
+            return [`// TODO: translate ${tool} (skipped — unknown tool for spec emission)`];
+    }
+}
+/**
+ * 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) {
+    const trimmed = desc.trim();
+    if (!trimmed)
+        return `page.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)} })`;
+    }
+    // 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)})`;
+}
+/**
+ * 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) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return `page.locator('input')`;
+    if (type) {
+        const role = mapInputType(type);
+        if (role)
+            return `page.getByRole('${role}', { name: ${JSON.stringify(trimmed)} })`;
+    }
+    return `page.getByLabel(${JSON.stringify(trimmed)})`;
+}
+function mapInputType(type) {
+    switch (type.toLowerCase()) {
+        case 'textbox':
+        case 'text':
+        case 'email':
+        case 'tel':
+        case 'url':
+        case 'search':
+        case 'password':
+        case 'number':
+            return 'textbox';
+        case 'checkbox': return 'checkbox';
+        case 'radio': return 'radio';
+        case 'combobox':
+        case 'select': return 'combobox';
+        case 'slider': return 'slider';
+        case 'switch': return 'switch';
+        default: return null;
+    }
+}
+function stripBaseUrl(url) {
+    // http://localhost:5173/checkout → /checkout, http://localhost:5173/ → /
+    if (!/^https?:\/\//.test(url))
+        return url;
+    const u = new URL(url);
+    return u.pathname + u.search + u.hash || '/';
+}

package/mcp.config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest",
+        "--cdp-endpoint", "http://localhost:9222"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@hover-dev/core",
+  "version": "0.2.0",
+  "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
+  "license": "Apache-2.0",
+  "author": "Hyperyond",
+  "homepage": "https://github.com/Hyperyond/Hover#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hyperyond/Hover.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/Hyperyond/Hover/issues",
+  "keywords": [
+    "hover",
+    "playwright",
+    "mcp",
+    "agent",
+    "browser-testing",
+    "claude"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "import": "./dist/agents/index.js"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "import": "./dist/service.js"
+    },
+    "./launch-chrome": {
+      "types": "./dist/playwright/launchChrome.d.ts",
+      "import": "./dist/playwright/launchChrome.js"
+    }
+  },
+  "files": [
+    "dist",
+    "mcp.config.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "playwright-core": "^1.50.0",
+    "ws": "^8.20.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/ws": "^8.18.1",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "smoke": "tsx src/smoke.ts",
+    "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",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hover-chrome": "dist/scripts/start-chrome.js"
+  }
+}