@hover-dev/core 0.16.0 → 0.18.0

package/dist/agents/types.d.ts

@@ -1,186 +0,0 @@
-/**
- * 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;
-    /** Optional model API key. Injected into the spawned CLI's environment under
-     *  the descriptor's `apiKeyEnv` var (e.g. ANTHROPIC_API_KEY) so a user without
-     *  a logged-in subscription can drive Hover with their own key. Never logged,
-     *  never persisted server-side — held only for the lifetime of the spawn. */
-    apiKey?: 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;
-    costUsdSnapshot?: number;
-} | {
-    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;
-}
-/** End-of-session event. Three terminal states the widget renders distinctly:
- *
- *   - normal completion: `isError: false`, no `cancelled` flag
- *   - agent / runtime failure: `isError: true`, no `cancelled` flag
- *   - user-initiated stop: `cancelled: true` (and we leave `isError: false`
- *     so downstream "did the agent fail?" predicates don't conflate
- *     "user pressed Stop" with "agent crashed mid-run"). The widget
- *     renders this as a neutral "Stopped" state, not a red Failed card.
- */
- | {
-    kind: 'session_end';
-    turns?: number;
-    costUsd?: number;
-    isError?: boolean;
-    cancelled?: boolean;
-    summary?: string;
-} | {
-    kind: 'raw';
-    line: string;
-};
-/**
- * How tightly the agent's tool surface can be locked down per invocation.
- *
- *   'hard' — the agent CLI accepts a deny-list / allow-list that effectively
- *            removes built-in tools (shell, file edit, etc.) so the only
- *            callable surface is whatever MCP servers we configure. Claude
- *            Code's `--strict-mcp-config` + `--allowedTools mcp__playwright`
- *            + `--disallowedTools <every built-in>` is the canonical example.
- *
- *   'soft' — the agent CLI does not expose a way to disable its built-in
- *            tools (shell, fs). We can constrain side-effects via OS-level
- *            sandbox flags (e.g. codex's `--sandbox read-only`) and we lean
- *            on a strict `developer_instructions` system-prompt to nudge the
- *            agent toward MCP-only behavior, but a determined / hallucinating
- *            agent COULD still try a built-in shell call. The widget should
- *            mark this agent with a warning indicator.
- */
-export type SandboxStrength = 'hard' | 'soft';
-/**
- * Human-facing metadata for the widget's agent picker. None of these affect
- * agent invocation — they only shape how the agent is presented in the UI.
- */
-export interface AgentDisplay {
-    /** Pretty name for the dropdown ("Claude Code", "OpenAI Codex"). */
-    label: string;
-    /** One-line tagline shown under the label. */
-    tagline?: string;
-    /** Vendor / source URL — clicking the agent name in the widget can open
-     *  this in a new tab when the agent isn't installed. */
-    homepage?: string;
-    /** Shell command the user can run to install (copy-paste from a tooltip
-     *  in the widget when the agent is listed but not on PATH). */
-    installHint?: string;
-}
-/**
- * Per-invocation parser state. A fresh object is created by `invokeAgent`
- * for each spawn and passed to both `parseEvent` and `onStreamEnd`.
- *
- * Descriptors that need to accumulate state across lines (cost, turn count,
- * last agent message for synthesized session_end, etc.) read and write
- * their own keys on this object. There is no shared shape — each agent
- * uses whatever fields it needs.
- *
- * Why: module-level state in claude.ts / codex.ts worked only because the
- * service enforces one in-flight invocation per Node process. Two concurrent
- * agent runs (future: tests in parallel, in-process workers) would silently
- * smear their cost accumulators together. Threading the state object per
- * invocation removes that hazard at zero runtime cost.
- */
-export type ParserState = Record<string, unknown>;
-export interface AgentDescriptor {
-    id: string;
-    binName: string;
-    protocol: AgentProtocol;
-    streamFormat: StreamFormat;
-    sandboxStrength: SandboxStrength;
-    display: AgentDisplay;
-    /** Hard-sandbox agents pass this list to `disallowedTools` when the
-     *  service-level allow/deny config isn't explicitly overridden. Lets the
-     *  per-CLI deny list live alongside its descriptor instead of as a magic
-     *  array in the service. Soft-sandbox agents leave this undefined. */
-    defaultDisallowedTools?: readonly string[];
-    /** Environment variable this CLI reads its model API key from
-     *  (claude: ANTHROPIC_API_KEY, codex: OPENAI_API_KEY). When set and the
-     *  caller supplies `InvokeOptions.apiKey`, the key is injected into the spawn
-     *  env so the user can run on a raw key instead of a logged-in subscription.
-     *  Undefined for agents that have no API-key env path. */
-    apiKeyEnv?: string;
-    buildArgs(opts: InvokeOptions): string[];
-    /**
-     * Parse a single line of agent stdout into normalised InvokeEvents.
-     * `state` is a per-invocation scratch pad (see ParserState). Optional
-     * for callers that don't accumulate across lines (and for unit tests
-     * that don't care about cost / turn carry-over) — descriptors that
-     * DO accumulate must check / initialise the state object themselves.
-     */
-    parseEvent(line: string, state?: ParserState): InvokeEvent[];
-    /**
-     * Optional. Called once after the agent's stream closes, with the child's
-     * exit code (or null if it was aborted). Lets agents whose protocol does
-     * NOT emit an explicit session-terminating event synthesize one from
-     * accumulated parser state. Returns `null` if the agent's own `parseEvent`
-     * already emitted a `session_end` and nothing further is needed.
-     *
-     * Used by codex.ts (no native session_end). Claude does not implement
-     * this — `result` events terminate naturally.
-     */
-    onStreamEnd?(exitCode: number | null, state?: ParserState): InvokeEvent | null;
-}
-//# sourceMappingURL=types.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}

