sequant 2.2.0 → 2.4.0

package/dist/src/lib/cli-ui/run-renderer.d.ts

@@ -0,0 +1,265 @@
+/**
+ * RunRenderer — single coordinator for all `sequant run` stdout output.
+ *
+ * Replaces the dual-output regression where `PhaseSpinner` (legacy, #244) and
+ * the parallel-mode `▸/✔` lines (#458) both wrote to stdout for single-issue
+ * runs and produced overwritten / missing-duration lines.
+ *
+ * Three modes implement the same `RunRenderer` interface:
+ *   - TTYRenderer:           live grid (top, redrawn ~1Hz) + events log (below)
+ *   - NonTTYRenderer:        append-only `[HH:MM:SS]` events + 60s heartbeat
+ *   - OrchestratorRenderer:  no-op when SEQUANT_ORCHESTRATOR is set so MCP's
+ *                            `emitProgressLine` JSON is the only stdout
+ *
+ * See issue #618.
+ */
+import type { PhasePauseHandle } from "../workflow/types.js";
+import type { IssueRegistration, IssueState, ProgressEvent, RenderOptions, RendererMode, RunRenderer, SummaryRenderInput } from "./run-renderer-types.js";
+/**
+ * #624 Item 4: normalized failure signature for dedup decisions.
+ *
+ * Strips ANSI escape sequences, lowercases, trims whitespace, and truncates to
+ * the first 80 visible chars. The plan deliberately chose a length-bounded
+ * prefix over a crypto hash so debugging can match signatures by eye.
+ */
+export declare function failureSignature(error: string | undefined): string;
+/**
+ * #624 Item 3 / Derived AC-D2: shared suffix builder used by all three retry
+ * sites (NonTTY events log, TTY events log, TTY status header). Centralizes
+ * the `(attempt N/M)` / `loop N/M` literals so they cannot drift between paths.
+ *
+ * `kind` selects the surface:
+ *   - "events" → events-log line: leading space + parentheses
+ *   - "header" → status cell: leading space, no parentheses
+ *
+ * Returns the empty string when the attempt counter does not apply
+ * (no iteration, iteration === 1, or non-positive).
+ */
+export declare function formatRetrySuffix(iteration: number | undefined, maxIterations: number, kind: "events" | "header"): string;
+declare abstract class BaseRenderer implements RunRenderer, PhasePauseHandle {
+    protected readonly issues: Map<number, IssueState>;
+    protected readonly stdoutWrite: (s: string) => void;
+    protected readonly stderrWrite: (s: string) => void;
+    protected readonly now: () => number;
+    protected readonly wallClock: () => Date;
+    protected readonly noColor: boolean;
+    protected readonly runStartedAt: number;
+    protected paused: boolean;
+    protected disposed: boolean;
+    constructor(options: RenderOptions);
+    registerIssue(reg: IssueRegistration): void;
+    setPhasePlan(issue: number, phases: string[]): void;
+    onEvent(event: ProgressEvent): void;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    pause(): void;
+    resume(): void;
+    /**
+     * #647 AC-3: default notice path — just write to the renderer's stdout
+     * channel. NonTTYRenderer keeps this default (no live zone to manage).
+     * TTYRenderer overrides to clear the live zone before writing so
+     * log-update's cursor model stays consistent with the actual terminal.
+     */
+    appendNotice(message: string): void;
+    abstract renderSummary(input: SummaryRenderInput): void;
+    dispose(): void;
+    protected applyEvent(state: IssueState, event: ProgressEvent): void;
+    /** Mark an issue done after PR is recorded — derived from phase completion. */
+    protected maybeMarkIssueDone(state: IssueState): void;
+    protected afterEvent(_event: ProgressEvent, state: IssueState): void;
+    protected afterStateChange(): void;
+    protected onPause(): void;
+    protected onResume(): void;
+    protected onDispose(): void;
+}
+/**
+ * No-op renderer used when `SEQUANT_ORCHESTRATOR` is set.
+ *
+ * The orchestrator (e.g. MCP server) consumes `emitProgressLine` JSON from
+ * batch-executor directly. Rendering anything else from the CLI would be
+ * double-emission. We still track state so `renderSummary` could be useful
+ * if explicitly invoked, but neither stdout nor stderr is touched.
+ */
+export declare class OrchestratorRenderer extends BaseRenderer {
+    renderSummary(): void;
+}
+export declare class NonTTYRenderer extends BaseRenderer {
+    private heartbeatTimer;
+    private readonly heartbeatMs;
+    private readonly columnsOverride?;
+    private readonly maxLoopIterations;
+    private lastEventAt;
+    constructor(options: RenderOptions);
+    private getColumns;
+    private startHeartbeat;
+    /** Test hook: drive a heartbeat without waiting on real timers. */
+    tickHeartbeatNow(): void;
+    private tickHeartbeat;
+    protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    private emitEventLine;
+    /** Append a single `\n`-terminated line with `[HH:MM:SS]` prefix. */
+    private emitLine;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    renderSummary(input: SummaryRenderInput): void;
+    protected onDispose(): void;
+}
+/**
+ * #624 Derived AC-D1: test-only observability for the log-update stub. Tests
+ * can read `replacementCount` and `lastFrame` to verify the frame is *replaced*
+ * on each redraw rather than appended — the foundational guarantee that Items
+ * 1 and 2 rely on.
+ *
+ * `clearCalls` / `doneCalls` (added in the hardening pass) let AC-2.2 verify
+ * the renderer actually invokes `logUpdate.clear()` + `logUpdate.done()` during
+ * `renderSummary` teardown — not just that the stub's local `lastFrame` was
+ * reset.
+ */
+export interface TTYTestStub {
+    /** Number of times the live frame was replaced (not the initial write). */
+    readonly replacementCount: number;
+    /** The most recent live frame text passed to log-update. */
+    readonly lastFrame: string;
+    /** Number of times `logUpdate.clear()` was invoked. */
+    readonly clearCalls: number;
+    /** Number of times `logUpdate.done()` was invoked. */
+    readonly doneCalls: number;
+}
+export declare class TTYRenderer extends BaseRenderer {
+    private readonly liveTickMs;
+    private liveTimer;
+    private spinnerFrame;
+    private readonly columnsOverride?;
+    private readonly rowsOverride?;
+    private readonly noSignalListeners;
+    private readonly stallThresholdMs;
+    private readonly multiIssueRowCap;
+    private readonly maxLoopIterations;
+    private readonly logUpdateImpl;
+    private readonly logUpdateClear;
+    private readonly logUpdateDone;
+    private resizeListener;
+    private banner;
+    private readonly _testStub;
+    constructor(options: RenderOptions);
+    /**
+     * #624 Derived AC-D1: expose the test-only log-update stub. Returns `null`
+     * when not in test mode (production renders go through real `log-update`).
+     *
+     * #647 AC-D3 warning: this stub does NOT model `log-update`'s ANSI cursor
+     * or scrollback semantics. Tests that assert on `stub.lastFrame` only see
+     * the most recent frame, not whether earlier frames remained stranded in
+     * scrollback. Header-count / duplicate-header assertions MUST use
+     * `scrollback-harness.ts` (real `createLogUpdate` + VirtualTerminal),
+     * otherwise they will pass green even when the production rendering is
+     * broken — see #624 for the precedent.
+     */
+    getTestStub(): TTYTestStub | null;
+    private startLiveTimer;
+    private installSignalListeners;
+    /** Test hook: drive a tick without waiting on real timers. */
+    tickNow(): void;
+    private tick;
+    protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    protected afterStateChange(): void;
+    /** Set a banner that renders above the live grid (e.g. worktree-loss). */
+    setBanner(text: string | null): void;
+    private appendEventLine;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    renderSummary(input: SummaryRenderInput): void;
+    protected onPause(): void;
+    protected onResume(): void;
+    /**
+     * #647 AC-3: TTYRenderer override. Writes the notice above the live zone
+     * the same way `appendEventLine` does (clear → write → redraw), so
+     * log-update's `previousLineCount` stays consistent with the actual
+     * terminal state. If the renderer is already paused (e.g., during
+     * verbose subprocess streaming), skip the clear/redraw and just write;
+     * the eventual `resume()` will redraw cleanly.
+     */
+    appendNotice(message: string): void;
+    protected onDispose(): void;
+    private getColumns;
+    /**
+     * #624 Item 1: terminal row count, with a safe default for piped / detached
+     * stdout where `process.stdout.rows` is undefined.
+     */
+    private getRows;
+    /**
+     * #624 Item 1: hard ceiling on live-zone height. The cap is
+     * `max(8, rows - 5)`, dropping to `max(8, rows - 7)` when a banner is active
+     * so the banner + a few separator rows still fit. The floor of 8 prevents
+     * the live zone from collapsing on tiny terminals.
+     */
+    private getMaxLiveRows;
+    private redraw;
+    /** Public for tests — render the live zone to a string without emitting. */
+    renderLiveFrame(columns?: number): string;
+    /**
+     * #624 Item 1 (AC-1.1): hard ceiling on rendered frame height. The interior
+     * `applyRowCap` already collapses excess issues into the rollup row, but the
+     * frame can still drift over the cap if many issues have multi-line status
+     * cells (sub-status + phase sequence). This is the belt-and-braces clamp
+     * that guarantees `log-update` never sees a frame taller than the terminal.
+     *
+     * Always engages — when `rows` isn't explicitly provided, `getRows()` returns
+     * `DEFAULT_TERMINAL_ROWS` (100) so the cap is generous but never disengaged.
+     */
+    private clampFrameHeight;
+    private renderNarrowFrame;
+    private renderSingleIssueFrame;
+    private renderMultiIssueFrame;
+    /**
+     * AC-28 + #624 Item 1: enforce the per-frame issue row cap, derived from
+     * the smaller of `multiIssueRowCap` (static config) and a dynamic ceiling
+     * computed from terminal height. The dynamic ceiling reserves ~3 lines per
+     * issue (status header + sub-status + separator) and a fixed overhead for
+     * the frame header, blank lines, grid borders, and the rollup line.
+     *
+     * If the cap is not exceeded, returns all issues unchanged. Otherwise: keep
+     * all non-done rows, then fill remaining slots with the most recently
+     * completed done rows; older done rows roll up into a single summary entry.
+     */
+    private applyRowCap;
+    /**
+     * #624 Item 1 (AC-1.1): smaller of the configured static cap and the
+     * dynamic terminal-height-derived cap. Each issue row takes roughly 3 grid
+     * lines (header, sub-status, separator); the fixed overhead covers the
+     * frame title, blank lines, grid borders, and the rollup row.
+     *
+     * Always engages — when `rows` isn't explicitly provided, `getRows()` returns
+     * `DEFAULT_TERMINAL_ROWS` (100) which produces a dynamic cap of ~30, well
+     * above the static `multiIssueRowCap` default of 10, so the static cap stays
+     * in charge for normal-height terminals.
+     */
+    private effectiveRowCap;
+    private statusHeader;
+    private statusSubLines;
+    private statusCellLines;
+    private runHeader;
+    private rollupLine;
+    private drawKeyValueTable;
+    private drawIssueGrid;
+}
+export interface CreateRendererOptions extends RenderOptions {
+    /** Force a specific mode (otherwise auto-detected from env + TTY). */
+    mode?: RendererMode;
+}
+/**
+ * Create a `RunRenderer` matching the current execution context.
+ *
+ * Detection order:
+ *   1. Explicit `mode` override.
+ *   2. `SEQUANT_ORCHESTRATOR` env var → orchestrator (no-op).
+ *   3. `process.stdout.isTTY` (or `options.isTTY`) → TTY renderer.
+ *   4. Otherwise → non-TTY renderer.
+ */
+export declare function createRunRenderer(options?: CreateRendererOptions): RunRenderer;
+/**
+ * Public summary helper — used by the legacy displaySummary path so callers
+ * that bypass the renderer still get the new grid layout.
+ */
+export declare function renderRunSummary(input: SummaryRenderInput, options?: {
+    stdoutWrite?: (s: string) => void;
+    noColor?: boolean;
+    columns?: number;
+}): void;
+export {};