@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tui/components/editor.js

@@ -0,0 +1,530 @@
+/**
+ * 多行编辑器组件（设计 §12.3、§12.4）。[B4]
+ *
+ * - 渲染：上下边框之间按列宽折行（不切开字素与折叠标记）；超过 `maxVisibleLines` 时视窗跟随光标，
+ *   边框上提示上 / 下方隐藏的行数；获焦时在光标处输出 CURSOR_MARKER 并反显光标格。
+ * - 键位：`tui.editor.*`（见 keybindings.ts）。Enter 提交（`disableSubmit` 时忽略）；Shift+Enter / Ctrl+J 换行；
+ *   Up/Down 在首 / 末视觉行时浏览历史（单行文本或空文本或已在浏览中），否则按视觉行移动。
+ * - 括号粘贴（`ESC[200~…ESC[201~`，由 StdinBuffer 合成一次输入）：> 10 行或 > 1 000 字符折叠为
+ *   `[paste #N +M lines]`，提交时展开；粘贴期间不触发补全；粘贴后紧随的 `\r` 是普通 Enter（提交）。
+ * - 补全：提供者由外部注入（`/` 命令、`@` 文件等由 B7 实现）；同步或异步返回候选与替换起点。
+ * - 历史：会话内 + 可选历史文件（JSONL，每行一个 JSON 字符串，保留最近 500 条）。
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { CURSOR_MARKER } from "../component.js";
+import { truncateToWidth, visibleWidth } from "../ansi.js";
+import { defaultKeybindings } from "../keybindings.js";
+import { isPasteData, isPrintableText, unwrapPaste } from "../keys.js";
+import { plainTheme } from "../theme.js";
+import { EditorBuffer } from "./editor-buffer.js";
+import { PasteStore } from "./editor-paste.js";
+import { SelectList } from "./select-list.js";
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+export function loadHistoryFile(path, limit = 500) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (typeof value === "string" && value !== "")
+                entries.push(value);
+        }
+        catch {
+            // 损坏的行跳过
+        }
+    }
+    return entries.slice(-limit);
+}
+function appendHistoryFile(path, entry, limit) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, JSON.stringify(entry) + "\n", { mode: 0o600 });
+        const all = loadHistoryFile(path, Number.MAX_SAFE_INTEGER);
+        if (all.length > limit * 2) {
+            writeFileSync(path, all
+                .slice(-limit)
+                .map((e) => JSON.stringify(e) + "\n")
+                .join(""));
+        }
+    }
+    catch {
+        // 历史写失败不影响编辑
+    }
+}
+export class Editor {
+    options;
+    focused = false;
+    /** 审批对话框期间置 true：Enter 不提交。 */
+    disableSubmit = false;
+    buffer;
+    pastes = new PasteStore();
+    keys;
+    theme;
+    history = [];
+    historyIndex = -1;
+    draft = "";
+    lastWidth = 80;
+    scrollTop = 0;
+    preferredCol = null;
+    completion = null;
+    completionToken = 0;
+    constructor(options = {}) {
+        this.options = options;
+        this.buffer = new EditorBuffer({ atomic: (line) => this.pastes.ranges(line) });
+        this.keys = options.keybindings ?? defaultKeybindings;
+        this.theme = options.theme ?? plainTheme();
+        if (options.historyFile)
+            this.history = loadHistoryFile(options.historyFile, this.historyLimit);
+    }
+    get historyLimit() {
+        return this.options.historyLimit ?? 500;
+    }
+    // ---- 公共 API -------------------------------------------------------------
+    /** 编辑器原文（折叠标记未展开）。 */
+    getText() {
+        return this.buffer.getText();
+    }
+    /** 展开折叠标记后的文本（即提交内容）。 */
+    getExpandedText() {
+        return this.pastes.expand(this.buffer.getText());
+    }
+    setText(text) {
+        this.buffer.setText(text);
+        this.afterEdit(false);
+    }
+    insertText(text) {
+        this.buffer.insert(text);
+        this.afterEdit(false);
+    }
+    clear() {
+        this.buffer.reset();
+        this.pastes.clear();
+        this.closeCompletion();
+        this.historyIndex = -1;
+        this.options.onChange?.("");
+    }
+    isEmpty() {
+        return this.buffer.isEmpty();
+    }
+    get cursor() {
+        return this.buffer.cursor;
+    }
+    get isCompletionOpen() {
+        return this.completion !== null;
+    }
+    getHistory() {
+        return this.history;
+    }
+    setHistory(entries) {
+        this.history = entries.slice(-this.historyLimit);
+        this.historyIndex = -1;
+    }
+    addToHistory(text) {
+        if (text.trim() === "" || this.history[this.history.length - 1] === text)
+            return;
+        this.history.push(text);
+        if (this.history.length > this.historyLimit)
+            this.history.shift();
+        if (this.options.historyFile)
+            appendHistoryFile(this.options.historyFile, text, this.historyLimit);
+    }
+    /** 取出提交内容（展开、记历史、清空），不调用 onSubmit；空文本返回 null。供 followUp 等使用。 */
+    takeSubmission() {
+        const text = this.getExpandedText();
+        if (text.trim() === "")
+            return null;
+        this.addToHistory(text);
+        this.clear();
+        return text;
+    }
+    submit() {
+        if (this.disableSubmit)
+            return;
+        const text = this.takeSubmission();
+        if (text !== null)
+            this.options.onSubmit?.(text);
+    }
+    // ---- 输入 -----------------------------------------------------------------
+    handleInput(data) {
+        if (isPasteData(data)) {
+            this.closeCompletion();
+            this.buffer.insert(this.pastes.accept(unwrapPaste(data)));
+            this.afterEdit(false);
+            return;
+        }
+        if (this.completion && this.handleCompletionKey(data))
+            return;
+        if (this.handleAction(data))
+            return;
+        if (isPrintableText(data)) {
+            this.buffer.insert(data);
+            this.afterEdit(true);
+        }
+    }
+    handleCompletionKey(data) {
+        const k = this.keys;
+        const list = this.completion.list;
+        if (k.matches(data, "tui.select.up"))
+            list.moveSelection(-1);
+        else if (k.matches(data, "tui.select.down"))
+            list.moveSelection(1);
+        else if (k.matches(data, "tui.editor.submit")) {
+            // Enter：接受候选；候选与已输入完全相同（没有可补的了）则直接提交
+            const before = this.buffer.getText();
+            this.acceptCompletion();
+            if (this.buffer.getText() === before)
+                this.submit();
+        }
+        else if (k.matches(data, "tui.select.confirm"))
+            this.acceptCompletion();
+        else if (k.matches(data, "tui.select.cancel"))
+            this.closeCompletion();
+        else
+            return false;
+        return true;
+    }
+    handleAction(data) {
+        const k = this.keys;
+        const b = this.buffer;
+        const edit = (fn) => {
+            fn();
+            this.afterEdit(true);
+            return true;
+        };
+        const move = (fn) => {
+            fn();
+            this.preferredCol = null;
+            this.closeCompletion();
+            return true;
+        };
+        if (k.matches(data, "tui.editor.submit")) {
+            this.submit();
+            return true;
+        }
+        if (k.matches(data, "tui.editor.newLine"))
+            return edit(() => b.newLine());
+        if (k.matches(data, "tui.editor.deleteBackward"))
+            return edit(() => b.backspace());
+        if (k.matches(data, "tui.editor.deleteForward"))
+            return edit(() => b.deleteForward());
+        if (k.matches(data, "tui.editor.deleteWordBackward"))
+            return edit(() => b.deleteWordBackward());
+        if (k.matches(data, "tui.editor.deleteWordForward"))
+            return edit(() => b.deleteWordForward());
+        if (k.matches(data, "tui.editor.deleteToLineStart"))
+            return edit(() => b.deleteToLineStart());
+        if (k.matches(data, "tui.editor.deleteToLineEnd"))
+            return edit(() => b.deleteToLineEnd());
+        if (k.matches(data, "tui.editor.undo"))
+            return edit(() => b.undo());
+        if (k.matches(data, "tui.editor.cursorLeft"))
+            return move(() => b.moveLeft());
+        if (k.matches(data, "tui.editor.cursorRight"))
+            return move(() => b.moveRight());
+        if (k.matches(data, "tui.editor.wordLeft"))
+            return move(() => b.moveWordLeft());
+        if (k.matches(data, "tui.editor.wordRight"))
+            return move(() => b.moveWordRight());
+        if (k.matches(data, "tui.editor.lineStart"))
+            return move(() => b.moveLineStart());
+        if (k.matches(data, "tui.editor.lineEnd"))
+            return move(() => b.moveLineEnd());
+        if (k.matches(data, "tui.editor.cursorUp")) {
+            this.closeCompletion();
+            this.verticalMove(-1);
+            return true;
+        }
+        if (k.matches(data, "tui.editor.cursorDown")) {
+            this.closeCompletion();
+            this.verticalMove(1);
+            return true;
+        }
+        if (k.matches(data, "tui.editor.complete") && this.options.autocomplete) {
+            this.requestCompletion(true);
+            return true;
+        }
+        return false;
+    }
+    afterEdit(triggerCompletion) {
+        this.historyIndex = -1;
+        this.preferredCol = null;
+        this.options.onChange?.(this.buffer.getText());
+        if (triggerCompletion)
+            this.requestCompletion(false);
+        else
+            this.closeCompletion();
+    }
+    // ---- 历史与纵向移动 -------------------------------------------------------
+    verticalMove(direction) {
+        const rows = this.layout(this.contentWidth(this.lastWidth));
+        const at = this.cursorRowIndex(rows);
+        const singleLine = !this.buffer.getText().includes("\n");
+        const browsing = this.historyIndex !== -1;
+        if (direction === -1 && at === 0) {
+            if (this.history.length > 0 && (this.buffer.isEmpty() || singleLine || browsing)) {
+                this.historyStep(-1);
+            }
+            else
+                this.buffer.moveLineStart();
+            return;
+        }
+        if (direction === 1 && at === rows.length - 1) {
+            if (browsing)
+                this.historyStep(1);
+            else
+                this.buffer.moveLineEnd();
+            return;
+        }
+        const row = rows[at];
+        const line = this.buffer.getLines()[row.line];
+        const col = this.preferredCol ?? visibleWidth(line.slice(row.start, this.buffer.cursor.col));
+        this.preferredCol = col;
+        const target = rows[at + direction];
+        this.buffer.setCursor({ line: target.line, col: this.colAtWidth(target, col) });
+    }
+    historyStep(direction) {
+        if (direction === -1) {
+            if (this.historyIndex === -1) {
+                this.draft = this.buffer.getText();
+                this.historyIndex = this.history.length - 1;
+            }
+            else if (this.historyIndex > 0)
+                this.historyIndex--;
+            else
+                return;
+            this.buffer.setText(this.history[this.historyIndex], false);
+        }
+        else {
+            this.historyIndex++;
+            if (this.historyIndex >= this.history.length) {
+                this.historyIndex = -1;
+                this.buffer.setText(this.draft, false);
+            }
+            else
+                this.buffer.setText(this.history[this.historyIndex], false);
+        }
+        this.preferredCol = null;
+        this.options.onChange?.(this.buffer.getText());
+    }
+    colAtWidth(row, targetWidth) {
+        const line = this.buffer.getLines()[row.line];
+        let col = row.start;
+        let width = 0;
+        for (const { segment, index } of segmenter.segment(line.slice(row.start, row.end))) {
+            const w = visibleWidth(segment);
+            if (width + w > targetWidth)
+                break;
+            width += w;
+            col = row.start + index + segment.length;
+        }
+        // 不能停在下一段的起点之后（非末段时 end 属于下一行）
+        if (!row.last && col >= row.end)
+            col = this.prevGrapheme(line, row.end);
+        return col;
+    }
+    prevGrapheme(line, col) {
+        let prev = 0;
+        for (const { index } of segmenter.segment(line)) {
+            if (index >= col)
+                break;
+            prev = index;
+        }
+        return prev;
+    }
+    // ---- 补全 -----------------------------------------------------------------
+    requestCompletion(force) {
+        const provider = this.options.autocomplete;
+        if (!provider)
+            return;
+        const token = ++this.completionToken;
+        const lines = this.buffer.getLines();
+        const context = {
+            line: lines[this.buffer.cursor.line],
+            textBeforeCursor: this.buffer.textBeforeCursor(),
+            text: this.buffer.getText(),
+            force,
+        };
+        const result = provider.getSuggestions(context);
+        if (result instanceof Promise) {
+            result.then((r) => {
+                if (token !== this.completionToken)
+                    return;
+                this.applyCompletion(r, force);
+                this.options.requestRender?.();
+            }, () => undefined);
+        }
+        else
+            this.applyCompletion(result, force);
+    }
+    applyCompletion(result, force) {
+        if (!result || result.items.length === 0) {
+            this.closeCompletion();
+            return;
+        }
+        if (force && result.items.length === 1) {
+            this.buffer.replaceBeforeCursor(result.from, result.items[0].value);
+            this.closeCompletion();
+            this.options.onChange?.(this.buffer.getText());
+            return;
+        }
+        const items = result.items.map((item) => item.description === undefined
+            ? { value: item.value, label: item.label }
+            : { value: item.value, label: item.label, description: item.description });
+        this.completion = {
+            list: new SelectList(items, { maxVisible: 8, theme: this.theme, keybindings: this.keys }),
+            from: result.from,
+        };
+    }
+    acceptCompletion() {
+        const c = this.completion;
+        if (!c)
+            return;
+        const item = c.list.getSelected();
+        this.closeCompletion();
+        if (!item)
+            return;
+        this.buffer.replaceBeforeCursor(c.from, item.value);
+        this.historyIndex = -1;
+        this.options.onChange?.(this.buffer.getText());
+    }
+    closeCompletion() {
+        this.completion = null;
+        this.completionToken++;
+    }
+    // ---- 渲染 -----------------------------------------------------------------
+    contentWidth(width) {
+        return Math.max(1, width - 1);
+    }
+    /** 逻辑行 → 视觉行（按列宽折行，不切开字素与折叠标记）。 */
+    layout(width) {
+        const rows = [];
+        this.buffer.getLines().forEach((text, line) => {
+            const atomic = this.pastes.ranges(text);
+            let start = 0;
+            let used = 0;
+            let pos = 0;
+            const graphemes = [...segmenter.segment(text)];
+            let gi = 0;
+            while (gi < graphemes.length) {
+                const g = graphemes[gi];
+                pos = g.index;
+                const range = atomic.find(([s]) => s === pos);
+                const unitEnd = range ? range[1] : pos + g.segment.length;
+                const unitWidth = visibleWidth(text.slice(pos, unitEnd));
+                if (used > 0 && used + unitWidth > width) {
+                    rows.push({ line, start, end: pos, last: false });
+                    start = pos;
+                    used = 0;
+                }
+                if (range && unitWidth > width) {
+                    // 标记比整行还宽：按字素拆开显示（逻辑上仍不可分割）
+                    used += visibleWidth(g.segment);
+                    gi++;
+                    continue;
+                }
+                used += unitWidth;
+                while (gi < graphemes.length && graphemes[gi].index < unitEnd)
+                    gi++;
+            }
+            rows.push({ line, start, end: text.length, last: true });
+        });
+        return rows;
+    }
+    cursorRowIndex(rows) {
+        const { line, col } = this.buffer.cursor;
+        for (let i = 0; i < rows.length; i++) {
+            const r = rows[i];
+            if (r.line === line && col >= r.start && (col < r.end || r.last))
+                return i;
+        }
+        return rows.length - 1;
+    }
+    renderRow(row, withCursor) {
+        const text = this.buffer.getLines()[row.line];
+        const atomic = this.pastes.ranges(text);
+        const cursorCol = withCursor ? this.buffer.cursor.col : -1;
+        let out = "";
+        let pos = row.start;
+        while (pos < row.end || pos === cursorCol) {
+            if (pos === cursorCol) {
+                const g = pos < row.end ? nextGrapheme(text, pos) : " ";
+                out += CURSOR_MARKER + `\x1b[7m${g}\x1b[27m`;
+                if (pos >= row.end)
+                    break;
+                pos += g.length;
+                continue;
+            }
+            const range = atomic.find(([s, e]) => pos >= s && pos < e);
+            if (range) {
+                const end = Math.min(range[1], row.end, cursorCol > pos ? cursorCol : Infinity);
+                out += this.theme.fg("accent", text.slice(pos, end));
+                pos = end;
+                continue;
+            }
+            let end = row.end;
+            if (cursorCol > pos && cursorCol < end)
+                end = cursorCol;
+            const nextAtomic = atomic.find(([s]) => s > pos && s < end);
+            if (nextAtomic)
+                end = nextAtomic[0];
+            out += text.slice(pos, end);
+            pos = end;
+        }
+        return out;
+    }
+    render(width) {
+        this.lastWidth = width;
+        const theme = this.theme;
+        const contentWidth = this.contentWidth(width);
+        const rows = this.layout(contentWidth);
+        const cursorRow = this.cursorRowIndex(rows);
+        const maxVisible = Math.max(1, this.options.maxVisibleLines ?? 10);
+        if (cursorRow < this.scrollTop)
+            this.scrollTop = cursorRow;
+        if (cursorRow >= this.scrollTop + maxVisible)
+            this.scrollTop = cursorRow - maxVisible + 1;
+        this.scrollTop = Math.max(0, Math.min(this.scrollTop, rows.length - maxVisible));
+        const end = Math.min(rows.length, this.scrollTop + maxVisible);
+        const lines = [this.border(width, this.scrollTop > 0 ? `↑ ${this.scrollTop}` : "")];
+        if (this.buffer.isEmpty() && this.options.placeholder && !this.focused) {
+            lines.push(truncateToWidth(theme.fg("dim", this.options.placeholder), width));
+        }
+        else {
+            for (let i = this.scrollTop; i < end; i++) {
+                lines.push(this.renderRow(rows[i], this.focused && i === cursorRow));
+            }
+        }
+        lines.push(this.border(width, end < rows.length ? `↓ ${rows.length - end}` : ""));
+        if (this.completion) {
+            for (const line of this.completion.list.render(width))
+                lines.push(line);
+        }
+        return lines;
+    }
+    border(width, label) {
+        if (label === "" || width < label.length + 6)
+            return this.theme.fg("border", "─".repeat(width));
+        const tail = "─".repeat(width - label.length - 5);
+        return (this.theme.fg("border", "─── ") +
+            this.theme.fg("dim", label) +
+            this.theme.fg("border", " " + tail));
+    }
+    invalidate() {
+        this.completion?.list.invalidate();
+    }
+}
+function nextGrapheme(text, pos) {
+    const first = segmenter
+        .segment(text.slice(pos, pos + 32))[Symbol.iterator]()
+        .next();
+    return first.done ? " " : first.value.segment;
+}