package/dist/agents/types.js

@@ -1,23 +0,0 @@
-/**
- * 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

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

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"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

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

package/dist/mcp/sourceFence.d.ts

@@ -1,23 +0,0 @@
-export interface FenceOk {
-    ok: true;
-    /** Absolute, root-anchored path the server may stat/read (after realpath). */
-    abs: string;
-    /** POSIX-style path relative to the root — safe to echo back to the agent. */
-    rel: string;
-}
-export interface FenceErr {
-    ok: false;
-    reason: string;
-}
-/**
- * Resolve `input` against `root`, refusing anything outside the root or matching
- * a secret pattern. `input` is treated as relative to the root; an absolute
- * input is resolved too but will fail the containment check unless it happens to
- * live under the root (the agent should pass repo-relative paths).
- */
-export declare function resolveSourcePath(root: string, input: string): FenceOk | FenceErr;
-/** True if a resolved-and-realpathed absolute path is still inside the root.
- *  The server calls this AFTER realpath to defeat symlink escape (a symlink
- *  whose lexical path passed resolveSourcePath but points outside the root). */
-export declare function isWithinRoot(root: string, realAbs: string): boolean;
-//# sourceMappingURL=sourceFence.d.ts.map

package/dist/mcp/sourceFence.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sourceFence.d.ts","sourceRoot":"","sources":["../../src/mcp/sourceFence.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAsBjF;AAED;;gFAEgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAInE"}

package/dist/mcp/sourceFence.js

@@ -1,75 +0,0 @@
-/**
- * The path fence for the opt-in `read_source` capability (codeContext).
- *
- * Giving the agent the ability to read source is the ONE place Hover relaxes
- * its "the agent only touches the browser" rule, so the fence is the whole
- * security story. It must guarantee, on every call, that a caller-supplied path:
- *   1. resolves to a location INSIDE the project root (no `..` / absolute-path
- *      escape — symlink escape is caught by the server's realpath re-check), and
- *   2. is not a credential / secret / VCS / dependency file.
- * Pure + lexical so it's exhaustively unit-testable; the server layers a
- * realpath check + a size/binary guard on top.
- */
-import { resolve, relative, isAbsolute, sep } from 'node:path';
-/** Files we refuse to read even inside the root — credentials, keys, VCS,
- *  dependency trees, build caches. Matched against the POSIX-style relative
- *  path (so `\` on Windows is normalised first). */
-const SECRET_PATTERNS = [
-    /(^|\/)\.env(\.[^/]*)?$/i, //              .env, .env.local, .env.production
-    /(^|\/)\.git(\/|$)/, //                    the git dir
-    /(^|\/)node_modules(\/|$)/, //             dependency tree
-    /(^|\/)\.(next|nuxt|svelte-kit|astro|turbo|cache|output|vercel)(\/|$)/, // build caches
-    /(^|\/)(dist|build|coverage)(\/|$)/, //    build output
-    /\.(pem|key|p12|pfx|crt|cer|der|keystore|jks)$/i, // key / cert material
-    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.[^/]*)?$/i, // ssh keys
-    /(^|\/)\.(npmrc|netrc|pgpass)$/i, //       token-bearing rc files
-    /(^|\/)\.(ssh|aws|gnupg|gcloud|kube|docker)(\/|$)/i, // credential dirs
-    /(^|\/)secrets?(\/|\.[^/]*$|$)/i, //       a secrets dir, or a secret(s).<ext> file
-    /(^|\/)credentials?(\/|\.[^/]*$|$)/i, //   a credentials dir, or credential(s).<ext>
-    /\.(secret|secrets)$/i,
-];
-/** A path containing a NUL or C0 control char is never a legitimate source file. */
-function hasControlChar(s) {
-    for (let i = 0; i < s.length; i++) {
-        if (s.charCodeAt(i) < 0x20)
-            return true;
-    }
-    return false;
-}
-/**
- * Resolve `input` against `root`, refusing anything outside the root or matching
- * a secret pattern. `input` is treated as relative to the root; an absolute
- * input is resolved too but will fail the containment check unless it happens to
- * live under the root (the agent should pass repo-relative paths).
- */
-export function resolveSourcePath(root, input) {
-    if (typeof input !== 'string' || !input.trim()) {
-        return { ok: false, reason: 'path is required' };
-    }
-    if (hasControlChar(input)) {
-        return { ok: false, reason: 'path contains control characters' };
-    }
-    const rootAbs = resolve(root);
-    const abs = resolve(rootAbs, input);
-    const rel = relative(rootAbs, abs);
-    // Outside the root: relative() returns '' for the root itself, a '..'-prefixed
-    // path for an ancestor/sibling, or an absolute path when on a different drive.
-    if (rel === '' || rel === '..' || rel.startsWith('..' + sep) || rel.startsWith('../') || isAbsolute(rel)) {
-        return { ok: false, reason: 'path escapes the project root' };
-    }
-    const relPosix = rel.split(sep).join('/');
-    for (const pat of SECRET_PATTERNS) {
-        if (pat.test(relPosix)) {
-            return { ok: false, reason: `refused: "${relPosix}" matches an excluded (secret / build / VCS) pattern` };
-        }
-    }
-    return { ok: true, abs, rel: relPosix };
-}
-/** True if a resolved-and-realpathed absolute path is still inside the root.
- *  The server calls this AFTER realpath to defeat symlink escape (a symlink
- *  whose lexical path passed resolveSourcePath but points outside the root). */
-export function isWithinRoot(root, realAbs) {
-    const rootAbs = resolve(root);
-    const rel = relative(rootAbs, realAbs);
-    return rel !== '' && rel !== '..' && !rel.startsWith('..' + sep) && !rel.startsWith('../') && !isAbsolute(rel);
-}

