@unscientificjszhai/howto 1.0.0 → 1.0.1

package/dist/shell/command-analysis.js

@@ -0,0 +1,373 @@
+import { posix } from "node:path";
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const SHELLS = new Set(["sh", "bash", "zsh", "fish", "csh", "tcsh", "ksh", "dash"]);
+const REINTERPRETING_PREFIXES = new Set([
+    "command",
+    "exec",
+    "builtin",
+    "time",
+    "noglob",
+    "nocorrect",
+    "eval",
+    "source",
+    ".",
+]);
+const RESERVED_WORDS = new Set([
+    "if",
+    "then",
+    "elif",
+    "else",
+    "fi",
+    "for",
+    "while",
+    "until",
+    "do",
+    "done",
+    "case",
+    "esac",
+    "select",
+    "function",
+    "coproc",
+    "repeat",
+    "and",
+    "or",
+    "not",
+    "!",
+]);
+const WRAPPER_PATHS = new Set([
+    "sudo",
+    "env",
+    "/usr/bin/sudo",
+    "/bin/sudo",
+    "/usr/bin/env",
+    "/bin/env",
+]);
+const SUDO_ZERO_SHORT = new Set("ABbEHknPS");
+const SUDO_ONE_SHORT = new Set("CDghpRTu");
+const SUDO_ZERO_LONG = new Set([
+    "--askpass",
+    "--bell",
+    "--background",
+    "--preserve-env",
+    "--set-home",
+    "--reset-timestamp",
+    "--non-interactive",
+    "--preserve-groups",
+    "--stdin",
+]);
+const SUDO_ONE_LONG = new Set([
+    "--close-from",
+    "--chdir",
+    "--group",
+    "--host",
+    "--prompt",
+    "--chroot",
+    "--command-timeout",
+    "--user",
+]);
+const ENV_ZERO_SHORT = new Set("iv");
+const ENV_ONE_SHORT = new Set("uCP");
+const ENV_ZERO_LONG = new Set(["--ignore-environment", "--debug"]);
+const ENV_ONE_LONG = new Set(["--unset", "--chdir"]);
+export function isShellExecutable(value) {
+    return SHELLS.has(posix.basename(value));
+}
+export function parseShellCommand(command) {
+    const lexed = lexShellCommand(command);
+    if (lexed.kind === "unsupported")
+        return lexed;
+    const commands = [];
+    let words = [];
+    let needsCommand = false;
+    let hasRedirection = false;
+    for (let index = 0; index < lexed.tokens.length; index += 1) {
+        const token = lexed.tokens[index];
+        if (token.kind === "word") {
+            words.push(token.word);
+            needsCommand = false;
+        }
+        else if (token.kind === "redirect") {
+            hasRedirection = true;
+            if (token.needsTarget) {
+                const target = lexed.tokens[index + 1];
+                if (target?.kind !== "word")
+                    return unsupported("syntax");
+                index += 1;
+            }
+        }
+        else {
+            if (words.length === 0) {
+                if (hasRedirection)
+                    return unsupported("syntax");
+                if (token.separator === "\n")
+                    continue;
+                return unsupported("syntax");
+            }
+            commands.push({ words, separator: token.separator });
+            words = [];
+            hasRedirection = false;
+            needsCommand =
+                token.separator === "&&" || token.separator === "||" || token.separator === "|";
+        }
+    }
+    if (needsCommand)
+        return unsupported("syntax");
+    if (words.length === 0 && hasRedirection)
+        return unsupported("syntax");
+    if (words.length > 0)
+        commands.push({ words });
+    return commands.length > 0 ? { kind: "parsed", commands } : unsupported("missing-executable");
+}
+export function resolveCommandPrefix(words) {
+    let index = 0;
+    while (words[index]?.assignmentOperator === "=")
+        index += 1;
+    while (index < words.length) {
+        const word = words[index];
+        // += 在 Bash/zsh 与 dash 中语义不同；无法确定 shell 时不能跳过它证明工具身份。
+        if (word.assignmentOperator === "+=" ||
+            word.hasExpansion ||
+            word.value === "" ||
+            word.value.startsWith("-"))
+            return unsupported("prefix");
+        const name = posix.basename(word.value);
+        if (REINTERPRETING_PREFIXES.has(name) || RESERVED_WORDS.has(word.value))
+            return unsupported("prefix");
+        if (name !== "sudo" && name !== "env") {
+            return { kind: "parsed", executable: word, args: words.slice(index + 1) };
+        }
+        if (!WRAPPER_PATHS.has(word.value))
+            return unsupported("prefix");
+        const skipped = skipWrapperOptions(words, index + 1, name);
+        if (typeof skipped !== "number")
+            return skipped;
+        index = skipped;
+        // wrapper 按 argv 识别赋值；env 的非空名称不受 shell 标识符规则限制。
+        // sudo 保留 NAME= 白名单，其他含等号形式及动态赋值不推测为工具。
+        while (words[index] !== undefined) {
+            const assignment = words[index];
+            const equals = assignment.value.indexOf("=");
+            if (equals < 0)
+                break;
+            if (assignment.hasExpansion ||
+                (name === "env" ? equals === 0 : !ASSIGNMENT.test(assignment.value)))
+                return unsupported("prefix");
+            index += 1;
+        }
+    }
+    return unsupported("missing-executable");
+}
+function skipWrapperOptions(words, start, wrapper) {
+    const zeroShort = wrapper === "sudo" ? SUDO_ZERO_SHORT : ENV_ZERO_SHORT;
+    const oneShort = wrapper === "sudo" ? SUDO_ONE_SHORT : ENV_ONE_SHORT;
+    const zeroLong = wrapper === "sudo" ? SUDO_ZERO_LONG : ENV_ZERO_LONG;
+    const oneLong = wrapper === "sudo" ? SUDO_ONE_LONG : ENV_ONE_LONG;
+    let index = start;
+    while (index < words.length) {
+        const word = words[index];
+        if (word.hasExpansion)
+            return unsupported("prefix");
+        const option = word.value;
+        if (option === "--")
+            return index + 1;
+        if (option === "-" && wrapper === "env")
+            return index + 1;
+        if (!option.startsWith("-") || option === "-")
+            return index;
+        let needsArgument = false;
+        if (option.startsWith("--")) {
+            const equals = option.indexOf("=");
+            const name = equals < 0 ? option : option.slice(0, equals);
+            if (zeroLong.has(name)) {
+                if (equals >= 0 && !(wrapper === "sudo" && name === "--preserve-env"))
+                    return unsupported("option");
+            }
+            else if (oneLong.has(name)) {
+                if (equals >= 0) {
+                    if (option.slice(equals + 1) === "")
+                        return unsupported("missing-argument");
+                }
+                else {
+                    needsArgument = true;
+                }
+            }
+            else {
+                return unsupported("option");
+            }
+        }
+        else {
+            for (let offset = 1; offset < option.length; offset += 1) {
+                const flag = option[offset];
+                if (zeroShort.has(flag))
+                    continue;
+                if (!oneShort.has(flag))
+                    return unsupported("option");
+                needsArgument = offset === option.length - 1;
+                break;
+            }
+        }
+        index += 1;
+        if (needsArgument) {
+            const argument = words[index];
+            if (argument === undefined || argument.value === "")
+                return unsupported("missing-argument");
+            if (argument.hasExpansion)
+                return unsupported("prefix");
+            index += 1;
+        }
+    }
+    return index;
+}
+function lexShellCommand(command) {
+    const tokens = [];
+    let index = 0;
+    while (index < command.length) {
+        const char = command[index];
+        if (char === " " || char === "\t") {
+            index += 1;
+            continue;
+        }
+        if (char === "\\" && command[index + 1] === "\n") {
+            index += 2;
+            continue;
+        }
+        if (char === "#") {
+            while (index < command.length && command[index] !== "\n")
+                index += 1;
+            continue;
+        }
+        if (";\n&|".includes(char)) {
+            if (char === "&" && command[index + 1] === ">")
+                return unsupported("syntax");
+            const pair = command.slice(index, index + 2);
+            const separator = pair === "&&" || pair === "||" ? pair : char;
+            tokens.push({ kind: "separator", separator });
+            index += separator.length;
+            continue;
+        }
+        if ("(){}".includes(char))
+            return unsupported("syntax");
+        const redirect = /^(?:\d+)?(?:>>|[<>])/.exec(command.slice(index));
+        if (redirect !== null) {
+            index += redirect[0].length;
+            if (command[index] === "<" || command[index] === ">" || command[index] === "(")
+                return unsupported("syntax");
+            if (command[index] === "&") {
+                const descriptor = /^&(?:\d+|-)(?=$|[ \t\n;&|<>])/.exec(command.slice(index));
+                if (descriptor === null)
+                    return unsupported("syntax");
+                index += descriptor[0].length;
+                tokens.push({ kind: "redirect", needsTarget: false });
+            }
+            else {
+                tokens.push({ kind: "redirect", needsTarget: true });
+            }
+            continue;
+        }
+        const word = readWord(command, index);
+        if (word.kind === "unsupported")
+            return word;
+        const rawWord = command.slice(index, word.word.end);
+        if ((command[word.word.end] === "<" || command[word.word.end] === ">") &&
+            /^\d+$/.test(word.word.value) &&
+            rawWord.includes("\\\n") &&
+            rawWord.replaceAll("\\\n", "") === word.word.value) {
+            // 数字 fd 内的续行在 sh/bash 与 zsh 中分词不同，不能把它当作确定的工具名。
+            return unsupported("syntax");
+        }
+        tokens.push({ kind: "word", word: word.word });
+        index = word.word.end;
+    }
+    return { kind: "parsed", tokens };
+}
+function readWord(command, start) {
+    let index = start;
+    let value = "";
+    let quote;
+    let hasExpansion = false;
+    let assignmentEligible = true;
+    let assignmentOperator;
+    while (index < command.length) {
+        const char = command[index];
+        if (quote === "'") {
+            if (char === "'")
+                quote = undefined;
+            else
+                value += char;
+            index += 1;
+            continue;
+        }
+        if (char === "\\") {
+            const next = command[index + 1];
+            if (next === undefined)
+                return unsupported("syntax");
+            if (next === "\n") {
+                index += 2;
+                continue;
+            }
+            if (quote === undefined || '$`"\\'.includes(next)) {
+                value += next;
+                assignmentEligible = false;
+                index += 2;
+                continue;
+            }
+            value += char;
+            index += 1;
+            continue;
+        }
+        if (quote === '"' && char === '"') {
+            quote = undefined;
+            index += 1;
+            continue;
+        }
+        if (quote === undefined && (char === "'" || char === '"')) {
+            quote = char;
+            assignmentEligible = false;
+            index += 1;
+            continue;
+        }
+        if (char === "`")
+            return unsupported("expansion");
+        if (char === "$") {
+            const next = command[index + 1];
+            if (next === "(" || next === "'" || next === '"')
+                return unsupported("expansion");
+            if (next === "{") {
+                const parameter = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}/.exec(command.slice(index));
+                if (parameter === null)
+                    return unsupported("expansion");
+                value += parameter[0];
+                hasExpansion = true;
+                assignmentEligible = false;
+                index += parameter[0].length;
+                continue;
+            }
+            // 未引用或转义的美元字符保守视为动态，不能用不完整白名单排除 shell 扩展。
+            hasExpansion = true;
+        }
+        if (quote === undefined) {
+            if (" \t\n;&|<>".includes(char))
+                break;
+            if ("(){}".includes(char))
+                return unsupported("syntax");
+            if ("*?[".includes(char) ||
+                (char === "~" && value === "") ||
+                (char === "=" && value === "" && assignmentEligible))
+                hasExpansion = true;
+            if (char === "=" && assignmentEligible) {
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(value))
+                    assignmentOperator = "=";
+                else if (/^[A-Za-z_][A-Za-z0-9_]*\+$/.test(value))
+                    assignmentOperator = "+=";
+            }
+        }
+        value += char;
+        index += 1;
+    }
+    if (quote !== undefined)
+        return unsupported("syntax");
+    return { kind: "parsed", word: { value, start, end: index, hasExpansion, assignmentOperator } };
+}
+function unsupported(reason) {
+    return { kind: "unsupported", reason };
+}

