@cruxy/cli 0.6.0 → 0.8.0

package/dist/render/plain-renderer.js

@@ -0,0 +1,61 @@
+import pc from "picocolors";
+import { createStreamPrinter } from "../cli/stream-print.js";
+import { renderActionPreview } from "./diff.js";
+/**
+ * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
+ * cursor-control sequences ever, and no color unless the capabilities say so
+ * (FORCE_COLOR); with color off, not a single ANSI byte leaves this class.
+ *
+ * Assistant text goes to `out` verbatim (beyond the per-turn leading-newline
+ * trim) so piped stdout stays pure model output; chrome (`note`) goes to `err`,
+ * matching the logger's stdout/stderr split. Transient `status` has no meaning
+ * in an append-only medium and is dropped — the loop reports anything durable
+ * via `note`.
+ */
+export class PlainRenderer {
+    caps;
+    out;
+    err;
+    colors;
+    /** Per-turn leading-newline trim; also tells endSegment whether to newline. */
+    print;
+    wroteInSegment = false;
+    constructor(caps, out, err) {
+        this.caps = caps;
+        this.out = out;
+        this.err = err;
+        this.colors = pc.createColors(caps.color);
+        this.print = this.newPrinter();
+    }
+    newPrinter() {
+        return createStreamPrinter((text) => {
+            this.wroteInSegment = true;
+            this.out.write(text);
+        });
+    }
+    beginTurn() {
+        this.print = this.newPrinter();
+        this.wroteInSegment = false;
+    }
+    write(delta) {
+        this.print(delta);
+    }
+    endSegment() {
+        if (this.wroteInSegment)
+            this.out.write("\n");
+        this.wroteInSegment = false;
+    }
+    note(text) {
+        this.err.write(this.colors.dim(text) + "\n");
+    }
+    preview(preview) {
+        const block = renderActionPreview(preview, this.colors);
+        if (block)
+            this.out.write(block + "\n");
+    }
+    status() {
+        // Append-only medium: transient state is dropped by design.
+    }
+    endTurn() { }
+    close() { }
+}

package/dist/render/tty-renderer.d.ts

@@ -0,0 +1,47 @@
+import type { ActionPreview } from "../tools/types.js";
+import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.js";
+/**
+ * The interactive renderer: committed content is append-only; the one transient
+ * thing on screen is a single managed status line, redrawn in place.
+ *
+ * The no-flicker discipline, concretely:
+ * - Only the status line is ever rewritten, via `\r` + erase-line — never a
+ *   screen clear, never a repaint of committed rows.
+ * - Every committed write first erases the status line, so the live region is
+ *   always the last row and committed text can never interleave with it. A
+ *   committed write *dismisses* the status (it does not redraw underneath), so
+ *   nothing re-renders per delta while text streams.
+ * - The status text is hard-truncated to the terminal width: a soft-wrapped
+ *   status would span two rows and erase-line could no longer clean it up.
+ *
+ * Fenced code blocks are highlighted incrementally (see highlight.ts): prose
+ * deltas pass straight through, code is styled line-by-line on arrival.
+ */
+export declare class TtyRenderer implements StreamRenderer {
+    readonly caps: RenderCapabilities;
+    private readonly out;
+    private readonly colors;
+    private print;
+    private highlighter;
+    private wroteInSegment;
+    private statusText;
+    private timer;
+    private frame;
+    private closed;
+    constructor(caps: RenderCapabilities, out: RenderStream);
+    private newPrinter;
+    /** Append committed content, erasing the status line first if one is live. */
+    private commit;
+    /** Erase the live status line (if any) and stop the spinner. */
+    private dismissStatus;
+    private stopTimer;
+    private drawStatus;
+    beginTurn(): void;
+    write(delta: string): void;
+    endSegment(): void;
+    note(text: string): void;
+    preview(preview: ActionPreview): void;
+    status(text: string | null): void;
+    endTurn(): void;
+    close(): void;
+}

package/dist/render/tty-renderer.js

