@hover-dev/core 0.2.0 → 0.2.3

package/dist/playwright/cdpStatus.js

@@ -13,6 +13,7 @@
  */
 import { chromium } from 'playwright-core';
 import { preflightCDP } from './preflight.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
@@ -72,25 +73,47 @@ export async function focusDebugTab(cdpUrl, pageUrl) {
         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();
-            return { ok: true, focusedUrl: match.url() };
+            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();
         }
-        // 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) {
+        await browser.close().catch(() => { });
         const msg = err instanceof Error ? err.message : String(err);
         return { ok: false, reason: `bringToFront failed: ${msg}` };
     }
-    finally {
-        await browser.close().catch(() => { });
+    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/raiseWindow.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Find the OS PID of the process listening on the given TCP port.
+ * Returns null if nothing is listening or the lookup tool isn't available.
+ */
+export declare function findCdpPid(port: number): Promise<number | null>;
+/**
+ * Raise the Chrome window owned by `pid` to the OS foreground. Best-effort.
+ */
+export declare function raiseChromeWindow(pid: number): Promise<void>;
+//# sourceMappingURL=raiseWindow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raiseWindow.d.ts","sourceRoot":"","sources":["../../src/playwright/raiseWindow.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8BrE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwClE"}

package/dist/playwright/raiseWindow.js

@@ -0,0 +1,124 @@
+/**
+ * Raise the OS-level Chrome window to the foreground.
+ *
+ * Why this exists: CDP's `Page.bringToFront()` and `Target.activateTarget`
+ * only reorder tabs *inside* the Chrome process — they do not raise the
+ * Chrome application window in the OS's window stack. When the user clicks
+ * "Switch me to it" from a widget hosted in a different window, the tab
+ * activates correctly inside the (possibly background) debug Chrome, but
+ * the window stays buried. The user then has to manually click the Chrome
+ * Dock icon / Alt-Tab to it, which defeats the point of the button.
+ *
+ * Fix: after `bringToFront()`, run an OS-specific command that raises the
+ * specific Chrome *process* (matched by PID, found from the CDP port via
+ * `lsof` / `netstat`). PID-matching is critical — the user's own primary
+ * Chrome and Hover's debug Chrome are both "Google Chrome" to AppleScript,
+ * so raising by app name would risk activating the wrong window.
+ *
+ * Best-effort and non-blocking — if the helper fails, we still leave the
+ * tab correctly focused inside the debug Chrome and the user can click
+ * over manually like before. Logging is to stderr only; this never throws
+ * back to the caller.
+ */
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+/**
+ * Find the OS PID of the process listening on the given TCP port.
+ * Returns null if nothing is listening or the lookup tool isn't available.
+ */
+export async function findCdpPid(port) {
+    const os = platform();
+    if (os === 'darwin' || os === 'linux') {
+        // -t prints just PIDs, -sTCP:LISTEN filters to listeners (otherwise
+        // every client connection's PID would show up too).
+        const out = await runCapture('lsof', ['-tiTCP:' + port, '-sTCP:LISTEN']);
+        if (!out)
+            return null;
+        // lsof may print multiple lines if forked workers also hold the port;
+        // take the first numeric one.
+        for (const line of out.split('\n')) {
+            const pid = Number.parseInt(line.trim(), 10);
+            if (Number.isInteger(pid) && pid > 0)
+                return pid;
+        }
+        return null;
+    }
+    if (os === 'win32') {
+        // `netstat -ano` columns: Proto Local Foreign State PID
+        const out = await runCapture('netstat', ['-ano']);
+        if (!out)
+            return null;
+        for (const line of out.split('\n')) {
+            // Match `TCP    127.0.0.1:9222    0.0.0.0:0    LISTENING    1234`
+            const m = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)\s*$/i);
+            if (m && Number(m[1]) === port)
+                return Number(m[2]);
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Raise the Chrome window owned by `pid` to the OS foreground. Best-effort.
+ */
+export async function raiseChromeWindow(pid) {
+    const os = platform();
+    try {
+        if (os === 'darwin') {
+            // System Events can frontmost any process by its unix PID, regardless
+            // of app bundle. This works even when several "Google Chrome"
+            // processes coexist (user's primary + Hover's debug).
+            await runDetached('osascript', [
+                '-e',
+                `tell application "System Events" to set frontmost of (first process whose unix id is ${pid}) to true`,
+            ]);
+            return;
+        }
+        if (os === 'linux') {
+            // wmctrl is the most common helper for X11; not always installed,
+            // but the alternative (xdotool) needs the same dependency story.
+            // We try wmctrl with the PID match; if it isn't installed the
+            // outer try/catch swallows the ENOENT and we degrade gracefully.
+            await runDetached('wmctrl', ['-ia', String(pid)]);
+            return;
+        }
+        if (os === 'win32') {
+            // PowerShell is bundled with Windows 10+. AppActivate is best-effort:
+            // it requires the target to have a visible main window, which a
+            // headless-less Chrome with a tab open satisfies.
+            const ps = `$p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue; ` +
+                `if ($p) { ` +
+                `  Add-Type -AssemblyName Microsoft.VisualBasic; ` +
+                `  [Microsoft.VisualBasic.Interaction]::AppActivate($p.Id) ` +
+                `}`;
+            await runDetached('powershell', ['-NoProfile', '-Command', ps]);
+            return;
+        }
+    }
+    catch {
+        // Best-effort. CDP-level bringToFront already ran; user can still
+        // click the Chrome window manually.
+    }
+}
+function runCapture(cmd, args) {
+    return new Promise(resolve => {
+        let out = '';
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        child.stdout.on('data', chunk => {
+            out += chunk.toString();
+        });
+        child.on('error', () => resolve(null));
+        child.on('close', code => resolve(code === 0 ? out : null));
+    });
+}
+function runDetached(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: 'ignore' });
+        child.on('error', reject);
+        child.on('close', code => {
+            // Don't treat non-zero as fatal — caller already wraps in try/catch.
+            resolve();
+            void code;
+        });
+    });
+}

