@hover-dev/core 0.16.0 → 0.18.0

package/dist/sessions/sessions.js

@@ -0,0 +1,175 @@
+/**
+ * Session ledger — one summary JSON per completed agent run, appended under
+ * `.hover/sessions/`. The local console (S3) reads these for run history +
+ * spend; Hover Cloud sync (S4) uploads them as-is.
+ *
+ * Deliberately summary-only: full `SkillStep[]` lives in the spec sidecar for
+ * saved sessions and is dropped for unsaved ones (persisting unsaved
+ * transcripts is a privacy decision deferred to a future opt-in).
+ *
+ * Writes are best-effort: a ledger failure must never break a run or a save.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runDir, conversationsDir } from '../specs/sidecar.js';
+export const SESSION_RECORD_VERSION = 2;
+/** Unescape literal "\n" / "\r\n" / "\t" sequences (e.g. an agent double-escaped
+ *  its newlines) into real whitespace so markdown renders properly. */
+function deEsc(s) {
+    return s.replace(/\\r\\n/g, '\n').replace(/\\n/g, '\n').replace(/\\t/g, '  ');
+}
+/** Defensive leak-guard, NOT a parse path. The agent is directed to emit a
+ *  plain-markdown report (REPORTING_DIRECTIVE) — no JSON. A non-compliant agent
+ *  that still wraps its report in a ```json block would otherwise leak raw JSON
+ *  to the UI, so strip it: recover the `summary` field as prose when present
+ *  (tolerating unescaped quotes by matching up to `","findings"`), else drop the
+ *  block. Findings are NEVER extracted from JSON — they come only from the
+ *  markdown `## Findings` section below. */
+function stripJsonArtifact(summary) {
+    const block = summary.match(/```json\s*([\s\S]*?)```/i);
+    if (!block)
+        return summary;
+    const sm = block[1].match(/"summary"\s*:\s*"([\s\S]*?)"\s*,\s*"findings"/i);
+    if (sm)
+        return deEsc(sm[1].replace(/\\"/g, '"')).trim();
+    return summary.replace(block[0], '').replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * Strip leaked function-call syntax a model sometimes emits as TEXT instead of
+ * actually invoking the tool — e.g. a final summary that ends with
+ * `call\n<invoke name="mcp__playwright__browser_wait_for">…</invoke>`. The model
+ * "writes out" the call (a known tool-calling glitch, common at end-of-turn /
+ * budget cap) and the parser renders it verbatim into the report + Done card.
+ * This keeps user-facing prose about the APP, not Hover's tooling
+ * (REPORTING_DIRECTIVE). Defensive + total: any agent can trip this.
+ */
+export function stripToolCallNoise(text) {
+    return text
+        .replace(/<function_calls>[\s\S]*?<\/function_calls>/gi, '') // wrapper form
+        .replace(/<invoke\b[\s\S]*?<\/invoke>/gi, '') // closed call block
+        .replace(/<invoke\b[\s\S]*$/gi, '') // dangling (truncated) call
+        .replace(/<parameter\b[\s\S]*?<\/parameter>/gi, '') // stray parameter
+        .replace(/^[ \t]*call[ \t]*$/gim, '') // lone "call" lead-in line
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** Markdown-forced: the agent emits a plain-markdown report (REPORTING_DIRECTIVE)
+ *  — ONE outcome line, `- ` bullets, and an optional `## Findings` section with
+ *  `- **severity** — text` items. Parse the summary + findings from that markdown
+ *  only; a stray ```json block (a non-compliant agent) is stripped, never parsed
+ *  for findings and never leaked. Pure + total — no Findings block yields none. */
+export function parseFindings(summary) {
+    const cleaned = stripToolCallNoise(stripJsonArtifact(summary));
+    const lines = cleaned.split('\n');
+    let hi = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (/^#{1,6}\s*(findings|bugs|issues)\b/i.test(t) || /^findings\s*:/i.test(t)) {
+            hi = i;
+            break;
+        }
+    }
+    if (hi < 0)
+        return { summary: cleaned.trim(), findings: [] };
+    let j = hi + 1;
+    while (j < lines.length && lines[j].trim() === '')
+        j++;
+    const start = j;
+    while (j < lines.length && /^\s*[-*]\s+/.test(lines[j]))
+        j++;
+    const bullets = lines.slice(start, j);
+    const findings = [];
+    for (const line of bullets) {
+        const m = line.match(/^\s*[-*]\s+(?:\*\*\s*([^*]+?)\s*\*\*\s*[—–:-]?\s*)?([\s\S]+)$/);
+        if (!m)
+            continue;
+        const text = (m[2] || '').trim();
+        if (!text)
+            continue;
+        findings.push({ severity: (m[1] || 'note').trim(), text });
+    }
+    const main = lines.slice(0, hi).concat(lines.slice(j)).join('\n').replace(/\n{3,}/g, '\n\n').trim();
+    return { summary: main, findings };
+}
+/** Count tool_use steps by tool name for the `toolCounts` field. */
+export function tallyTools(steps) {
+    const counts = {};
+    for (const s of steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        counts[s.tool] = (counts[s.tool] ?? 0) + 1;
+    }
+    return counts;
+}
+/** Write one session record as `<runDir>/meta.json`. The id (runId) + the
+ *  conversation are decided by the caller at run start (so screenshots + report
+ *  share the folder). NEVER throws; returns the path or an error string. */
+export async function writeSessionRecord(devRoot, conversationId, runId, rec) {
+    try {
+        const dir = runDir(devRoot, conversationId, runId);
+        await mkdir(dir, { recursive: true });
+        const record = { version: SESSION_RECORD_VERSION, id: runId, conversationId, ...rec };
+        const path = join(dir, 'meta.json');
+        await writeFile(path, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+        return { path, id: runId };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** List every run's meta.json across all conversations: `.hover/runs/<conv>/<run>/meta.json`.
+ *  Best-effort; returns [] if no runs yet. */
+export async function listSessionRecords(devRoot) {
+    const out = [];
+    const root = conversationsDir(devRoot);
+    let convs;
+    try {
+        convs = await readdir(root);
+    }
+    catch {
+        return out;
+    }
+    for (const conv of convs) {
+        let runIds;
+        try {
+            runIds = await readdir(join(root, conv));
+        }
+        catch {
+            continue;
+        }
+        for (const rid of runIds) {
+            const path = join(root, conv, rid, 'meta.json');
+            try {
+                out.push({ path, rec: JSON.parse(await readFile(path, 'utf-8')) });
+            }
+            catch {
+                /* not a run dir / unreadable — skip */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Mark the session that produced `promptText` as crystallized: find the most
+ * recent record matching the prompt that has no `specSlug` yet, set
+ * `outcome: 'saved'` + the slug. Save-as-spec arrives as a separate WS message
+ * after the run record was already written, so this is a patch, keyed on the
+ * prompt (the `user` seed step) — tolerant by design; a miss is a no-op.
+ * NEVER throws.
+ */
+export async function markSessionSaved(devRoot, promptText, specSlug) {
+    try {
+        const records = (await listSessionRecords(devRoot)).sort((a, b) => String(b.rec.startedAt).localeCompare(String(a.rec.startedAt)));
+        for (const { path, rec } of records) {
+            if (rec.specSlug || rec.prompt !== promptText)
+                continue;
+            rec.outcome = 'saved';
+            rec.specSlug = specSlug;
+            await writeFile(path, JSON.stringify(rec, null, 2) + '\n', 'utf-8');
+            return;
+        }
+    }
+    catch {
+        /* no ledger yet / unreadable — fine */
+    }
+}

package/dist/specs/authFixture.d.ts

@@ -0,0 +1,30 @@
+import type { SkillStep } from './specStep.js';
+/**
+ * Length of the leading login prefix among `actions` (a spec's tool steps,
+ * POST-redaction). The login flow = the steps up to AND INCLUDING the submit
+ * click that follows the LAST credential fill (e.g. navigate → type email →
+ * type password → click "Sign in"). `envVars` are the redaction env-var names.
+ *
+ * Returns 0 when there are no redacted credentials, or none are filled in the
+ * steps — so a spec with no login keeps today's inline behavior unchanged (no
+ * regression). The caller slices `actions[0..N)` as the auth prefix and
+ * `actions[N..]` as the business flow.
+ */
+export declare function authPrefixLength(actions: SkillStep[], envVars: readonly string[]): number;
+/**
+ * Stage 4a — propose the playwright.config edit that registers the auth-fixture
+ * setup project. AST-based (ts-morph) so it only reprints what it touches and
+ * preserves the user's formatting. Adds:
+ *
+ *   projects: [
+ *     { name: 'setup', testMatch: /.*\.setup\.ts$/ },
+ *     { name: 'chromium', dependencies: ['setup'] },
+ *   ]
+ *
+ * Returns the edited source, or null when it can't safely edit — no config
+ * object found, or `projects` ALREADY exists (merging into a user's project
+ * matrix is risky; the caller degrades to the static paste hint instead). The
+ * edit is never applied here; the caller shows it for approval first.
+ */
+export declare function addSetupProjectToConfig(source: string): string | null;
+//# sourceMappingURL=authFixture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authFixture.d.ts","sourceRoot":"","sources":["../../src/specs/authFixture.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAiC/C;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAazF;AA0BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBrE"}

package/dist/specs/authFixture.js

@@ -0,0 +1,145 @@
+/**
+ * Auth-as-fixture (crystallization debt 3) — login-prefix detection.
+ *
+ * Today a recorded login is crystallized INLINE into every spec and re-run
+ * through the UI each test. The fix is to lift the login into a Playwright setup
+ * project that authenticates ONCE, save `storageState`, and have specs start
+ * already authenticated. The first, pure step is detecting which leading steps
+ * ARE the login flow — done here so it can be unit-tested in isolation, with no
+ * codegen changes (those land in later stages).
+ *
+ * Signal: `redactSteps` (writeSpec.ts) already rewrites credential values to
+ * `process.env.<envVar> ?? ''`, so the credential-bearing steps are exactly the
+ * fills whose value references one of the run's redaction env vars. The login
+ * prefix is the run of steps up to AND INCLUDING the submit click that follows
+ * the last credential fill.
+ *
+ * See docs/superpowers/specs/2026-06-24-auth-as-fixture.md.
+ */
+import { Project, SyntaxKind, Node } from 'ts-morph';
+const CLICK_TOOLS = new Set(['browser_click', 'click_control']);
+/** Bare tool name — grounded steps arrive as `mcp__hover-control__click_control`,
+ *  playwright ones as bare `browser_click`. */
+const bareTool = (t) => (t ?? '').replace(/^mcp__[a-z0-9_-]+?__/, '');
+/** The string values a fill-type action writes, across the tool variants
+ *  (browser_type / fill_control / select_control / browser_fill_form). */
+function fillValues(step) {
+    if (step.kind !== 'step' || !step.input)
+        return [];
+    const input = step.input;
+    const out = [];
+    if (typeof input.text === 'string')
+        out.push(input.text); // browser_type
+    if (typeof input.value === 'string')
+        out.push(input.value); // fill_control / select_control
+    if (Array.isArray(input.fields)) {
+        // browser_fill_form
+        for (const f of input.fields) {
+            if (f && typeof f.value === 'string')
+                out.push(f.value);
+        }
+    }
+    return out;
+}
+/** True when an action fills one of the redacted credential env refs. `actions`
+ *  are POST-redaction, so a credential value reads `process.env.<envVar> ?? ''`. */
+function fillsCredential(step, envVars) {
+    if (!envVars.length)
+        return false;
+    const values = fillValues(step);
+    return values.some((v) => envVars.some((name) => v.includes(`process.env.${name}`)));
+}
+/**
+ * Length of the leading login prefix among `actions` (a spec's tool steps,
+ * POST-redaction). The login flow = the steps up to AND INCLUDING the submit
+ * click that follows the LAST credential fill (e.g. navigate → type email →
+ * type password → click "Sign in"). `envVars` are the redaction env-var names.
+ *
+ * Returns 0 when there are no redacted credentials, or none are filled in the
+ * steps — so a spec with no login keeps today's inline behavior unchanged (no
+ * regression). The caller slices `actions[0..N)` as the auth prefix and
+ * `actions[N..]` as the business flow.
+ */
+export function authPrefixLength(actions, envVars) {
+    if (!envVars.length)
+        return 0;
+    let lastCred = -1;
+    for (let i = 0; i < actions.length; i++) {
+        if (fillsCredential(actions[i], envVars))
+            lastCred = i;
+    }
+    if (lastCred < 0)
+        return 0;
+    // Extend through the submit click immediately after the last credential fill
+    // (the "Sign in" button). A non-click next step means login auto-submitted (or
+    // we've already moved into the app), so stop at the fill — don't over-capture.
+    const next = actions[lastCred + 1];
+    if (next && CLICK_TOOLS.has(bareTool(next.tool)))
+        return lastCred + 2;
+    return lastCred + 1;
+}
+/**
+ * Locate the Playwright config object literal — the argument of `defineConfig({…})`
+ * or a bare `export default {…}` — so the setup project can be inserted into it.
+ */
+function findConfigObject(sf) {
+    const def = sf.getExportAssignment((d) => !d.isExportEquals());
+    const expr = def?.getExpression();
+    if (expr) {
+        if (Node.isObjectLiteralExpression(expr))
+            return expr;
+        if (Node.isCallExpression(expr)) {
+            const arg = expr.getArguments()[0];
+            if (arg && Node.isObjectLiteralExpression(arg))
+                return arg;
+        }
+    }
+    // Fallback: a defineConfig(...) call anywhere in the file.
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (call.getExpression().getText() === 'defineConfig') {
+            const arg = call.getArguments()[0];
+            if (arg && Node.isObjectLiteralExpression(arg))
+                return arg;
+        }
+    }
+    return undefined;
+}
+/**
+ * Stage 4a — propose the playwright.config edit that registers the auth-fixture
+ * setup project. AST-based (ts-morph) so it only reprints what it touches and
+ * preserves the user's formatting. Adds:
+ *
+ *   projects: [
+ *     { name: 'setup', testMatch: /.*\.setup\.ts$/ },
+ *     { name: 'chromium', dependencies: ['setup'] },
+ *   ]
+ *
+ * Returns the edited source, or null when it can't safely edit — no config
+ * object found, or `projects` ALREADY exists (merging into a user's project
+ * matrix is risky; the caller degrades to the static paste hint instead). The
+ * edit is never applied here; the caller shows it for approval first.
+ */
+export function addSetupProjectToConfig(source) {
+    try {
+        const project = new Project({ useInMemoryFileSystem: true, compilerOptions: { allowJs: true } });
+        const sf = project.createSourceFile('__pwconfig.ts', source, { overwrite: true });
+        const obj = findConfigObject(sf);
+        if (!obj)
+            return null;
+        if (obj.getProperty('projects'))
+            return null; // user already manages projects — don't risk it
+        obj.addPropertyAssignment({
+            name: 'projects',
+            initializer: [
+                '[',
+                "    { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },",
+                "    { name: 'chromium', dependencies: ['setup'] },",
+                '  ]',
+            ].join('\n'),
+        });
+        return sf.getFullText();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/specs/detectSharedFlows.d.ts

@@ -1,4 +1,4 @@
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 export interface SharedFlow {
     /** The shared signature prefix, one entry per step. */
     signatures: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgC5E;AAuDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}
+{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgC5E;AAwDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}

package/dist/specs/detectSharedFlows.js

@@ -17,9 +17,9 @@
  * same signature even though their typed values differ — value vs. structure
  * separation is mechanical (D4).
  */
-import { readdir, readFile } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sidecarDir } from './sidecar.js';
+import { sidecarDir, legacySidecarDir, parseSidecarFile } from './sidecar.js';
 import { humanStep } from './humanSteps.js';
 /**
  * Reduce one captured step to a signature string: the tool plus its structural
@@ -60,31 +60,30 @@ export function stepSignature(tool, rawInput) {
             return null;
     }
 }
-/** Read and parse every sidecar under `.hover/`. Malformed files are skipped
- *  (better to detect across the valid ones than fail because one is broken). */
+/** Read and parse every sidecar under `.hover/sidecars/`, unioned with any
+ *  still in the legacy `__vibe_tests__/.hover/` home (current home wins on a
+ *  slug collision). Malformed files are skipped (better to detect across the
+ *  valid ones than fail because one is broken). */
 async function readSidecars(devRoot) {
-    const dir = sidecarDir(devRoot);
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.endsWith('.json'))
-            continue;
+    const bySlug = new Map();
+    for (const dir of [legacySidecarDir(devRoot), sidecarDir(devRoot)]) {
+        let entries;
         try {
-            const sc = JSON.parse(await readFile(join(dir, entry), 'utf-8'));
-            if (Array.isArray(sc.steps) && typeof sc.slug === 'string')
-                out.push(sc);
+            entries = await readdir(dir);
         }
         catch {
-            // skip malformed sidecar
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const sc = await parseSidecarFile(join(dir, entry));
+            if (sc && Array.isArray(sc.steps) && typeof sc.slug === 'string') {
+                bySlug.set(sc.slug, sc); // later dir (current home) overwrites
+            }
         }
     }
-    return out;
+    return [...bySlug.values()];
 }
 /** Project a sidecar's steps to (signature, prose) lists, dropping
  *  non-flow steps. */

package/dist/specs/generatePageObject.d.ts

@@ -11,7 +11,7 @@
  * emitters with a `this.page` page variable, so a Page Object's selectors match
  * the crystallized specs exactly.
  */
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 export interface PageObjectResult {
     /** PascalCase class name, e.g. `LoginPage`. */
     className: string;

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

@@ -1 +1 @@
-{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAUzD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CAoElB"}
+{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAUtD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CAoElB"}

package/dist/specs/healPrompt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Self-heal Stage 2 — the heal prompt.
+ *
+ * When a saved spec fails on replay (the app changed → a locator no longer
+ * matches), healing re-performs the flow against the LIVE app and fixes the
+ * broken step(s). This builds the instruction that drives that run: the agent
+ * gets the spec's intended flow (its source) + exactly what broke (the parsed
+ * failures), and re-locates via the grounded control tools + source reader.
+ *
+ * The heal then crystallizes through the normal candidate flow (record_candidate
+ * / fallback) — deterministic re-render, human-reviewed; the agent re-locates,
+ * it does not author the spec. Pure: prompt-building only.
+ */
+import type { RunFailure } from './runFailures.js';
+/** A short, chat-friendly label for the heal run (the user bubble), vs the full
+ *  prompt the agent receives. */
+export declare function healLabel(slug: string): string;
+export declare function buildHealPrompt(slug: string, specSource: string, failures: RunFailure[]): string;
+//# sourceMappingURL=healPrompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"healPrompt.d.ts","sourceRoot":"","sources":["../../src/specs/healPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;iCACiC;AACjC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CA2ChG"}

package/dist/specs/healPrompt.js

@@ -0,0 +1,48 @@
+/** A short, chat-friendly label for the heal run (the user bubble), vs the full
+ *  prompt the agent receives. */
+export function healLabel(slug) {
+    return `🏥 Heal "${slug}" — re-running the flow to fix what changed`;
+}
+export function buildHealPrompt(slug, specSource, failures) {
+    const failureLines = failures.length > 0
+        ? failures.map(f => {
+            const what = f.failingLocator
+                ? `${f.failingAction ?? 'a step'} on \`${f.failingLocator}\` no longer matches`
+                : (f.error || 'a step failed');
+            return `  - ${what}`;
+        }).join('\n')
+        : '  - (no structured failure captured — re-run the whole flow and fix whatever no longer works)';
+    return [
+        `You are REPAIRING a saved Playwright test that no longer passes because the`,
+        `app under test changed. Re-perform its flow against the LIVE app and fix only`,
+        `the step(s) that broke — do not invent new behavior or add unrelated steps.`,
+        ``,
+        `Test: "${slug}"`,
+        ``,
+        `What it does (the saved spec — this is the intended flow to reproduce):`,
+        `\`\`\`ts`,
+        specSource.trim(),
+        `\`\`\``,
+        ``,
+        `What broke on replay:`,
+        failureLines,
+        ``,
+        `How to repair it:`,
+        `  - Open the app and walk the SAME flow, interacting through the grounded`,
+        `    control tools (click_control / fill_control / select_control / …) so the`,
+        `    repaired selectors stay replayable.`,
+        `  - Where a step's old selector no longer matches, find the element that step`,
+        `    INTENDED and operate that instead. Read the component source if you are`,
+        `    unsure why it moved or what replaced it.`,
+        `  - JUDGE broke-vs-changed: if a failure is because the app INTENTIONALLY`,
+        `    changed (the feature now works differently — not a regression), adapt the`,
+        `    flow to the new correct behavior and say so in your summary. If it looks`,
+        `    like a real regression (the app is wrong), report it as a finding and heal`,
+        `    to what the test originally intended.`,
+        `  - Keep dynamic content dynamic: if a step grounds on data that varies`,
+        `    run-to-run, flag it dynamic — don't freeze this run's value.`,
+        ``,
+        `When the flow works end to end, call record_candidate with the test's name so`,
+        `the repaired version can be saved. Do not write any file yourself.`,
+    ].join('\n');
+}

package/dist/specs/humanSteps.d.ts

@@ -1,18 +1,14 @@
 /**
  * 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.
+ * Used by writeSpec.ts to enrich the generated `.spec.ts` JSDoc with a
+ * numbered "Steps:" block that QA / PMs can read without grokking
+ * `getByRole(...)`.
  *
  * 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';
+import type { SkillStep } from '../specs/specStep.js';
 /** A single human-readable line for one tool call, or null to skip. */
 export declare function humanStep(tool: string, rawInput: unknown): string | null;
 /**

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

@@ -1 +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"}
+{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,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

@@ -91,7 +91,12 @@ 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. */
+/** Wrap in double-quotes for prose; escape internal quotes. A redacted
+ *  credential (stored as a `process.env.X …` expression) shows as the masked
+ *  `$X` instead — the prose, like the code, never reveals the secret. */
 function quote(s) {
+    const env = /^process\.env\.([A-Za-z0-9_]+)/.exec(s);
+    if (env)
+        return `$${env[1]}`;
     return `"${s.replace(/"/g, '\\"')}"`;
 }

package/dist/specs/optimizeSpec.d.ts

@@ -5,6 +5,20 @@ export declare class OptimizeError extends Error {
 }
 /** Runs the codegen LLM on a prompt and returns its raw text output. */
 export type RunCodegen = (prompt: string) => Promise<string>;
+/** Project context fed to the refinement pass so the candidate FITS the existing
+ *  suite: the team's conventions + the reusable Page Objects to prefer over raw
+ *  locators. Relevant files only (POMs + conventions), NOT the whole suite — the
+ *  refinement is a cheap pass, keep the context bounded. */
+export interface SuiteContext {
+    conventions?: string;
+    pages: {
+        name: string;
+        source: string;
+    }[];
+}
+/** Best-effort gather of the suite context (conventions.md + __vibe_tests__/pages
+ *  Page Objects). Missing files → empty; never throws. */
+export declare function gatherSuiteContext(devRoot: string): Promise<SuiteContext>;
 export interface OptimizeResult {
     /** Absolute path of the written candidate (never the original spec). */
     candidatePath: string;
@@ -20,7 +34,7 @@ export declare function optimizeSpec(devRoot: string, slug: string, runCodegen:
  * same rules the deterministic path enforces (semantic selectors, no XPath, no
  * waitForTimeout, keep the test.step shape).
  */
-export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[]): string;
+export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[], suite?: SuiteContext): string;
 /** Strip a ```ts fence if the model wrapped its output in one. */
 export declare function extractCode(raw: string): string;
 /**
@@ -32,11 +46,4 @@ export declare function validateSpecCode(code: string): {
     ok: boolean;
     errors: string[];
 };
-/** Promote an optimization candidate to the real spec (overwriting it) and
- *  remove the candidate. Returns the written spec path. The human's "Use
- *  optimized" / `mv` action. */
-export declare function promoteOptimized(devRoot: string, slug: string): Promise<string>;
-/** Discard an optimization candidate (delete the .draft, leave the spec). The
- *  human's "Keep original". */
-export declare function discardOptimized(devRoot: string, slug: string): Promise<void>;
 //# sourceMappingURL=optimizeSpec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGrE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CA2CzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,GACrB,MAAM,CAmDR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF;AAyBD;;gCAEgC;AAChC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYrF;AAED;+BAC+B;AAC/B,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF"}
+{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAgC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D;;;4DAG4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAOD;0DAC0D;AAC1D,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/E;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CAwCzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,EACtB,KAAK,GAAE,YAA4B,GAClC,MAAM,CAkFR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF"}