package/dist/terminal-text.js

@@ -0,0 +1,33 @@
+export function hasUnsafeTerminalControlCharacters(value) {
+    for (let index = 0; index < value.length; index++) {
+        if (isUnsafeTerminalControlCodeUnit(value.charCodeAt(index))) {
+            return true;
+        }
+    }
+    return false;
+}
+export function renderTerminalSafeText(value) {
+    let rendered = "";
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit === 0x0d) {
+            rendered += "␍";
+        }
+        else if (codeUnit === 0x0a) {
+            rendered += "␊";
+        }
+        else if (isUnsafeTerminalControlCodeUnit(codeUnit)) {
+            rendered += "�";
+        }
+        else {
+            rendered += value[index];
+        }
+    }
+    return rendered;
+}
+function isUnsafeTerminalControlCodeUnit(codeUnit) {
+    return (codeUnit <= 0x09 ||
+        (codeUnit >= 0x0b && codeUnit <= 0x0c) ||
+        (codeUnit >= 0x0e && codeUnit <= 0x1f) ||
+        (codeUnit >= 0x7f && codeUnit <= 0x9f));
+}

package/dist/ui/App.js

@@ -1,5 +1,7 @@
-import React, { useState, useEffect } from "react";
-import { Box, Text, useWindowSize } from "ink";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Box, Text, usePaste, useWindowSize } from "ink";
+import { useKeyboardInput } from "./use-keyboard-input.js";
+import { useInteractiveSession } from "./InteractiveSessionProvider.js";
 import { LoadingView } from "./LoadingView.js";
 import { SelectCommandView } from "./SelectCommandView.js";
 import { ResolvePlaceholdersView } from "./ResolvePlaceholdersView.js";