package/dist/service/cdpHandlers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CDP-related WebSocket message handlers.
+ *
+ *   check-cdp     → checkCdpStatus → emit cdp-status
+ *   launch-chrome → emit "launching" placeholder → launchDebugChrome →
+ *                   re-check status → emit cdp-status
+ *   focus-debug   → focusDebugTab → no message on success (the widget the
+ *                   user is about to focus runs its own check-cdp anyway)
+ *
+ * Extracted from service.ts during the v0.2.x refactor pass so the main
+ * file can be a thin orchestrator.
+ */
+import type { WebSocket } from 'ws';
+import { type ClientMessage } from './types.js';
+/**
+ * "Is this widget running inside the debug Chrome?" The widget asks this on
+ * connect (and after every status-changing event) so it can render itself as
+ * either:
+ *   - same-window  → normal, drives the page
+ *   - wrong-window → disabled, with a "use the other window" notice
+ *   - no-cdp       → enabled but click triggers launch-chrome instead
+ */
+export declare function handleCheckCdp(ws: WebSocket, msg: ClientMessage, cdpUrl: string): Promise<void>;
+/**
+ * Launch a debug Chrome navigated to `pageUrl`, then re-check status. The
+ * re-check usually returns 'wrong-window' (because the widget asking is in
+ * the user's regular Chrome, not the freshly-launched one) — the widget then
+ * displays the "use the other window" state.
+ */
+export declare function handleLaunchChrome(ws: WebSocket, msg: ClientMessage, cdpUrl: string): Promise<void>;
+/**
+ * bringToFront the debug-Chrome tab matching `pageUrl`'s origin (or open one
+ * if none exists). Used by the wrong-window UI's "switch to debug Chrome"
+ * button. Doesn't return cdp-status — bringToFront doesn't change anything
+ * the widget cares about, and the widget the user is about to focus is a
+ * different page (and will run its own check-cdp on its own ws connection).
+ */
+export declare function handleFocusDebug(ws: WebSocket, msg: ClientMessage, cdpUrl: string): Promise<void>;
+//# sourceMappingURL=cdpHandlers.d.ts.map

package/dist/service/cdpHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdpHandlers.d.ts","sourceRoot":"","sources":["../../src/service/cdpHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAGpC,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/service/cdpHandlers.js

