@hover-dev/core 0.16.0 → 0.17.0

package/dist/specs/sidecar.js

@@ -1,29 +1,62 @@
 /**
  * Structured-session sidecar for a generated spec.
  *
- * Every saved spec gets a companion `__vibe_tests__/.hover/<slug>.json` holding
+ * Every saved spec gets a companion `.hover/sidecars/<slug>.json` holding
  * the original structured `SpecStep[]` (plus assertions + metadata). The
  * `.spec.ts` is the human / CI artifact; this sidecar is the machine record
  * that downstream work reads instead of parsing generated code:
  *   - F4 cross-session extraction signature-matches `steps` across sidecars.
  *   - F7 optimization pass feeds the draft + this sidecar to the LLM.
  *
- * It lands in a dot-prefixed `.hover/` dir so Playwright's default `*.spec.ts`
- * glob never collects it, and it is pure data — no Hover runtime import.
+ * Home is the project-root `.hover/` directory (the same home as
+ * `.hover/conventions.md`) — Hover-derived data lives outside
+ * `__vibe_tests__/`, which stays 100% user-owned Playwright code. Sidecars
+ * historically lived nested at `__vibe_tests__/.hover/<slug>.json`; readers
+ * fall back to that legacy path and lazily copy-forward, so pre-existing
+ * projects keep working without a migration step.
  */
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 /** Current sidecar schema version. Bump when the shape changes so readers
  *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
 export const SIDECAR_VERSION = 1;
-/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
- *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+/** Project-root `.hover/` directory — the single home for Hover-derived data
+ *  (sidecars, runs, rules, conventions). */
+export function hoverDir(devRoot) {
+    return join(devRoot, '.hover');
+}
+/** Sanitize an id segment for use as a directory name (conversation / run id). */
+export function safeSeg(s) {
+    return (s || '').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'unknown';
+}
+/** Per-run home: `<devRoot>/.hover/conversations/<conversationId>/<runId>/`.
+ *  Everything a single agent run produces — meta.json (the ledger record),
+ *  report.md (QA), screenshots/ — lives here, grouped under its conversation so
+ *  deleting a conversation is one `rm -rf .hover/conversations/<conversationId>`.
+ *  (Distinct from `.hover/runs/`, which is the Playwright spec-run-results
+ *  ledger written by ▶ Run.) */
+export function conversationsDir(devRoot) {
+    return join(hoverDir(devRoot), 'conversations');
+}
+export function conversationDir(devRoot, conversationId) {
+    return join(conversationsDir(devRoot), safeSeg(conversationId));
+}
+export function runDir(devRoot, conversationId, runId) {
+    return join(conversationDir(devRoot, conversationId), safeSeg(runId));
+}
+/** Sidecar directory: `<devRoot>/.hover/sidecars`. Outside `__vibe_tests__/`,
+ *  so Playwright's default `*.spec.ts` glob trivially never reaches it. */
 export function sidecarDir(devRoot) {
+    return join(hoverDir(devRoot), 'sidecars');
+}
+/** Pre-relocation sidecar home (`__vibe_tests__/.hover/`). Read-only fallback;
+ *  nothing writes here anymore. */
+export function legacySidecarDir(devRoot) {
     return join(devRoot, '__vibe_tests__', '.hover');
 }