@@ -0,0 +1,149 @@
+import pc from "picocolors";
+import { createStreamPrinter } from "../cli/stream-print.js";
+import { renderActionPreview } from "./diff.js";
+import { createStreamHighlighter, } from "./highlight.js";
+/** Erase the current line and return the cursor to column 0. */
+const CLEAR_LINE = "\r\x1b[2K";
+/** Spinner frames (braille); a static glyph when animation is disabled. */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const STATIC_FRAME = "◐";
+const SPINNER_INTERVAL_MS = 100;
+/**
+ * The interactive renderer: committed content is append-only; the one transient
+ * thing on screen is a single managed status line, redrawn in place.
+ *
+ * The no-flicker discipline, concretely:
+ * - Only the status line is ever rewritten, via `\r` + erase-line — never a
+ *   screen clear, never a repaint of committed rows.
+ * - Every committed write first erases the status line, so the live region is
+ *   always the last row and committed text can never interleave with it. A
+ *   committed write *dismisses* the status (it does not redraw underneath), so
+ *   nothing re-renders per delta while text streams.
+ * - The status text is hard-truncated to the terminal width: a soft-wrapped
+ *   status would span two rows and erase-line could no longer clean it up.
+ *
+ * Fenced code blocks are highlighted incrementally (see highlight.ts): prose
+ * deltas pass straight through, code is styled line-by-line on arrival.
+ */
+export class TtyRenderer {
+    caps;
+    out;
+    colors;
+    print;
+    highlighter;
+    wroteInSegment = false;
+    statusText = null;
+    timer = null;
+    frame = 0;
+    closed = false;
+    constructor(caps, out) {
+        this.caps = caps;
+        this.out = out;
+        this.colors = pc.createColors(caps.color);
+        this.highlighter = createStreamHighlighter(this.colors);
+        this.print = this.newPrinter();
+    }
+    newPrinter() {
+        return createStreamPrinter((text) => {
+            this.commit(this.highlighter.push(text));
+        });
+    }
+    /** Append committed content, erasing the status line first if one is live. */
+    commit(text) {
+        if (text === "")
+            return;
+        this.dismissStatus();
+        this.wroteInSegment = true;
+        this.out.write(text);
+    }
+    /** Erase the live status line (if any) and stop the spinner. */
+    dismissStatus() {
+        if (this.statusText === null)
+            return;
+        this.statusText = null;
+        this.stopTimer();
+        this.out.write(CLEAR_LINE);
+    }
+    stopTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    drawStatus() {
+        if (this.statusText === null)
+            return;
+        const glyph = this.caps.spinner
+            ? FRAMES[this.frame % FRAMES.length]
+            : STATIC_FRAME;
+        // Reserve glyph + space; truncate so the live line can never soft-wrap.
+        const room = Math.max(1, this.caps.width - 2);
+        const text = this.statusText.length > room
+            ? this.statusText.slice(0, Math.max(0, room - 1)) + "…"
+            : this.statusText;
+        this.out.write(`${CLEAR_LINE}${this.colors.cyan(glyph)} ${this.colors.dim(text)}`);
+    }
+    beginTurn() {
+        this.highlighter = createStreamHighlighter(this.colors);
+        this.print = this.newPrinter();
+        this.wroteInSegment = false;
+    }
+    write(delta) {
+        if (this.closed)
+            return;
+        this.print(delta);
+    }
+    endSegment() {
+        if (this.closed)
+            return;
+        this.commit(this.highlighter.flush());
+        if (this.wroteInSegment) {
+            this.commit("\n");
+            this.wroteInSegment = false;
+        }
+    }
+    note(text) {
+        if (this.closed)
+            return;
+        const room = Math.max(1, this.caps.width);
+        const line = text.length > room ? text.slice(0, room - 1) + "…" : text;
+        this.commit(this.colors.dim(line) + "\n");
+    }
+    preview(preview) {
+        if (this.closed)
+            return;
+        const block = renderActionPreview(preview, this.colors);
+        if (block)
+            this.commit(block + "\n");
+    }
+    status(text) {
+        if (this.closed)
+            return;
+        if (text === null) {
+            this.dismissStatus();
+            return;
+        }
+        this.statusText = text;
+        this.drawStatus();
+        if (this.caps.spinner && this.timer === null) {
+            this.timer = setInterval(() => {
+                this.frame++;
+                this.drawStatus();
+            }, SPINNER_INTERVAL_MS);
+            // Never hold the process open for a spinner.
+            this.timer.unref?.();
+        }
+    }
+    endTurn() {
+        if (this.closed)
+            return;
+        this.dismissStatus();
+        this.commit(this.highlighter.flush());
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.endTurn();
+        this.closed = true;
+    }
+}

