@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/extension/pipeline/events.d.ts

@@ -0,0 +1,56 @@
+/**
+ * PURE reducers over the `--mode json` NDJSON event stream.
+ *
+ * The runner stays thin: it only line-buffers + `JSON.parse`s each line into a
+ * `JsonEvent`. These functions turn that parsed array into the final assistant
+ * text and aggregated usage, copying the subagent example's
+ * `getFinalOutput` / usage-accumulation logic (index.ts L170-180, L351-369).
+ *
+ * Note the corrected event taxonomy: the real tool-result event is
+ * `tool_execution_end`; the example's `tool_result_end` branch is dead/never
+ * emitted, so `collectToolResults` reads the former and ignores the latter.
+ */
+import type { JsonEvent, StageUsage } from "./types.js";
+/**
+ * The final assistant text handed forward as the next stage's `{previous}`.
+ * Biased toward the model's GENUINE turn-end: prefer the last assistant message
+ * that stopped naturally (`stopReason === "stop"`) and carries text, so a
+ * trailing aborted / errored / text-less turn does not become the handoff. Falls
+ * back to the last assistant message with any text part when no clean "stop" turn
+ * exists, and returns '' when there is no assistant text at all. Pure, defensive,
+ * never throws.
+ */
+export declare function extractFinalOutput(events: JsonEvent[]): string;
+/** Sum token/cost usage across assistant turns and count the turns. */
+export declare function aggregateUsage(events: JsonEvent[]): StageUsage;
+/** The last assistant stop reason / error message seen on the stream. */
+export declare function extractStopReason(events: JsonEvent[]): {
+    stopReason?: string;
+    errorMessage?: string;
+};
+/**
+ * Collect structured tool results from `tool_execution_end` events. The legacy
+ * `tool_result_end` shape is intentionally ignored so a stray dead event can't
+ * corrupt counts. (v1 findings come from the final assistant TEXT, not here —
+ * this is exposed for any future stage that needs tool-level results.)
+ */
+export declare function collectToolResults(events: JsonEvent[]): Array<{
+    toolName: string;
+    isError: boolean;
+}>;
+export interface EventAccumulator {
+    usage: StageUsage;
+    stopReason?: string;
+    errorMessage?: string;
+    toolCalls: number;
+    toolErrors: number;
+    /** Last assistant text on a genuine "stop" turn, and on any turn — extractFinalOutput's two tiers. */
+    lastStopText?: string;
+    lastAnyText?: string;
+}
+export declare function newEventAccumulator(): EventAccumulator;
+/** Fold one streamed event into `acc`. Retains nothing per-event. */
+export declare function foldEvent(acc: EventAccumulator, ev: JsonEvent): void;
+/** Final assistant text, biased to the last genuine "stop" turn — mirrors extractFinalOutput. */
+export declare function finalOutputFrom(acc: EventAccumulator): string;
+//# sourceMappingURL=events.d.ts.map

package/dist/extension/pipeline/events.js

