@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tui/components/editor-buffer.js

@@ -0,0 +1,300 @@
+/**
+ * 编辑器文本缓冲（设计 §12.4）：行 / 光标 / 撤销栈（50 步）/ 单词导航 / 不可分割段。[B4]
+ *
+ * - 光标列是该行内的 UTF-16 下标，移动与删除按字素簇进行（emoji、组合字符不会被切开）。
+ * - 不可分割段（大粘贴折叠标记）由 `atomic` 回调按行给出区间：光标不会停在段内，
+ *   退格 / 删除 / 删词把整段一起删掉，单词导航把整段当作一个词。
+ * - 撤销：每次编辑前存快照；连续输入同类字符合并为一步；上限 50 步。
+ * - 不做选区（无鼠标、无 kill ring，§12.9）。
+ */
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+function graphemeStarts(line) {
+    const starts = [];
+    for (const { index } of segmenter.segment(line))
+        starts.push(index);
+    starts.push(line.length);
+    return starts;
+}
+function classify(ch) {
+    if (/\s/.test(ch))
+        return "space";
+    if (/[\p{L}\p{N}_]/u.test(ch))
+        return "word";
+    return "punct";
+}
+export class EditorBuffer {
+    lines = [""];
+    cur = { line: 0, col: 0 };
+    undoStack = [];
+    lastKind = null;
+    undoLimit;
+    atomic;
+    constructor(options = {}) {
+        this.undoLimit = options.undoLimit ?? 50;
+        this.atomic = options.atomic ?? (() => []);
+    }
+    get cursor() {
+        return { ...this.cur };
+    }
+    getLines() {
+        return this.lines;
+    }
+    getText() {
+        return this.lines.join("\n");
+    }
+    isEmpty() {
+        return this.lines.length === 1 && this.lines[0] === "";
+    }
+    get undoDepth() {
+        return this.undoStack.length;
+    }
+    /** 替换全部文本，光标到末尾。recordUndo=false 时不进撤销栈（历史浏览、提交清空）。 */
+    setText(text, recordUndo = true) {
+        if (recordUndo)
+            this.snapshot("other");
+        this.lines = text.split("\n");
+        const last = this.lines.length - 1;
+        this.cur = { line: last, col: this.lines[last].length };
+        if (!recordUndo)
+            this.lastKind = null;
+    }
+    /** 清空并丢弃撤销历史。 */
+    reset() {
+        this.lines = [""];
+        this.cur = { line: 0, col: 0 };
+        this.undoStack = [];
+        this.lastKind = null;
+    }
+    setCursor(pos) {
+        const line = Math.max(0, Math.min(this.lines.length - 1, pos.line));
+        const col = Math.max(0, Math.min(this.lines[line].length, pos.col));
+        this.cur = { line, col: this.snapOutOfAtomic(line, col) };
+        this.lastKind = null;
+    }
+    /** 插入文本（可含换行）。 */
+    insert(text) {
+        if (text === "")
+            return;
+        const kind = text.length <= 2 && !text.includes("\n")
+            ? /\s/.test(text)
+                ? "type-space"
+                : "type-word"
+            : "other";
+        this.snapshot(kind);
+        const line = this.lines[this.cur.line];
+        const before = line.slice(0, this.cur.col);
+        const after = line.slice(this.cur.col);
+        const parts = text.split("\n");
+        if (parts.length === 1) {
+            this.lines[this.cur.line] = before + text + after;
+            this.cur = { line: this.cur.line, col: this.cur.col + text.length };
+            return;
+        }
+        const newLines = [before + parts[0], ...parts.slice(1, -1), parts[parts.length - 1] + after];
+        this.lines.splice(this.cur.line, 1, ...newLines);
+        this.cur = { line: this.cur.line + parts.length - 1, col: parts[parts.length - 1].length };
+    }
+    newLine() {
+        this.insert("\n");
+    }
+    backspace() {
+        const { line, col } = this.cur;
+        if (col === 0) {
+            if (line === 0)
+                return;
+            this.snapshot("other");
+            const prevLen = this.lines[line - 1].length;
+            this.lines[line - 1] += this.lines[line];
+            this.lines.splice(line, 1);
+            this.cur = { line: line - 1, col: prevLen };
+            return;
+        }
+        const start = this.prevStop(line, col);
+        this.snapshot("other");
+        this.deleteRange(line, start, col);
+    }
+    deleteForward() {
+        const { line, col } = this.cur;
+        const text = this.lines[line];
+        if (col >= text.length) {
+            if (line >= this.lines.length - 1)
+                return;
+            this.snapshot("other");
+            this.lines[line] = text + this.lines[line + 1];
+            this.lines.splice(line + 1, 1);
+            return;
+        }
+        this.snapshot("other");
+        this.deleteRange(line, col, this.nextStop(line, col));
+    }
+    moveLeft() {
+        const { line, col } = this.cur;
+        if (col > 0)
+            this.cur = { line, col: this.prevStop(line, col) };
+        else if (line > 0)
+            this.cur = { line: line - 1, col: this.lines[line - 1].length };
+        this.lastKind = null;
+    }
+    moveRight() {
+        const { line, col } = this.cur;
+        if (col < this.lines[line].length)
+            this.cur = { line, col: this.nextStop(line, col) };
+        else if (line < this.lines.length - 1)
+            this.cur = { line: line + 1, col: 0 };
+        this.lastKind = null;
+    }
+    moveLineStart() {
+        this.cur = { line: this.cur.line, col: 0 };
+        this.lastKind = null;
+    }
+    moveLineEnd() {
+        this.cur = { line: this.cur.line, col: this.lines[this.cur.line].length };
+        this.lastKind = null;
+    }
+    moveWordLeft() {
+        const { line, col } = this.cur;
+        if (col === 0)
+            return this.moveLeft();
+        this.cur = { line, col: this.wordStartBefore(line, col) };
+        this.lastKind = null;
+    }
+    moveWordRight() {
+        const { line, col } = this.cur;
+        if (col >= this.lines[line].length)
+            return this.moveRight();
+        this.cur = { line, col: this.wordEndAfter(line, col) };
+        this.lastKind = null;
+    }
+    deleteWordBackward() {
+        const { line, col } = this.cur;
+        if (col === 0)
+            return this.backspace();
+        this.snapshot("other");
+        this.deleteRange(line, this.wordStartBefore(line, col), col);
+    }
+    deleteWordForward() {
+        const { line, col } = this.cur;
+        if (col >= this.lines[line].length)
+            return this.deleteForward();
+        this.snapshot("other");
+        this.deleteRange(line, col, this.wordEndAfter(line, col));
+    }
+    deleteToLineStart() {
+        const { line, col } = this.cur;
+        if (col === 0)
+            return this.backspace();
+        this.snapshot("other");
+        this.deleteRange(line, 0, col);
+    }
+    deleteToLineEnd() {
+        const { line, col } = this.cur;
+        if (col >= this.lines[line].length)
+            return this.deleteForward();
+        this.snapshot("other");
+        this.deleteRange(line, col, this.lines[line].length);
+    }
+    undo() {
+        const snap = this.undoStack.pop();
+        if (!snap)
+            return false;
+        this.lines = snap.lines;
+        this.cur = snap.cursor;
+        this.lastKind = null;
+        return true;
+    }
+    /** 光标所在行内、光标前的文本（补全提供者用）。 */
+    textBeforeCursor() {
+        return this.lines[this.cur.line].slice(0, this.cur.col);
+    }
+    /** 把当前行 [from, cursor) 替换为 text（补全接受）。 */
+    replaceBeforeCursor(from, text) {
+        this.snapshot("other");
+        const { line, col } = this.cur;
+        const current = this.lines[line];
+        const start = Math.max(0, Math.min(from, col));
+        this.lines[line] = current.slice(0, start) + text + current.slice(col);
+        this.cur = { line, col: start + text.length };
+    }
+    deleteRange(line, from, to) {
+        const text = this.lines[line];
+        this.lines[line] = text.slice(0, from) + text.slice(to);
+        this.cur = { line, col: from };
+    }
+    snapshot(kind) {
+        const coalesce = kind !== "other" && kind === this.lastKind;
+        this.lastKind = kind === "other" ? null : kind;
+        if (coalesce)
+            return;
+        this.undoStack.push({ lines: [...this.lines], cursor: { ...this.cur } });
+        if (this.undoStack.length > this.undoLimit)
+            this.undoStack.shift();
+    }
+    atomicAt(line, col, inclusiveEnd) {
+        return this.atomic(this.lines[line]).find(([s, e]) => inclusiveEnd ? col > s && col <= e : col >= s && col < e);
+    }
+    snapOutOfAtomic(line, col) {
+        const range = this.atomic(this.lines[line]).find(([s, e]) => col > s && col < e);
+        return range ? range[1] : col;
+    }
+    /** 光标左侧的停靠点（字素簇或整段不可分割段）。 */
+    prevStop(line, col) {
+        const range = this.atomicAt(line, col, true);
+        if (range)
+            return range[0];
+        const starts = graphemeStarts(this.lines[line]);
+        let prev = 0;
+        for (const s of starts) {
+            if (s >= col)
+                break;
+            prev = s;
+        }
+        return prev;
+    }
+    nextStop(line, col) {
+        const range = this.atomicAt(line, col, false);
+        if (range)
+            return range[1];
+        const starts = graphemeStarts(this.lines[line]);
+        return starts.find((s) => s > col) ?? this.lines[line].length;
+    }
+    classAt(line, col) {
+        if (this.atomicAt(line, col, false))
+            return "word";
+        return classify(this.lines[line][col] ?? " ");
+    }
+    wordStartBefore(line, col) {
+        let pos = col;
+        while (pos > 0 && this.classAt(line, this.prevStop(line, pos)) === "space") {
+            pos = this.prevStop(line, pos);
+        }
+        if (pos === 0)
+            return 0;
+        const first = this.prevStop(line, pos);
+        if (this.atomicAt(line, pos, true))
+            return first;
+        const cls = this.classAt(line, first);
+        pos = first;
+        while (pos > 0) {
+            const p = this.prevStop(line, pos);
+            if (this.atomicAt(line, pos, true) || this.classAt(line, p) !== cls)
+                break;
+            pos = p;
+        }
+        return pos;
+    }
+    wordEndAfter(line, col) {
+        const len = this.lines[line].length;
+        let pos = col;
+        while (pos < len && this.classAt(line, pos) === "space")
+            pos = this.nextStop(line, pos);
+        if (pos >= len)
+            return len;
+        if (this.atomicAt(line, pos, false))
+            return this.nextStop(line, pos);
+        const cls = this.classAt(line, pos);
+        while (pos < len && !this.atomicAt(line, pos, false) && this.classAt(line, pos) === cls) {
+            pos = this.nextStop(line, pos);
+        }
+        return pos;
+    }
+}

