@cruxy/cli 0.7.0 → 0.8.0

package/dist/render/diff.d.ts

@@ -0,0 +1,19 @@
+import pc from "picocolors";
+import type { ActionPreview } from "../tools/types.js";
+/**
+ * The one diff/action-preview renderer (U.2). The approval prompt, PR preview,
+ * and the streaming render path all draw diffs through here — there is no
+ * second implementation to drift. Pure data → string; color is gated on a
+ * picocolors instance, so NO_COLOR/non-TTY callers get symbol-only `+`/`-`
+ * lines from the exact same code path.
+ */
+/** The picocolors instance type (colorless or not), from createColors. */
+export type Colors = ReturnType<typeof pc.createColors>;
+/** Cap on rendered preview lines before collapsing the rest. */
+export declare const PREVIEW_MAX_LINES = 40;
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export declare function renderActionPreview(preview: ActionPreview | undefined, c: Colors): string;

package/dist/render/diff.js

@@ -0,0 +1,80 @@
+/** Cap on rendered preview lines before collapsing the rest. */
+export const PREVIEW_MAX_LINES = 40;
+function diffLines(oldStr, newStr, c) {
+    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
+    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
+    return [...removed, ...added];
+}
+function renderPatchFiles(files, c) {
+    const out = [];
+    for (const file of files) {
+        if (file.op === "delete") {
+            out.push(c.red(`delete ${file.path}`));
+        }
+        else if (file.op === "create") {
+            out.push(c.green(`create ${file.path}`));
+            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
+            if (file.omittedLines > 0)
+                out.push(c.dim(`  ...${file.omittedLines} more lines`));
+        }
+        else {
+            out.push(c.yellow(`update ${file.path}`));
+            for (const hunk of file.hunks)
+                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
+        }
+    }
+    return out;
+}
+/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
+function renderPrPreview(preview, c) {
+    const out = [];
+    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
+    out.push("");
+    out.push(c.bold("commit"));
+    out.push(`  ${preview.commitSubject}`);
+    for (const line of bodyLines(preview.commitBody))
+        out.push(c.dim(`  ${line}`));
+    out.push("");
+    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
+    for (const line of bodyLines(preview.prBody))
+        out.push(c.dim(`  ${line}`));
+    return out;
+}
+/** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
+function bodyLines(body) {
+    const lines = body.replace(/\s+$/, "").split("\n");
+    return lines.length === 1 && lines[0] === "" ? [] : lines;
+}
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export function renderActionPreview(preview, c) {
+    if (!preview)
+        return "";
+    let lines;
+    if (preview.type === "edit") {
+        lines = diffLines(preview.oldStr, preview.newStr, c);
+    }
+    else if (preview.type === "patch") {
+        lines = renderPatchFiles(preview.files, c);
+    }
+    else if (preview.type === "pr") {
+        lines = renderPrPreview(preview, c);
+    }
+    else {
+        const header = preview.exists
+            ? c.yellow("OVERWRITE existing")
+            : c.green("create");
+        const body = preview.lines.map((l) => `  ${l}`);
+        if (preview.omittedLines > 0)
+            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
+        lines = [header, ...body];
+    }
+    if (lines.length > PREVIEW_MAX_LINES) {
+        const hidden = lines.length - PREVIEW_MAX_LINES;
+        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
+    }
+    return lines.map((l) => `  ${l}`).join("\n");
+}

package/dist/render/highlight.d.ts

@@ -0,0 +1,47 @@
+import type { Colors } from "./diff.js";
+/**
+ * Best-effort, bounded syntax highlighting for fenced code blocks in streamed
+ * markdown (U.2). Priorities, in order: never crash the stream, never hold the
+ * stream back, then look nice.
+ *
+ * - Prose passes through immediately, byte for byte. The only hold-back is a
+ *   line that is still a plausible fence opener (a leading backtick run), held
+ *   until disambiguated — bounded by one short line, never a block.
+ * - Inside a fence, lines are highlighted incrementally: each line is emitted
+ *   the moment its newline arrives, so latency is one line, and committed
+ *   output is never repainted.
+ * - Unknown language → plain text. A tokenizer throw → that line plain. The
+ *   tokenizer is hand-rolled (no highlighter dependency, in the same spirit as
+ *   the hand-rolled HTTP client) and colors only what it is sure about:
+ *   comments, strings, keywords, numbers.
+ */
+/** Cross-line tokenizer state (block comments / multi-line strings). */
+export interface HighlightCarry {
+    /** Inside a block comment (`/* … *``/`). */
+    blockComment: boolean;
+    /** Inside a multi-line string; the delimiter that will close it. */
+    stringDelim: string | null;
+}
+/** One line of code → styled line + the carry for the next line. */
+export type LineHighlighter = (line: string, lang: string | null, carry: HighlightCarry) => {
+    text: string;
+    carry: HighlightCarry;
+};
+/** Incremental highlighter for one streamed text segment. */
+export interface StreamHighlighter {
+    /** Feed a delta; returns the styled text that is safe to emit now. */
+    push(delta: string): string;
+    /** Return whatever is still held (segment end); resets to prose state. */
+    flush(): string;
+}
+/**
+ * Create the per-segment streaming highlighter. `highlightLine` is injectable
+ * for tests (e.g. to prove a throwing tokenizer degrades to plain text).
+ */
+export declare function createStreamHighlighter(c: Colors, highlightLine?: LineHighlighter): StreamHighlighter;
+/**
+ * Build the default per-line tokenizer over `c`. A plain left-to-right scan:
+ * comments dim, strings green, keywords magenta, numbers yellow, everything
+ * else untouched. Unknown language → identity.
+ */
+export declare function defaultLineHighlighter(c: Colors): LineHighlighter;

