xcoder-dna 0.0.0-stage → 1.3.1

package/dist/util/footer-manager.d.ts

@@ -0,0 +1,124 @@
+import { FooterRenderer } from "./footer-renderer.js";
+import { type ScrollRegionGuard } from "./scroll-region-guard.js";
+import type { SdlcStage } from "../types.js";
+/**
+ * Specification passed to FooterManager.init() from the orchestrator.
+ */
+export interface FooterSpec {
+    /** Effective ANSI gate: TTY attached and NO_COLOR unset (see isInteractiveStdout). */
+    tty: boolean;
+    /**
+     * RAW task title (the goal) shown in the footer. NOT pre-truncated — the
+     * renderer owns the 50-character field.
+     */
+    taskTitle?: string;
+    /**
+     * @deprecated Use `taskTitle`. Retained for compatibility: when `taskTitle`
+     * is absent this value is treated as the raw title.
+     */
+    taskDesc?: string;
+    /**
+     * Optional opt-out for orchestrator-adjacent runners. When true the
+     * singleton still exists (consumers may optional-chain safely) but no
+     * footer output, scroll region, spinner, or ANSI escapes are ever
+     * emitted. Defaults to false.
+     */
+    quiet?: boolean;
+}
+/**
+ * Public API facade for the terminal status footer.
+ *
+ * Manages FooterState + FooterRenderer lifecycle.
+ * Serializes concurrent updates via a microtask queue (the JS event loop
+ * naturally batches all synchronous calls into one render).
+ *
+ * Design reference: `src/util/footer-state.ts`, `src/util/footer-renderer.ts`
+ */
+export declare class FooterManager {
+    private static _instance;
+    private _state;
+    private _renderer;
+    private _scrollRegionGuard;
+    private _muted;
+    private _pending;
+    private _flushScheduled;
+    private constructor();
+    /**
+     * Initialize the singleton footer. Sole caller: SdlcOrchestrator._runLoop.
+     * Consumers are restricted to `FooterManager.instance()?.` optional-chained
+     * update/hide/show/shutdown/writeSafe and must never call init.
+     *
+     * Availability matrix — the footer is visible iff ALL of these hold:
+     *
+     * 1) Path gate: the task runs through SdlcOrchestrator.run()/resume() into
+     *    _runLoop. Status/bench/backlog list|status|pick|done/sprint/observe/
+     *    release/index/test/swarm never construct the orchestrator and never
+     *    show a footer. Backlog start/continue DO route through the
+     *    orchestrator and DO show one.
+     * 2) TTY gate: process.stdout.isTTY === true at init time (ANSI/cursor/
+     *    scroll-region output is only safe on a real terminal; piped output
+     *    stays raw).
+     * 3) NO_COLOR gate: process.env.NO_COLOR is unset. Setting NO_COLOR makes
+     *    spec.tty false, so zero escape sequences are emitted and redirected
+     *    output stays clean.
+     * 4) Lifecycle gate: the footer is outside the interrupt-hide window and
+     *    has not yet been shut down by the execution loop.
+     *
+     * The quiet flag is a deliberate opt-out for orchestrator-adjacent runners:
+     * the singleton exists (so optional-chained consumers are safe) but no
+     * footer is ever painted and no timer is started.
+     */
+    static init(spec: FooterSpec): FooterManager;
+    /** Get the current singleton instance (may be null if not initialized). */
+    static instance(): FooterManager | null;
+    /** Whether the footer is active (TTY attached). */
+    static isActive(): boolean;
+    /**
+     * Write text safely above the footer. If the footer is active (TTY),
+     * routes through the ScrollRegionGuard to preserve the reserved bottom row.
+     * If inactive, writes directly to process.stdout.
+     */
+    static writeSafe(text: string): void;
+    /** Get the ScrollRegionGuard instance (for OutputInterceptor). */
+    getScrollRegionGuard(): ScrollRegionGuard | null;
+    /** Get the FooterRenderer instance (for direct access to writeAbove / forceRender). */
+    getFooterRenderer(): FooterRenderer;
+    /** Agent started thinking — show spinner and agent ID. */
+    updateThinkingStart(agentId: string): void;
+    /** Agent stopped thinking. */
+    updateThinkingStop(): void;
+    /** Agent performed an action. */
+    updateAction(tool: string): void;
+    /** Agent received an observation. */
+    updateObservation(ok: boolean, text: string): void;
+    /** Update token count display. */
+    updateTokens(inputTokens: number, outputTokens: number): void;
+    /** Update current SDLC stage. */
+    updateStage(stage: SdlcStage): void;
+    /** Update document info. */
+    updateDocument(docs: string): void;
+    /**
+     * Temporarily hide the footer (e.g. for interrupt prompts).
+     * Call show() to restore.
+     */
+    hide(): void;
+    /**
+     * Restore the footer after being hidden.
+     */
+    show(): void;
+    /**
+     * Shutdown the footer — teardown scroll region, clear line, null singleton.
+     * Called when the task run finishes or is interrupted.
+     */
+    shutdown(): void;
+    /**
+     * Handle terminal resize by reconfiguring the renderer.
+     */
+    onResize(): void;
+    /**
+     * Accumulate partial state changes and flush on the next microtask.
+     * This coalesces multiple synchronous calls into a single render.
+     */
+    private _apply;
+    private _flush;
+}