@@ -0,0 +1,147 @@
+/**
+ * PURE reducers over the `--mode json` NDJSON event stream.
+ *
+ * The runner stays thin: it only line-buffers + `JSON.parse`s each line into a
+ * `JsonEvent`. These functions turn that parsed array into the final assistant
+ * text and aggregated usage, copying the subagent example's
+ * `getFinalOutput` / usage-accumulation logic (index.ts L170-180, L351-369).
+ *
+ * Note the corrected event taxonomy: the real tool-result event is
+ * `tool_execution_end`; the example's `tool_result_end` branch is dead/never
+ * emitted, so `collectToolResults` reads the former and ignores the latter.
+ */
+/** True for an assistant `message_end` event carrying a message. */
+function isAssistantMessage(ev) {
+    return ev.type === "message_end" && ev.message?.role === "assistant";
+}
+/** The last text part of the last assistant message matching `pred`, or undefined. */
+function lastAssistantText(events, pred) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (!isAssistantMessage(ev) || !pred(ev))
+            continue;
+        const parts = ev.message?.content ?? [];
+        for (let j = parts.length - 1; j >= 0; j--) {
+            const part = parts[j];
+            if (part.type === "text" && typeof part.text === "string")
+                return part.text;
+        }
+    }
+    return undefined;
+}
+/**
+ * The final assistant text handed forward as the next stage's `{previous}`.
+ * Biased toward the model's GENUINE turn-end: prefer the last assistant message
+ * that stopped naturally (`stopReason === "stop"`) and carries text, so a
+ * trailing aborted / errored / text-less turn does not become the handoff. Falls
+ * back to the last assistant message with any text part when no clean "stop" turn
+ * exists, and returns '' when there is no assistant text at all. Pure, defensive,
+ * never throws.
+ */
+export function extractFinalOutput(events) {
+    // First choice: the last real turn-end ("stop") that actually produced text.
+    const stopText = lastAssistantText(events, (ev) => ev.message?.stopReason === "stop");
+    if (stopText !== undefined)
+        return stopText;
+    // Fallback (stop-reason-blind): the last assistant message with any text part.
+    return lastAssistantText(events, () => true) ?? "";
+}
+/** Sum token/cost usage across assistant turns and count the turns. */
+export function aggregateUsage(events) {
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    for (const ev of events) {
+        if (!isAssistantMessage(ev))
+            continue;
+        usage.turns += 1;
+        const u = ev.message?.usage;
+        if (!u)
+            continue;
+        usage.input += u.input ?? 0;
+        usage.output += u.output ?? 0;
+        usage.cacheRead += u.cacheRead ?? 0;
+        usage.cacheWrite += u.cacheWrite ?? 0;
+        usage.cost += u.cost?.total ?? 0;
+    }
+    return usage;
+}
+/** The last assistant stop reason / error message seen on the stream. */
+export function extractStopReason(events) {
+    const out = {};
+    for (const ev of events) {
+        if (!isAssistantMessage(ev))
+            continue;
+        if (ev.message?.stopReason)
+            out.stopReason = ev.message.stopReason;
+        if (ev.message?.errorMessage)
+            out.errorMessage = ev.message.errorMessage;
+    }
+    return out;
+}
+/**
+ * Collect structured tool results from `tool_execution_end` events. The legacy
+ * `tool_result_end` shape is intentionally ignored so a stray dead event can't
+ * corrupt counts. (v1 findings come from the final assistant TEXT, not here —
+ * this is exposed for any future stage that needs tool-level results.)
+ */
+export function collectToolResults(events) {
+    const out = [];
+    for (const ev of events) {
+        if (ev.type !== "tool_execution_end")
+            continue;
+        out.push({ toolName: ev.toolName ?? "", isError: ev.isError ?? false });
+    }
+    return out;
+}
+export function newEventAccumulator() {
+    return {
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+        toolCalls: 0,
+        toolErrors: 0,
+    };
+}
+/** The last text part of a single assistant message, or undefined. */
+function messageText(ev) {
+    const parts = ev.message?.content ?? [];
+    for (let j = parts.length - 1; j >= 0; j--) {
+        const part = parts[j];
+        if (part.type === "text" && typeof part.text === "string")
+            return part.text;
+    }
+    return undefined;
+}
+/** Fold one streamed event into `acc`. Retains nothing per-event. */
+export function foldEvent(acc, ev) {
+    if (ev.type === "tool_execution_end") {
+        acc.toolCalls += 1;
+        if (ev.isError)
+            acc.toolErrors += 1;
+        return;
+    }
+    if (!isAssistantMessage(ev))
+        return;
+    acc.usage.turns += 1;
+    const u = ev.message?.usage;
+    if (u) {
+        acc.usage.input += u.input ?? 0;
+        acc.usage.output += u.output ?? 0;
+        acc.usage.cacheRead += u.cacheRead ?? 0;
+        acc.usage.cacheWrite += u.cacheWrite ?? 0;
+        acc.usage.cost += u.cost?.total ?? 0;
+    }
+    // last-wins, matching extractStopReason
+    if (ev.message?.stopReason)
+        acc.stopReason = ev.message.stopReason;
+    if (ev.message?.errorMessage)
+        acc.errorMessage = ev.message.errorMessage;
+    const text = messageText(ev);
+    if (text !== undefined) {
+        acc.lastAnyText = text;
+        if (ev.message?.stopReason === "stop")
+            acc.lastStopText = text;
+    }
+}
+/** Final assistant text, biased to the last genuine "stop" turn — mirrors extractFinalOutput. */
+export function finalOutputFrom(acc) {
+    return acc.lastStopText ?? acc.lastAnyText ?? "";
+}
+//# sourceMappingURL=events.js.map

