@hover-dev/core 0.16.0 → 0.17.0

package/dist/sessions/sessions.d.ts

@@ -0,0 +1,125 @@
+export declare const SESSION_RECORD_VERSION = 2;
+/** One agent-reported finding (the ## Findings block), persisted so the
+ *  ledger becomes a reusable findings log — not just a run-history list.
+ *  Severity is the raw marker the agent emitted (Bug / Minor / Info / …);
+ *  readers normalise it for display. */
+export interface SessionFinding {
+    severity: string;
+    text: string;
+    /** Optional short headline (from the structured JSON findings block). */
+    title?: string;
+    /** Endpoint / method when the finding is about an API call — used to
+     *  crystallize a request-based regression later. */
+    endpoint?: string;
+    method?: string;
+}
+export interface SessionRecord {
+    /** Bumped to 2 when the reproducibility + outcome fields below were added.
+     *  Readers must tolerate v1 records (every new field is optional). */
+    version: number;
+    /** `<sanitized-startedAt>-<rand>` — the runId, generated at run start; names
+     *  the run folder `.hover/runs/<conversationId>/<id>/` and is the meta.json id. */
+    id: string;
+    /** The chat conversation this run belongs to — the folder it's grouped under,
+     *  so deleting a conversation removes all its runs. */
+    conversationId?: string;
+    startedAt: string;
+    endedAt: string;
+    /** Real wall-clock of the agent run (endedAt − startedAt in ms). The bare
+     *  timestamps can collapse to ~0 for an instant failure; this is explicit. */
+    durationMs?: number;
+    agent: string;
+    model?: string;
+    /** Active mode: null/absent = normal authoring, else 'api-test' / 'pentest'.
+     *  A pentest record is a different artifact from a normal one. */
+    mode?: string | null;
+    prompt: string;
+    outcome: 'saved' | 'completed' | 'error' | 'aborted';
+    /** Why an error/aborted run ended — engine message, preflight failure,
+     *  budget cutoff, user cancel. Makes a failed record diagnostic. */
+    errorReason?: string;
+    /** The agent's final verification prose (the Result card body), minus the
+     *  Findings block. Searchable history + context, not just the prompt. */
+    summary?: string;
+    /** Parsed ## Findings — the run's actual product output. */
+    findings?: SessionFinding[];
+    /** Per-tool call counts (browser_snapshot → 12, browser_click → 8). Explains
+     *  cost and feeds optimization targeting. */
+    toolCounts?: Record<string, number>;
+    /** What this run drove. envId/envName come from the editor's environment
+     *  store (Local vs a remote target); url is the active dev tab. The Cloud
+     *  run layer keys flakiness + scheduling off these. */
+    target?: {
+        url?: string;
+        envId?: string;
+        envName?: string;
+    };
+    /** @account labels this run logged in with — LABELS ONLY, never the
+     *  username/password (same contract as spec redaction). */
+    accountLabels?: string[];
+    /** Tag of the `.hover/screenshots/<tag>` dir this run wrote to, so the UI
+     *  can open the run's artifacts. (Distinct from `id` because the screenshot
+     *  dir is named at MCP-launch time, before the record id exists.) */
+    screenshotTag?: string;
+    /** Chaining hook (reserved for Cloud): the prior turn's session id when this
+     *  was a `--resume` follow-up, so a multi-turn conversation links as one. */
+    resumeOf?: string;
+    /** Set when the session was crystallized into a spec. */
+    specSlug?: string;
+    turns?: number;
+    costUsd?: number;
+    /** Total tokens consumed (input + output + cache) — the raw-usage counterpart
+     *  to costUsd, surfaced by the widget/dashboard for users who track tokens
+     *  rather than dollars. */
+    tokensUsed?: number;
+    stepCount: number;
+}
+/**
+ * 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 declare function stripToolCallNoise(text: string): string;
+/** 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 declare function parseFindings(summary: string): {
+    summary: string;
+    findings: SessionFinding[];
+};
+/** Count tool_use steps by tool name for the `toolCounts` field. */
+export declare function tallyTools(steps: {
+    kind: string;
+    tool?: string;
+}[]): Record<string, number>;
+/** 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 declare function writeSessionRecord(devRoot: string, conversationId: string, runId: string, rec: Omit<SessionRecord, 'version' | 'id' | 'conversationId'>): Promise<{
+    path: string;
+    id: string;
+} | {
+    error: string;
+}>;
+/** List every run's meta.json across all conversations: `.hover/runs/<conv>/<run>/meta.json`.
+ *  Best-effort; returns [] if no runs yet. */
+export declare function listSessionRecords(devRoot: string): Promise<{
+    path: string;
+    rec: SessionRecord;
+}[]>;
+/**
+ * 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 declare function markSessionSaved(devRoot: string, promptText: string, specSlug: string): Promise<void>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions/sessions.d.ts.map

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

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/businessMap.d.ts

@@ -0,0 +1,29 @@
+export type MapNodeKind = 'app' | 'area' | 'line' | 'spec';
+export type CoverageStatus = 'covered' | 'uncovered';
+export interface MapNode {
+    id: string;
+    label: string;
+    kind: MapNodeKind;
+    /** Coverage of a business line (only on `line` nodes). */
+    status?: CoverageStatus;
+    /** Entry route of a business line, if given. */
+    route?: string;
+    /** Spec filename a line is covered by (on `line` and `spec` nodes). */
+    spec?: string;
+}
+export interface MapEdge {
+    source: string;
+    target: string;
+}
+export interface BusinessMapGraph {
+    app: string;
+    nodes: MapNode[];
+    edges: MapEdge[];
+    stats: {
+        lines: number;
+        covered: number;
+        areas: number;
+    };
+}
+export declare function parseBusinessMap(md: string, fallbackApp?: string): BusinessMapGraph;
+//# sourceMappingURL=businessMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"businessMap.d.ts","sourceRoot":"","sources":["../../src/specs/businessMap.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAErD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAClB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AA8BD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,SAAQ,GAAG,gBAAgB,CAwDlF"}

