@unscientificjszhai/howto 1.0.0-alpha.3 → 1.0.1

package/dist/ui/SelectedCommandDisplay.js

@@ -1,31 +1,33 @@
 import React from "react";
 import { Box, Text } from "ink";
+import { toSingleLinePreview } from "./single-line-preview.js";
 export const SelectedCommandDisplay = ({ candidate, resolvedValues, currentBuffer, }) => {
     // Split command by {{placeholder}} pattern, keeping the delimiters
     const parts = candidate.command.split(/({{.*?}})/);
     return (React.createElement(Box, { flexDirection: "column", marginBottom: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1 },
         React.createElement(Box, null,
             React.createElement(Text, { color: "cyan", bold: true }, "> "),
-            React.createElement(Text, { bold: true }, candidate.title)),
-        React.createElement(Box, { marginLeft: 2 },
-            React.createElement(Text, null, parts.map((part, index) => {
+            React.createElement(Box, { flexGrow: 1, overflowX: "hidden" },
+                React.createElement(Text, { bold: true, wrap: "truncate-end" }, toSingleLinePreview(candidate.title)))),
+        React.createElement(Box, { marginLeft: 2, overflowX: "hidden" },
+            React.createElement(Text, { wrap: "truncate-middle" }, parts.map((part, index) => {
                 const match = part.match(/^{{(.*)}}$/);
                 if (match) {
                     const placeholderName = match[1];
                     // If it's the current buffer, show the buffer in yellow
                     if (currentBuffer && currentBuffer.name === placeholderName) {
-                        return (React.createElement(Text, { key: index, color: "yellow" }, currentBuffer.value || part));
+                        return (React.createElement(Text, { key: index, color: "yellow" }, toSingleLinePreview(currentBuffer.value || part)));
                     }
                     // If it's already resolved, show the value in yellow
                     if (resolvedValues.has(placeholderName)) {
-                        return (React.createElement(Text, { key: index, color: "yellow" }, resolvedValues.get(placeholderName)));
+                        return (React.createElement(Text, { key: index, color: "yellow" }, toSingleLinePreview(resolvedValues.get(placeholderName) ?? "")));
                     }
                     // Otherwise show the original {{placeholder}} in default gray
-                    return (React.createElement(Text, { key: index, color: "gray" }, part));
+                    return (React.createElement(Text, { key: index, color: "gray" }, toSingleLinePreview(part)));
                 }
                 // Normal text
-                return React.createElement(Text, { key: index }, part);
+                return React.createElement(Text, { key: index }, toSingleLinePreview(part));
             }))),
-        React.createElement(Box, { marginLeft: 2 },
-            React.createElement(Text, { italic: true, color: "dim" }, candidate.description))));
+        React.createElement(Box, { marginLeft: 2, overflowX: "hidden" },
+            React.createElement(Text, { italic: true, color: "dim", wrap: "truncate-end" }, toSingleLinePreview(candidate.description)))));
 };

package/dist/ui/interactive-session.js

@@ -0,0 +1,407 @@
+import { Readable } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
+import { ReadStream } from "node:tty";
+import { normalizePhysicalRows, toResizeSafeOutput } from "./resize-safe-output.js";
+import { PasteFramingFilter, PasteStartObserver } from "./paste-framing.js";
+export const ENABLE_PASTE = "\u001b[?2004h";
+export const DISABLE_PASTE = "\u001b[?2004l";
+export class InteractiveSessionError extends Error {
+    constructor(message = "交互终端输入不可用。") {
+        super(message);
+        this.name = "InteractiveSessionError";
+    }
+}
+function inputIsUnavailable(input, expectedClose = false) {
+    return (input.errored !== null ||
+        (!expectedClose &&
+            (input.destroyed || input.closed || input.readableEnded || input.readable === false)));
+}
+function outputIsUnavailable(output) {
+    return (output.errored !== null ||
+        output.destroyed ||
+        output.closed ||
+        output.writableEnded ||
+        output.writableFinished ||
+        output.writable === false);
+}
+function assertAvailableInput(input, output) {
+    if (!input.isTTY ||
+        !output.isTTY ||
+        inputIsUnavailable(input) ||
+        outputIsUnavailable(output) ||
+        input.listenerCount("readable") > 0 ||
+        input.listenerCount("data") > 0) {
+        throw new InteractiveSessionError();
+    }
+}
+class SessionInput extends Readable {
+    isTTY = true;
+    isRaw = true;
+    _read() { }
+    setRawMode(enabled) {
+        this.isRaw = enabled;
+        return this;
+    }
+    ref() {
+        return this;
+    }
+    unref() {
+        return this;
+    }
+}
+export class InteractiveSession {
+    physicalInput;
+    physicalOutput;
+    resources;
+    input;
+    output;
+    bridge = new SessionInput();
+    observer = new PasteStartObserver();
+    filter = new PasteFramingFilter();
+    decoder = new StringDecoder("utf8");
+    policyListeners = new Set();
+    failureListeners = new Set();
+    policy = "execute";
+    failure;
+    closed = false;
+    disposing = false;
+    inputAcquired = false;
+    inputCloseExpected = false;
+    inputCloseSeen = false;
+    outputCloseSeen = false;
+    inputActive = false;
+    rawAcquired = false;
+    refAcquired = false;
+    pasteAcquired = false;
+    originalRaw;
+    view;
+    viewEnabled = false;
+    prefixTimer;
+    constructor(physicalInput, physicalOutput, resources = {}) {
+        this.physicalInput = physicalInput;
+        this.physicalOutput = physicalOutput;
+        this.resources = resources;
+        this.input = this.bridge;
+        this.output = toResizeSafeOutput(this.wrapOutput());
+        this.originalRaw = resources.restoreRaw ?? physicalInput.isRaw === true;
+        try {
+            assertAvailableInput(physicalInput, physicalOutput);
+            // 校验拒绝时不能读取仍由原消费者持有的缓冲。
+            this.inputAcquired = true;
+            physicalInput.on("readable", this.drain);
+            physicalInput.on("error", this.handleFailure);
+            physicalInput.on("end", this.handleFailure);
+            physicalInput.on("close", this.handleInputClose);
+            physicalOutput.on("error", this.handleFailure);
+            physicalOutput.on("close", this.handleOutputClose);
+            physicalOutput.on("finish", this.handleFailure);
+            physicalOutput.on("resize", this.updateVisibility);
+            if (!physicalInput.isRaw) {
+                this.rawAcquired = true;
+                physicalInput.setRawMode(true);
+                this.checkTerminalState();
+                this.throwIfFailed();
+                this.refAcquired = true;
+                physicalInput.ref();
+                this.checkTerminalState();
+                this.throwIfFailed();
+            }
+            this.pasteAcquired = true;
+            physicalOutput.write(ENABLE_PASTE);
+            this.checkTerminalState();
+            this.throwIfFailed();
+            this.drain();
+            this.throwIfFailed();
+        }
+        catch {
+            this.fail(new InteractiveSessionError());
+            throw this.failure ?? new InteractiveSessionError();
+        }
+    }
+    getExecutionPolicy = () => this.policy;
+    subscribeExecutionPolicy = (listener) => {
+        this.policyListeners.add(listener);
+        return () => {
+            this.policyListeners.delete(listener);
+        };
+    };
+    subscribeFailure(listener) {
+        if (this.failure)
+            listener(this.failure);
+        else
+            this.failureListeners.add(listener);
+        return () => {
+            this.failureListeners.delete(listener);
+        };
+    }
+    beginView() {
+        this.throwIfFailed();
+        if (this.closed)
+            throw new InteractiveSessionError();
+        const token = {};
+        this.suspendViewInput();
+        this.view = token;
+        this.viewEnabled = true;
+        this.updateVisibility();
+        return () => {
+            if (this.view === token) {
+                this.suspendViewInput();
+                this.view = undefined;
+            }
+        };
+    }
+    suspendViewInput() {
+        this.viewEnabled = false;
+        this.setInputActive(false);
+        this.drain();
+        while (this.bridge.read() !== null) {
+            /* 丢弃旧 UI 尚未消费的输入。 */
+        }
+    }
+    handoff(actions) {
+        this.throwIfFailed();
+        if (this.closed)
+            throw new InteractiveSessionError();
+        this.drain();
+        this.throwIfFailed();
+        this.dispose();
+        this.throwIfFailed();
+        // 本次检查后不经过 await，执行 action 必须同步到达实际 spawn。
+        return this.getExecutionPolicy() === "print" ? actions.print() : actions.execute();
+    }
+    dispose() {
+        if (this.closed || this.disposing)
+            return;
+        this.disposing = true;
+        const previousFailure = this.failure;
+        this.checkTerminalState();
+        this.viewEnabled = false;
+        this.setInputActive(false);
+        this.clearPrefixTimer();
+        this.filter.clear();
+        let cleanupFailed = false;
+        const cleanup = (action) => {
+            try {
+                action();
+            }
+            catch {
+                cleanupFailed = true;
+            }
+            this.checkTerminalState();
+        };
+        if (this.pasteAcquired && !this.physicalOutput.destroyed && !this.physicalOutput.writableEnded)
+            cleanup(() => {
+                this.physicalOutput.write(DISABLE_PASTE);
+            });
+        if (this.rawAcquired)
+            cleanup(() => {
+                this.physicalInput.setRawMode(this.originalRaw);
+            });
+        if (this.refAcquired)
+            cleanup(() => {
+                this.physicalInput.unref();
+            });
+        // 恢复终端时仍保留原始观察，最后再同步排空并撤下监听。
+        this.drain();
+        this.checkTerminalState();
+        this.physicalInput.off("readable", this.drain);
+        this.physicalInput.off("end", this.handleFailure);
+        this.physicalOutput.off("resize", this.updateVisibility);
+        this.physicalOutput.off("finish", this.handleFailure);
+        if (this.resources.releaseInput) {
+            // 构造尚未取得消费权时，自有 reader 的关闭仍需要错误接收者。
+            if (!this.inputAcquired) {
+                this.physicalInput.on("error", this.handleFailure);
+                this.physicalInput.on("close", this.handleInputClose);
+            }
+            this.checkTerminalState();
+            this.inputCloseExpected = true;
+        }
+        // 只关闭会话自己的读者，同步停止物理读取后才允许 handoff 检查权限并 spawn。
+        cleanup(() => {
+            this.resources.releaseInput?.();
+        });
+        this.closed = true;
+        // destroyed/closed 可以先于排队中的 error/close 变为 true，必须等真实 close 收尾。
+        if (this.inputCloseSeen ||
+            (!this.inputCloseExpected && (!this.inputAcquired || !inputIsUnavailable(this.physicalInput)))) {
+            this.physicalInput.off("error", this.handleFailure);
+            this.physicalInput.off("close", this.handleInputClose);
+        }
+        if (this.outputCloseSeen || !this.inputAcquired || !outputIsUnavailable(this.physicalOutput)) {
+            this.physicalOutput.off("error", this.handleFailure);
+            this.physicalOutput.off("close", this.handleOutputClose);
+        }
+        this.bridge.destroy();
+        this.policyListeners.clear();
+        this.failureListeners.clear();
+        if (cleanupFailed && !this.failure) {
+            this.failure = new InteractiveSessionError("无法恢复交互终端状态。");
+        }
+        if (!previousFailure && this.failure)
+            throw this.failure;
+    }
+    throwIfFailed() {
+        if (this.failure)
+            throw this.failure;
+    }
+    fail(error) {
+        if (this.closed || this.failure)
+            return;
+        this.failure = error;
+        this.policy = "print";
+        const listeners = [...this.failureListeners];
+        this.failureListeners.clear();
+        this.dispose();
+        for (const listener of listeners)
+            listener(error);
+    }
+    handleFailure = () => {
+        this.fail(new InteractiveSessionError());
+    };
+    checkTerminalState() {
+        if (this.inputAcquired &&
+            (inputIsUnavailable(this.physicalInput, this.inputCloseExpected) ||
+                outputIsUnavailable(this.physicalOutput))) {
+            this.handleFailure();
+        }
+    }
+    handleInputClose = () => {
+        this.inputCloseSeen = true;
+        if (this.closed) {
+            this.physicalInput.off("error", this.handleFailure);
+            this.physicalInput.off("close", this.handleInputClose);
+        }
+        else if (!this.inputCloseExpected)
+            this.handleFailure();
+    };
+    handleOutputClose = () => {
+        this.outputCloseSeen = true;
+        if (this.closed) {
+            this.physicalOutput.off("error", this.handleFailure);
+            this.physicalOutput.off("close", this.handleOutputClose);
+        }
+        else
+            this.handleFailure();
+    };
+    setInputActive(active) {
+        if (active !== this.inputActive) {
+            // 隐藏边界不能把未完成的 UTF-8 字符带入下一个可见输入阶段。
+            this.decoder = new StringDecoder("utf8");
+        }
+        this.inputActive = active;
+        this.filter.setActive(active);
+    }
+    updateVisibility = () => {
+        const active = this.viewEnabled && normalizePhysicalRows(this.physicalOutput.rows) > 1;
+        if (active && !this.inputActive)
+            this.drain();
+        this.setInputActive(active);
+    };
+    clearPrefixTimer() {
+        if (this.prefixTimer !== undefined)
+            clearTimeout(this.prefixTimer);
+        this.prefixTimer = undefined;
+    }
+    drain = () => {
+        if (this.closed || !this.inputAcquired)
+            return;
+        try {
+            this.clearPrefixTimer();
+            let chunk;
+            while ((chunk = this.physicalInput.read()) !== null) {
+                if (typeof chunk !== "string" && !Buffer.isBuffer(chunk))
+                    throw new InteractiveSessionError();
+                const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+                if (this.observer.observe(bytes) && this.policy !== "print") {
+                    this.policy = "print";
+                    for (const listener of this.policyListeners)
+                        listener();
+                }
+                if (normalizePhysicalRows(this.physicalOutput.rows) <= 1)
+                    this.setInputActive(false);
+                const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+                const filtered = this.filter.push(text);
+                if (filtered !== "")
+                    this.bridge.push(filtered);
+            }
+            if (!this.disposing && this.filter.hasPendingKeyboardPrefix()) {
+                // 此延迟仅保留独立 Esc 的键盘语义，绝不用于恢复执行权限。
+                this.prefixTimer = setTimeout(() => {
+                    this.prefixTimer = undefined;
+                    if (this.closed)
+                        return;
+                    const text = this.filter.flushKeyboardPrefix();
+                    if (text !== "")
+                        this.bridge.push(text);
+                }, 20);
+            }
+        }
+        catch {
+            this.handleFailure();
+        }
+    };
+    wrapOutput() {
+        const physical = this.physicalOutput;
+        const methods = new Map();
+        const proxy = new Proxy(physical, {
+            get: (target, property) => {
+                if (property === "write") {
+                    return (chunk, ...args) => {
+                        const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+                        if (this.failure ||
+                            target.destroyed ||
+                            target.writableEnded ||
+                            (!this.closed && (text === ENABLE_PASTE || text === DISABLE_PASTE))) {
+                            const callback = args.find((arg) => typeof arg === "function");
+                            callback?.();
+                            return true;
+                        }
+                        return Reflect.apply(target.write.bind(target), target, [chunk, ...args]);
+                    };
+                }
+                const value = Reflect.get(target, property, target);
+                if (property === "constructor" || typeof value !== "function")
+                    return value;
+                if (!methods.has(property))
+                    methods.set(property, (...args) => {
+                        const result = Reflect.apply(value, target, args);
+                        return result === target ? proxy : result;
+                    });
+                return methods.get(property);
+            },
+        });
+        return proxy;
+    }
+}
+export function createInteractiveSession(options) {
+    if (options.input !== process.stdin) {
+        return new InteractiveSession(options.input, options.output);
+    }
+    // 仅供内部 CLI 的冷 stdin 路径；这些状态不能认证任意外部代码的完整读取历史。
+    assertAvailableInput(options.input, options.output);
+    if (process.stdin.fd !== 0 ||
+        options.input.readableFlowing !== null ||
+        options.input.readableDidRead ||
+        options.input.readableLength > 0) {
+        throw new InteractiveSessionError();
+    }
+    const restoreRaw = options.input.isRaw === true;
+    let reader;
+    let released = false;
+    const releaseInput = () => {
+        if (released)
+            return;
+        released = true;
+        reader?.destroy();
+    };
+    try {
+        // 标准 fd 0 保留给原 stdin 和子进程；该读者的生命周期只属于本会话。
+        reader = new ReadStream(0);
+        return new InteractiveSession(reader, options.output, { restoreRaw, releaseInput });
+    }
+    catch {
+        releaseInput();
+        throw new InteractiveSessionError();
+    }
+}

package/dist/ui/paste-framing.js

@@ -0,0 +1,105 @@
+import { hasUnsafeTerminalControlCharacters } from "../terminal-text.js";
+export const PASTE_START = "\u001b[200~";
+export const PASTE_END = "\u001b[201~";
+/** 权限观察不受键盘解析、隐藏状态或组件生命周期影响。 */
+export class PasteStartObserver {
+    suffix = Buffer.alloc(0);
+    observe(chunk) {
+        const combined = Buffer.concat([this.suffix, chunk]);
+        const found = combined.includes(Buffer.from(PASTE_START));
+        this.suffix = Buffer.from(combined.subarray(Math.max(0, combined.length - 5)));
+        return found;
+    }
+}
+/** 只交付完整的可见粘贴；按解码后的字符检查 C1，避免误拒绝 UTF-8 延续字节。 */
+export class PasteFramingFilter {
+    active = false;
+    pending = "";
+    flushedPrefix = 0;
+    invalidPrefix = false;
+    collecting = false;
+    discardPaste = false;
+    paste = "";
+    setActive(active) {
+        this.active = active;
+        if (!active) {
+            this.invalidPrefix = true;
+            if (this.collecting) {
+                this.discardPaste = true;
+                this.paste = "";
+            }
+        }
+    }
+    push(text) {
+        let output = "";
+        for (const character of text) {
+            if (this.pending === "" && !this.collecting)
+                this.invalidPrefix = !this.active;
+            this.pending += character;
+            if (!this.active)
+                this.invalidPrefix = true;
+            if (this.collecting) {
+                while (this.pending !== "" && !PASTE_END.startsWith(this.pending)) {
+                    if (!this.discardPaste)
+                        this.paste += this.pending[0];
+                    this.pending = this.pending.slice(1);
+                }
+                if (this.pending === PASTE_END) {
+                    if (this.active &&
+                        !this.discardPaste &&
+                        !hasUnsafeTerminalControlCharacters(this.paste)) {
+                        output += PASTE_START + this.paste + PASTE_END;
+                    }
+                    this.collecting = false;
+                    this.paste = "";
+                    this.pending = "";
+                    this.invalidPrefix = false;
+                }
+                continue;
+            }
+            while (this.pending !== "" &&
+                !PASTE_START.startsWith(this.pending) &&
+                !PASTE_END.startsWith(this.pending)) {
+                if (this.flushedPrefix > 0)
+                    this.flushedPrefix--;
+                else if (this.active && !this.invalidPrefix)
+                    output += this.pending[0];
+                this.pending = this.pending.slice(1);
+                if (this.pending === "")
+                    this.invalidPrefix = !this.active;
+            }
+            if (this.pending === PASTE_START) {
+                this.collecting = true;
+                this.discardPaste = !this.active || this.invalidPrefix || this.flushedPrefix > 0;
+                this.pending = "";
+                this.flushedPrefix = 0;
+                this.paste = "";
+            }
+            else if (this.pending === PASTE_END) {
+                // 孤立的协议结束标记不作为表单文字交付。
+                this.pending = "";
+                this.flushedPrefix = 0;
+                this.invalidPrefix = false;
+            }
+        }
+        return output;
+    }
+    hasPendingKeyboardPrefix() {
+        return !this.collecting && this.pending.length > this.flushedPrefix;
+    }
+    flushKeyboardPrefix() {
+        if (this.collecting)
+            return "";
+        const result = this.active && !this.invalidPrefix ? this.pending.slice(this.flushedPrefix) : "";
+        // 刷新只影响键盘体验，保留完整标记匹配状态；权限观察器也完全独立。
+        this.flushedPrefix = this.pending.length;
+        return result;
+    }
+    clear() {
+        this.pending = "";
+        this.paste = "";
+        this.flushedPrefix = 0;
+        this.collecting = false;
+        this.active = false;
+    }
+}

package/dist/ui/placeholder-logic.js

@@ -1,19 +1,120 @@
-const UNRESOLVED_PLACEHOLDER_PATTERN = /{{[^{}]*}}/;
+import { deleteLastGrapheme } from "./text-input.js";
+const PLACEHOLDER_REFERENCE_PATTERN = /{{([^{}]*)}}/g;
 export class PlaceholderResolutionError extends Error {
     constructor(message) {
         super(message);
         this.name = "PlaceholderResolutionError";
     }
 }
+export function createPlaceholderResolution(candidate) {
+    if (candidate.placeholders.length === 0) {
+        throw new PlaceholderResolutionError("cannot resolve command without placeholders");
+    }
+    return {
+        candidate,
+        activeIndex: 0,
+        values: candidate.placeholders.map(() => ""),
+        buffer: "",
+    };
+}
+export function getPlaceholderResolutionView(state) {
+    const currentPlaceholder = state.candidate.placeholders[state.activeIndex];
+    if (!currentPlaceholder) {
+        throw new PlaceholderResolutionError("placeholder resolution state is out of bounds");
+    }
+    const resolvedValues = new Map();
+    state.candidate.placeholders.forEach((placeholder, index) => {
+        if (index < state.activeIndex) {
+            resolvedValues.set(placeholder.name, state.values[index]);
+        }
+    });
+    return {
+        currentPlaceholder,
+        currentBuffer: {
+            name: currentPlaceholder.name,
+            value: state.buffer,
+        },
+        resolvedValues,
+    };
+}
+export function applyPlaceholderResolutionInput(state, input) {
+    switch (input.type) {
+        case "append":
+            return {
+                type: "editing",
+                state: {
+                    ...state,
+                    buffer: state.buffer + input.value,
+                },
+            };
+        case "delete":
+            return {
+                type: "editing",
+                state: {
+                    ...state,
+                    buffer: deleteLastGrapheme(state.buffer),
+                },
+            };
+        case "escape":
+            return applyEscape(state);
+        case "commit":
+            return applyCommit(state);
+    }
+}
+export function resolveCandidatePlaceholders(candidate, values) {
+    const command = replaceCommandPlaceholders(candidate.command, values);
+    return {
+        candidate,
+        values,
+        command,
+    };
+}
 export function replaceCommandPlaceholders(command, values) {
-    let resolvedCommand = command;
-    for (const [name, value] of values) {
-        resolvedCommand = resolvedCommand.split(`{{${name}}}`).join(value);
+    return command.replace(PLACEHOLDER_REFERENCE_PATTERN, (_reference, name) => {
+        if (!values.has(name)) {
+            throw new PlaceholderResolutionError("final command contains unresolved placeholders");
+        }
+        return values.get(name) ?? "";
+    });
+}
+function applyEscape(state) {
+    if (state.activeIndex === 0) {
+        return { type: "back-to-selection" };
     }
-    return resolvedCommand;
+    const previousIndex = state.activeIndex - 1;
+    const values = [...state.values];
+    values[state.activeIndex] = "";
+    return {
+        type: "editing",
+        state: {
+            ...state,
+            activeIndex: previousIndex,
+            values,
+            buffer: values[previousIndex],
+        },
+    };
 }
-export function assertNoUnresolvedPlaceholders(command) {
-    if (UNRESOLVED_PLACEHOLDER_PATTERN.test(command)) {
-        throw new PlaceholderResolutionError("final command contains unresolved placeholders");
+function applyCommit(state) {
+    const values = [...state.values];
+    values[state.activeIndex] = state.buffer;
+    if (state.activeIndex === state.candidate.placeholders.length - 1) {
+        const resolvedValues = new Map();
+        state.candidate.placeholders.forEach((placeholder, index) => {
+            resolvedValues.set(placeholder.name, values[index]);
+        });
+        return {
+            type: "complete",
+            resolved: resolveCandidatePlaceholders(state.candidate, resolvedValues),
+        };
     }
+    const nextIndex = state.activeIndex + 1;
+    return {
+        type: "editing",
+        state: {
+            ...state,
+            activeIndex: nextIndex,
+            values,
+            buffer: values[nextIndex],
+        },
+    };
 }