package/dist/extension/pipeline/findings.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PURE findings parser + the review→fix loop reducers — the analogue of the
+ * backend's `extractCitations`.
+ *
+ * `parseFindings` tolerantly reads the reviewer's machine-readable trailing
+ * section (a fenced ```findings block of `SEVERITY | file:line | message`
+ * lines, OR a JSON array), ignoring surrounding prose. Unparseable/empty input
+ * yields [] — honest: treated as "no blockers" and the caller logs a
+ * parse-warning rather than fabricating findings or throwing.
+ *
+ * `hasBlockingFindings` + `shouldStop` are the trivially-unit-testable stop rule
+ * (spec §7.3): only Critical + High block; stop when there are no blockers OR
+ * after MAX_REVIEW_ROUNDS rounds, always with an explicit reason.
+ */
+import { type Finding, type ReviewLens } from "./types.js";
+/**
+ * Extract the inner text of a fenced ```findings block, if present. Exported
+ * (spec §3e) so the orchestrator can distinguish "explicit empty findings
+ * fence" (a real clean review) from "no fence at all" (a likely format miss
+ * worth one re-ask) — `parseFindings` returning [] cannot tell them apart.
+ */
+export declare function extractFindingsBlock(raw: string): string | null;
+/**
+ * Parse a reviewer's raw output into structured findings. Tries the JSON-array
+ * form first, then the fenced ```findings block, then a tolerant scan of every
+ * line. Never throws; never fabricates a finding from prose.
+ */
+export declare function parseFindings(raw: string, lens?: ReviewLens): Finding[];
+/** Concatenate per-lens findings, preserving order and each lens tag. */
+export declare function unionFindings(perLens: Finding[][]): Finding[];
+/** True iff at least one finding is Critical or High (the only blockers). */
+export declare function hasBlockingFindings(findings: Finding[]): boolean;
+/**
+ * The bounded review→fix stop rule (spec §7.3): stop 'clean' when nothing
+ * blocks, else stop 'round_cap' once the round hits MAX_REVIEW_ROUNDS, else
+ * keep going. Always returns an explicit reason (no silent truncation).
+ */
+export declare function shouldStop(findings: Finding[], round: number): {
+    stop: boolean;
+    reason: "clean" | "round_cap" | null;
+};
+//# sourceMappingURL=findings.d.ts.map

package/dist/extension/pipeline/findings.js

