@hover-dev/core 0.2.1 → 0.2.4

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

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

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"}