@hover-dev/core 0.2.0

package/dist/skills/writeSkill.js

@@ -0,0 +1,169 @@
+/**
+ * Save a completed Hover session as a Claude Code skill.
+ *
+ * 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.
+ */
+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;
+}

package/dist/specs/humanSteps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Translate the captured `browser_*` tool calls into plain English.
+ *
+ * Used by:
+ *   - writeSpec.ts — to enrich the generated `.spec.ts` JSDoc with a
+ *     numbered "Steps:" block that QA / PMs can read without grokking
+ *     `getByRole(...)`.
+ *   - writeCaseCsv.ts — to populate the Step column of an
+ *     Xray-compatible test case CSV, so the same prose travels into
+ *     Jira / Xray / Zephyr.
+ *
+ * Mirrors the tool dispatch table in writeSpec.ts:translateStep — when
+ * a new replayable browser action is added there, add it here too.
+ */
+import type { SkillStep } from '../skills/writeSkill.js';
+/** A single human-readable line for one tool call, or null to skip. */
+export declare function humanStep(tool: string, rawInput: unknown): string | null;
+/**
+ * Walk a captured session's step events and return a flat list of
+ * human-readable lines, with consecutive identical sentences collapsed
+ * into "<sentence> (× N)". Empty array if the session had no replayable
+ * tool calls (only diagnostics / text / done).
+ */
+export declare function humanSteps(steps: SkillStep[]): string[];
+//# sourceMappingURL=humanSteps.d.ts.map

package/dist/specs/humanSteps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwDxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}

package/dist/specs/humanSteps.js

@@ -0,0 +1,97 @@
+/** A single human-readable line for one tool call, or null to skip. */
+export function humanStep(tool, rawInput) {
+    const input = (rawInput ?? {});
+    switch (tool) {
+        case 'browser_navigate': {
+            const url = String(input.url ?? '').trim();
+            return url ? `Open ${url}` : null;
+        }
+        case 'browser_click':
+            return `Click ${describe(input.element)}`;
+        case 'browser_double_click':
+            return `Double-click ${describe(input.element)}`;
+        case 'browser_hover':
+            return `Hover over ${describe(input.element)}`;
+        case 'browser_type': {
+            const text = String(input.text ?? '');
+            return `Type ${quote(text)} into ${describe(input.element)}`;
+        }
+        case 'browser_fill_form': {
+            const fields = input.fields ?? [];
+            if (fields.length === 0)
+                return null;
+            // Join multi-field fills into one sentence to keep the Steps block
+            // compact on long forms. Per-field bullets would balloon a 7-step
+            // flow into 30 lines.
+            const parts = fields.map(raw => {
+                const f = raw;
+                const target = f.name ?? f.element ?? 'field';
+                return `${target}=${quote(String(f.value ?? ''))}`;
+            });
+            return `Fill ${parts.join(', ')}`;
+        }
+        case 'browser_select_option': {
+            const target = describe(input.element);
+            const values = input.values;
+            const val = (values && values.length > 0 ? values[0] : input.value) ?? '';
+            return `Select ${quote(String(val))} in ${target}`;
+        }
+        case 'browser_press_key': {
+            const key = String(input.key ?? '');
+            return key ? `Press ${key}` : null;
+        }
+        // Diagnostic / read-only — same skip list as writeSpec.translateStep.
+        case 'browser_wait_for':
+        case 'browser_tabs':
+        case 'browser_snapshot':
+        case 'browser_take_screenshot':
+        case 'browser_resize':
+        case 'browser_evaluate':
+        case 'browser_console_messages':
+        case 'browser_network_requests':
+            return null;
+        default:
+            // Unknown tools shouldn't pollute the prose; the spec emitter
+            // already drops a TODO comment in the code for these, that's
+            // enough signal for the developer.
+            return null;
+    }
+}
+/**
+ * Walk a captured session's step events and return a flat list of
+ * human-readable lines, with consecutive identical sentences collapsed
+ * into "<sentence> (× N)". Empty array if the session had no replayable
+ * tool calls (only diagnostics / text / done).
+ */
+export function humanSteps(steps) {
+    const out = [];
+    let lastSentence = null;
+    let repeatCount = 0;
+    for (const s of steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        const sentence = humanStep(s.tool, s.input);
+        if (sentence == null)
+            continue;
+        if (sentence === lastSentence) {
+            repeatCount += 1;
+            // Re-write the previous line with an incremented multiplier.
+            out[out.length - 1] = `${sentence} (× ${repeatCount + 1})`;
+        }
+        else {
+            out.push(sentence);
+            lastSentence = sentence;
+            repeatCount = 0;
+        }
+    }
+    return out;
+}
+// ───────── helpers ─────────
+function describe(raw) {
+    const s = String(raw ?? '').trim();
+    return s.length > 0 ? s : 'the target element';
+}
+/** Wrap in double-quotes for prose; escape internal quotes. */
+function quote(s) {
+    return `"${s.replace(/"/g, '\\"')}"`;
+}