@@ -0,0 +1,82 @@
+/**
+ * CDP-related WebSocket message handlers.
+ *
+ *   check-cdp     → checkCdpStatus → emit cdp-status
+ *   launch-chrome → emit "launching" placeholder → launchDebugChrome →
+ *                   re-check status → emit cdp-status
+ *   focus-debug   → focusDebugTab → no message on success (the widget the
+ *                   user is about to focus runs its own check-cdp anyway)
+ *
+ * Extracted from service.ts during the v0.2.x refactor pass so the main
+ * file can be a thin orchestrator.
+ */
+import { checkCdpStatus, focusDebugTab } from '../playwright/cdpStatus.js';
+import { launchDebugChrome } from '../playwright/launchChrome.js';
+import { send } from './types.js';
+/**
+ * "Is this widget running inside the debug Chrome?" The widget asks this on
+ * connect (and after every status-changing event) so it can render itself as
+ * either:
+ *   - same-window  → normal, drives the page
+ *   - wrong-window → disabled, with a "use the other window" notice
+ *   - no-cdp       → enabled but click triggers launch-chrome instead
+ */
+export async function handleCheckCdp(ws, msg, cdpUrl) {
+    const pageUrl = msg.payload?.pageUrl;
+    if (typeof pageUrl !== 'string' || !pageUrl) {
+        send(ws, { type: 'error', payload: { message: 'check-cdp: pageUrl is required' } });
+        return;
+    }
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
+    send(ws, { type: 'cdp-status', payload: status });
+}
+/**
+ * Launch a debug Chrome navigated to `pageUrl`, then re-check status. The
+ * re-check usually returns 'wrong-window' (because the widget asking is in
+ * the user's regular Chrome, not the freshly-launched one) — the widget then
+ * displays the "use the other window" state.
+ */
+export async function handleLaunchChrome(ws, msg, cdpUrl) {
+    const pageUrl = msg.payload?.pageUrl;
+    if (typeof pageUrl !== 'string' || !pageUrl) {
+        send(ws, { type: 'error', payload: { message: 'launch-chrome: pageUrl is required' } });
+        return;
+    }
+    // Tell the widget we're launching so it can render a spinner immediately —
+    // findChromeBinary + spawn + ready-poll can take a few seconds.
+    send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', launching: true } });
+    const port = (() => {
+        try {
+            return Number(new URL(cdpUrl).port) || 9222;
+        }
+        catch {
+            return 9222;
+        }
+    })();
+    const result = await launchDebugChrome({ url: pageUrl, port });
+    if (!result.ok) {
+        send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', reason: result.reason } });
+        return;
+    }
+    // Re-check after launch so the widget gets the real status.
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
+    send(ws, { type: 'cdp-status', payload: status });
+}
+/**
+ * bringToFront the debug-Chrome tab matching `pageUrl`'s origin (or open one
+ * if none exists). Used by the wrong-window UI's "switch to debug Chrome"
+ * button. Doesn't return cdp-status — bringToFront doesn't change anything
+ * the widget cares about, and the widget the user is about to focus is a
+ * different page (and will run its own check-cdp on its own ws connection).
+ */
+export async function handleFocusDebug(ws, msg, cdpUrl) {
+    const pageUrl = msg.payload?.pageUrl;
+    if (typeof pageUrl !== 'string' || !pageUrl) {
+        send(ws, { type: 'error', payload: { message: 'focus-debug: pageUrl is required' } });
+        return;
+    }
+    const result = await focusDebugTab(cdpUrl, pageUrl);
+    if (!result.ok) {
+        send(ws, { type: 'error', payload: { message: `focus-debug: ${result.reason}` } });
+    }
+}

package/dist/service/cdpHint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * System-prompt addendum sent to the agent on every command.
+ *
+ * Two roles:
+ *   1. Navigation rules — the most failure-prone agent behaviours are
+ *      `browser_navigate` to same-origin paths (kills the widget) and
+ *      reading the JS bundle for credentials. We tell the agent both
+ *      mistakes by name, including the actual origin to forbid.
+ *   2. Narration format — how the widget renders the run depends on the
+ *      agent emitting short imperative one-liners before each logical
+ *      step. The good/bad examples are present-tense and 3–8 words.
+ *
+ * Lives in its own file because this string is the most-tuned text in the
+ * repo and the easiest to break with a typo. Tests can import directly.
+ */
+export declare function buildCdpHint(tabs: {
+    url: string;
+    title?: string;
+}[]): string;
+//# sourceMappingURL=cdpHint.d.ts.map

package/dist/service/cdpHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdpHint.d.ts","sourceRoot":"","sources":["../../src/service/cdpHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAmE5E"}

package/dist/service/cdpHint.js