@@ -8,8 +10,12 @@ import { generateValidatedCommandCandidates } from "../validation/generated-comm
 import { detectDangerousCommand } from "../safety/dangerous-command.js";
 import { resolveCandidatePlaceholders } from "./placeholder-logic.js";
 import { InteractionCancelledError } from "./tty.js";
+import { usePhysicalStdoutRows } from "./resize-safe-output.js";
+import { getUserVisibleErrorMessage } from "../errors.js";
 export const App = ({ provider, request, onSuccess, onError }) => {
-    const { rows } = useWindowSize();
+    const session = useInteractiveSession();
+    const rows = usePhysicalStdoutRows();
+    const { columns } = useWindowSize();
     const [status, setStatus] = useState("loading");
     const [candidates, setCandidates] = useState([]);
     const [selectedCandidate, setSelectedCandidate] = useState(null);
@@ -17,20 +23,56 @@ export const App = ({ provider, request, onSuccess, onError }) => {
     const [finalCommand, setFinalCommand] = useState("");
     const [danger, setDanger] = useState(undefined);
     const [errorMessage, setErrorMessage] = useState("");
-    useEffect(() => {
-        if (status === "loading") {
-            generateValidatedCommandCandidates(provider, request)
-                .then((generatedCandidates) => {
-                setCandidates(generatedCandidates);
-                setStatus("selecting");
-            })
-                .catch((error) => {
-                const appError = normalizeError(error);
-                setErrorMessage(appError.message);
-                setStatus("error");
-                onError(appError);
-            });
+    const activeRequestControllerRef = useRef(null);
+    const cancellationReportedRef = useRef(false);
+    const frameRows = Math.max(0, rows - 1);
+    const isFrameVisible = frameRows > 0;
+    usePaste(() => { }, { isActive: isFrameVisible });
+    const handleCancel = useCallback(() => {
+        session.suspendViewInput();
+        activeRequestControllerRef.current?.abort();
+        if (cancellationReportedRef.current)
+            return;
+        cancellationReportedRef.current = true;
+        onError(new InteractionCancelledError());
+    }, [onError, session]);
+    useKeyboardInput((input, key) => {
+        if (frameRows === 0)
+            return;
+        if (status !== "loading")
+            return;
+        if (key.ctrl && input === "c") {
+            handleCancel();
         }
+    });
+    useEffect(() => {
+        if (status !== "loading")
+            return;
+        const controller = new AbortController();
+        let isCurrent = true;
+        activeRequestControllerRef.current = controller;
+        void generateValidatedCommandCandidates(provider, request, controller.signal)
+            .then((generatedCandidates) => {
+            if (!isCurrent || controller.signal.aborted)
+                return;
+            setCandidates(generatedCandidates);
+            setStatus("selecting");
+        })
+            .catch((error) => {
+            if (!isCurrent || controller.signal.aborted)
+                return;
+            const appError = normalizeError(error);
+            setErrorMessage(getUserVisibleErrorMessage(appError));
+            setStatus("error");
+            onError(appError);
+        });
+        return () => {
+            isCurrent = false;
+            controller.abort();
+            if (activeRequestControllerRef.current === controller) {
+                activeRequestControllerRef.current = null;
+            }
+        };
     }, [status, provider, request, onError]);
     const handleSelect = (candidate) => {
         setSelectedCandidate(candidate);
@@ -48,7 +90,7 @@ export const App = ({ provider, request, onSuccess, onError }) => {
             }
             catch (error) {
                 const appError = normalizeError(error);
-                setErrorMessage(appError.message);
+                setErrorMessage(getUserVisibleErrorMessage(appError));
                 setStatus("error");
                 onError(appError);
             }
@@ -68,20 +110,17 @@ export const App = ({ provider, request, onSuccess, onError }) => {
         }
     }, [status, finalCommand, onSuccess]);
     const handleConfirm = () => {
+        session.suspendViewInput();
         setStatus("done");
     };
-    const handleCancel = () => {
-        onError(new InteractionCancelledError());
-    };
     const handleBackToSelection = () => {
         setStatus("selecting");
     };
-    const maxFrameRows = Math.max(1, rows - 1);
-    return (React.createElement(Box, { flexDirection: "column", maxHeight: maxFrameRows, overflowY: "hidden" },
+    return (React.createElement(Box, { flexDirection: "column", display: isFrameVisible ? "flex" : "none", maxHeight: frameRows, overflowY: "hidden" },
         status === "loading" && React.createElement(LoadingView, null),
-        status === "selecting" && (React.createElement(SelectCommandView, { candidates: candidates, onSelect: handleSelect, onCancel: handleCancel })),
-        status === "resolving" && selectedCandidate && (React.createElement(ResolvePlaceholdersView, { candidate: selectedCandidate, onResolve: handleResolve, onBack: handleBackToSelection, onCancel: handleCancel })),
-        (status === "confirming" || status === "done") && selectedCandidate && (React.createElement(ConfirmView, { candidate: selectedCandidate, command: finalCommand, resolvedValues: resolvedValues, danger: danger, onConfirm: handleConfirm, onCancel: handleCancel, isDone: status === "done" })),
+        status === "selecting" && (React.createElement(SelectCommandView, { candidates: candidates, availableRows: frameRows, isInputActive: isFrameVisible, onSelect: handleSelect, onCancel: handleCancel })),
+        status === "resolving" && selectedCandidate && (React.createElement(ResolvePlaceholdersView, { candidate: selectedCandidate, availableRows: frameRows, availableColumns: columns, isInputActive: isFrameVisible, onResolve: handleResolve, onBack: handleBackToSelection, onCancel: handleCancel })),
+        (status === "confirming" || status === "done") && selectedCandidate && (React.createElement(ConfirmView, { candidate: selectedCandidate, command: finalCommand, resolvedValues: resolvedValues, danger: danger, availableRows: frameRows, availableColumns: columns, isInputActive: isFrameVisible, onConfirm: handleConfirm, onCancel: handleCancel, isDone: status === "done" })),
         status === "error" && React.createElement(Text, { color: "red" },
             "Error: ",
             errorMessage)));