-/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
- *  the data minus the stamped fields (`version`, `createdAt`), which this
- *  function fills. Returns the absolute path written. */
+/** Write the structured-session sidecar at `.hover/sidecars/<slug>.json`.
+ *  Caller passes the data minus the stamped fields (`version`, `createdAt`),
+ *  which this function fills. Returns the absolute path written. */
 export async function writeSidecar(devRoot, data) {
     const dir = sidecarDir(devRoot);
     await mkdir(dir, { recursive: true });
@@ -36,3 +69,40 @@ export async function writeSidecar(devRoot, data) {
     await writeFile(path, JSON.stringify(sidecar, null, 2) + '\n', 'utf-8');
     return path;
 }
+/**
+ * Read one sidecar by slug, with legacy fallback + lazy copy-forward: when a
+ * sidecar only exists at the pre-relocation `__vibe_tests__/.hover/` path it
+ * is parsed from there and best-effort re-written into `.hover/sidecars/` so
+ * the next read hits the new home. Returns `null` when absent or malformed.
+ */
+export async function readSidecar(devRoot, slug) {
+    const current = await parseSidecarFile(join(sidecarDir(devRoot), `${slug}.json`));
+    if (current)
+        return current;
+    const legacy = await parseSidecarFile(join(legacySidecarDir(devRoot), `${slug}.json`));
+    if (legacy) {
+        // Copy-forward, best effort — a read must never fail because the
+        // migration write did.
+        try {
+            const dir = sidecarDir(devRoot);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, `${slug}.json`), JSON.stringify(legacy, null, 2) + '\n', 'utf-8');
+        }
+        catch {
+            /* leave it in the legacy home */
+        }
+    }
+    return legacy;
+}
+/** Parse one sidecar file, or `null` when absent / not JSON. Deliberately
+ *  lenient on shape (an empty `{}` still counts as "a sidecar exists") —
+ *  consumers that need `steps`/`slug` filter for themselves. */
+export async function parseSidecarFile(path) {
+    try {
+        const sc = JSON.parse(await readFile(path, 'utf-8'));
+        return sc && typeof sc === 'object' ? sc : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/specs/specStep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The serialized captured-step shape the whole spec pipeline (writeSpec,
+ * sidecar, Page-Object extraction, the session record) consumes.
+ *
+ * One entry per recorded chat message: a user prompt, an agent narration, a
+ * `browser_*` / control-MCP tool call (`step`), or the terminal `done` summary.
+ * (Formerly `SkillStep` in specs/specStep.ts, back when a run could be saved
+ * as a `.claude/skills/<slug>/SKILL.md` — that feature was retired; only the
+ * type survived, now relocated here.)
+ */
+export interface SkillStep {
+    kind: 'user' | 'system' | 'step' | 'ai' | 'done';
+    text?: string;
+    tool?: string;
+    input?: unknown;
+    isError?: boolean;
+    turns?: number;
+    costUsd?: number;
+    summary?: string;
+}
+//# sourceMappingURL=specStep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specStep.d.ts","sourceRoot":"","sources":["../../src/specs/specStep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;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/specs/specStep.js

@@ -0,0 +1 @@
+export {};

package/dist/specs/text.d.ts

@@ -1,17 +1,19 @@
 /**
- * Small text helpers shared across the spec/CSV emitters.
+ * Small text helpers for the spec emitter.
  *
- * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
- * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
- * same way — they used to carry byte-identical copies of this logic.
+ * Hoisted here so writeSpec's JSDoc header derives a slug and a one-sentence
+ * "Expected" line through one shared implementation.
  */
 /** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
 export declare function slugify(name: string): string;
 /**
  * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
  * Expected blocks only want the leading sentence. Splits on the gap that
- * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
- * punctuation comes back trimmed in full.
+ * follows sentence-ending punctuation — Latin (`.`, `!`, `?`) AND CJK
+ * (`。`, `！`, `？`) so a Chinese summary doesn't dump its whole multi-line body
+ * (which then broke the JSDoc block). Also cuts at the first hard line break, so
+ * a summary that runs straight into a `\n\n- bullet` list keeps only the lead
+ * sentence. A summary with no such break comes back trimmed in full.
  */
 export declare function firstSentence(summary: string): string;
 //# sourceMappingURL=text.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/specs/text.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/specs/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD"}

package/dist/specs/text.js

@@ -1,9 +1,8 @@
 /**
- * Small text helpers shared across the spec/CSV emitters.
+ * Small text helpers for the spec emitter.
  *
- * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
- * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
- * same way — they used to carry byte-identical copies of this logic.
+ * Hoisted here so writeSpec's JSDoc header derives a slug and a one-sentence
+ * "Expected" line through one shared implementation.
  */
 /** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
 export function slugify(name) {
@@ -16,9 +15,13 @@ export function slugify(name) {
 /**
  * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
  * Expected blocks only want the leading sentence. Splits on the gap that
- * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
- * punctuation comes back trimmed in full.
+ * follows sentence-ending punctuation — Latin (`.`, `!`, `?`) AND CJK
+ * (`。`, `！`, `？`) so a Chinese summary doesn't dump its whole multi-line body
+ * (which then broke the JSDoc block). Also cuts at the first hard line break, so
+ * a summary that runs straight into a `\n\n- bullet` list keeps only the lead
+ * sentence. A summary with no such break comes back trimmed in full.
  */
 export function firstSentence(summary) {
-    return summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? summary.trim();
+    const bySentence = summary.split(/(?<=[.!?。！？])\s+/)[0] ?? summary;
+    return bySentence.split(/\n/)[0]?.trim() ?? summary.trim();
 }

package/dist/specs/writeSpec.d.ts

@@ -1,4 +1,4 @@
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 export type SpecStep = SkillStep;
 /**
  * Marker the deterministic translator leaves where a captured action is a real
@@ -24,6 +24,18 @@ export declare class SpecExistsError extends Error {
     readonly path: string;
     constructor(slug: string, path: string);
 }
+/**
+ * A credential to keep out of the generated spec. The deterministic translator
+ * replaces any fill value that exactly equals `value` with a
+ * `process.env.<envVar>` reference — so the literal password/username never
+ * lands in the spec source, the JSDoc header, OR the `.hover/` sidecar. The
+ * value comes from the caller (the editor resolves an `@account` mention from
+ * its vault); core only uses it to match-and-replace, never to write.
+ */
+export interface Redaction {
+    value: string;
+    envVar: string;
+}
 export interface WriteSpecOptions {
     devRoot: string;
     name: string;
@@ -31,10 +43,51 @@ export interface WriteSpecOptions {
     steps: SpecStep[];
     assertions?: SpecAssertion[];
     overwrite?: boolean;
+    /** Credentials to parameterize into `process.env.<envVar>` references. */
+    redactions?: Redaction[];
+    /** The run's target URL (the active environment / dev origin). Used to
+     *  guarantee the spec opens the app: if the captured session has NO
+     *  navigation (the agent connected to an already-open tab and never called
+     *  browser_navigate), a leading `page.goto()` is synthesized from this, and
+     *  it's the fallback origin for the scaffolded playwright config. */
+    startUrl?: string;
+    /** Recon-discovered reset recipe for the run's environment (debt-2 reproducible
+     *  state isolation). When tier 1, a shared `support/resetState.ts` helper is
+     *  generated and called in a `beforeEach` so the spec re-enters from a clean
+     *  client state every run. Tier 2/3 (backend-state) emit no reset here. (Engine
+     *  shape, decoupled from the extension's ResetRecipe — only tier/keys matter.) */
+    resetRecipe?: {
+        tier: number;
+        storageKeys?: string[];
+        hook?: string;
+    };
+    /** Auth-as-fixture (debt 3): engage the fixture EVEN WHEN a user playwright.config
+     *  already exists — i.e. the user approved Hover editing their config (Stage 4).
+     *  Without it, an existing config keeps login inline (Hover never edits a user's
+     *  config unprompted). When true, writeSpec also applies the setup-project edit
+     *  to the config. No effect when no login prefix is detected. */
+    authFixture?: boolean;
 }
 export interface WriteSpecResult {
+    /** Primary written file (the first flow when split, else the single spec). */
     path: string;
     slug: string;
+    /** Every file written — one per `mark_flow` feature when the run was split. */
+    files: {
+        path: string;
+        slug: string;
+        flow: string;
+    }[];
+    /** Auth-as-fixture (debt 3, Stage 4): a login was detected but a USER
+     *  playwright.config already exists, so Hover left login inline rather than
+     *  edit their config unprompted. This is the proposed edit to offer for
+     *  approval — on approval the caller re-saves with `authFixture: true`, which
+     *  applies it. Absent when there's no login, no user config, or the config
+     *  can't be safely edited (already has `projects`). */
+    authFixtureOffer?: {
+        configPath: string;
+        proposedConfig: string;
+    };
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
 /**
@@ -68,6 +121,14 @@ export declare function blockScope(lines: string[]): string[];
  * trailing role keyword is the convention Playwright MCP uses.
  */
 export declare function selectorFromDescription(desc: string, pageVar?: string): string;
+/**
+ * browser_select_option always targets a native `<select>` — whose ARIA role
+ * is `combobox`. The agent's description is usually the label ("marital
+ * status"), with no role keyword, so selectorFromDescription would fall back to
+ * getByText and match the *label text*, not the control — and `.selectOption()`
+ * on a text node throws. Force the combobox role by accessible name instead.
+ */
+export declare function selectorForSelect(desc: string, pageVar?: string): string;
 /**
  * Form fields from browser_fill_form have a `name` that's typically the
  * accessible name / label / aria-label. getByLabel is the right primitive.

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

@@ -1 +1 @@
-{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAWzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,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,CAiChF;AAuUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,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;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;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;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AA+mBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}