@hover-dev/core 0.2.0

package/dist/agents/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Local CLI Agent First — agent abstraction layer.
+ *
+ * Hover does not bundle any AI runtime. It spawns whatever coding-agent CLI the
+ * user has on PATH (`claude`, `codex`, `cursor`, `aider`, ...) and treats it as
+ * a strategy implementation behind this interface.
+ *
+ * To add a new agent: write an AgentDescriptor and register it in registry.ts.
+ */
+export type AgentProtocol = 'argv' | 'stdin' | 'acp' | 'pi-rpc';
+export type StreamFormat = 'stream-json' | 'sse' | 'plain-text' | 'json-lines';
+export declare class UnsupportedAgentProtocolError extends Error {
+    constructor(message: string);
+}
+export declare class AgentNotInstalledError extends Error {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+export interface InvokeOptions {
+    agentId: string;
+    prompt: string;
+    mcpConfig?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxBudgetUsd?: number;
+    model?: string;
+    cwd?: string;
+    sessionId?: string;
+    /** Extra text appended to the agent's system prompt (claude: via
+     *  --append-system-prompt). Used to inject session-specific context like
+     *  "the user's current Chrome tab is already on http://localhost:5173/,
+     *  don't browser_navigate there". */
+    appendSystemPrompt?: string;
+    /** Aborts the spawned child if signaled. Used to stop an orphan run when
+     *  the WebSocket caller disconnects (e.g. user reloads the dev page). */
+    signal?: AbortSignal;
+}
+/**
+ * Normalized event emitted by every agent, regardless of its native wire format.
+ * Each agent's `parseEvent` translates its own stream into these.
+ */
+export type InvokeEvent = {
+    kind: 'session_start';
+    sessionId: string;
+    model?: string;
+} | {
+    kind: 'mcp_status';
+    server: string;
+    status: string;
+} | {
+    kind: 'tool_use';
+    tool: string;
+    input: unknown;
+} | {
+    kind: 'tool_result';
+    isError?: boolean;
+    preview?: string;
+} | {
+    kind: 'text';
+    text: string;
+}
+/** Running cost / turn-count update emitted mid-session so the widget can
+ *  show a live $ counter without waiting for session_end. Claude Code's
+ *  stream-json includes `total_cost_usd` on intermediate result-ish events;
+ *  agents that don't surface running cost simply never emit this. */
+ | {
+    kind: 'usage';
+    costUsd?: number;
+    turns?: number;
+} | {
+    kind: 'session_end';
+    turns?: number;
+    costUsd?: number;
+    isError?: boolean;
+    summary?: string;
+} | {
+    kind: 'raw';
+    line: string;
+};
+export interface AgentDescriptor {
+    id: string;
+    binName: string;
+    protocol: AgentProtocol;
+    streamFormat: StreamFormat;
+    buildArgs(opts: InvokeOptions): string[];
+    parseEvent(line: string): InvokeEvent[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,OAAO,GACP,KAAK,GACL,QAAQ,CAAC;AAEb,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,KAAK,GACL,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAI5C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;yCAGqC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;6EACyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC;;;qEAGqE;GACnE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9F;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAAC;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACzC"}

package/dist/agents/types.js

@@ -0,0 +1,23 @@
+/**
+ * Local CLI Agent First — agent abstraction layer.
+ *
+ * Hover does not bundle any AI runtime. It spawns whatever coding-agent CLI the
+ * user has on PATH (`claude`, `codex`, `cursor`, `aider`, ...) and treats it as
+ * a strategy implementation behind this interface.
+ *
+ * To add a new agent: write an AgentDescriptor and register it in registry.ts.
+ */
+export class UnsupportedAgentProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsupportedAgentProtocolError';
+    }
+}
+export class AgentNotInstalledError extends Error {
+    agentId;
+    constructor(agentId) {
+        super(`Agent "${agentId}" is not installed (binary not found on PATH).`);
+        this.agentId = agentId;
+        this.name = 'AgentNotInstalledError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './agents/index.js';
+export { connectAndListTabs } from './playwright/preflight.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './agents/index.js';
+export { connectAndListTabs } from './playwright/preflight.js';

package/dist/playwright/cdpStatus.d.ts

@@ -0,0 +1,29 @@
+export type CdpState = 'same-window' | 'wrong-window' | 'no-cdp';
+export interface CdpStatusResult {
+    state: CdpState;
+    /** Tab count when state !== 'no-cdp'. */
+    tabCount?: number;
+    /** Matching tab URL inside the debug Chrome (only set for 'wrong-window'). */
+    matchingTabUrl?: string;
+    /** Browser product string from /json/version when state !== 'no-cdp'. */
+    browser?: string;
+    /** When state === 'no-cdp', the preflight reason. */
+    reason?: string;
+}
+export declare function checkCdpStatus(cdpUrl: string, pageUrl: string): Promise<CdpStatusResult>;
+/**
+ * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
+ * matching tab exists, open a new tab on the origin. Returns the URL of the
+ * tab that was focused (or opened) for logging.
+ *
+ * Uses a short-lived playwright-core connection — opens it, does the work,
+ * closes it. We don't keep a long-lived browser handle.
+ */
+export declare function focusDebugTab(cdpUrl: string, pageUrl: string): Promise<{
+    ok: true;
+    focusedUrl: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+//# sourceMappingURL=cdpStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAiC3E"}

package/dist/playwright/cdpStatus.js

@@ -0,0 +1,96 @@
+/**
+ * "Is the widget running in the debug Chrome?" — answered by comparing the
+ * widget's page origin against the CDP tab list.
+ *
+ * Three states:
+ *   - 'same-window'   widget IS in the debug Chrome; agent can drive this tab.
+ *   - 'wrong-window'  debug Chrome is up, but on a different Chrome process.
+ *                     Widget should disable itself; service can bringToFront
+ *                     the corresponding tab in the debug Chrome so the user
+ *                     can switch windows.
+ *   - 'no-cdp'        no debug Chrome at all; the widget should let the user
+ *                     trigger a launch.
+ */
+import { chromium } from 'playwright-core';
+import { preflightCDP } from './preflight.js';
+/**
+ * Parse a page URL down to its origin (protocol + host + port). We compare
+ * by origin, not full URL — the user might be on /login while the debug
+ * Chrome tab is on /, but they're the same SPA, same app, same target.
+ */
+function originOf(rawUrl) {
+    try {
+        return new URL(rawUrl).origin;
+    }
+    catch {
+        return null;
+    }
+}
+export async function checkCdpStatus(cdpUrl, pageUrl) {
+    const wantOrigin = originOf(pageUrl);
+    if (!wantOrigin) {
+        // Treat unparseable page URLs as no-cdp so the UI nudges a relaunch.
+        return { state: 'no-cdp', reason: `unparseable page URL: ${pageUrl}` };
+    }
+    const cdp = await preflightCDP(cdpUrl);
+    if (!cdp.ok) {
+        return { state: 'no-cdp', reason: cdp.reason };
+    }
+    const match = cdp.tabs.find(t => originOf(t.url) === wantOrigin);
+    if (match) {
+        return {
+            state: 'same-window',
+            tabCount: cdp.tabs.length,
+            browser: cdp.browser,
+            matchingTabUrl: match.url,
+        };
+    }
+    return {
+        state: 'wrong-window',
+        tabCount: cdp.tabs.length,
+        browser: cdp.browser,
+    };
+}
+/**
+ * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
+ * matching tab exists, open a new tab on the origin. Returns the URL of the
+ * tab that was focused (or opened) for logging.
+ *
+ * Uses a short-lived playwright-core connection — opens it, does the work,
+ * closes it. We don't keep a long-lived browser handle.
+ */
+export async function focusDebugTab(cdpUrl, pageUrl) {
+    const wantOrigin = originOf(pageUrl);
+    if (!wantOrigin) {
+        return { ok: false, reason: `unparseable page URL: ${pageUrl}` };
+    }
+    let browser;
+    try {
+        browser = await chromium.connectOverCDP(cdpUrl);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `couldn't connect to CDP at ${cdpUrl}: ${msg}` };
+    }
+    try {
+        const pages = browser.contexts().flatMap(c => c.pages());
+        const match = pages.find(p => originOf(p.url()) === wantOrigin);
+        if (match) {
+            await match.bringToFront();
+            return { ok: true, focusedUrl: match.url() };
+        }
+        // No tab on the dev origin yet — open one so the widget appears.
+        const context = browser.contexts()[0] ?? (await browser.newContext());
+        const page = await context.newPage();
+        await page.goto(pageUrl, { waitUntil: 'domcontentloaded' });
+        await page.bringToFront();
+        return { ok: true, focusedUrl: page.url() };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `bringToFront failed: ${msg}` };
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}

package/dist/playwright/launchChrome.d.ts

@@ -0,0 +1,29 @@
+export interface LaunchOptions {
+    /** CDP port to expose (default 9222). */
+    port?: number;
+    /** Isolated user-data-dir (default `<tmpdir>/hover-chrome`). */
+    userDataDir?: string;
+    /** Initial URL (default 'about:blank'). */
+    url?: string;
+    /** How long to wait for /json/version to respond (default 9000ms). */
+    readyTimeoutMs?: number;
+    /** Poll interval while waiting (default 300ms). */
+    pollMs?: number;
+}
+export type LaunchResult = {
+    ok: true;
+    alreadyRunning: boolean;
+    userDataDir: string;
+    port: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function findChromeBinary(): string | null;
+/**
+ * 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
+ * running.
+ */
+export declare function launchDebugChrome(opts?: LaunchOptions): Promise<LaunchResult>;
+//# sourceMappingURL=launchChrome.d.ts.map

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

@@ -0,0 +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;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;AA8BD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAwDvF"}

package/dist/playwright/launchChrome.js

@@ -0,0 +1,137 @@
+/**
+ * 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
+ *
+ * The user-data-dir is isolated under tmpdir so we never touch the user's
+ * primary Chrome profile.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, unlinkSync } from 'node:fs';
+import { platform, tmpdir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_PORT = 9222;
+const DEFAULT_READY_TIMEOUT_MS = 9000;
+const DEFAULT_POLL_MS = 300;
+export function findChromeBinary() {
+    const candidates = [];
+    switch (platform()) {
+        case 'darwin':
+            candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome');
+            if (process.env.HOME) {
+                candidates.push(join(process.env.HOME, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome'));
+            }
+            candidates.push('/Applications/Chromium.app/Contents/MacOS/Chromium');
+            break;
+        case 'win32': {
+            const programFiles = process.env['ProgramFiles'] ?? 'C:\\Program Files';
+            const programFilesX86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+            const localAppData = process.env['LOCALAPPDATA'];
+            candidates.push(join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+            candidates.push(join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+            if (localAppData) {
+                candidates.push(join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+            }
+            // Edge fallback (Chromium-based, supports --remote-debugging-port too)
+            candidates.push(join(programFiles, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+            candidates.push(join(programFilesX86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+            break;
+        }
+        default:
+            candidates.push('/usr/bin/google-chrome');
+            candidates.push('/usr/bin/google-chrome-stable');
+            candidates.push('/usr/bin/chromium');
+            candidates.push('/usr/bin/chromium-browser');
+            candidates.push('/snap/bin/chromium');
+            break;
+    }
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    return null;
+}
+async function isCdpAlive(port) {
+    try {
+        const res = await fetch(`http://localhost:${port}/json/version`, {
+            signal: AbortSignal.timeout(1500),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * If a previous Chrome instance crashed it can leave SingletonLock files in the
+ * user-data-dir. Stale locks prevent the next launch from binding cleanly.
+ */
+function clearStaleProfileLock(dir) {
+    for (const file of ['SingletonLock', 'SingletonCookie', 'SingletonSocket']) {
+        const p = join(dir, file);
+        if (existsSync(p)) {
+            try {
+                unlinkSync(p);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * 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
+ * running.
+ */
+export async function launchDebugChrome(opts = {}) {
+    const port = opts.port ?? DEFAULT_PORT;
+    const userDataDir = opts.userDataDir ?? join(tmpdir(), 'hover-chrome');
+    const url = opts.url ?? 'about:blank';
+    const readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    if (await isCdpAlive(port)) {
+        return { ok: true, alreadyRunning: true, userDataDir, port };
+    }
+    const chrome = findChromeBinary();
+    if (!chrome) {
+        return {
+            ok: false,
+            reason: `Chrome not found in any standard location for ${platform()}`,
+        };
+    }
+    clearStaleProfileLock(userDataDir);
+    const args = [
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        url,
+    ];
+    const child = spawn(chrome, args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    const spawnError = { err: null };
+    child.on('error', err => {
+        spawnError.err = err;
+    });
+    child.unref();
+    const deadline = Date.now() + readyTimeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise(res => setTimeout(res, pollMs));
+        if (spawnError.err) {
+            return { ok: false, reason: `failed to spawn Chrome: ${spawnError.err.message}` };
+        }
+        if (await isCdpAlive(port)) {
+            return { ok: true, alreadyRunning: false, userDataDir, port };
+        }
+    }
+    return {
+        ok: false,
+        reason: `Chrome started but /json/version did not respond within ${readyTimeoutMs}ms`,
+    };
+}

package/dist/playwright/preflight.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Connect to the user's Chrome via CDP and return the URLs of all open tabs.
+ * Closes the connection before returning (does not hold a Playwright session).
+ */
+export declare function connectAndListTabs(cdpUrl: string): Promise<string[]>;
+export interface CdpTabInfo {
+    url: string;
+    title?: string;
+    type?: string;
+}
+export type CdpPreflightResult = {
+    ok: true;
+    browser: string;
+    tabs: CdpTabInfo[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Lightweight CDP health check via the /json endpoints.
+ *
+ * Critical: this MUST run before invoking the agent. If CDP isn't responsive,
+ * the Playwright MCP server falls back to launching its OWN Chromium — and
+ * Hover's premise is to drive the user's existing Chrome (with their dev
+ * state, cookies, devtools open), never spawn a fresh one.
+ *
+ * Pure HTTP — no playwright-core handshake, no setDownloadBehavior nonsense
+ * that can get stuck on busy CDP sessions.
+ */
+export declare function preflightCDP(cdpUrl: string, timeoutMs?: number): Promise<CdpPreflightResult>;
+//# sourceMappingURL=preflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/playwright/preflight.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ1E;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,EAAE,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,SAAS,SAAO,GACf,OAAO,CAAC,kBAAkB,CAAC,CA4C7B"}

package/dist/playwright/preflight.js

@@ -0,0 +1,71 @@
+import { chromium } from 'playwright-core';
+/**
+ * Connect to the user's Chrome via CDP and return the URLs of all open tabs.
+ * Closes the connection before returning (does not hold a Playwright session).
+ */
+export async function connectAndListTabs(cdpUrl) {
+    const browser = await chromium.connectOverCDP(cdpUrl);
+    try {
+        const pages = browser.contexts().flatMap(c => c.pages());
+        return pages.map(p => p.url());
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * Lightweight CDP health check via the /json endpoints.
+ *
+ * Critical: this MUST run before invoking the agent. If CDP isn't responsive,
+ * the Playwright MCP server falls back to launching its OWN Chromium — and
+ * Hover's premise is to drive the user's existing Chrome (with their dev
+ * state, cookies, devtools open), never spawn a fresh one.
+ *
+ * Pure HTTP — no playwright-core handshake, no setDownloadBehavior nonsense
+ * that can get stuck on busy CDP sessions.
+ */
+export async function preflightCDP(cdpUrl, timeoutMs = 2000) {
+    let versionRes;
+    try {
+        versionRes = await fetch(`${cdpUrl}/json/version`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `Chrome debug session not detected at ${cdpUrl}. Start it with: pnpm exec hover-chrome (or: npx hover-chrome)`,
+        };
+    }
+    if (!versionRes.ok) {
+        return { ok: false, reason: `CDP returned HTTP ${versionRes.status}` };
+    }
+    let versionJson;
+    try {
+        versionJson = (await versionRes.json());
+    }
+    catch {
+        return { ok: false, reason: 'CDP /json/version returned non-JSON' };
+    }
+    let tabs = [];
+    try {
+        const listRes = await fetch(`${cdpUrl}/json/list`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (listRes.ok) {
+            const raw = (await listRes.json());
+            tabs = raw
+                .filter(t => t.type === 'page' || !t.type)
+                .map(t => ({ url: t.url ?? '', title: t.title, type: t.type }))
+                .filter(t => t.url.length > 0);
+        }
+    }
+    catch {
+        // tab list is best-effort
+    }
+    return {
+        ok: true,
+        browser: versionJson.Browser ?? 'unknown',
+        tabs,
+    };
+}

package/dist/scripts/start-chrome.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=start-chrome.d.ts.map

package/dist/scripts/start-chrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-chrome.d.ts","sourceRoot":"","sources":["../../src/scripts/start-chrome.ts"],"names":[],"mappings":""}

package/dist/scripts/start-chrome.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * "Start debug Chrome on port 9222" CLI.
+ *
+ * Two entry points:
+ *   - Repo dev:    `pnpm smoke:chrome`           → tsx src/scripts/start-chrome.ts
+ *   - npm consumer: `pnpm exec hover-chrome`     → dist/scripts/start-chrome.js
+ *                  (or `npx hover-chrome`, bin exposed by vite-plugin-hover)
+ *
+ * All actual launch logic lives in ../playwright/launchChrome.ts.
+ */
+import { launchDebugChrome } from '../playwright/launchChrome.js';
+const result = await launchDebugChrome();
+if (!result.ok) {
+    console.error(`[hover:chrome] ${result.reason}`);
+    process.exit(1);
+}
+if (result.alreadyRunning) {
+    console.log(`[hover:chrome] already listening on ${result.port}`);
+}
+else {
+    console.log(`[hover:chrome] ready on ${result.port} (data-dir=${result.userDataDir})`);
+}

package/dist/service.d.ts

@@ -0,0 +1,22 @@
+export interface ServiceOptions {
+    port: number;
+    agentId?: string;
+    model?: string;
+    maxBudgetUsd?: number;
+    mcpConfig?: string;
+    /** CDP URL to preflight before each command (default http://localhost:9222). */
+    cdpUrl?: string;
+    /** Working directory for the spawned agent. Also where skills are saved
+     *  ('<devRoot>/.claude/skills/<slug>/SKILL.md'). Defaults to process.cwd().
+     *  In Vite plugin context, set to `server.config.root` so Claude
+     *  auto-discovers skills the user previously saved from this project. */
+    devRoot?: string;
+}
+export interface ServiceHandle {
+    /** The port the WebSocketServer actually bound to. May differ from
+     *  the requested port if it was taken (we auto-bump up to 10 times). */
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startService(opts: ServiceOptions): Promise<ServiceHandle>;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAoDA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAkED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAuM/E"}