package/dist/util/footer-manager.js

@@ -0,0 +1,195 @@
+// xcoder:version 4 | xcoder:task task-3e056b | xcoder:updated 2026-11-03T17:57:40.885Z | xcoder:subtask code-st-f19254
+import { FooterRenderer } from "./footer-renderer.js";
+import { createFooterState } from "./footer-state.js";
+import { createScrollRegionGuard } from "./scroll-region-guard.js";
+import { XCODER_VERSION } from "../version.js";
+/**
+ * Public API facade for the terminal status footer.
+ *
+ * Manages FooterState + FooterRenderer lifecycle.
+ * Serializes concurrent updates via a microtask queue (the JS event loop
+ * naturally batches all synchronous calls into one render).
+ *
+ * Design reference: `src/util/footer-state.ts`, `src/util/footer-renderer.ts`
+ */
+export class FooterManager {
+    static _instance = null;
+    _state;
+    _renderer;
+    _scrollRegionGuard = null;
+    _muted = false;
+    _pending = {};
+    _flushScheduled = false;
+    constructor(state) {
+        this._state = state;
+        this._renderer = new FooterRenderer();
+    }
+    /**
+     * Initialize the singleton footer. Sole caller: SdlcOrchestrator._runLoop.
+     * Consumers are restricted to `FooterManager.instance()?.` optional-chained
+     * update/hide/show/shutdown/writeSafe and must never call init.
+     *
+     * Availability matrix — the footer is visible iff ALL of these hold:
+     *
+     * 1) Path gate: the task runs through SdlcOrchestrator.run()/resume() into
+     *    _runLoop. Status/bench/backlog list|status|pick|done/sprint/observe/
+     *    release/index/test/swarm never construct the orchestrator and never
+     *    show a footer. Backlog start/continue DO route through the
+     *    orchestrator and DO show one.
+     * 2) TTY gate: process.stdout.isTTY === true at init time (ANSI/cursor/
+     *    scroll-region output is only safe on a real terminal; piped output
+     *    stays raw).
+     * 3) NO_COLOR gate: process.env.NO_COLOR is unset. Setting NO_COLOR makes
+     *    spec.tty false, so zero escape sequences are emitted and redirected
+     *    output stays clean.
+     * 4) Lifecycle gate: the footer is outside the interrupt-hide window and
+     *    has not yet been shut down by the execution loop.
+     *
+     * The quiet flag is a deliberate opt-out for orchestrator-adjacent runners:
+     * the singleton exists (so optional-chained consumers are safe) but no
+     * footer is ever painted and no timer is started.
+     */
+    static init(spec) {
+        if (FooterManager._instance) {
+            FooterManager._instance.shutdown();
+        }
+        const state = createFooterState({
+            tty: spec.tty,
+            // Raw title — the renderer applies the 50-char field. `taskDesc` is the
+            // deprecated alias, accepted so older callers keep working.
+            taskDesc: spec.taskTitle ?? spec.taskDesc ?? null,
+            version: XCODER_VERSION,
+        });
+        const mgr = new FooterManager(state);
+        mgr._muted = spec.quiet === true;
+        FooterManager._instance = mgr;
+        if (state.tty && !mgr._muted) {
+            mgr._renderer.setup(state);
+            // Create the ScrollRegionGuard after setup so it knows the active state.
+            mgr._scrollRegionGuard = createScrollRegionGuard(mgr._renderer, () => mgr._state);
+        }
+        return mgr;
+    }
+    /** Get the current singleton instance (may be null if not initialized). */
+    static instance() {
+        return FooterManager._instance;
+    }
+    /** Whether the footer is active (TTY attached). */
+    static isActive() {
+        return FooterManager._instance != null && FooterManager._instance._state.tty;
+    }
+    /**
+     * Write text safely above the footer. If the footer is active (TTY),
+     * routes through the ScrollRegionGuard to preserve the reserved bottom row.
+     * If inactive, writes directly to process.stdout.
+     */
+    static writeSafe(text) {
+        const mgr = FooterManager._instance;
+        if (mgr && mgr._scrollRegionGuard && mgr._state.tty) {
+            mgr._scrollRegionGuard.write(text);
+        }
+        else {
+            process.stdout.write(text);
+        }
+    }
+    /** Get the ScrollRegionGuard instance (for OutputInterceptor). */
+    getScrollRegionGuard() {
+        return this._scrollRegionGuard;
+    }
+    /** Get the FooterRenderer instance (for direct access to writeAbove / forceRender). */
+    getFooterRenderer() {
+        return this._renderer;
+    }
+    // ── update helpers ──
+    /** Agent started thinking — show spinner and agent ID. */
+    updateThinkingStart(agentId) {
+        this._apply({ agentId, spinner: true });
+        if (!this._muted) {
+            this._renderer.startSpinner();
+        }
+    }
+    /** Agent stopped thinking. */
+    updateThinkingStop() {
+        this._renderer.stopSpinner();
+        this._apply({ spinner: false });
+    }
+    /** Agent performed an action. */
+    updateAction(tool) {
+        this._apply({ action: tool });
+    }
+    /** Agent received an observation. */
+    updateObservation(ok, text) {
+        // Show observing state briefly.
+        const preview = text.length > 40 ? text.slice(0, 37) + "..." : text;
+        this._apply({ observing: true, action: ok ? preview : `✗ ${preview}` });
+        // Clear observing after a tick.
+        setTimeout(() => {
+            if (this._state.observing) {
+                this._apply({ observing: false });
+            }
+        }, 0);
+    }
+    /** Update token count display. */
+    updateTokens(inputTokens, outputTokens) {
+        this._apply({ tokens: `${inputTokens} in / ${outputTokens} out` });
+    }
+    /** Update current SDLC stage. */
+    updateStage(stage) {
+        this._apply({ stage });
+    }
+    /** Update document info. */
+    updateDocument(docs) {
+        this._apply({ docs });
+    }
+    /**
+     * Temporarily hide the footer (e.g. for interrupt prompts).
+     * Call show() to restore.
+     */
+    hide() {
+        this._renderer.hide();
+    }
+    /**
+     * Restore the footer after being hidden.
+     */
+    show() {
+        this._renderer.show(this._state);
+    }
+    /**
+     * Shutdown the footer — teardown scroll region, clear line, null singleton.
+     * Called when the task run finishes or is interrupted.
+     */
+    shutdown() {
+        this._renderer.teardown();
+        if (FooterManager._instance === this) {
+            FooterManager._instance = null;
+        }
+    }
+    /**
+     * Handle terminal resize by reconfiguring the renderer.
+     */
+    onResize() {
+        this._renderer.reconfigure(this._state);
+    }
+    // ── private ──
+    /**
+     * Accumulate partial state changes and flush on the next microtask.
+     * This coalesces multiple synchronous calls into a single render.
+     */
+    _apply(patch) {
+        Object.assign(this._pending, patch);
+        if (!this._flushScheduled) {
+            this._flushScheduled = true;
+            Promise.resolve().then(() => {
+                this._flush();
+            });
+        }
+    }
+    _flush() {
+        this._flushScheduled = false;
+        Object.assign(this._state, this._pending);
+        this._pending = {};
+        if (this._state.tty) {
+            this._renderer.render(this._state);
+        }
+    }
+}