package/dist/tui/components/key-value.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 两列键值表（第三波 A8，供 `/session` 等面板）。[W3-B9a-2]
+ *
+ * - 键列宽 = 最长键的可见宽度，但不超过总宽的 `maxKeyRatio`（缺省 0.4，至少 4 列），超出的键截断；
+ * - 值在剩余宽度内截断（不换行，保留 ANSI 样式）；值里的换行折成 ` ⏎ `；
+ * - 宽度连键列都放不下时退化为只显示截断后的键；空行（`key` 为空串）原样输出空行，可作分组间隔。
+ */
+import type { Component, SemanticColor, Theme } from "../component.js";
+export interface KeyValueRow {
+    key: string;
+    value: string;
+}
+export interface KeyValueOptions {
+    theme?: Theme;
+    /** 键的颜色（需要 theme），缺省 dim。 */
+    keyColor?: SemanticColor;
+    /** 两列之间的空白，缺省 2。 */
+    gap?: number;
+    maxKeyRatio?: number;
+}
+export declare class KeyValue implements Component {
+    private rows;
+    private readonly options;
+    private cache;
+    constructor(rows?: readonly KeyValueRow[], options?: KeyValueOptions);
+    setRows(rows: readonly KeyValueRow[]): void;
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/tui/components/key-value.js

@@ -0,0 +1,48 @@
+/**
+ * 两列键值表（第三波 A8，供 `/session` 等面板）。[W3-B9a-2]
+ *
+ * - 键列宽 = 最长键的可见宽度，但不超过总宽的 `maxKeyRatio`（缺省 0.4，至少 4 列），超出的键截断；
+ * - 值在剩余宽度内截断（不换行，保留 ANSI 样式）；值里的换行折成 ` ⏎ `；
+ * - 宽度连键列都放不下时退化为只显示截断后的键；空行（`key` 为空串）原样输出空行，可作分组间隔。
+ */
+import { padToWidth, truncateToWidth, visibleWidth } from "../ansi.js";
+/** 键列至少保留的宽度（键更短时取键宽）；再窄就只显示键。 */
+const MIN_KEY_WIDTH = 4;
+export class KeyValue {
+    rows;
+    options;
+    cache = null;
+    constructor(rows = [], options = {}) {
+        this.rows = rows;
+        this.options = options;
+    }
+    setRows(rows) {
+        this.rows = rows;
+        this.cache = null;
+    }
+    render(width) {
+        if (this.cache?.width === width)
+            return this.cache.lines;
+        const gap = this.options.gap ?? 2;
+        const longest = Math.max(0, ...this.rows.map((r) => visibleWidth(r.key)));
+        const share = Math.floor(width * (this.options.maxKeyRatio ?? 0.4));
+        const keyWidth = Math.min(longest, Math.max(share, MIN_KEY_WIDTH));
+        const valueWidth = width - keyWidth - gap;
+        const { theme, keyColor = "dim" } = this.options;
+        const lines = this.rows.map(({ key, value }) => {
+            if (key === "" && value === "")
+                return "";
+            const shownKey = truncateToWidth(key, Math.max(keyWidth, 1));
+            const styledKey = theme ? theme.fg(keyColor, shownKey) : shownKey;
+            if (valueWidth < 1)
+                return truncateToWidth(styledKey, width);
+            const flat = value.replace(/\r?\n/g, " ⏎ ");
+            return padToWidth(styledKey, keyWidth) + " ".repeat(gap) + truncateToWidth(flat, valueWidth);
+        });
+        this.cache = { width, lines };
+        return lines;
+    }
+    invalidate() {
+        this.cache = null;
+    }
+}

package/dist/tui/components/loader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 旋转指示器（设计 §12.1、§12.6：运行中显示 Loader 与已用时）。[B4]
+ *
+ * 帧由定时器推进并调用 `requestRender`；`stop()` 后不再触发渲染。时钟可注入便于测试。
+ */
+import type { Component, Theme } from "../component.js";
+export declare const LOADER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export interface LoaderOptions {
+    message?: string;
+    theme?: Theme;
+    /** 帧间隔（ms），缺省 80。 */
+    intervalMs?: number;
+    /** 显示已用时（`12s`、`1m05s`），缺省 true。 */
+    showElapsed?: boolean;
+    now?: () => number;
+}
+export declare function formatElapsed(ms: number): string;
+export declare class Loader implements Component {
+    private readonly requestRender;
+    private readonly options;
+    private frame;
+    private timer;
+    private startedAt;
+    private message;
+    private readonly now;
+    constructor(requestRender: () => void, options?: LoaderOptions);
+    get running(): boolean;
+    setMessage(message: string): void;
+    start(): void;
+    stop(): void;
+    /** 推进一帧（定时器调用；测试可直接调用）。 */
+    tick(): void;
+    render(width: number): string[];
+    invalidate(): void;
+}