package/dist/specs/writeCaseCsv.d.ts

@@ -0,0 +1,28 @@
+import type { SkillStep } from '../skills/writeSkill.js';
+import type { SpecAssertion } from './writeSpec.js';
+export declare class CaseCsvExistsError extends Error {
+    readonly slug: string;
+    readonly path: string;
+    constructor(slug: string, path: string);
+}
+export interface WriteCaseCsvOptions {
+    devRoot: string;
+    name: string;
+    description?: string;
+    steps: SkillStep[];
+    assertions?: SpecAssertion[];
+    /** Optional Jira project key prefix (e.g. "PROJ"). Goes into Labels so
+     *  the importer can route the test cases without rewriting the CSV.
+     *  Stripped of whitespace; if empty, no project label is added. */
+    jiraProjectKey?: string;
+    /** Free-form labels appended after the default "hover" label. Split
+     *  on commas/whitespace and lowercased. */
+    labels?: string;
+    overwrite?: boolean;
+}
+export interface WriteCaseCsvResult {
+    path: string;
+    slug: string;
+}
+export declare function writeCaseCsv(opts: WriteCaseCsvOptions): Promise<WriteCaseCsvResult>;
+//# sourceMappingURL=writeCaseCsv.d.ts.map

package/dist/specs/writeCaseCsv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeCaseCsv.d.ts","sourceRoot":"","sources":["../../src/specs/writeCaseCsv.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBzF"}

package/dist/specs/writeCaseCsv.js

