@unscientificjszhai/howto 1.0.0 → 1.0.1

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,4 +1,5 @@
-const UNRESOLVED_PLACEHOLDER_PATTERN = /{{[^{}]*}}/;
+import { deleteLastGrapheme } from "./text-input.js";
+const PLACEHOLDER_REFERENCE_PATTERN = /{{([^{}]*)}}/g;
 export class PlaceholderResolutionError extends Error {
     constructor(message) {
         super(message);
@@ -41,12 +42,18 @@ export function applyPlaceholderResolutionInput(state, input) {
         case "append":
             return {
                 type: "editing",
-                state: Object.assign(Object.assign({}, state), { buffer: state.buffer + input.value }),
+                state: {
+                    ...state,
+                    buffer: state.buffer + input.value,
+                },
             };
         case "delete":
             return {
                 type: "editing",
-                state: Object.assign(Object.assign({}, state), { buffer: state.buffer.slice(0, -1) }),
+                state: {
+                    ...state,
+                    buffer: deleteLastGrapheme(state.buffer),
+                },
             };
         case "escape":
             return applyEscape(state);
@@ -56,7 +63,6 @@ export function applyPlaceholderResolutionInput(state, input) {
 }
 export function resolveCandidatePlaceholders(candidate, values) {
     const command = replaceCommandPlaceholders(candidate.command, values);
-    assertNoUnresolvedPlaceholders(command);
     return {
         candidate,
         values,
@@ -64,16 +70,12 @@ export function resolveCandidatePlaceholders(candidate, values) {
     };
 }
 export function replaceCommandPlaceholders(command, values) {
-    let resolvedCommand = command;
-    for (const [name, value] of values) {
-        resolvedCommand = resolvedCommand.split(`{{${name}}}`).join(value);
-    }
-    return resolvedCommand;
-}
-export function assertNoUnresolvedPlaceholders(command) {
-    if (UNRESOLVED_PLACEHOLDER_PATTERN.test(command)) {
-        throw new PlaceholderResolutionError("final command contains unresolved placeholders");
-    }
+    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) {
@@ -84,7 +86,12 @@ function applyEscape(state) {
     values[state.activeIndex] = "";
     return {
         type: "editing",
-        state: Object.assign(Object.assign({}, state), { activeIndex: previousIndex, values, buffer: values[previousIndex] }),
+        state: {
+            ...state,
+            activeIndex: previousIndex,
+            values,
+            buffer: values[previousIndex],
+        },
     };
 }
 function applyCommit(state) {
@@ -103,6 +110,11 @@ function applyCommit(state) {
     const nextIndex = state.activeIndex + 1;
     return {
         type: "editing",
-        state: Object.assign(Object.assign({}, state), { activeIndex: nextIndex, values, buffer: values[nextIndex] }),
+        state: {
+            ...state,
+            activeIndex: nextIndex,
+            values,
+            buffer: values[nextIndex],
+        },
     };
 }

package/dist/ui/resize-safe-output.js

@@ -0,0 +1,73 @@
+import { useEffect, useState } from "react";
+import { useStdout } from "ink";
+const SAFE_INK_ROWS = Number.MAX_SAFE_INTEGER;
+const DEFAULT_PHYSICAL_ROWS = 24;
+const physicalToProxy = new WeakMap();
+const proxyToPhysical = new WeakMap();
+export function toResizeSafeOutput(output) {
+    if (proxyToPhysical.has(output)) {
+        return output;
+    }
+    const existingProxy = physicalToProxy.get(output);
+    if (existingProxy) {
+        return existingProxy;
+    }
+    const wrappedFunctions = new Map();
+    const proxy = new Proxy(output, {
+        get(target, property) {
+            if (property === "rows") {
+                return SAFE_INK_ROWS;
+            }
+            if (property === "constructor") {
+                const constructor = Reflect.get(target, property, target);
+                return constructor;
+            }
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== "function") {
+                return value;
+            }
+            if (wrappedFunctions.has(property)) {
+                return wrappedFunctions.get(property);
+            }
+            // Stream 方法必须绑定物理流，确保 EventEmitter 的 this 与监听移除语义保持不变。
+            const streamMethod = value;
+            const wrappedFunction = (...arguments_) => {
+                const result = Reflect.apply(streamMethod, target, arguments_);
+                return result === target ? proxy : result;
+            };
+            wrappedFunctions.set(property, wrappedFunction);
+            return wrappedFunction;
+        },
+    });
+    physicalToProxy.set(output, proxy);
+    proxyToPhysical.set(proxy, output);
+    return proxy;
+}
+export function unwrapResizeSafeOutput(output) {
+    return proxyToPhysical.get(output) ?? output;
+}
+export function usePhysicalStdoutRows() {
+    const { stdout } = useStdout();
+    const physicalStdout = unwrapResizeSafeOutput(stdout);
+    const [rows, setRows] = useState(() => readPhysicalRows(physicalStdout));
+    useEffect(() => {
+        const updateRows = () => {
+            setRows(readPhysicalRows(physicalStdout));
+        };
+        physicalStdout.on("resize", updateRows);
+        updateRows();
+        return () => {
+            physicalStdout.off("resize", updateRows);
+        };
+    }, [physicalStdout]);
+    return rows;
+}
+export function normalizePhysicalRows(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_PHYSICAL_ROWS;
+    }
+    return Math.max(0, Math.floor(value));
+}
+function readPhysicalRows(output) {
+    return normalizePhysicalRows(output.rows);
+}