@@ -0,0 +1,86 @@
+/**
+ * System-prompt addendum sent to the agent on every command.
+ *
+ * Two roles:
+ *   1. Navigation rules — the most failure-prone agent behaviours are
+ *      `browser_navigate` to same-origin paths (kills the widget) and
+ *      reading the JS bundle for credentials. We tell the agent both
+ *      mistakes by name, including the actual origin to forbid.
+ *   2. Narration format — how the widget renders the run depends on the
+ *      agent emitting short imperative one-liners before each logical
+ *      step. The good/bad examples are present-tense and 3–8 words.
+ *
+ * Lives in its own file because this string is the most-tuned text in the
+ * repo and the easiest to break with a typo. Tests can import directly.
+ */
+export function buildCdpHint(tabs) {
+    if (tabs.length === 0)
+        return '';
+    // Prefer the localhost tab if we have multiple — that's almost always the
+    // dev server the user is testing against.
+    const localhost = tabs.find(t => /localhost|127\.0\.0\.1/.test(t.url));
+    const active = localhost ?? tabs[0];
+    let activeOrigin = '';
+    try {
+        activeOrigin = new URL(active.url).origin;
+    }
+    catch { /* malformed url — fall back to no-origin guard */ }
+    return [
+        `The user's Chrome currently has these tabs open:`,
+        ...tabs.map(t => `  - ${t.url}${t.title ? `  (${t.title})` : ''}`),
+        ``,
+        `The likely active dev tab is: ${active.url}`,
+        ``,
+        `Navigation rules — read carefully, these mistakes are the #1 cause of failed`,
+        `runs:`,
+        ``,
+        `  1. Do NOT call browser_navigate to a URL that is already the active tab.`,
+        `     The widget that hosts this session lives inside the page; reloading the`,
+        `     page kills the WebSocket connection and your run gets aborted mid-flight.`,
+        ``,
+        activeOrigin
+            ? `  2. Do NOT call browser_navigate to ANY path on origin ${activeOrigin}`
+            : `  2. Do NOT call browser_navigate to source-file paths on the dev server`,
+        `     just to "read source code for hints" — paths like /src/Login.tsx,`,
+        `     /@vite/client, /node_modules/* are served by Vite as JS modules and`,
+        `     loading them triggers the same widget-killing reload. To inspect the`,
+        `     page, use browser_snapshot — the accessibility tree already exposes`,
+        `     labels, placeholders, and roles.`,
+        ``,
+        `  3. Do NOT read the JS bundle, evaluate page source, or scrape DOM for`,
+        `     hardcoded credentials, API keys, or secrets. If the task needs login,`,
+        `     the user must provide credentials in their prompt; if they didn't,`,
+        `     report "no credentials provided" and stop — do not guess.`,
+        ``,
+        `  4. To see the current page state, call browser_snapshot first. Only`,
+        `     navigate if you actually need a different URL.`,
+        ``,
+        `Narration format — affects how the widget renders your run for the user:`,
+        ``,
+        `  Before each LOGICAL STEP (a coherent unit of work like "Open the login`,
+        `  form", "Fill credentials", "Verify the welcome message"), emit ONE short`,
+        `  imperative sentence describing what you're about to do — present tense,`,
+        `  3–8 words, no markdown. The widget uses that sentence as the step's title.`,
+        ``,
+        `  Good examples:`,
+        `    "Open the login form."`,
+        `    "Fill credentials and submit."`,
+        `    "Verify the welcome message."`,
+        `    "Now testing the Counter section."`,
+        ``,
+        `  Bad examples (too verbose / too vague):`,
+        `    "Let me check the current state of the app and then drive the login flow."`,
+        `    "First, I'll take a snapshot, then I'll look at the page structure, and..."`,
+        ``,
+        `  After the run, if you discovered bugs or unexpected behavior, summarize`,
+        `  them in the FINAL message using these markers so the widget can extract`,
+        `  them into a Findings card:`,
+        ``,
+        `    ## Findings`,
+        `    - **Bug** — <one-line summary>`,
+        `    - **Minor** — <one-line summary>`,
+        ``,
+        `  Do NOT spread bug discoveries across mid-run narration — keep them in the`,
+        `  final summary so they group cleanly. Mid-run, just narrate the next step.`,
+    ].join('\n');
+}