package/dist/specs/businessMap.js

@@ -0,0 +1,95 @@
+/*
+ * Business-map parser: turn the `.hover/hover-map.md` wiki the agent maintains
+ * into a graph model the cockpit renders (areas → business lines → specs, with
+ * coverage). The map is a human-curated markdown checklist:
+ *
+ *   # Business map — myapp
+ *   ## Auth
+ *   - [ ] Log in — /login
+ *   - [x] Checkout — /checkout — checkout.spec.ts
+ *
+ * Pure + total: malformed lines are skipped, never thrown. The graph is
+ * hierarchical (app → area → line → spec); richer relationship edges
+ * (depends-on / shares-state / navigates-to) are a later format extension.
+ */
+function slug(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'x');
+}
+const SPEC_RE = /\.spec\.tsx?$/;
+/** Split a business-line item on " — " / " – " / " - " (em/en/hyphen, spaced). */
+function splitItem(rest) {
+    const parts = rest
+        .split(/\s+[—–-]\s+/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const name = parts.shift() ?? rest.trim();
+    let route;
+    let spec;
+    for (const p of parts) {
+        if (SPEC_RE.test(p))
+            spec = p;
+        else if (p.startsWith('/'))
+            route = p;
+        else if (!spec && SPEC_RE.test(p))
+            spec = p;
+    }
+    return { name, route, spec };
+}
+export function parseBusinessMap(md, fallbackApp = 'app') {
+    const nodes = [];
+    const edges = [];
+    const seen = new Set();
+    const add = (n) => {
+        if (seen.has(n.id))
+            return;
+        seen.add(n.id);
+        nodes.push(n);
+    };
+    let app = fallbackApp;
+    // Title: `# Business map — <app>` (or any `# <title>`).
+    const title = md.match(/^#\s+(.+)$/m);
+    if (title) {
+        const t = title[1].trim();
+        const m = t.match(/business\s*map\s*[—–-]\s*(.+)$/i);
+        app = (m ? m[1] : t).trim() || fallbackApp;
+    }
+    add({ id: 'app', label: app, kind: 'app' });
+    let area = null;
+    let covered = 0;
+    let lineCount = 0;
+    let areaCount = 0;
+    for (const raw of md.split('\n')) {
+        const line = raw.trimEnd();
+        const areaM = line.match(/^##\s+(.+)$/);
+        if (areaM) {
+            const label = areaM[1].trim();
+            const id = `area:${slug(label)}`;
+            area = { id };
+            add({ id, label, kind: 'area' });
+            edges.push({ source: 'app', target: id });
+            areaCount++;
+            continue;
+        }
+        const itemM = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+        if (itemM) {
+            const status = itemM[1].toLowerCase() === 'x' ? 'covered' : 'uncovered';
+            const { name, route, spec } = splitItem(itemM[2]);
+            const parentId = area?.id ?? 'app';
+            const lineId = `line:${slug(area ? area.id.slice(5) : 'top')}/${slug(name)}`;
+            add({ id: lineId, label: name, kind: 'line', status, route, spec });
+            edges.push({ source: parentId, target: lineId });
+            lineCount++;
+            if (status === 'covered')
+                covered++;
+            if (spec) {
+                const specId = `spec:${spec}`;
+                add({ id: specId, label: spec, kind: 'spec', spec });
+                edges.push({ source: lineId, target: specId });
+            }
+        }
+    }
+    return { app, nodes, edges, stats: { lines: lineCount, covered, areas: areaCount } };
+}

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