package/dist/util/footer-renderer.d.ts

@@ -0,0 +1,67 @@
+import type { FooterState } from "./footer-state.js";
+/**
+ * Converts a FooterState into a single ANSI escape sequence string
+ * that paints a 1-row footer at the bottom of the terminal.
+ *
+ * Design:
+ * - 1-row footer using scroll region to reserve the bottom line.
+ * - Truncation priority: stage+spinner > action > tokens > agentId > taskDesc > docs.
+ * - Respects NO_COLOR and TTY detection.
+ * - Handles window resize by re-reading process.stdout.columns.
+ */
+export declare class FooterRenderer {
+    private _active;
+    private _hidden;
+    private _spinnerIdx;
+    private _spinnerInterval;
+    private _currentState;
+    private _noColor;
+    /**
+     * Perform one-time setup: enable scroll region, hide cursor.
+     * Must be called before render(). Safe to call when already active (no-op).
+     */
+    setup(state: FooterState): void;
+    /**
+     * Render the current state to the reserved bottom row.
+     * Handles layout, truncation, and spinner animation.
+     */
+    render(state: FooterState): void;
+    /** Re-read terminal size and re-apply scroll region after a resize. */
+    reconfigure(state: FooterState, partial?: Partial<FooterState>): void;
+    /** Temporarily hide the footer (e.g. during interrupt prompts). */
+    hide(): void;
+    /** Restore the footer after being hidden. */
+    show(state: FooterState): void;
+    /**
+     * Return the current reserved scroll-region bottom row index (height - 1).
+     * Used by ScrollRegionGuard to know which row to keep free.
+     */
+    getScrollBottom(): number;
+    /**
+     * Force-render the footer without checking _hidden/_active guards.
+     * Used by ScrollRegionGuard during re-establish after a guarded write.
+     */
+    forceRender(state: FooterState): void;
+    /**
+     * Write text above the footer safely. Saves cursor, resets scroll region,
+     * writes the text, re-establishes scroll region, re-renders footer,
+     * and restores cursor. This is the core defensive write — it ensures
+     * no output can break the scroll region.
+     */
+    writeAbove(text: string, state: FooterState): void;
+    /**
+     * Tear down: reset scroll region, show cursor, clear footer.
+     */
+    teardown(): void;
+    private _render;
+    private _clearFooterRow;
+    /**
+     * Start spinner tick — called by FooterManager when initiating thinking.
+     * Managed here so the renderer owns the interval lifecycle.
+     */
+    startSpinner(): void;
+    /**
+     * Stop spinner tick — called by FooterManager when thinking stops.
+     */
+    stopSpinner(): void;
+}