package/dist/service/saveHandlers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Save-artifact WebSocket handlers (skill / spec / Jira CSV).
+ *
+ * All three save-* messages share the same shape: validate `name + steps`,
+ * call a per-kind writer, fork on Exists-error vs. success. The differences
+ * (which writer, which message names, which fields to pluck, skill's
+ * "push a fresh skills-list afterwards" tail) are captured in the
+ * `SaveArtifactConfig` descriptor table below.
+ *
+ * Replaces three near-identical handlers that drifted apart over time —
+ * see the v0.2.x refactor pass for the full rationale.
+ */
+import type { WebSocket } from 'ws';
+import { writeSkill, type SkillStep } from '../skills/writeSkill.js';
+import { writeSpec, type SpecAssertion } from '../specs/writeSpec.js';
+import { writeCaseCsv } from '../specs/writeCaseCsv.js';
+import { type ClientMessage } from './types.js';
+interface SaveArtifactConfig<TWriteResult extends {
+    slug: string;
+    path: string;
+}> {
+    /** Used in error messages. Mirrors the WS `type` the client sent. */
+    requestName: string;
+    /** Emitted on success. */
+    savedType: string;
+    /** Emitted when the writer threw an Exists-error. */
+    existsType: string;
+    /** Optional — fires after a successful write. Used by the skill flow to
+     *  push a refreshed `skills-list` to the widget. */
+    onSaved?: (ws: WebSocket, devRoot: string) => Promise<void>;
+    /** Class used in `err instanceof …` to detect "already exists" errors. */
+    ExistsError: new (...args: never[]) => {
+        slug: string;
+        path: string;
+    } & Error;
+    /** Pluck the payload fields this artifact needs and call its writer. */
+    write: (args: {
+        devRoot: string;
+        name: string;
+        description: string;
+        steps: SkillStep[];
+        assertions: SpecAssertion[];
+        payload: NonNullable<ClientMessage['payload']>;
+        overwrite: boolean;
+    }) => Promise<TWriteResult>;
+}
+export declare function handleSaveArtifact<TWriteResult extends {
+    slug: string;
+    path: string;
+}>(ws: WebSocket, msg: ClientMessage, devRoot: string, cfg: SaveArtifactConfig<TWriteResult>): Promise<void>;
+export declare const SKILL_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeSkill>>>;
+export declare const SPEC_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeSpec>>>;
+export declare const CASE_CSV_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeCaseCsv>>>;
+export {};
+//# sourceMappingURL=saveHandlers.d.ts.map

package/dist/service/saveHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saveHandlers.d.ts","sourceRoot":"","sources":["../../src/service/saveHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,UAAU,EAAgC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAE,SAAS,EAAmB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAsB,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD,UAAU,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9E,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB;wDACoD;IACpD,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IAC9E,wEAAwE;IACxE,KAAK,EAAE,CAAC,IAAI,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,UAAU,EAAE,aAAa,EAAE,CAAC;QAC5B,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,SAAS,EAAE,OAAO,CAAC;KACpB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7B;AAED,wBAAsB,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC1F,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,kBAAkB,CAAC,YAAY,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,eAAO,MAAM,YAAY,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAanF,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAOjF,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAYxF,CAAC"}

package/dist/service/saveHandlers.js

