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

package/dist/extension/pipeline/finish.js

@@ -0,0 +1,307 @@
+/**
+ * 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 { execFile } from "node:child_process";
+import { scrubSecrets } from "./scrubSecrets.js";
+import { parseChangedPaths } from "./verify.js";
+/** Cap on the commit subject's title half (keeps `git log --oneline` readable). */
+const TITLE_MAX = 72;
+/** Cap on the plan-summary body paragraph. */
+const SUMMARY_MAX = 400;
+/** Cap on a command-output tail quoted into an honest note. */
+const NOTE_TAIL_MAX = 200;
+/**
+ * Full-env exec (deliberately NOT {@link buildVerifyEnv}-scrubbed — see the
+ * module docblock): resolves `{code, output}` for a real exit, rejects only on
+ * a spawn-level error (ENOENT / abort), which callers catch into a note.
+ */
+const defaultExec = (argv, cwd, signal) => new Promise((resolve, reject) => {
+    execFile(argv[0], argv.slice(1), { cwd, signal, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const output = `${stdout ?? ""}${stderr ?? ""}`;
+        if (err) {
+            const code = err.code;
+            if (typeof code === "number")
+                return resolve({ code, output });
+            return reject(err);
+        }
+        resolve({ code: 0, output });
+    });
+});
+// ---------------------------------------------------------------------------
+// Pure message derivation
+// ---------------------------------------------------------------------------
+/** `fix` when the ticket brief (or, blind, the raw arg) says bug; else `feat` (spec §3c). */
+export function commitType(ticket, ticketBrief) {
+    return /\bbug/i.test(ticketBrief ?? ticket) ? "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 function commitTitle(ticket, ticketBrief) {
+    let title = ticketBrief?.split("\n").find((l) => l.trim().length > 0)?.trim() ?? ticket;
+    const echo = `${ticket.toLowerCase()}:`;
+    if (title.toLowerCase().startsWith(echo))
+        title = title.slice(echo.length).trim() || ticket;
+    return title.length > TITLE_MAX ? title.slice(0, TITLE_MAX).trimEnd() : title;
+}
+/**
+ * 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 function deriveCommitScope(paths) {
+    const candidates = new Set();
+    for (const p of paths) {
+        const segs = p.split("/").filter(Boolean);
+        if (segs.length < 2)
+            return undefined; // a root-level file has no scope
+        if (segs.length >= 3 && ["packages", "apps", "libs"].includes(segs[0]))
+            candidates.add(segs[1]);
+        else
+            candidates.add(segs[0]);
+    }
+    if (candidates.size !== 1)
+        return undefined;
+    return [...candidates][0];
+}
+/** `<type>(<scope>): <title>`, dropping the parens when no scope was derivable. */
+export function commitSubject(type, scope, title) {
+    return scope ? `${type}(${scope}): ${title}` : `${type}: ${title}`;
+}
+/**
+ * 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 function summarizePlan(planText, ticket) {
+    const flat = (planText ?? "")
+        .replace(/^#+\s*/gm, "")
+        .replace(/^\s*(?:[-*+]|\d+[.)])\s+/gm, "")
+        .replace(/`{1,3}/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!flat)
+        return `YAGNI Code /go run for ${ticket} (no plan text was available for this pass).`;
+    const sentences = flat.match(/[^.!?]+[.!?]+(?:\s+|$)/g);
+    let summary = sentences ? sentences.slice(0, 3).join("").trim() : flat;
+    if (summary.length > SUMMARY_MAX)
+        summary = `${summary.slice(0, SUMMARY_MAX).trimEnd()}…`;
+    return summary;
+}
+/**
+ * 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 function verifyTrailerValue(result) {
+    if (result.verifyCommand)
+        return `passed (${oneLine(result.verifyCommand)})`;
+    return `skipped (${oneLine(result.verifyNote ?? "verify did not run")})`;
+}
+/** Collapse a value onto one line so it can never break the trailer block. */
+function oneLine(s) {
+    return s.replace(/\s*\n\s*/g, " ").trim();
+}
+/** The exact provenance trailer block (spec §3c). */
+export function provenanceTrailer(t) {
+    return [
+        `YAGNI-Run: ${oneLine(t.runId)}`,
+        `YAGNI-Ticket: ${oneLine(t.ticket)}`,
+        `YAGNI-Verify: ${t.verify}`,
+        `YAGNI-Decisions: ${t.decisionsRecorded}`,
+        `YAGNI-Rounds: ${t.rounds}`,
+        "Co-Authored-By: YAGNI Code <code@yagni.app>",
+    ].join("\n");
+}
+/** Subject + blank line + plan summary + blank line + trailer. */
+export function buildCommitMessage(subject, summary, trailer) {
+    return `${subject}\n\n${summary}\n\n${trailer}`;
+}
+/** The PR body: plan summary, any unresolved medium/low findings, the trailer. */
+export function buildPrBody(summary, trailer, remaining = []) {
+    const parts = [summary];
+    if (remaining.length > 0) {
+        const lines = remaining.map((f) => {
+            const loc = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "(no location)";
+            return `- ${f.severity} | ${loc} | ${f.message}`;
+        });
+        parts.push(`Unresolved non-blocking findings:\n${lines.join("\n")}`);
+    }
+    parts.push(trailer);
+    return parts.join("\n\n");
+}
+/** Pull the PR URL (+ number) out of `gh pr create` output, if present. */
+export function parsePrUrl(output) {
+    const m = output.match(/https:\/\/\S+\/pull\/(\d+)/);
+    if (!m)
+        return {};
+    const prNumber = Number(m[1]);
+    return { prUrl: m[0], ...(Number.isFinite(prNumber) ? { prNumber } : {}) };
+}
+// ---------------------------------------------------------------------------
+// The impure runner
+// ---------------------------------------------------------------------------
+/**
+ * The last few output lines, flattened, for an honest note. Scrubbed FIRST
+ * (invariant §0.9): unlike verify's env-scrubbed commands, git push / gh run
+ * with the user's full environment, so their output can echo a credential
+ * embedded in a remote URL or a token in a gh error — and every note here is
+ * delivered as the durable /go handoff, landing in permanent scrollback.
+ */
+function tail(output) {
+    const t = scrubSecrets(output).trim().split("\n").slice(-3).join(" ").slice(0, NOTE_TAIL_MAX).trim();
+    return t;
+}
+/**
+ * Run the FINISH stage. NEVER throws; every failure path returns an honest
+ * {@link FinishResult} with notes. See the module docblock for the contract.
+ */
+export async function runFinish(opts) {
+    const exec = opts.exec ?? defaultExec;
+    const notes = [];
+    const skipped = (note) => ({
+        committed: false,
+        ...(opts.branch ? { branch: opts.branch } : {}),
+        notes: [...notes, note],
+    });
+    // A guarded exec: a spawn-level rejection (ENOENT / abort) becomes a non-zero
+    // ExecResult carrying the message, so every caller below handles one shape.
+    const run = async (argv) => {
+        try {
+            return await exec(argv, opts.cwd, opts.signal);
+        }
+        catch (err) {
+            return { code: -1, output: err instanceof Error ? err.message : String(err) };
+        }
+    };
+    try {
+        // --here commit gate: only a verifiably-clean pre-run baseline may commit
+        // (spec §3c — never mix user dirt into an agent commit). Worktree trees
+        // started clean, so everything in them is the run's own.
+        if (!opts.worktreeMode && opts.hereBaseline !== "clean") {
+            return skipped(opts.hereBaseline === "dirty"
+                ? "FINISH skipped the commit: the tree already had uncommitted changes before the run, and an agent commit must never mix in your work. Review the diff and commit it yourself."
+                : "FINISH skipped the commit: could not verify the pre-run tree was clean, so nothing was committed. Review the diff and commit it yourself.");
+        }
+        const status = await run(["git", "status", "--porcelain"]);
+        if (status.code !== 0) {
+            return skipped(`FINISH could not read the git status (${tail(status.output) || "git failed"}); nothing was committed.`);
+        }
+        if (!status.output.trim()) {
+            return skipped("FINISH found nothing to commit (the tree is already clean).");
+        }
+        // The run's OWN paths = everything changed now, minus what was already dirty
+        // at pipeline start (bootstrap lockfile churn, or a pre-existing edit). We
+        // commit only these, so the provenance commit never folds in non-run work.
+        const changed = parseChangedPaths(status.output);
+        const baseline = new Set(opts.baselinePaths ?? []);
+        const runOwned = baseline.size === 0 ? changed : changed.filter((p) => !baseline.has(p));
+        if (runOwned.length === 0) {
+            return skipped("FINISH found nothing of the run's own to commit (the only changes were already present before the run).");
+        }
+        // Message derivation off the run's real diff.
+        const subject = commitSubject(commitType(opts.ticket, opts.ticketBrief), deriveCommitScope(runOwned), commitTitle(opts.ticket, opts.ticketBrief));
+        const summary = summarizePlan(opts.planText, opts.ticket);
+        const trailer = provenanceTrailer(opts);
+        const message = buildCommitMessage(subject, summary, trailer);
+        // No baseline dirt ⇒ everything is the run's own: `git add -A` (preserves
+        // rename detection). With a baseline, stage only the run-owned paths so
+        // bootstrap/pre-existing dirt never lands (`--` guards flag-like paths).
+        const add = baseline.size === 0
+            ? await run(["git", "add", "-A"])
+            : await run(["git", "add", "--", ...runOwned]);
+        if (add.code !== 0) {
+            return skipped(`FINISH could not stage the changes (git add failed: ${tail(add.output)}); nothing was committed.`);
+        }
+        let commit = await run(["git", "commit", "-m", message]);
+        if (commit.code !== 0) {
+            // Most likely a missing git identity in a fresh environment (mirrors
+            // commitWip): retry once with an explicit YAGNI Code identity.
+            commit = await run([
+                "git",
+                "-c",
+                "user.name=YAGNI Code",
+                "-c",
+                "user.email=code@yagni.app",
+                "commit",
+                "-m",
+                message,
+            ]);
+        }
+        if (commit.code !== 0) {
+            return skipped(`FINISH could not commit (${tail(commit.output)}); the changes are left uncommitted in ${opts.cwd}.`);
+        }
+        const rev = await run(["git", "rev-parse", "HEAD"]);
+        if (rev.code !== 0 || !rev.output.trim()) {
+            // The commit reported success but we cannot confirm the sha: report the
+            // commit honestly without a sha rather than inventing one.
+            notes.push("FINISH committed, but could not read the commit sha (git rev-parse failed).");
+        }
+        const commitSha = rev.code === 0 ? rev.output.trim().split("\n")[0] : undefined;
+        const result = {
+            committed: true,
+            ...(commitSha ? { commitSha } : {}),
+            ...(opts.branch ? { branch: opts.branch } : {}),
+            notes,
+        };
+        if (!opts.openPr)
+            return result;
+        // Opt-in --pr half: push + gh, both fail-soft (the run stays successful).
+        if (!opts.branch) {
+            notes.push("Committed locally; push/PR skipped: the run branch is unknown.");
+            return result;
+        }
+        const push = await run(["git", "push", "-u", "origin", opts.branch]);
+        if (push.code !== 0) {
+            notes.push(`Committed locally; push failed: ${tail(push.output) || "git push failed"}.`);
+            return result;
+        }
+        const pr = await run(["gh", "pr", "create", "--title", subject, "--body", buildPrBody(summary, trailer, opts.remainingFindings)]);
+        if (pr.code !== 0) {
+            notes.push(`Committed and pushed ${opts.branch}; PR creation failed: ${tail(pr.output) || "gh failed"}.`);
+            return result;
+        }
+        const { prUrl, prNumber } = parsePrUrl(pr.output);
+        if (!prUrl) {
+            notes.push("Committed and pushed; gh pr create succeeded but no PR URL could be read from its output.");
+            return result;
+        }
+        return { ...result, prUrl, ...(prNumber != null ? { prNumber } : {}) };
+    }
+    catch (err) {
+        // Belt and braces: nothing above should throw, but the invariant (§0.1)
+        // outranks tidiness — a FINISH failure must never fail a clean run.
+        const msg = scrubSecrets(err instanceof Error ? err.message : String(err));
+        return { committed: false, ...(opts.branch ? { branch: opts.branch } : {}), notes: [...notes, `FINISH failed: ${msg}. The run itself is still clean; the changes are left in ${opts.cwd}.`] };
+    }
+}
+//# sourceMappingURL=finish.js.map

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

@@ -0,0 +1,128 @@
+/**
+ * Registers the `/go <ticket>` entry point (spec decision §5 — NOT `/run` or
+ * `/work`, which collide with the Run and Work concepts), plus its companions
+ * `/go-status` and `/go-clean` (registered from this same pipeline registration
+ * path — src/index.ts only ever calls registerGoCommand).
+ *
+ * A `registerCommand` (not a static chain prompt) is used because the review→fix
+ * LOOP needs a runtime condition a markdown chain cannot express. The handler
+ * parses the remainder through the flag parser (`--here` in-place, `--fg`
+ * blocking, `--pr` push + PR at FINISH; unknown flags are refused with
+ * a usage warning), guards on `ctx.isIdle()` plus the run registry (same-ticket
+ * in-flight refusal, MAX_CONCURRENT_RUNS), and runs the pipeline. Everything
+ * downstream — ticket resolution, sessionKey, registry, run-row arg, the
+ * ActivityFeed header, and the handoff copy — receives the FLAG-FREE ticket.
+ *
+ * FINISH STAGE (spec §3c): when the review loop stops `clean`, the handler runs
+ * the deterministic FINISH stage (finish.ts): commit the run's work (worktree
+ * mode always; --here only when the pre-run baseline was verifiably clean) with
+ * a conventional subject + plan summary + the provenance trailer, and — with
+ * `--pr` — push the run branch and open a PR under the user's own gh auth. A
+ * FINISH failure NEVER flips a clean run to failed and never fakes a commit
+ * (§0.1): every skip/failure is an honest note on the handoff. The commit/PR
+ * land on `PipelineResult.finish`, `session.finish`, the registry row, a
+ * `finish_done` checkpoint record, and a `finish` row in the activity feed.
+ *
+ * WORKTREE BY DEFAULT (spec §3b): the run gets its own worktree + branch FIRST
+ * (`git worktree add -b yagni/<slug>-<shortId> ~/.yagni-code/worktrees/<shortId>
+ * HEAD`), and repoCtx, sessionKey, the checkpoint journal, and every resume
+ * snapshot are resolved against the WORKTREE path — fresh runs and
+ * registry-driven resumes agree on the same tree, so the same run always maps to
+ * the same sha1(sessionKey) journal file. A best-effort bootstrap installs
+ * dependencies (fail-open with an honest note; verify's infra-failure
+ * classification covers the rest). `--here` opts back into the legacy in-place
+ * behavior: dirty-tree guard + no-op guard unchanged, sessionKey from ctx.cwd,
+ * and never a WIP commit. If worktree creation itself fails, default /go stops
+ * before mutating the user's tree; `--here` is the explicit in-place escape
+ * hatch.
+ *
+ * DETACHED BY DEFAULT: /go returns the prompt as soon as the run session opens;
+ * the pipeline promise is tracked in the module-scoped run registry (mirrored to
+ * ~/.yagni-code/registry.ndjson) and completion delivers the existing handoff
+ * via `pi.sendUserMessage(handoff, { deliverAs: "followUp" })` (try/catch with a
+ * notify fallback — pi requires deliverAs when the agent is streaming). `--fg`
+ * restores blocking. On a NON-clean terminal outcome in worktree mode the run's
+ * work is preserved as a clearly-marked `wip(yagni): <ticket> - <stopReason>`
+ * commit on the run branch, so nothing is lost and /go-clean can remove the tree.
+ *
+ * When the session has a UI, it also paints a live activity feed in an
+ * `aboveEditor` widget (spec §1) under a PER-RUN key (`yagni-go:<runShortId>`) so
+ * two concurrent runs never flicker-fight one widget and one run's clearUI only
+ * removes its own panel. Every UI call is guarded behind `ctx.hasUI` and
+ * optional-chained so headless runs degrade gracefully. `runPipeline` is
+ * injected so the handler is unit-testable without spawning.
+ *
+ * Run tracking: the handler opens a tracked run session (a `runs` row visible on
+ * the Work page) around the pipeline — `start` before, `stage` for each pipeline
+ * boundary, and `finish` with an honest outcome afterwards. Every session call
+ * is fail-soft, so recording can never break `/go`.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { runFinish as defaultRunFinish } from "./finish.js";
+import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
+import { makeRunSession as defaultMakeRunSession } from "./runSession.js";
+import { bootstrapWorktree as defaultBootstrapWorktree, createRunWorktree as defaultCreateRunWorktree } from "./worktree.js";
+import type { CheckpointRecord, CheckpointStore, WorkspaceSnapshot } from "./types.js";
+/** Best-effort git context for the current worktree (all fields optional). */
+export interface RepoContext {
+    repo?: string;
+    branch?: string;
+    commitSha?: string;
+}
+export interface RegisterGoDeps {
+    runPipeline?: typeof defaultRunPipeline;
+    /** Injectable so the handler can be unit-tested without a network. */
+    makeRunSession?: typeof defaultMakeRunSession;
+    /** Injectable so the handler can be unit-tested without spawning git. */
+    resolveRepoContext?: (cwd: string | undefined, signal?: AbortSignal) => Promise<RepoContext>;
+    /** Injectable durable journal (default = local file + pi-journal combined). */
+    makeCheckpointStore?: (sessionKey: string, pi: ExtensionAPI, ctx: ExtensionCommandContext) => CheckpointStore;
+    /** Injectable live workspace snapshot used by the resume decision (default = git). */
+    resolveSnapshot?: (cwd: string, signal?: AbortSignal) => Promise<WorkspaceSnapshot>;
+    /**
+     * Resolve the ticket reference to its REAL brief (verbatim title + body) before
+     * planning. Default = a fail-soft POST to YAGNI's `/ask` ticketRef federation
+     * (live, workspace-scoped connector read). Injected so the handler is unit-testable
+     * without a network; a non-identifier arg short-circuits to null (raw arg passes
+     * through). Returns null on any miss / transport error (the honest blind fallback).
+     */
+    resolveTicketBrief?: (rawArg: string) => Promise<string | null>;
+    /** Injectable worktree creation (default: real `git worktree add -b … HEAD`). */
+    createWorktree?: typeof defaultCreateRunWorktree;
+    /** Injectable worktree bootstrap (default: best-effort `<pm> install --prefer-offline`). */
+    bootstrap?: typeof defaultBootstrapWorktree;
+    /** Injectable WIP-commit seam (default: real `git add -A` + commit in the worktree). */
+    commitWip?: (worktreePath: string, message: string) => Promise<string | undefined>;
+    /** Injectable FINISH stage (default: real git commit + optional push/PR). Never throws. */
+    runFinish?: typeof defaultRunFinish;
+    /** Injectable journal read for cross-process liveness (default: the file checkpoint store). */
+    loadJournal?: (sessionKey: string) => CheckpointRecord[];
+    /** Injectable fs existence check (worktree adoption on resume). */
+    exists?: (path: string) => boolean;
+    /** Clock seam for registry rows + staleness. */
+    now?: () => number;
+    baseUrl?: string;
+    getToken?: () => string | undefined;
+}
+/**
+ * Per-run UI key prefix: the widget/status keys are `yagni-go:<runShortId>` so
+ * two concurrent runs each own their panel and clearUI removes only its own.
+ */
+export declare const STATUS_KEY_PREFIX = "yagni-go:";
+/**
+ * Per-run key for the desktop's structured state record. Distinct from
+ * STATUS_KEY_PREFIX so the app routes by key rather than sniffing content.
+ */
+export declare const STATE_KEY_PREFIX = "yagni-go:state:";
+/**
+ * Steady animation cadence. The pipeline only emits events at stage/tool
+ * boundaries, so between them nothing would repaint and the spinner (and elapsed
+ * clock) freeze. A steady interval re-paints on its own, and the spinner frame is
+ * derived from wall-clock time so it advances smoothly no matter what triggered
+ * the paint. `setInterval` (not a self-rescheduling `setTimeout`) keeps the
+ * existing setTimeout-only mock-timer tests green: a real, immediately-cleared
+ * interval never fires inside those synchronous runs.
+ */
+export declare const ANIMATION_INTERVAL_MS = 120;
+export declare function registerGoCommand(pi: ExtensionAPI, deps?: RegisterGoDeps): void;
+//# sourceMappingURL=goCommand.d.ts.map