@@ -0,0 +1,144 @@
+/**
+ * PURE findings parser + the review→fix loop reducers — the analogue of the
+ * backend's `extractCitations`.
+ *
+ * `parseFindings` tolerantly reads the reviewer's machine-readable trailing
+ * section (a fenced ```findings block of `SEVERITY | file:line | message`
+ * lines, OR a JSON array), ignoring surrounding prose. Unparseable/empty input
+ * yields [] — honest: treated as "no blockers" and the caller logs a
+ * parse-warning rather than fabricating findings or throwing.
+ *
+ * `hasBlockingFindings` + `shouldStop` are the trivially-unit-testable stop rule
+ * (spec §7.3): only Critical + High block; stop when there are no blockers OR
+ * after MAX_REVIEW_ROUNDS rounds, always with an explicit reason.
+ */
+import { MAX_REVIEW_ROUNDS } from "./types.js";
+const SEVERITIES = ["critical", "high", "medium", "low"];
+const DEFAULT_LENS = "correctness";
+function isSeverity(value) {
+    return SEVERITIES.includes(value);
+}
+/** Parse a `file:line` location into its parts (line optional). */
+function parseLocation(loc) {
+    const trimmed = loc.trim();
+    if (!trimmed)
+        return {};
+    const m = trimmed.match(/^(.*):(\d+)$/);
+    if (m && m[1])
+        return { file: m[1], line: Number(m[2]) };
+    return { file: trimmed };
+}
+/** Parse one `SEVERITY | file:line | message` line, or null if it is not one. */
+function parsePipeLine(line, lens) {
+    const parts = line.split("|").map((p) => p.trim());
+    if (parts.length < 2)
+        return null;
+    const severity = parts[0].toLowerCase();
+    if (!isSeverity(severity))
+        return null;
+    let finding;
+    if (parts.length >= 3) {
+        const { file, line: lineNo } = parseLocation(parts[1]);
+        const message = parts.slice(2).join(" | ").trim();
+        finding = { severity, lens, message };
+        if (file)
+            finding.file = file;
+        if (lineNo !== undefined)
+            finding.line = lineNo;
+    }
+    else {
+        finding = { severity, lens, message: parts[1] };
+    }
+    return finding;
+}
+/**
+ * Extract the inner text of a fenced ```findings block, if present. Exported
+ * (spec §3e) so the orchestrator can distinguish "explicit empty findings
+ * fence" (a real clean review) from "no fence at all" (a likely format miss
+ * worth one re-ask) — `parseFindings` returning [] cannot tell them apart.
+ */
+export function extractFindingsBlock(raw) {
+    const m = raw.match(/```findings[^\n]*\n([\s\S]*?)```/i);
+    return m ? m[1] : null;
+}
+/** Best-effort parse of a JSON array of findings (fenced ```json or bare). */
+function parseJsonFindings(raw, lens) {
+    const fenced = raw.match(/```json[^\n]*\n([\s\S]*?)```/i);
+    const candidate = fenced ? fenced[1].trim() : raw.trim();
+    if (!candidate.startsWith("["))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(candidate);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const findings = [];
+    for (const item of parsed) {
+        if (!item || typeof item !== "object")
+            continue;
+        const obj = item;
+        const severity = typeof obj.severity === "string" ? obj.severity.toLowerCase() : "";
+        if (!isSeverity(severity))
+            continue;
+        const finding = {
+            severity,
+            lens: typeof obj.lens === "string" && isLens(obj.lens) ? obj.lens : lens,
+            message: typeof obj.message === "string" ? obj.message : "",
+        };
+        if (typeof obj.file === "string")
+            finding.file = obj.file;
+        if (typeof obj.line === "number")
+            finding.line = obj.line;
+        findings.push(finding);
+    }
+    return findings;
+}
+function isLens(value) {
+    return value === "correctness" || value === "business_fit" || value === "does_it_hold";
+}
+/**
+ * Parse a reviewer's raw output into structured findings. Tries the JSON-array
+ * form first, then the fenced ```findings block, then a tolerant scan of every
+ * line. Never throws; never fabricates a finding from prose.
+ */
+export function parseFindings(raw, lens = DEFAULT_LENS) {
+    if (!raw || !raw.trim())
+        return [];
+    const json = parseJsonFindings(raw, lens);
+    if (json.length > 0)
+        return json;
+    const block = extractFindingsBlock(raw);
+    const source = block ?? raw;
+    const findings = [];
+    for (const line of source.split("\n")) {
+        const parsed = parsePipeLine(line, lens);
+        if (parsed)
+            findings.push(parsed);
+    }
+    return findings;
+}
+/** Concatenate per-lens findings, preserving order and each lens tag. */
+export function unionFindings(perLens) {
+    return perLens.flat();
+}
+/** True iff at least one finding is Critical or High (the only blockers). */
+export function hasBlockingFindings(findings) {
+    return findings.some((f) => f.severity === "critical" || f.severity === "high");
+}
+/**
+ * The bounded review→fix stop rule (spec §7.3): stop 'clean' when nothing
+ * blocks, else stop 'round_cap' once the round hits MAX_REVIEW_ROUNDS, else
+ * keep going. Always returns an explicit reason (no silent truncation).
+ */
+export function shouldStop(findings, round) {
+    if (!hasBlockingFindings(findings))
+        return { stop: true, reason: "clean" };
+    if (round >= MAX_REVIEW_ROUNDS)
+        return { stop: true, reason: "round_cap" };
+    return { stop: false, reason: null };
+}
+//# sourceMappingURL=findings.js.map

