@hover-dev/core 0.14.1 → 0.15.0

package/dist/service.d.ts

@@ -4,13 +4,16 @@ export interface ServiceOptions {
     agentId?: string;
     model?: string;
     maxBudgetUsd?: number;
+    /** How the optimization pass (F7) surfaces in the widget. Default 'suggest'.
+     *  'off' = no nudge, 'suggest' = ✦ hint, 'on' = auto-run after Save-as-spec. */
+    optimizeMode?: 'off' | 'suggest' | 'on';
     mcpConfig?: string;
     /** CDP URL to preflight before each command (default http://localhost:9222). */
     cdpUrl?: string;
-    /** Working directory for the spawned agent. Also where skills are saved
-     *  ('<devRoot>/.claude/skills/<slug>/SKILL.md'). Defaults to process.cwd().
-     *  In Vite plugin context, set to `server.config.root` so Claude
-     *  auto-discovers skills the user previously saved from this project. */
+    /** Working directory for the spawned agent. Also the root under which saved
+     *  specs (`__vibe_tests__/`), sidecars + seeds (`.hover/`) live. Defaults to
+     *  process.cwd(); in Vite plugin context, set to `server.config.root` so the
+     *  agent runs against the project (and Claude Code reads its CLAUDE.md). */
     devRoot?: string;
     /** Plugins contributed by the bundler-plugin wrapper. Each manifest can
      *  add a widget mode, MCP servers, Chrome flags, and lifecycle hooks.

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA8EA,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;IAChC;;;;;;uEAMmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;wDAEoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAs2B/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;oFACgF;IAChF,YAAY,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;gFAG4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;;;;uEAMmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;wDAEoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA64B/E"}

package/dist/service.js

@@ -10,10 +10,8 @@
  *     { type: 'hello',           payload: { agentId, model, version } }
  *     { type: 'event',           payload: InvokeEvent }              // see agents/types.ts
  *     { type: 'cdp-status',      payload: { state, reason?, matchingTabUrl?, browser?, launching? } }
- *     { type: 'skill-saved',     payload: { name, path } }
- *     { type: 'skill-exists',    payload: { slug, existingPath } }
- *     { type: 'skills-list',     payload: { skills: SkillSummary[] } }
  *     { type: 'specs-list',      payload: { specs: SpecSummary[] } }
+ *     { type: 'seeds-list',      payload: { seeds: { name, note, signature, code, source }[] } }
  *     { type: 'spec-saved',      payload: { name, path } }
  *     { type: 'spec-exists',     payload: { slug, existingPath } }
  *     { type: 'case-csv-saved',  payload: { name, path } }
@@ -31,11 +29,10 @@
  *     { type: 'check-cdp',     payload: { pageUrl } }                 // "is this widget in the debug Chrome?"
  *     { type: 'launch-chrome', payload: { pageUrl } }                 // start debug Chrome, navigate to pageUrl
  *     { type: 'focus-debug',   payload: { pageUrl } }                 // bringToFront the matching tab in debug Chrome
- *     { type: 'save-skill',    payload: { name, description, steps, overwrite? } }
  *     { type: 'save-spec',     payload: { name, description, steps, assertions?, overwrite? } }
  *     { type: 'save-case-csv', payload: { name, description, steps, assertions?, jiraProjectKey?, labels?, overwrite? } }
- *     { type: 'list-skills' }
  *     { type: 'list-specs' }                                            // ask for every spec under __vibe_tests__/, with parsed JSDoc headers
+ *     { type: 'list-seeds' }                                            // ask for built-in + .hover/rules/ translation seeds (read-only)
  *     { type: 'list-agents' }                                          // ask for the full agent registry + install status
  *     { type: 'switch-agent',  payload: { agentId } }                  // set the service's current agent; broadcasts to all connections
  *
@@ -49,18 +46,21 @@
  *     { type: 'list-modes' }
  */
 import { WebSocketServer, WebSocket } from 'ws';
-import { invokeAgent } from './agents/invoke.js';
+import { runSession } from './runSession.js';
+import { readConventions } from './service/conventions.js';
+import { optimizeSpecWithAgent } from './specs/optimizeSpecWithAgent.js';
+import { promoteOptimized, discardOptimized } from './specs/optimizeSpec.js';
 import { listAgentAvailability, pickPrimaryAgent, } from './agents/detect.js';
 import { getAgent } from './agents/registry.js';
 import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
 import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
 import { launchDebugChrome } from './playwright/launchChrome.js';
-import { listSkills } from './skills/writeSkill.js';
 import { listSpecs } from './specs/listSpecs.js';
+import { readSeeds, BUILTIN_SEEDS } from './specs/seeds.js';
 import { send, sendIfOpen } from './service/types.js';
 import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
 import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
-import { handleSaveArtifact, SKILL_CONFIG, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
+import { handleSaveArtifact, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
 import { CURRENT_API_VERSION, } from './plugin-api.js';
 // ClientMessage + send moved to ./service/types.ts so the cdp + save
 // handler modules can share them. See those files for the wire shape.
@@ -129,6 +129,11 @@ export async function startService(opts) {
     const preferred = opts.agentId ?? process.env.HOVER_AGENT;
     const primary = await pickPrimaryAgent(preferred);
     let currentAgentId = primary?.descriptor.id ?? preferred ?? 'claude';
+    // Optional model API key the widget supplied (set-api-key). Held in memory
+    // for this service's lifetime only — never written to disk, never logged.
+    // Injected into the spawned CLI's env so a user without a logged-in
+    // subscription can drive Hover on their own key.
+    let currentApiKey = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? undefined;
     if (!primary) {
         // Nothing installed — still bind so the widget can show a helpful
         // "install one of these" dialog. Commands will fail with
@@ -147,6 +152,7 @@ export async function startService(opts) {
     // so the user can hit Stop when they've seen enough. Pass maxBudgetUsd
     // explicitly (or via the Vite plugin option) if a hard ceiling is needed.
     const maxBudgetUsd = opts.maxBudgetUsd;
+    const optimizeMode = opts.optimizeMode ?? 'suggest';
     const cdpUrl = opts.cdpUrl ?? 'http://localhost:9222';
     const devRoot = opts.devRoot ?? process.cwd();
     const wss = await pickAndBind('127.0.0.1', requestedPort, PORT_RETRIES);
@@ -384,7 +390,7 @@ export async function startService(opts) {
     wss.on('connection', ws => {
         send(ws, {
             type: 'hello',
-            payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION },
+            payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION, optimizeMode },
         });
         // Send the agent list as a follow-up event so the widget can render the
         // dropdown immediately on connect / reconnect (e.g. after HMR). The
@@ -531,13 +537,14 @@ export async function startService(opts) {
                 await broadcastAgents();
                 return;
             }
-            if (msg.type === 'save-skill') {
-                await handleSaveArtifact(ws, msg, devRoot, SKILL_CONFIG);
-                return;
-            }
-            if (msg.type === 'list-skills') {
-                const skills = await listSkills(devRoot);
-                send(ws, { type: 'skills-list', payload: { skills } });
+            if (msg.type === 'set-api-key') {
+                // The widget supplies (or clears) a model API key. Stored in memory
+                // only and injected into the spawned CLI's env at invoke time — never
+                // persisted, never logged, never echoed back. Empty/missing clears it.
+                const key = msg.payload?.key;
+                currentApiKey = typeof key === 'string' && key.trim() ? key.trim() : undefined;
+                const envVar = getAgent(currentAgentId)?.apiKeyEnv;
+                send(ws, { type: 'api-key-status', payload: { hasKey: !!currentApiKey, envVar } });
                 return;
             }
             if (msg.type === 'list-specs') {
@@ -549,6 +556,21 @@ export async function startService(opts) {
                 send(ws, { type: 'specs-list', payload: { specs } });
                 return;
             }
+            if (msg.type === 'list-seeds') {
+                // Widget's Seeds tab: show which translation seeds Hover sees — the
+                // built-in set + whatever the user dropped in <devRoot>/.hover/rules/.
+                // Read-only; users add seeds by hand (no download path).
+                const builtinNames = new Set(BUILTIN_SEEDS.map(s => s.name));
+                const seeds = (await readSeeds(devRoot)).map(s => ({
+                    name: s.name,
+                    note: s.note ?? '',
+                    signature: s.signature,
+                    code: s.example?.code ?? '',
+                    source: builtinNames.has(s.name) ? 'builtin' : 'project',
+                }));
+                send(ws, { type: 'seeds-list', payload: { seeds } });
+                return;
+            }
             if (msg.type === 'save-spec') {
                 await handleSaveArtifact(ws, msg, devRoot, SPEC_CONFIG);
                 return;
@@ -557,6 +579,55 @@ export async function startService(opts) {
                 await handleSaveArtifact(ws, msg, devRoot, CASE_CSV_CONFIG);
                 return;
             }
+            // Stage 7 (F7) widget flow: optimize a saved spec, then promote/discard
+            // the candidate after the human reviews the diff. optimizeSpecWithAgent
+            // spawns the codegen LLM (no browser, no MCP); the original spec is never
+            // touched until an explicit promote.
+            if (msg.type === 'optimize-spec') {
+                const slug = msg.payload?.slug;
+                if (typeof slug !== 'string' || !slug) {
+                    send(ws, { type: 'error', payload: { message: 'optimize-spec: slug is required' } });
+                    return;
+                }
+                try {
+                    const res = await optimizeSpecWithAgent(devRoot, slug, {
+                        agentId: currentAgentId, model, maxBudgetUsd, apiKey: currentApiKey,
+                    });
+                    send(ws, { type: 'optimize-result', payload: { slug, original: res.original, candidate: res.code } });
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    send(ws, { type: 'optimize-failed', payload: { slug, reason } });
+                }
+                return;
+            }
+            if (msg.type === 'promote-optimized') {
+                const slug = msg.payload?.slug;
+                if (typeof slug !== 'string' || !slug) {
+                    send(ws, { type: 'error', payload: { message: 'promote-optimized: slug is required' } });
+                    return;
+                }
+                try {
+                    const path = await promoteOptimized(devRoot, slug);
+                    send(ws, { type: 'optimized-promoted', payload: { slug, path } });
+                    send(ws, { type: 'specs-list', payload: { specs: await listSpecs(devRoot) } });
+                }
+                catch (err) {
+                    const m = err instanceof Error ? err.message : String(err);
+                    send(ws, { type: 'error', payload: { message: `promote-optimized: ${m}` } });
+                }
+                return;
+            }
+            if (msg.type === 'discard-optimized') {
+                const slug = msg.payload?.slug;
+                if (typeof slug !== 'string' || !slug) {
+                    send(ws, { type: 'error', payload: { message: 'discard-optimized: slug is required' } });
+                    return;
+                }
+                await discardOptimized(devRoot, slug);
+                send(ws, { type: 'optimized-discarded', payload: { slug } });
+                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`
@@ -609,11 +680,11 @@ export async function startService(opts) {
                 ? msg.payload.sessionId
                 : undefined;
             // Re-record mode: when the client (widget Specs tab or hover CLI)
-            // passes `reRecord: { slug }`, we collect tool_use events server-side
-            // into a SkillStep[] and, on session_end with no error, overwrite the
-            // existing __vibe_tests__/<slug>.spec.ts. This is the same flow the
-            // widget uses for "Save as Spec", but the spec already exists and is
-            // being regenerated for the current UI.
+            // passes `reRecord: { slug }`, runSession collects the tool_use events
+            // into a SpecStep[] and, on a clean finish, we overwrite the existing
+            // __vibe_tests__/<slug>.spec.ts. Same flow the widget uses for "Save as
+            // Spec", but the spec already exists and is being regenerated for the
+            // current UI.
             const reRecordSlug = msg.payload && typeof msg.payload === 'object' && 'reRecord' in msg.payload
                 ? msg.payload.reRecord?.slug
                 : undefined;
@@ -629,16 +700,6 @@ export async function startService(opts) {
             busy = true;
             cancelled = false;
             inflight = new AbortController();
-            // Re-record step collector — populated as tool_use events stream by,
-            // consumed at session_end to overwrite the original spec. Empty unless
-            // reRecordSlug is set on this command. We seed with a synthetic
-            // `user` step so writeSpec's JSDoc Original-prompt: line carries the
-            // text the agent was actually given (which is the prompt we read out
-            // of the existing spec — the same one we're regenerating).
-            const reRecordSteps = [];
-            if (reRecordSlug) {
-                reRecordSteps.push({ kind: 'user', text });
-            }
             try {
                 // Build the MCP config first — it's pure local file IO and lets
                 // us assert plugin-contributed servers landed in the config even
@@ -682,6 +743,15 @@ export async function startService(opts) {
                 let appendSystemPrompt = resumeSessionId
                     ? buildCdpHintResume(cdp.tabs)
                     : buildCdpHint(cdp.tabs);
+                // Knowledge layer (F5): on the first turn, fold in the project's
+                // .hover/conventions.md (static, like cdpHint's rules — skipped on
+                // resume to keep the prompt cache intact). The service reads the file;
+                // the agent never gains filesystem access (D2).
+                if (!resumeSessionId) {
+                    const conventions = await readConventions(devRoot);
+                    if (conventions)
+                        appendSystemPrompt = `${appendSystemPrompt}\n\n${conventions}`;
+                }
                 // Add plugin-contributed prompt additions whose scope includes the
                 // current mode (or '*' for always-on). Walks ALL loaded plugins,
                 // not just the active-mode plugin — a plugin that contributes
@@ -714,16 +784,9 @@ export async function startService(opts) {
                 }
                 // Snapshot the agent id so a switch-agent message during the run
                 // can't smear two agents across one invocation. (We also gate
-                // switch-agent on `busy`, but defense in depth.)
+                // switch-agent on `busy`, but defense in depth.) runSession gates the
+                // allow/deny lists on the agent's sandboxStrength internally.
                 const invokedAgentId = currentAgentId;
-                const invokedDescriptor = getAgent(invokedAgentId);
-                // Only Claude's `--allowedTools`/`--disallowedTools` flags are
-                // honoured — passing them to a soft-sandbox agent like codex is a
-                // no-op (its buildArgs ignores them). We still gate at the service
-                // layer for clarity: a hard-sandbox agent gets the tight allowlist,
-                // a soft one gets nothing and relies on its descriptor's built-in
-                // sandbox flags + developer_instructions.
-                const isHardSandbox = invokedDescriptor?.sandboxStrength === 'hard';
                 // Active mode's plugin-contributed MCP server ids — added to the
                 // hard-sandbox allow list so Claude can actually call them. Claude
                 // sanitises non-alphanumeric chars in the id when forming tool
@@ -743,87 +806,61 @@ export async function startService(opts) {
                         }
                     }
                 }
-                for await (const ev of invokeAgent({
+                const runResult = await runSession({
                     agentId: invokedAgentId,
                     prompt: text,
                     sessionId: resumeSessionId,
                     mcpConfig,
-                    // cwd = devRoot so Claude Code auto-discovers `.claude/skills/`
-                    // saved from this project (and CLAUDE.md, if any).
+                    // cwd = devRoot so the agent runs against the project (and Claude
+                    // Code reads its CLAUDE.md, if any).
                     cwd: devRoot,
                     appendSystemPrompt,
-                    // Skill stays in the allow list so saved skills under
-                    // <devRoot>/.claude/skills/ can be invoked. mcp__playwright covers
-                    // every browser tool. Plugin-contributed MCPs are appended when
-                    // the corresponding mode is active.
-                    allowedTools: isHardSandbox
-                        ? ['mcp__playwright', 'Skill', ...activePluginMcpIds]
-                        : undefined,
-                    disallowedTools: isHardSandbox
-                        ? (invokedDescriptor?.defaultDisallowedTools
-                            ? [...invokedDescriptor.defaultDisallowedTools]
-                            : undefined)
-                        : undefined,
+                    // mcp__playwright covers every browser tool; active-mode plugin MCP
+                    // servers are appended. (Save-as-Skill retired → no Skill tool.)
+                    allowedToolsExtra: activePluginMcpIds,
                     maxBudgetUsd,
                     model,
+                    apiKey: currentApiKey,
                     signal: inflight.signal,
-                })) {
+                }, (ev) => {
                     if (cancelled || ws.readyState !== WebSocket.OPEN)
                         return;
                     send(ws, { type: 'event', payload: ev });
-                    // Re-record collection. Mirror what widget client.js does on the
-                    // way past tool_use events: accumulate into a SkillStep[] so we
-                    // can write a fresh spec when the session ends. We do this only
-                    // when this command was launched in re-record mode; ordinary
-                    // commands don't need server-side step retention (widget owns
-                    // that for normal saves).
-                    if (reRecordSlug && ev.kind === 'tool_use') {
-                        reRecordSteps.push({
-                            kind: 'step',
-                            tool: ev.tool,
-                            input: ev.input,
+                });
+                // Re-record: write a fresh spec from the steps runSession accumulated
+                // (`user` → `step`* → `done`). Only on a clean, non-cancelled finish —
+                // a cancelled/aborted run throws out of runSession into the catch
+                // below, and an errored agent leaves the original spec untouched.
+                if (reRecordSlug && !cancelled) {
+                    if (runResult.isError) {
+                        sendIfOpen(ws, {
+                            type: 'error',
+                            payload: {
+                                message: `Re-record failed: ${runResult.summary || 'agent reported an error'}. ` +
+                                    `Original spec left unchanged.`,
+                            },
                         });
                     }
-                    if (reRecordSlug && ev.kind === 'session_end') {
-                        // Cancelled or errored runs: don't overwrite — the existing
-                        // spec is still valid. Tell the client what happened.
-                        if (ev.isError) {
+                    else {
+                        try {
+                            const { writeSpec } = await import('./specs/writeSpec.js');
+                            const written = await writeSpec({
+                                devRoot,
+                                name: reRecordSlug,
+                                steps: runResult.steps,
+                                overwrite: true,
+                            });
                             sendIfOpen(ws, {
-                                type: 'error',
-                                payload: {
-                                    message: `Re-record failed: ${ev.summary ?? 'agent reported an error'}. ` +
-                                        `Original spec left unchanged.`,
-                                },
+                                type: 'spec-saved',
+                                payload: { name: reRecordSlug, path: written.path },
                             });
                         }
-                        else {
-                            // Snapshot the agent's final summary into a synthetic `done`
-                            // step so writeSpec's `Outcome:` header reflects the new run.
-                            if (ev.summary) {
-                                reRecordSteps.push({ kind: 'done', summary: ev.summary });
-                            }
-                            // Overwrite. writeSpec uses the slug to name the file; we
-                            // pass the original slug verbatim so the path is stable.
-                            try {
-                                const { writeSpec } = await import('./specs/writeSpec.js');
-                                const result = await writeSpec({
-                                    devRoot,
-                                    name: reRecordSlug,
-                                    steps: reRecordSteps,
-                                    overwrite: true,
-                                });
-                                sendIfOpen(ws, {
-                                    type: 'spec-saved',
-                                    payload: { name: reRecordSlug, path: result.path },
-                                });
-                            }
-                            catch (e) {
-                                const m = e instanceof Error ? e.message : String(e);
-                                sendIfOpen(ws, {
-                                    type: 'error',
-                                    payload: { message: `Re-record could not write spec: ${m}` },
-                                });
-                            }
+                        catch (e) {
+                            const m = e instanceof Error ? e.message : String(e);
+                            sendIfOpen(ws, {
+                                type: 'error',
+                                payload: { message: `Re-record could not write spec: ${m}` },
+                            });
                         }
                     }
                 }

package/dist/skills/writeSkill.d.ts

@@ -1,8 +1,15 @@
-export declare class SkillExistsError extends Error {
-    readonly slug: string;
-    readonly path: string;
-    constructor(slug: string, path: string);
-}
+/**
+ * Captured-step type.
+ *
+ * NOTE: Save-as-Skill (writing `.claude/skills/<slug>/SKILL.md` for agent
+ * replay) was retired — `spec` + ⟳ Re-record covers intent-driven replay, and
+ * "skill" collided with Claude Code's own skills concept. All that remains
+ * here is `SkillStep`: the serialized message shape from the widget's
+ * localStorage, which the whole spec pipeline (writeSpec, sidecar, listSpecs,
+ * Page-Object extraction) consumes as `SpecStep`. The file keeps its path so
+ * the many `import { SkillStep } from '../skills/writeSkill.js'` call sites
+ * don't churn; renaming to a neutral module is a separate mechanical pass.
+ */
 /**
  * Serialized message shape from the widget's localStorage. Matches the
  * `state.messages` schema in packages/widget-bootstrap/src/widget/client.js.
@@ -17,34 +24,4 @@ export interface SkillStep {
     costUsd?: number;
     summary?: string;
 }
-export interface WriteSkillOptions {
-    /** Directory under which `.claude/skills/<slug>/` is created. Usually the
-     *  Vite project root (`server.config.root`). */
-    devRoot: string;
-    name: string;
-    description?: string;
-    steps: SkillStep[];
-    /** If false (default), throws SkillExistsError when a skill with the same
-     *  slug already exists. If true, overwrites unconditionally. The widget
-     *  uses the two paths to give the user a confirm dialog. */
-    overwrite?: boolean;
-}
-export interface WriteSkillResult {
-    path: string;
-    slug: string;
-}
-export declare function writeSkill(opts: WriteSkillOptions): Promise<WriteSkillResult>;
-export interface SkillSummary {
-    slug: string;
-    name: string;
-    description: string;
-    path: string;
-}
-/**
- * List skills under <devRoot>/.claude/skills/, reading the YAML frontmatter
- * of each SKILL.md for `name` and `description`. Malformed entries are
- * silently skipped — better to show 9 valid skills than refuse to render
- * because one is broken. Hand-edited skills are first-class.
- */
-export declare function listSkills(devRoot: string): Promise<SkillSummary[]>;
 //# sourceMappingURL=writeSkill.d.ts.map

package/dist/skills/writeSkill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeSkill.d.ts","sourceRoot":"","sources":["../../src/skills/writeSkill.ts"],"names":[],"mappings":"AAmBA,qBAAa,gBAAiB,SAAQ,KAAK;aACb,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC;oDACgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoBnF;AA8ED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA8BzE"}
+{"version":3,"file":"writeSkill.d.ts","sourceRoot":"","sources":["../../src/skills/writeSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/skills/writeSkill.js

@@ -1,169 +1,13 @@
 /**
- * Save a completed Hover session as a Claude Code skill.
+ * Captured-step type.
  *
- * Writes a SKILL.md under `<devRoot>/.claude/skills/<slug>/`. When the agent
- * is later spawned with `cwd: devRoot`, Claude Code auto-discovers the skill
- * and can replay it when the user describes the same task in natural language
- * (e.g. "run the login-and-add-todo skill").
- *
- * Two reasons this is just-good-enough for v1:
- *  - The exact tool calls (with args) become numbered steps the agent can
- *    replay literally. Same dev server, same selectors → same outcome.
- *  - The original user prompt + AI outcome are preserved as prose. If the
- *    page changed and the literal selectors no longer apply, the agent has
- *    enough context to adapt rather than fail.
- */
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-export class SkillExistsError extends Error {
-    slug;
-    path;
-    constructor(slug, path) {
-        super(`Skill "${slug}" already exists at ${path}`);
-        this.slug = slug;
-        this.path = path;
-        this.name = 'SkillExistsError';
-    }
-}
-export async function writeSkill(opts) {
-    const slug = slugify(opts.name);
-    if (!slug) {
-        throw new Error('skill name must contain at least one alphanumeric character');
-    }
-    if (!opts.steps.some(s => s.kind === 'step')) {
-        throw new Error('skill must contain at least one tool_use step to replay');
-    }
-    const dir = join(opts.devRoot, '.claude', 'skills', slug);
-    const path = join(dir, 'SKILL.md');
-    if (!opts.overwrite && existsSync(path)) {
-        throw new SkillExistsError(slug, path);
-    }
-    await mkdir(dir, { recursive: true });
-    const md = renderSkill(slug, opts.description ?? '', opts.steps);
-    await writeFile(path, md, 'utf-8');
-    return { path, slug };
-}
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
-function renderSkill(slug, description, steps) {
-    const userMsg = steps.find(s => s.kind === 'user');
-    const doneMsg = [...steps].reverse().find(s => s.kind === 'done');
-    const toolSteps = steps.filter(s => s.kind === 'step');
-    const out = [];
-    out.push('---');
-    out.push(`name: ${slug}`);
-    // YAML description — quote if it contains anything that could confuse the parser
-    out.push(`description: ${yamlString(description || slug)}`);
-    out.push('---');
-    out.push('');
-    if (userMsg?.text) {
-        out.push('## Original intent');
-        out.push('');
-        out.push(blockquote(userMsg.text));
-        out.push('');
-    }
-    out.push('## Replay steps');
-    out.push('');
-    out.push('Replay these steps using the `mcp__playwright` tools, in order. ' +
-        'If a literal selector id (e.g. `e15`) no longer matches, interpret the ' +
-        'natural-language element description instead — selector ids regenerate on every snapshot.');
-    out.push('');
-    out.push('Do not narrate each step, do not summarize at the end. Hover surfaces ' +
-        'tool calls + the final result to the user automatically — extra commentary is noise.');
-    out.push('');
-    toolSteps.forEach((step, i) => {
-        const tool = step.tool ?? '(unknown)';
-        const inputStr = JSON.stringify(step.input ?? {});
-        const truncated = inputStr.length > 240 ? inputStr.slice(0, 237) + '…' : inputStr;
-        out.push(`${i + 1}. \`${tool}\` — \`${truncated}\``);
-    });
-    out.push('');
-    if (doneMsg?.summary) {
-        out.push('## Original outcome');
-        out.push('');
-        out.push(doneMsg.summary.trim());
-        out.push('');
-    }
-    return out.join('\n');
-}
-function yamlString(s) {
-    // Cheap quoting — if it has YAML-significant chars, double-quote and escape.
-    if (/[:#\n"'\\]/.test(s)) {
-        return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-    }
-    return s;
-}
-function blockquote(s) {
-    return s
-        .split('\n')
-        .map(line => `> ${line}`)
-        .join('\n');
-}
-/**
- * List skills under <devRoot>/.claude/skills/, reading the YAML frontmatter
- * of each SKILL.md for `name` and `description`. Malformed entries are
- * silently skipped — better to show 9 valid skills than refuse to render
- * because one is broken. Hand-edited skills are first-class.
+ * NOTE: Save-as-Skill (writing `.claude/skills/<slug>/SKILL.md` for agent
+ * replay) was retired — `spec` + ⟳ Re-record covers intent-driven replay, and
+ * "skill" collided with Claude Code's own skills concept. All that remains
+ * here is `SkillStep`: the serialized message shape from the widget's
+ * localStorage, which the whole spec pipeline (writeSpec, sidecar, listSpecs,
+ * Page-Object extraction) consumes as `SpecStep`. The file keeps its path so
+ * the many `import { SkillStep } from '../skills/writeSkill.js'` call sites
+ * don't churn; renaming to a neutral module is a separate mechanical pass.
  */
-export async function listSkills(devRoot) {
-    const root = join(devRoot, '.claude', 'skills');
-    let entries;
-    try {
-        entries = await readdir(root);
-    }
-    catch {
-        return [];
-    }
-    const skills = [];
-    for (const slug of entries) {
-        if (slug.startsWith('.'))
-            continue;
-        const path = join(root, slug, 'SKILL.md');
-        let content;
-        try {
-            content = await readFile(path, 'utf-8');
-        }
-        catch {
-            continue;
-        }
-        const fm = parseFrontmatter(content);
-        skills.push({
-            slug,
-            name: fm.name ?? slug,
-            description: fm.description ?? '',
-            path,
-        });
-    }
-    // Sort newest-first by mtime would require fs.stat; alpha is fine and stable.
-    skills.sort((a, b) => a.slug.localeCompare(b.slug));
-    return skills;
-}
-function parseFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match)
-        return {};
-    const out = {};
-    for (const line of match[1].split('\n')) {
-        const m = line.match(/^(\w+)\s*:\s*(.+)$/);
-        if (!m)
-            continue;
-        let value = m[2].trim();
-        // Strip wrapping quotes if present (yamlString() in renderSkill quotes
-        // strings with YAML-significant chars).
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value
-                .slice(1, -1)
-                .replace(/\\"/g, '"')
-                .replace(/\\\\/g, '\\');
-        }
-        out[m[1]] = value;
-    }
-    return out;
-}
+export {};