@hover-dev/core 0.11.0 → 0.13.0

package/README.md

@@ -2,7 +2,7 @@
 
 The local Node service. Owns:
 
-- **Agent invocation** (`src/agents/`) — Local CLI Agent First. Spawns `claude` / `codex` / `cursor` / ... and normalizes their output into a single `InvokeEvent` stream.
+- **Agent invocation** (`src/agents/`) — Local CLI Agent First. Spawns `claude` / `codex` / `cursor-agent` / `aider` / `gemini-cli` / `qwen-code` and normalizes their output into a single `InvokeEvent` stream.
 - **Playwright preflight** (`src/playwright/`) — verifies CDP connection to the user's Chrome.
 - **Smoke test** (`src/smoke.ts`) — end-to-end verification of the whole chain.
 
@@ -20,6 +20,9 @@ The local Node service. Owns:
 | `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, hard sandbox flags |
 | `codex.ts` | OpenAI Codex CLI descriptor: `codex exec --json`, JSONL parser, soft sandbox (`--sandbox read-only`) |
 | `cursor.ts` | Cursor CLI descriptor (v0.9): stream-JSON / NDJSON parser, soft sandbox |
+| `aider.ts` | Aider CLI descriptor (v0.10): JSON-stream parser, soft sandbox |
+| `gemini.ts` | Gemini CLI descriptor (v0.10): stream parser, soft sandbox |
+| `qwen.ts` | Qwen Code descriptor (v0.10): stream parser, soft sandbox |
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
@@ -45,7 +48,7 @@ pnpm smoke http://localhost:5173/ "log in then add a todo named 'verify hover'"
 Environment variables:
 
 - `HOVER_CDP` — CDP URL (default `http://localhost:9222`)
-- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` today)
+- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` → `aider` → `gemini-cli` → `qwen-code` today)
 - `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
 
 ## Sandboxing (what the smoke test enforces)
@@ -53,9 +56,9 @@ Environment variables:
 The `claude -p` invocation is locked down so Claude can only drive the browser:
 
 - `--strict-mcp-config` — ignore any MCP servers in `~/.claude/` or `.mcp.json`
-- `--allowedTools mcp__playwright` — only Playwright MCP is callable
-- `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch` — every built-in tool explicitly denied
+- `--allowedTools mcp__playwright Skill` — only Playwright MCP and the Skill tool are callable
+- `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch EnterWorktree CronCreate …` — every built-in tool explicitly denied (full list in `CLAUDE_DEFAULT_DISALLOWED_TOOLS` in `claude.ts`)
 - `--permission-mode dontAsk` — anything not whitelisted aborts the run
-- `--max-budget-usd 0.50` — hard ceiling per session
+- `--max-budget-usd <n>` — optional hard $ ceiling per session (no default; pass `maxBudgetUsd` in plugin options or via the CLI flag to enable)
 
 Together these enforce the rule that the spawned agent can only reach the browser via Playwright MCP — never the host filesystem, shell, or network. A hijacked prompt or hallucinated destructive action has nowhere to land.

package/dist/plugin-api.d.ts

@@ -149,8 +149,42 @@ export interface HoverPluginManifest {
      *  inside their server-side entry. If absent, the plugin contributes
      *  no widget code (server-side-only plugin). */
     widgetEntry?: string;
+    /** v0.12 — plugin-contributed save handlers. The widget Save dropdown
+     *  picks up these entries via the host API (`host.registerSaveEntry`)
+     *  and the service routes incoming `save:<type>` WS messages to the
+     *  plugin's handler. Each plugin owns its own write semantics — the
+     *  service does NOT touch the payload, it just delivers it. Letting
+     *  plugins write entirely different artefacts (security regression
+     *  specs, performance reports, …) without forcing them into core's
+     *  SkillStep[] shape. */
+    saveHandlers?: HoverPluginSaveHandler[];
     hooks?: HoverHooks;
 }
+export interface HoverPluginSaveHandler {
+    /** WS message type the widget sends — the service uses this verbatim
+     *  in its router. Convention: `save:<plugin>:<kind>`. Example:
+     *  `'save:security:spec'`. Must be unique across all loaded plugins. */
+    type: string;
+    /** UI label shown in the widget's Save dropdown. Example: "Security spec". */
+    label: string;
+    /** Optional short hint shown under the label. Example: "Playwright
+     *  regression spec for the IDOR / authz probes the agent recorded." */
+    description?: string;
+    /** Modes in which this Save entry is offered. Defaults to the
+     *  plugin's own mode (or `['*']` if the plugin has no mode). */
+    activeInModes?: string[];
+    /** Server-side handler. Receives the raw payload the widget sent
+     *  alongside `devRoot`. Returns the on-disk path + slug for the
+     *  service to echo back as `<type>:saved`. Throw to signal failure;
+     *  service surfaces the error message to the widget. */
+    handle(ctx: {
+        devRoot: string;
+        payload: unknown;
+    }): Promise<{
+        path: string;
+        slug: string;
+    }>;
+}
 /**
  * Branded factory that wraps a plugin manifest factory. The wrapper
  * - asserts `apiVersion` matches this core's version at construction time

package/dist/plugin-api.d.ts.map

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

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA6EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,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;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAswB/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA6EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,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;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqyB/E"}

package/dist/service.js

@@ -550,6 +550,39 @@ export async function startService(opts) {
                 await handleSaveArtifact(ws, msg, devRoot, CASE_CSV_CONFIG);
                 return;
             }
+            // v0.12 — plugin-contributed save handlers. Lookup is O(plugins),
+            // which is fine because there's at most a handful of plugins ever
+            // loaded. Each plugin's manifest declares `saveHandlers[].type`
+            // as the WS message type the widget sends; we match exactly.
+            if (typeof msg.type === 'string' && msg.type.startsWith('save:')) {
+                for (const p of plugins) {
+                    const handler = p.saveHandlers?.find((h) => h.type === msg.type);
+                    if (!handler)
+                        continue;
+                    try {
+                        const result = await handler.handle({ devRoot, payload: msg.payload });
+                        send(ws, {
+                            type: `${msg.type}:saved`,
+                            payload: { name: result.slug, path: result.path },
+                        });
+                    }
+                    catch (err) {
+                        const m = err instanceof Error ? err.message : String(err);
+                        send(ws, {
+                            type: 'error',
+                            payload: { message: `${msg.type}: ${m}` },
+                        });
+                    }
+                    return;
+                }
+                // No plugin matched — surface as a normal error rather than
+                // silently swallowing.
+                send(ws, {
+                    type: 'error',
+                    payload: { message: `no plugin registered for save type "${msg.type}"` },
+                });
+                return;
+            }
             if (msg.type === 'check-cdp') {
                 await handleCheckCdp(ws, msg, cdpUrl, effectiveLaunchExtras());
                 return;

package/dist/specs/writeSpec.js

@@ -122,10 +122,19 @@ function renderSpec(slug, displayName, description, steps, assertions) {
             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;
         }
     }
+    // `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('');
@@ -152,30 +161,30 @@ function translateStep(tool, rawInput) {
             return [`await page.goto(${JSON.stringify(path)});`];
         }
         case 'browser_click':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.click();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'click()');
         case 'browser_double_click':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.dblclick();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'dblclick()');
         case 'browser_hover':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.hover();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'hover()');
         case 'browser_fill_form': {
             const fields = input.fields ?? [];
-            return fields.map(raw => {
+            return fields.flatMap(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)});`;
+                return emitInteraction(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)});`];
+            return emitInteraction(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))});`];
+            return emitInteraction(selectorFromDescription(target), `selectOption(${JSON.stringify(String(val))})`);
         }
         case 'browser_press_key': {
             const key = String(input.key ?? '');
@@ -197,6 +206,40 @@ function translateStep(tool, rawInput) {
             return [`// TODO: translate ${tool} (skipped — unknown tool for spec emission)`];
     }
 }
+/**
+ * Wrap an interaction (click / dblclick / hover / fill / selectOption) in a
+ * block-scoped visibility prelude. Replaces the prior one-liner emit:
+ *
+ *    // before
+ *    await page.getByRole('button', { name: 'Submit' }).click();
+ *
+ *    // after
+ *    {
+ *      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.
+ *
+ * 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.
+ */
+function emitInteraction(selectorExpr, action) {
+    return [
+        `{`,
+        `  const el = ${selectorExpr};`,
+        `  await expect(el).toBeVisible();`,
+        `  await el.${action};`,
+        `}`,
+    ];
+}
 /**
  * Parse element descriptions like "Submit button" / "+1 button" / "Email
  * textbox" / "Plan radio" into `getByRole(role, { name })` selectors. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",