package/dist/extension/pipeline/finish.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The FINISH stage (spec §3c) — the deterministic commit / push / PR step that
+ * runs ONLY when the review loop stops `clean`.
+ *
+ * What it does:
+ *  - Commit the run's work: in worktree mode `git add -A` + commit on the run
+ *    branch (the tree started clean, so everything is the run's own). In --here
+ *    mode it commits ONLY when the pre-run baseline was verifiably clean;
+ *    otherwise it skips with an honest note (never mixing user dirt into an
+ *    agent commit).
+ *  - Commit message: `<type>(<scope>): <title>` + a 2-3 sentence plan summary +
+ *    the exact provenance trailer (YAGNI-Run / YAGNI-Ticket / YAGNI-Verify /
+ *    YAGNI-Decisions / YAGNI-Rounds / Co-Authored-By: YAGNI Code).
+ *  - Opt-in `--pr`: `git push -u origin <branch>` + `gh pr create` with the
+ *    USER'S own gh auth. Any push/PR failure is a fail-soft note ("committed
+ *    locally; …"); the run stays successful.
+ *
+ * IRON INVARIANT (§0.1): a FINISH failure NEVER flips a clean run to failed and
+ * NEVER fakes a commit — {@link runFinish} never throws, `committed` is only
+ * true when `git rev-parse HEAD` confirmed the new commit, and every skip or
+ * failure lands as an honest note the /go handoff surfaces verbatim.
+ *
+ * All message/trailer/scope derivation is PURE (unit-tested directly); the one
+ * impure seam is the injectable exec. Unlike verify's scrubbed env, the exec
+ * here inherits the user's FULL environment on purpose: `git push` needs the
+ * ssh-agent and `gh` needs the user's own auth — these are OUR commands, not
+ * repo-defined ones, so invariant §0.9 (repo commands never see YAGNI_* vars)
+ * does not apply.
+ */
+import type { WorktreeExec } from "./worktree.js";
+import type { Finding } from "./types.js";
+/** How the pre-run tree looked for a --here run (worktree mode ignores it). */
+export type HereBaseline = "clean" | "dirty" | "unknown";
+/** The trailer inputs, all plumbed from the pipeline result + run identity. */
+export interface TrailerInputs {
+    runId: string;
+    /** The flag-free ticket identifier or free-text arg. */
+    ticket: string;
+    /** `passed (<cmds>)` or `skipped (<reason>)` — see {@link verifyTrailerValue}. */
+    verify: string;
+    decisionsRecorded: number;
+    rounds: number;
+}
+export interface RunFinishOpts extends TrailerInputs {
+    /** The run tree (the worktree path, or ctx.cwd for --here). */
+    cwd: string;
+    worktreeMode: boolean;
+    /** --here commit gate: only a verifiably-clean pre-run baseline may commit. */
+    hereBaseline: HereBaseline;
+    /** The run branch (worktree mode) or the user's current branch (--here). */
+    branch?: string;
+    /** The resolved ticket brief (verbatim title + body), when /go could fetch it. */
+    ticketBrief?: string;
+    /** The plan stage's finalOutput (absent on a resume, where the build was skipped). */
+    planText?: string;
+    /** --pr: push the branch + open a PR (fail-soft). */
+    openPr: boolean;
+    /** Unresolved medium/low findings, quoted into the PR body. */
+    remainingFindings?: Finding[];
+    /**
+     * Paths already dirty at pipeline start (post-bootstrap), so NOT the run's own
+     * work — e.g. a lockfile a fresh-worktree `install` rewrote. FINISH stages only
+     * `changed − baselinePaths` so bootstrap churn (or any pre-existing dirt) never
+     * lands in the run's provenance commit. Absent ⇒ the whole diff is the run's.
+     */
+    baselinePaths?: string[];
+    signal?: AbortSignal;
+    exec?: WorktreeExec;
+}
+/** What FINISH actually did. `committed` true only when the commit really landed. */
+export interface FinishResult {
+    committed: boolean;
+    commitSha?: string;
+    branch?: string;
+    prUrl?: string;
+    prNumber?: number;
+    /** Honest skip/failure notes, surfaced verbatim in the /go handoff. */
+    notes: string[];
+}
+/** `fix` when the ticket brief (or, blind, the raw arg) says bug; else `feat` (spec §3c). */
+export declare function commitType(ticket: string, ticketBrief?: string): "fix" | "feat";
+/**
+ * The commit subject's title half: the brief's first non-empty line (its
+ * verbatim ticket title) with a leading `<ticket>:` echo stripped (the trailer
+ * already carries the identifier), falling back to the raw arg. Capped.
+ */
+export declare function commitTitle(ticket: string, ticketBrief?: string): string;
+/**
+ * A conventional-commit scope from the run's changed paths: the package name
+ * when every changed path agrees on one (`packages/<name>/…`, `apps/…`,
+ * `libs/…`), else the shared top-level dir. Ambiguous or root-level changes
+ * yield no scope (the subject is `<type>: <title>`), never a guess.
+ */
+export declare function deriveCommitScope(paths: string[]): string | undefined;
+/** `<type>(<scope>): <title>`, dropping the parens when no scope was derivable. */
+export declare function commitSubject(type: "fix" | "feat", scope: string | undefined, title: string): string;
+/**
+ * A 2-3 sentence summary of the plan stage's output (markdown flattened, first
+ * three sentences, capped). No LLM call — this is a deterministic excerpt. A
+ * missing plan (a resumed run skipped the build half) degrades honestly.
+ */
+export declare function summarizePlan(planText: string | undefined, ticket: string): string;
+/**
+ * The trailer's YAGNI-Verify value, derived honestly from the pipeline result:
+ * `passed (<cmds>)` when the final round's verify gate ran (verify-FAILED can't
+ * reach `clean` by construction), else `skipped (<reason>)`.
+ */
+export declare function verifyTrailerValue(result: {
+    verifyCommand?: string;
+    verifyNote?: string;
+}): string;
+/** The exact provenance trailer block (spec §3c). */
+export declare function provenanceTrailer(t: TrailerInputs): string;
+/** Subject + blank line + plan summary + blank line + trailer. */
+export declare function buildCommitMessage(subject: string, summary: string, trailer: string): string;
+/** The PR body: plan summary, any unresolved medium/low findings, the trailer. */
+export declare function buildPrBody(summary: string, trailer: string, remaining?: Finding[]): string;
+/** Pull the PR URL (+ number) out of `gh pr create` output, if present. */
+export declare function parsePrUrl(output: string): {
+    prUrl?: string;
+    prNumber?: number;
+};
+/**
+ * Run the FINISH stage. NEVER throws; every failure path returns an honest
+ * {@link FinishResult} with notes. See the module docblock for the contract.
+ */
+export declare function runFinish(opts: RunFinishOpts): Promise<FinishResult>;
+//# sourceMappingURL=finish.d.ts.map