package/dist/tui/components/editor-paste.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 大粘贴折叠（设计 §12.4）：超过 10 行或超过 1 000 字符的粘贴折叠为 `[paste #N +M lines]`，
+ * 在编辑器里是不可分割段；提交时展开为原文。[B4]
+ *
+ * - 换行规范化：`\r\n` / 单独的 `\r` → `\n`（括号粘贴里终端常把换行发成 `\r`）。
+ * - 未折叠的粘贴把制表符换成 4 个空格（编辑器按列宽渲染，`\t` 没有确定宽度）；折叠内容保留原文。
+ * - 标记只在本编辑器记录过的编号上展开；用户手打的同形文本不会被替换成别的内容。
+ */
+export declare const PASTE_LINE_THRESHOLD = 10;
+export declare const PASTE_CHAR_THRESHOLD = 1000;
+export declare function normalizePastedText(text: string): string;
+export declare function countLines(text: string): number;
+/** 是否需要折叠（> 10 行或 > 1 000 字符）。 */
+export declare function shouldCollapse(text: string): boolean;
+export declare function formatMarker(id: number, lines: number): string;
+export declare class PasteStore {
+    private next;
+    private readonly entries;
+    /** 处理一次粘贴：返回要插入编辑器的文本（折叠标记或规范化后的原文）。 */
+    accept(raw: string): string;
+    get size(): number;
+    get(id: number): string | undefined;
+    /** 把文本里已登记的标记展开为原文。 */
+    expand(text: string): string;
+    /** 一行内已登记标记的区间（编辑器的不可分割段）。 */
+    ranges(line: string): Array<readonly [number, number]>;
+    /** 提交后清空（编号继续递增，避免历史里的旧标记与新粘贴混淆）。 */
+    clear(): void;
+}