@@ -0,0 +1,80 @@
+/**
+ * Save-artifact WebSocket handlers (skill / spec / Jira CSV).
+ *
+ * All three save-* messages share the same shape: validate `name + steps`,
+ * call a per-kind writer, fork on Exists-error vs. success. The differences
+ * (which writer, which message names, which fields to pluck, skill's
+ * "push a fresh skills-list afterwards" tail) are captured in the
+ * `SaveArtifactConfig` descriptor table below.
+ *
+ * Replaces three near-identical handlers that drifted apart over time —
+ * see the v0.2.x refactor pass for the full rationale.
+ */
+import { writeSkill, listSkills, SkillExistsError } from '../skills/writeSkill.js';
+import { writeSpec, SpecExistsError } from '../specs/writeSpec.js';
+import { writeCaseCsv, CaseCsvExistsError } from '../specs/writeCaseCsv.js';
+import { send } from './types.js';
+export async function handleSaveArtifact(ws, msg, devRoot, cfg) {
+    const name = msg.payload?.name;
+    const description = msg.payload?.description ?? '';
+    const steps = msg.payload?.steps;
+    const assertions = msg.payload?.assertions ?? [];
+    const overwrite = msg.payload?.overwrite === true;
+    if (typeof name !== 'string' || !name.trim()) {
+        send(ws, { type: 'error', payload: { message: `${cfg.requestName}: name is required` } });
+        return;
+    }
+    if (!Array.isArray(steps) || steps.length === 0) {
+        send(ws, { type: 'error', payload: { message: `${cfg.requestName}: no steps to save` } });
+        return;
+    }
+    try {
+        const result = await cfg.write({
+            devRoot, name, description, steps, assertions,
+            payload: msg.payload, overwrite,
+        });
+        send(ws, { type: cfg.savedType, payload: { name: result.slug, path: result.path } });
+        if (cfg.onSaved)
+            await cfg.onSaved(ws, devRoot);
+    }
+    catch (err) {
+        if (err instanceof cfg.ExistsError) {
+            send(ws, { type: cfg.existsType, payload: { slug: err.slug, existingPath: err.path } });
+            return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        send(ws, { type: 'error', payload: { message: `${cfg.requestName} failed: ${message}` } });
+    }
+}
+export const SKILL_CONFIG = {
+    requestName: 'save-skill',
+    savedType: 'skill-saved',
+    existsType: 'skill-exists',
+    ExistsError: SkillExistsError,
+    write: ({ devRoot, name, description, steps, overwrite }) => writeSkill({ devRoot, name, description, steps, overwrite }),
+    onSaved: async (ws, devRoot) => {
+        // Push a fresh list so the widget's skills overlay updates without a
+        // round-trip — most relevant right after the save.
+        const skills = await listSkills(devRoot);
+        send(ws, { type: 'skills-list', payload: { skills } });
+    },
+};
+export const SPEC_CONFIG = {
+    requestName: 'save-spec',
+    savedType: 'spec-saved',
+    existsType: 'spec-exists',
+    ExistsError: SpecExistsError,
+    write: ({ devRoot, name, description, steps, assertions, overwrite }) => writeSpec({ devRoot, name, description, steps, assertions, overwrite }),
+};
+export const CASE_CSV_CONFIG = {
+    requestName: 'save-case-csv',
+    savedType: 'case-csv-saved',
+    existsType: 'case-csv-exists',
+    ExistsError: CaseCsvExistsError,
+    write: ({ devRoot, name, description, steps, assertions, payload, overwrite }) => writeCaseCsv({
+        devRoot, name, description, steps, assertions,
+        jiraProjectKey: payload.jiraProjectKey,
+        labels: payload.labels,
+        overwrite,
+    }),
+};

package/dist/service/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared types for the service/ handler modules.
+ *
+ * `ClientMessage` describes the wire-protocol envelope every message from
+ * the widget arrives in. Lives here (not in service.ts) so individual
+ * handlers can type their `msg` argument without circular imports.
+ *
+ * `send` is the one-liner used by every handler to emit a typed message
+ * back to the widget. Centralised so the JSON.stringify happens in exactly
+ * one place.
+ */
+import type { WebSocket } from 'ws';
+import type { SkillStep } from '../skills/writeSkill.js';
+import type { SpecAssertion } from '../specs/writeSpec.js';
+export interface ClientMessage {
+    type: string;
+    payload?: {
+        text?: string;
+        sessionId?: string;
+        name?: string;
+        description?: string;
+        steps?: SkillStep[];
+        assertions?: SpecAssertion[];
+        overwrite?: boolean;
+        /** save-case-csv only — passed through to writeCaseCsv as extra
+         *  fields on the test case's Labels column. */
+        jiraProjectKey?: string;
+        labels?: string;
+        /** check-cdp / launch-chrome / focus-debug — the widget's
+         *  window.location.href so service can compare origins or navigate the
+         *  newly-launched debug Chrome to the same URL. */
+        pageUrl?: string;
+        /** switch-agent only — id of the agent to switch the service to. */
+        agentId?: string;
+    };
+}
+export declare function send(ws: WebSocket, message: {
+    type: string;
+    payload?: unknown;
+}): void;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF"}

package/dist/service/types.js

@@ -0,0 +1,14 @@
+/**
+ * Shared types for the service/ handler modules.
+ *
+ * `ClientMessage` describes the wire-protocol envelope every message from
+ * the widget arrives in. Lives here (not in service.ts) so individual
+ * handlers can type their `msg` argument without circular imports.
+ *
+ * `send` is the one-liner used by every handler to emit a typed message
+ * back to the widget. Centralised so the JSON.stringify happens in exactly
+ * one place.
+ */
+export function send(ws, message) {
+    ws.send(JSON.stringify(message));
+}

package/dist/service.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAmEA,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;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmT/E"}