@@ -0,0 +1,140 @@
+/**
+ * Save a completed Hover session as an Xray-compatible test case CSV
+ * (one file per session, multi-row layout — one row per replayable step).
+ *
+ * Target: Atlassian Marketplace's #1 test management for Jira (Xray,
+ * ~10M users, ~100M test cases / month). The same CSV imports cleanly
+ * into Zephyr Scale and the original Jira issue importer with minor
+ * column mapping, so this is the broadest single-format hand-off into
+ * a team's test management.
+ *
+ * Schema (Xray Test Case Importer — multi-row layout):
+ *
+ *   Issue Id        unique grouping key, repeated on every row of the
+ *                   same test case. We use the slug.
+ *   Summary         the test case title; set on the FIRST row only.
+ *   Test Type       "Manual" for everything Hover emits.
+ *   Priority        "Medium" by default; PMs can edit post-import.
+ *   Labels          space-separated; "hover" plus the user-supplied set.
+ *   Action          one human-readable imperative per row. Reuses the
+ *                   humanSteps helper that also feeds the .spec.ts JSDoc.
+ *   Expected Result attached to the LAST row of the case. Carries
+ *                   assertion hints if present, else the agent's
+ *                   done-summary first sentence.
+ *
+ * The "Issue Id" column is what tells Xray's importer that consecutive
+ * rows belong to the same test, even though only the first row has a
+ * Summary. The "Test Type" column tells it to instantiate the Manual
+ * Test issue type and use the Step / Expected Result fields.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { humanSteps } from './humanSteps.js';
+export class CaseCsvExistsError extends Error {
+    slug;
+    path;
+    constructor(slug, path) {
+        super(`Test case CSV "${slug}" already exists at ${path}`);
+        this.slug = slug;
+        this.path = path;
+        this.name = 'CaseCsvExistsError';
+    }
+}
+export async function writeCaseCsv(opts) {
+    const slug = slugify(opts.name);
+    if (!slug)
+        throw new Error('case name must contain at least one alphanumeric character');
+    if (!opts.steps.some(s => s.kind === 'step')) {
+        throw new Error('case must contain at least one tool step to describe');
+    }
+    const dir = join(opts.devRoot, '__vibe_tests__');
+    const path = join(dir, `${slug}.case.csv`);
+    if (!opts.overwrite && existsSync(path)) {
+        throw new CaseCsvExistsError(slug, path);
+    }
+    await mkdir(dir, { recursive: true });
+    const csv = renderCsv(slug, opts);
+    await writeFile(path, csv, 'utf-8');
+    return { path, slug };
+}
+// ───────── helpers ─────────
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function renderCsv(slug, opts) {
+    const rows = buildRows(slug, opts);
+    // CRLF row terminator — what Excel / Numbers / Xray's importer all
+    // assume by default. Comma column delimiter, fields with commas or
+    // newlines get wrapped in double-quotes (escaped by doubling).
+    const header = ['Issue Id', 'Summary', 'Test Type', 'Priority', 'Labels', 'Action', 'Expected Result'];
+    const lines = [header.map(escapeField).join(',')];
+    for (const r of rows)
+        lines.push(r.map(escapeField).join(','));
+    return lines.join('\r\n') + '\r\n';
+}
+function buildRows(slug, opts) {
+    const actions = humanSteps(opts.steps);
+    const summary = opts.description?.trim() || opts.name;
+    const expectedTail = expectedFor(opts.assertions ?? [], opts.steps);
+    const labels = buildLabels(opts.jiraProjectKey, opts.labels);
+    // Multi-row layout: one row per Action. First row carries the
+    // test-case-level fields (Summary, Test Type, Priority, Labels); the
+    // rest carry only the Issue Id + Action so Xray groups them.
+    if (actions.length === 0) {
+        // Defensive — writeCaseCsv() already throws on no replayable steps,
+        // but keep a single-row fallback so the file is still well-formed.
+        return [[slug, summary, 'Manual', 'Medium', labels, '(no replayable steps were captured)', expectedTail]];
+    }
+    const rows = [];
+    actions.forEach((action, i) => {
+        const isFirst = i === 0;
+        const isLast = i === actions.length - 1;
+        rows.push([
+            slug,
+            isFirst ? summary : '',
+            isFirst ? 'Manual' : '',
+            isFirst ? 'Medium' : '',
+            isFirst ? labels : '',
+            action,
+            isLast ? expectedTail : '',
+        ]);
+    });
+    return rows;
+}
+function expectedFor(assertions, steps) {
+    if (assertions.length > 0) {
+        return assertions.map(a => `• ${a.hint ?? a.code}`).join('\n');
+    }
+    const done = [...steps].reverse().find(s => s.kind === 'done');
+    if (done?.summary) {
+        return done.summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? done.summary.trim();
+    }
+    return '';
+}
+function buildLabels(jiraProjectKey, labels) {
+    const set = new Set(['hover']);
+    if (jiraProjectKey?.trim())
+        set.add(jiraProjectKey.trim().toLowerCase());
+    if (labels?.trim()) {
+        labels.split(/[\s,]+/).filter(Boolean).forEach(l => set.add(l.toLowerCase()));
+    }
+    // Xray and Jira both accept space-separated labels in a single cell.
+    return [...set].join(' ');
+}
+/**
+ * RFC 4180 escaping: any field containing a quote, comma, CR, or LF
+ * gets wrapped in double-quotes; embedded quotes are doubled.
+ */
+function escapeField(value) {
+    if (value === '')
+        return '';
+    if (/[",\r\n]/.test(value)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}

package/dist/specs/writeSpec.d.ts

@@ -0,0 +1,27 @@
+import type { SkillStep } from '../skills/writeSkill.js';
+export type SpecStep = SkillStep;
+export interface SpecAssertion {
+    /** Generated Playwright code (single line, no leading "await "). */
+    code: string;
+    /** Short human description for the spec comments. */
+    hint?: string;
+}
+export declare class SpecExistsError extends Error {
+    readonly slug: string;
+    readonly path: string;
+    constructor(slug: string, path: string);
+}
+export interface WriteSpecOptions {
+    devRoot: string;
+    name: string;
+    description?: string;
+    steps: SpecStep[];
+    assertions?: SpecAssertion[];
+    overwrite?: boolean;
+}
+export interface WriteSpecResult {
+    path: string;
+    slug: string;
+}
+export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
+//# sourceMappingURL=writeSpec.d.ts.map

package/dist/specs/writeSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBhF"}