package/dist/render/highlight.js

@@ -0,0 +1,265 @@
+const FRESH_CARRY = { blockComment: false, stringDelim: null };
+/** A fence opener: ``` or longer, optional language word. */
+const FENCE_OPEN = /^(`{3,})([\w+#.-]*)\s*$/;
+/** A line that could still grow into a fence opener. */
+const FENCE_PLAUSIBLE = /^(?:`{1,2}|`{3,}[\w+#.-]*\s*)$/;
+/**
+ * Create the per-segment streaming highlighter. `highlightLine` is injectable
+ * for tests (e.g. to prove a throwing tokenizer degrades to plain text).
+ */
+export function createStreamHighlighter(c, highlightLine = defaultLineHighlighter(c)) {
+    let mode = "prose";
+    let atLineStart = true;
+    let lineBuf = "";
+    let lang = null;
+    let carry = FRESH_CARRY;
+    /** Highlight one completed code line; any tokenizer throw → plain text. */
+    const styleCodeLine = (line) => {
+        try {
+            const res = highlightLine(line, lang, carry);
+            carry = res.carry;
+            return res.text;
+        }
+        catch {
+            carry = FRESH_CARRY; // state is suspect after a throw; start clean
+            return line;
+        }
+    };
+    const push = (delta) => {
+        let out = "";
+        for (const ch of delta) {
+            if (mode === "prose") {
+                if (atLineStart && ch === "`") {
+                    mode = "maybe-fence";
+                    lineBuf = ch;
+                }
+                else {
+                    out += ch;
+                    atLineStart = ch === "\n";
+                }
+            }
+            else if (mode === "maybe-fence") {
+                if (ch === "\n") {
+                    const m = FENCE_OPEN.exec(lineBuf);
+                    if (m) {
+                        lang = m[2] ? m[2].toLowerCase() : null;
+                        carry = FRESH_CARRY;
+                        mode = "code";
+                        out += c.dim(lineBuf) + "\n";
+                    }
+                    else {
+                        mode = "prose";
+                        out += lineBuf + "\n";
+                    }
+                    lineBuf = "";
+                    atLineStart = true;
+                }
+                else {
+                    lineBuf += ch;
+                    if (!FENCE_PLAUSIBLE.test(lineBuf)) {
+                        // Can no longer become a fence (e.g. inline `code`) — release it.
+                        mode = "prose";
+                        out += lineBuf;
+                        lineBuf = "";
+                        atLineStart = false;
+                    }
+                }
+            }
+            else {
+                // code
+                if (ch === "\n") {
+                    if (/^`{3,}\s*$/.test(lineBuf)) {
+                        mode = "prose";
+                        out += c.dim(lineBuf) + "\n";
+                    }
+                    else {
+                        out += styleCodeLine(lineBuf) + "\n";
+                    }
+                    lineBuf = "";
+                    atLineStart = true;
+                }
+                else {
+                    lineBuf += ch;
+                }
+            }
+        }
+        return out;
+    };
+    const flush = () => {
+        // Segment ended mid-line: release the held text as-is (highlighted when we
+        // know it's code — styled *before* the language resets) and start the next
+        // segment back in prose state.
+        const out = lineBuf === "" ? "" : mode === "code" ? styleCodeLine(lineBuf) : lineBuf;
+        mode = "prose";
+        lineBuf = "";
+        atLineStart = true;
+        lang = null;
+        carry = FRESH_CARRY;
+        return out;
+    };
+    return { push, flush };
+}
+const JS_KEYWORDS = "abstract as async await break case catch class const continue debugger default delete do else enum export extends false finally for from function get if implements import in instanceof interface let new null of private protected public readonly return satisfies set static super switch this throw true try type typeof undefined var void while with yield";
+const PY_KEYWORDS = "and as assert async await break class continue def del elif else except False finally for from global if import in is lambda None nonlocal not or pass raise return True try while with yield match case self";
+const SH_KEYWORDS = "if then else elif fi for while until do done case esac function in select time coproc break continue return exit export local readonly declare set unset shift trap source alias cd echo printf read test";
+const GO_KEYWORDS = "break case chan const continue default defer else fallthrough for func go goto if import interface map nil package range return select struct switch true false type var";
+const RUST_KEYWORDS = "as async await break const continue crate dyn else enum extern false fn for if impl in let loop match mod move mut pub ref return self Self static struct super trait true type unsafe use where while";
+const words = (list) => new Set(list.split(" "));
+const JS_DEF = {
+    keywords: words(JS_KEYWORDS),
+    lineComment: "//",
+    blockComment: ["/*", "*/"],
+    quotes: ['"', "'", "`"],
+    multiline: ["`"],
+};
+const LANGS = {
+    js: JS_DEF,
+    jsx: JS_DEF,
+    ts: JS_DEF,
+    tsx: JS_DEF,
+    javascript: JS_DEF,
+    typescript: JS_DEF,
+    json: {
+        keywords: words("true false null"),
+        quotes: ['"'],
+        multiline: [],
+    },
+    py: {
+        keywords: words(PY_KEYWORDS),
+        lineComment: "#",
+        quotes: ['"', "'", '"""', "'''"],
+        multiline: ['"""', "'''"],
+    },
+    sh: {
+        keywords: words(SH_KEYWORDS),
+        lineComment: "#",
+        quotes: ['"', "'"],
+        multiline: [],
+    },
+    go: {
+        keywords: words(GO_KEYWORDS),
+        lineComment: "//",
+        blockComment: ["/*", "*/"],
+        quotes: ['"', "'", "`"],
+        multiline: ["`"],
+    },
+    rust: {
+        keywords: words(RUST_KEYWORDS),
+        lineComment: "//",
+        blockComment: ["/*", "*/"],
+        quotes: ['"'],
+        multiline: [],
+    },
+};
+// Aliases.
+LANGS.python = LANGS.py;
+LANGS.bash = LANGS.sh;
+LANGS.shell = LANGS.sh;
+LANGS.zsh = LANGS.sh;
+LANGS.golang = LANGS.go;
+LANGS.rs = LANGS.rust;
+/** Word characters for keyword/identifier scanning. */
+const WORD = /[A-Za-z0-9_$]/;
+/**
+ * Build the default per-line tokenizer over `c`. A plain left-to-right scan:
+ * comments dim, strings green, keywords magenta, numbers yellow, everything
+ * else untouched. Unknown language → identity.
+ */
+export function defaultLineHighlighter(c) {
+    return (line, lang, carry) => {
+        const def = lang ? LANGS[lang] : undefined;
+        if (!def)
+            return { text: line, carry };
+        // Longest quote first so `"""` wins over `"` in python.
+        const quotes = [...def.quotes].sort((a, b) => b.length - a.length);
+        let out = "";
+        let i = 0;
+        let next = { ...carry };
+        // Resume a multi-line construct from the previous line.
+        if (next.blockComment && def.blockComment) {
+            const close = line.indexOf(def.blockComment[1]);
+            if (close === -1)
+                return { text: c.dim(line), carry: next };
+            const end = close + def.blockComment[1].length;
+            out += c.dim(line.slice(0, end));
+            i = end;
+            next.blockComment = false;
+        }
+        else if (next.stringDelim) {
+            const close = findStringEnd(line, 0, next.stringDelim);
+            if (close === -1)
+                return { text: c.green(line), carry: next };
+            out += c.green(line.slice(0, close));
+            i = close;
+            next.stringDelim = null;
+        }
+        while (i < line.length) {
+            const rest = line.slice(i);
+            if (def.lineComment && rest.startsWith(def.lineComment)) {
+                out += c.dim(rest);
+                i = line.length;
+                break;
+            }
+            if (def.blockComment && rest.startsWith(def.blockComment[0])) {
+                const close = line.indexOf(def.blockComment[1], i + def.blockComment[0].length);
+                if (close === -1) {
+                    out += c.dim(rest);
+                    next = { ...next, blockComment: true };
+                    i = line.length;
+                    break;
+                }
+                const end = close + def.blockComment[1].length;
+                out += c.dim(line.slice(i, end));
+                i = end;
+                continue;
+            }
+            const quote = quotes.find((q) => rest.startsWith(q));
+            if (quote) {
+                const close = findStringEnd(line, i + quote.length, quote);
+                if (close === -1) {
+                    out += c.green(rest);
+                    if (def.multiline.includes(quote))
+                        next = { ...next, stringDelim: quote };
+                    i = line.length;
+                    break;
+                }
+                out += c.green(line.slice(i, close));
+                i = close;
+                continue;
+            }
+            const ch = line[i];
+            if (WORD.test(ch)) {
+                let j = i + 1;
+                while (j < line.length && WORD.test(line[j]))
+                    j++;
+                const word = line.slice(i, j);
+                if (def.keywords.has(word))
+                    out += c.magenta(word);
+                else if (/^\d/.test(word))
+                    out += c.yellow(word);
+                else
+                    out += word;
+                i = j;
+                continue;
+            }
+            out += ch;
+            i++;
+        }
+        return { text: out, carry: next };
+    };
+}
+/**
+ * Index just past the closing `delim` starting the scan at `from`, honoring
+ * backslash escapes; -1 when the string does not close on this line.
+ */
+function findStringEnd(line, from, delim) {
+    for (let i = from; i < line.length; i++) {
+        if (line[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (line.startsWith(delim, i))
+            return i + delim.length;
+    }
+    return -1;
+}

package/dist/render/index.d.ts

@@ -0,0 +1,14 @@
+import type { RenderStream, StreamRenderer } from "./types.js";
+export type { RenderCapabilities, RenderStream, StreamRenderer, } from "./types.js";
+export { detectCapabilities } from "./capabilities.js";
+export { renderActionPreview, PREVIEW_MAX_LINES, type Colors } from "./diff.js";
+export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
+export { PlainRenderer } from "./plain-renderer.js";
+export { TtyRenderer } from "./tty-renderer.js";
+/**
+ * Build the renderer for the detected environment: the managed-live-region
+ * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
+ * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
+ * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ */
+export declare function createRenderer(out?: RenderStream, err?: RenderStream, env?: NodeJS.ProcessEnv): StreamRenderer;

package/dist/render/index.js

@@ -0,0 +1,20 @@
+import { detectCapabilities } from "./capabilities.js";
+import { PlainRenderer } from "./plain-renderer.js";
+import { TtyRenderer } from "./tty-renderer.js";
+export { detectCapabilities } from "./capabilities.js";
+export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
+export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
+export { PlainRenderer } from "./plain-renderer.js";
+export { TtyRenderer } from "./tty-renderer.js";
+/**
+ * Build the renderer for the detected environment: the managed-live-region
+ * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
+ * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
+ * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ */
+export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
+    const caps = detectCapabilities(out, env);
+    return caps.cursor
+        ? new TtyRenderer(caps, out)
+        : new PlainRenderer(caps, out, err);
+}

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

@@ -0,0 +1,32 @@
+import type { ActionPreview } from "../tools/types.js";
+import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.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 declare class PlainRenderer implements StreamRenderer {
+    readonly caps: RenderCapabilities;
+    private readonly out;
+    private readonly err;
+    private readonly colors;
+    /** Per-turn leading-newline trim; also tells endSegment whether to newline. */
+    private print;
+    private wroteInSegment;
+    constructor(caps: RenderCapabilities, out: RenderStream, err: RenderStream);
+    private newPrinter;
+    beginTurn(): void;
+    write(delta: string): void;
+    endSegment(): void;
+    note(text: string): void;
+    preview(preview: ActionPreview): void;
+    status(): void;
+    endTurn(): void;
+    close(): void;
+}

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;
+}