package/dist/tui/components/editor-paste.js

@@ -0,0 +1,64 @@
+/**
+ * 大粘贴折叠（设计 §12.4）：超过 10 行或超过 1 000 字符的粘贴折叠为 `[paste #N +M lines]`，
+ * 在编辑器里是不可分割段；提交时展开为原文。[B4]
+ *
+ * - 换行规范化：`\r\n` / 单独的 `\r` → `\n`（括号粘贴里终端常把换行发成 `\r`）。
+ * - 未折叠的粘贴把制表符换成 4 个空格（编辑器按列宽渲染，`\t` 没有确定宽度）；折叠内容保留原文。
+ * - 标记只在本编辑器记录过的编号上展开；用户手打的同形文本不会被替换成别的内容。
+ */
+export const PASTE_LINE_THRESHOLD = 10;
+export const PASTE_CHAR_THRESHOLD = 1000;
+const MARKER_RE = /\[paste #(\d+) \+(\d+) lines\]/g;
+export function normalizePastedText(text) {
+    return text.replace(/\r\n?/g, "\n");
+}
+export function countLines(text) {
+    return text === "" ? 0 : text.split("\n").length;
+}
+/** 是否需要折叠（> 10 行或 > 1 000 字符）。 */
+export function shouldCollapse(text) {
+    return countLines(text) > PASTE_LINE_THRESHOLD || text.length > PASTE_CHAR_THRESHOLD;
+}
+export function formatMarker(id, lines) {
+    return `[paste #${id} +${lines} lines]`;
+}
+export class PasteStore {
+    next = 1;
+    entries = new Map();
+    /** 处理一次粘贴：返回要插入编辑器的文本（折叠标记或规范化后的原文）。 */
+    accept(raw) {
+        const text = normalizePastedText(raw);
+        if (!shouldCollapse(text))
+            return text.replace(/\t/g, "    ");
+        const id = this.next++;
+        this.entries.set(id, text);
+        return formatMarker(id, countLines(text));
+    }
+    get size() {
+        return this.entries.size;
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    /** 把文本里已登记的标记展开为原文。 */
+    expand(text) {
+        if (this.entries.size === 0)
+            return text;
+        return text.replace(MARKER_RE, (marker, id) => this.entries.get(Number(id)) ?? marker);
+    }
+    /** 一行内已登记标记的区间（编辑器的不可分割段）。 */
+    ranges(line) {
+        if (this.entries.size === 0 || !line.includes("[paste #"))
+            return [];
+        const out = [];
+        for (const m of line.matchAll(MARKER_RE)) {
+            if (this.entries.has(Number(m[1])))
+                out.push([m.index, m.index + m[0].length]);
+        }
+        return out;
+    }
+    /** 提交后清空（编号继续递增，避免历史里的旧标记与新粘贴混淆）。 */
+    clear() {
+        this.entries.clear();
+    }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * 多行编辑器组件（设计 §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 { type Component, type Focusable, type Theme } from "../component.js";
+import { type Keybindings } from "../keybindings.js";
+export interface AutocompleteItem {
+    /** 接受后替换进编辑器的文本。 */
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface AutocompleteResult {
+    items: AutocompleteItem[];
+    /** 当前行内被替换区间的起点（UTF-16 列）；终点是光标。 */
+    from: number;
+}
+export interface AutocompleteContext {
+    /** 当前行全文。 */
+    line: string;
+    /** 当前行光标前的文本。 */
+    textBeforeCursor: string;
+    /** 编辑器全文（折叠标记未展开）。 */
+    text: string;
+    /** Tab 主动请求时为 true；输入触发时为 false。 */
+    force: boolean;
+}
+export interface AutocompleteProvider {
+    getSuggestions(context: AutocompleteContext): AutocompleteResult | null | Promise<AutocompleteResult | null>;
+}
+export interface EditorOptions {
+    theme?: Theme;
+    keybindings?: Keybindings;
+    /** 可见文本行上限，缺省 10。 */
+    maxVisibleLines?: number;
+    /** 历史条数上限，缺省 500。 */
+    historyLimit?: number;
+    /** 历史文件路径（JSONL）；缺省只保留会话内历史。 */
+    historyFile?: string;
+    autocomplete?: AutocompleteProvider;
+    /** 异步补全返回后请求重绘。 */
+    requestRender?: () => void;
+    placeholder?: string;
+    onSubmit?(text: string): void;
+    onChange?(text: string): void;
+}
+export declare function loadHistoryFile(path: string, limit?: number): string[];
+export declare class Editor implements Component, Focusable {
+    private readonly options;
+    focused: boolean;
+    /** 审批对话框期间置 true：Enter 不提交。 */
+    disableSubmit: boolean;
+    private readonly buffer;
+    private readonly pastes;
+    private readonly keys;
+    private readonly theme;
+    private history;
+    private historyIndex;
+    private draft;
+    private lastWidth;
+    private scrollTop;
+    private preferredCol;
+    private completion;
+    private completionToken;
+    constructor(options?: EditorOptions);
+    private get historyLimit();
+    /** 编辑器原文（折叠标记未展开）。 */
+    getText(): string;
+    /** 展开折叠标记后的文本（即提交内容）。 */
+    getExpandedText(): string;
+    setText(text: string): void;
+    insertText(text: string): void;
+    clear(): void;
+    isEmpty(): boolean;
+    get cursor(): {
+        line: number;
+        col: number;
+    };
+    get isCompletionOpen(): boolean;
+    getHistory(): readonly string[];
+    setHistory(entries: readonly string[]): void;
+    addToHistory(text: string): void;
+    /** 取出提交内容（展开、记历史、清空），不调用 onSubmit；空文本返回 null。供 followUp 等使用。 */
+    takeSubmission(): string | null;
+    submit(): void;
+    handleInput(data: string): void;
+    private handleCompletionKey;
+    private handleAction;
+    private afterEdit;
+    private verticalMove;
+    private historyStep;
+    private colAtWidth;
+    private prevGrapheme;
+    private requestCompletion;
+    private applyCompletion;
+    private acceptCompletion;
+    private closeCompletion;
+    private contentWidth;
+    /** 逻辑行 → 视觉行（按列宽折行，不切开字素与折叠标记）。 */
+    private layout;
+    private cursorRowIndex;
+    private renderRow;
+    render(width: number): string[];
+    private border;
+    invalidate(): void;
+}