package/dist/mcp/sourceServer.d.ts

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

package/dist/mcp/sourceServer.d.ts.map

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

package/dist/mcp/sourceServer.js

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-/**
- * Hover source-reader MCP server — the runtime behind the opt-in `codeContext`
- * switch. Spawned by the agent (Claude Code / Codex) as a stdio subprocess when
- * codeContext is enabled, in addition to Playwright MCP. It gives the agent
- * READ-ONLY, fenced access to the project's source so it can author smarter
- * tests and do white-box security/pentest work (read the actual query / authz
- * check, not just the rendered DOM).
- *
- * This is the ONE place Hover relaxes "the agent only touches the browser", so
- * the safety is all in the fence (src/mcp/sourceFence.ts) + the guards here:
- *   - every path is resolved INSIDE the project root (no `..` / absolute escape)
- *   - a realpath re-check defeats symlink escape
- *   - secret / VCS / dependency / build files are refused (.env, keys, .git, …)
- *   - read-only: there is no write / exec / delete tool here
- *   - a size cap + a binary guard keep it to actual source
- *
- * The project root comes in via env:
- *   HOVER_PROJECT_ROOT   absolute path to the dev project root (devRoot)
- *
- * Tools exposed:
- *   read_source({ path })            → the file's text (fenced, ≤256 KB, text-only)
- *   list_source({ subdir? })         → a shallow dir listing (secrets filtered out)
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-import { readFileSync, realpathSync, statSync, readdirSync } from 'node:fs';
-import { resolveSourcePath, isWithinRoot } from './sourceFence.js';
-const root = process.env.HOVER_PROJECT_ROOT;
-if (!root) {
-    process.stderr.write('[hover-source-mcp] HOVER_PROJECT_ROOT must be set by the host.\n');
-    process.exit(1);
-}
-const ROOT = root;
-const MAX_BYTES = 256 * 1024;
-function md(text) {
-    return { content: [{ type: 'text', text }] };
-}
-const server = new McpServer({ name: 'hover-source', version: '0.0.0' });
-server.registerTool('read_source', {
-    description: "Read a source file from THIS project (read-only). Pass a repo-relative path (e.g. the one in an element's data-hover-source, `src/app/login.tsx:42` → path `src/app/login.tsx`). Fenced to the project root: paths that escape it, or that name secrets / keys / .env / .git / node_modules / build output, are refused. Use this to write tests against the real selectors & routes, or — in security/pentest mode — to confirm a finding against the actual server code (the SQL query, the authz check). You cannot write, run, or delete anything.",
-    inputSchema: {
-        path: z.string().describe('Repo-relative path to a source file, e.g. "src/api/orders.ts".'),
-    },
-}, async ({ path }) => {
-    const f = resolveSourcePath(ROOT, path);
-    if (!f.ok)
-        return md(`✗ ${f.reason}`);
-    let real;
-    try {
-        real = realpathSync(f.abs);
-    }
-    catch {
-        return md(`✗ not found: ${f.rel}`);
-    }
-    if (!isWithinRoot(ROOT, real))
-        return md(`✗ refused: "${f.rel}" resolves (via a symlink) outside the project root`);
-    let st;
-    try {
-        st = statSync(real);
-    }
-    catch {
-        return md(`✗ not found: ${f.rel}`);
-    }
-    if (st.isDirectory())
-        return md(`✗ "${f.rel}" is a directory — use list_source`);
-    if (st.size > MAX_BYTES)
-        return md(`✗ "${f.rel}" is ${Math.round(st.size / 1024)} KB — too large to read (cap ${MAX_BYTES / 1024} KB)`);
-    let buf;
-    try {
-        buf = readFileSync(real);
-    }
-    catch (e) {
-        return md(`✗ could not read ${f.rel}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    // Binary guard — a NUL byte in the first 8 KB means it isn't source text.
-    if (buf.subarray(0, 8192).includes(0))
-        return md(`✗ "${f.rel}" looks binary — refused`);
-    return md(`\`\`\`\n// ${f.rel}\n${buf.toString('utf-8')}\n\`\`\``);
-});
-server.registerTool('list_source', {
-    description: 'List the entries of a directory in THIS project (shallow, read-only). Omit `subdir` for the project root. Secret / VCS / dependency / build entries are filtered out. Use it to discover what source exists before reading a file.',
-    inputSchema: {
-        subdir: z.string().optional().describe('Repo-relative directory, e.g. "src/api". Omit for the root.'),
-    },
-}, async ({ subdir }) => {
-    let dirAbs = ROOT;
-    let base = '';
-    if (subdir && subdir.trim() && subdir.trim() !== '.') {
-        const d = resolveSourcePath(ROOT, subdir);
-        if (!d.ok)
-            return md(`✗ ${d.reason}`);
-        dirAbs = d.abs;
-        base = d.rel;
-    }
-    let entries;
-    try {
-        entries = readdirSync(dirAbs, { withFileTypes: true });
-    }
-    catch {
-        return md(`✗ not a readable directory: ${base || '.'}`);
-    }
-    const rows = [];
-    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        const rel = base ? `${base}/${e.name}` : e.name;
-        // Filter via the same fence so secrets/build/VCS never even show up.
-        if (!resolveSourcePath(ROOT, rel).ok)
-            continue;
-        rows.push(e.isDirectory() ? `${rel}/` : rel);
-    }
-    if (rows.length === 0)
-        return md(`(empty or fully filtered) ${base || '.'}`);
-    return md(`${base || '.'} —\n${rows.join('\n')}`);
-});
-await server.connect(new StdioServerTransport());

package/dist/playwright/cdpStatus.d.ts

@@ -1,29 +0,0 @@
-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

@@ -1 +0,0 @@
-{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAiBA,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,CA8C3E"}

package/dist/playwright/cdpStatus.js

@@ -1,119 +0,0 @@
-/**
- * "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 { getPreflight } from './preflightCache.js';
-import { findCdpPid, raiseChromeWindow } from './raiseWindow.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 getPreflight(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}` };
-    }
-    let focusedUrl;
-    try {
-        const pages = browser.contexts().flatMap(c => c.pages());
-        const match = pages.find(p => originOf(p.url()) === wantOrigin);
-        if (match) {
-            await match.bringToFront();
-            focusedUrl = match.url();
-        }
-        else {
-            // 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();
-            focusedUrl = page.url();
-        }
-    }
-    catch (err) {
-        await browser.close().catch(() => { });
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `bringToFront failed: ${msg}` };
-    }
-    await browser.close().catch(() => { });
-    // CDP-level bringToFront only activates the tab inside the Chrome process;
-    // on macOS in particular the Chrome *window* stays buried if it wasn't
-    // foreground already. Raise the OS window too. Best-effort, never fatal.
-    const port = portFromCdpUrl(cdpUrl);
-    if (port !== null) {
-        const pid = await findCdpPid(port);
-        if (pid !== null)
-            await raiseChromeWindow(pid);
-    }
-    return { ok: true, focusedUrl };
-}
-function portFromCdpUrl(cdpUrl) {
-    try {
-        const u = new URL(cdpUrl);
-        const port = Number.parseInt(u.port, 10);
-        return Number.isInteger(port) && port > 0 ? port : null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/playwright/preflight.d.ts

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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,CAsD7B"}