package/dist/render/types.d.ts

@@ -0,0 +1,76 @@
+import type { ActionPreview } from "../tools/types.js";
+/**
+ * The streaming render seam (U.2): the agent loop talks to a
+ * {@link StreamRenderer}, never to raw stdout. Two implementations exist —
+ * `TtyRenderer` (managed one-line live region, append-only committed content)
+ * and `PlainRenderer` (append-only, zero ANSI) — picked by the factory from
+ * detected {@link RenderCapabilities}. Same swappable discipline as
+ * `Formatter`/`VectorStore`.
+ */
+/**
+ * What the output medium supports, detected once at construction (see
+ * `detectCapabilities`). Renderers and the factory key off these flags; nothing
+ * downstream re-probes the environment.
+ */
+export interface RenderCapabilities {
+    /** The primary output stream is a terminal. */
+    tty: boolean;
+    /** Emit ANSI color (NO_COLOR / FORCE_COLOR / TTY resolved; `TERM=dumb` → false). */
+    color: boolean;
+    /** Cursor-control sequences are safe (`tty` and not `TERM=dumb`). */
+    cursor: boolean;
+    /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
+    spinner: boolean;
+    /** Terminal columns; 80 when unknown (non-TTY). */
+    width: number;
+}
+/**
+ * How the agent loop paints a turn. The contract that keeps output flicker-free:
+ *
+ * - **Committed content is append-only.** `write`/`note`/`preview` output is
+ *   never repainted, moved, or cleared.
+ * - **Transient state is one line.** `status` owns a single live line that is
+ *   redrawn in place and erased before any committed write lands.
+ *
+ * Call shape per user turn: `beginTurn` → per model turn: `write`* +
+ * `endSegment`, with `status`/`note`/`preview` between segments → `endTurn`.
+ * All methods must be safe to call in any environment — degradation is the
+ * implementation's job, not the caller's.
+ */
+export interface StreamRenderer {
+    readonly caps: RenderCapabilities;
+    /** Start a user turn: reset leading-newline trim and code-fence state. */
+    beginTurn(): void;
+    /**
+     * Append streamed assistant text. Must forward promptly — implementations may
+     * hold back at most the current line (for fence detection), never the block
+     * or the response. Dismisses any live status first.
+     */
+    write(delta: string): void;
+    /**
+     * Close one model-turn text segment: flush any held partial line / open
+     * fence and terminate with a single newline (only if the segment produced
+     * visible text), so whatever follows starts on its own line.
+     */
+    endSegment(): void;
+    /** A committed one-line chrome note (e.g. `✓ read_file src/x.ts`), dim when colored. */
+    note(text: string): void;
+    /** A committed diff/action preview, rendered by the shared diff renderer. */
+    preview(preview: ActionPreview): void;
+    /**
+     * Replace the transient status line ("thinking…", "running bash…"); `null`
+     * clears it. Where in-place updates are impossible this may drop the text —
+     * status is progress decor, never information of record (use `note` for that).
+     */
+    status(text: string | null): void;
+    /** End the user turn: clear any status, flush everything held. */
+    endTurn(): void;
+    /** Release resources (spinner timer). Further calls are no-ops. */
+    close(): void;
+}
+/** The minimal stream surface a renderer writes to. Injectable for tests. */
+export interface RenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(text: string): unknown;
+}

package/dist/render/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {