@unscientificjszhai/howto 1.0.0 → 1.0.1

package/dist/ui/run-interactive-command.js

@@ -0,0 +1,55 @@
+import React from "react";
+import { render } from "ink";
+import { executeCommand } from "../execute.js";
+import { App } from "./App.js";
+import { InteractiveSessionProvider } from "./InteractiveSessionProvider.js";
+export const MANUAL_EXECUTION_NOTICE = "本次会话包含粘贴，howto 不会自动执行命令。请检查输出内容后手动运行。";
+export async function runInteractiveCommand({ session, provider, request, execute = executeCommand, print = (command) => {
+    console.error(MANUAL_EXECUTION_NOTICE);
+    console.log(command);
+}, }) {
+    let finalCommand;
+    let appError;
+    const instance = render(React.createElement(InteractiveSessionProvider, { session: session },
+        React.createElement(App, { provider: provider, request: request, onSuccess: (command) => {
+                finalCommand = command;
+                session.suspendViewInput();
+                instance.clear();
+                instance.unmount();
+            }, onError: (error) => {
+                appError = error;
+                session.suspendViewInput();
+                instance.clear();
+                instance.unmount();
+            } })), {
+        stdin: session.input,
+        stdout: session.output,
+        exitOnCtrlC: false,
+        // 会话已确认 TTY，避免 CI 环境关闭 Ink 的实时渲染。
+        interactive: true,
+    });
+    const unsubscribe = session.subscribeFailure((error) => {
+        appError = error;
+        instance.clear();
+        instance.unmount();
+    });
+    try {
+        await instance.waitUntilExit();
+        if (appError)
+            throw appError;
+        if (finalCommand === undefined)
+            return 1;
+        const command = finalCommand;
+        return await session.handoff({
+            execute: () => execute(command),
+            print: () => {
+                print(command);
+                return Promise.resolve(0);
+            },
+        });
+    }
+    finally {
+        unsubscribe();
+        instance.unmount();
+    }
+}

package/dist/ui/single-line-preview.js

@@ -0,0 +1,28 @@
+/// <reference lib="es2022.intl" />
+import stringWidth from "string-width";
+import { renderTerminalSafeText } from "../terminal-text.js";
+const graphemeSegmenter = new Intl.Segmenter(undefined, {
+    granularity: "grapheme",
+});
+export function toSingleLinePreview(value) {
+    return renderTerminalSafeText(value);
+}
+export function toTailPreview(value, maxColumns) {
+    if (maxColumns <= 0) {
+        return "";
+    }
+    const preview = toSingleLinePreview(value);
+    const graphemes = Array.from(graphemeSegmenter.segment(preview), ({ segment }) => segment);
+    let usedColumns = 0;
+    let startIndex = graphemes.length;
+    while (startIndex > 0) {
+        const grapheme = graphemes[startIndex - 1];
+        const graphemeColumns = stringWidth(grapheme);
+        if (usedColumns + graphemeColumns > maxColumns) {
+            break;
+        }
+        usedColumns += graphemeColumns;
+        startIndex--;
+    }
+    return graphemes.slice(startIndex).join("");
+}

package/dist/ui/text-input.js

@@ -0,0 +1,53 @@
+/// <reference lib="es2022.intl" />
+import { hasUnsafeTerminalControlCharacters } from "../terminal-text.js";
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+// eslint-disable-next-line no-control-regex -- 显式识别传统终端协议的按键控制字节。
+const LEGACY_CONTROL_PATTERN = /([\r\n\t\u0003\u0008\u001b\u007f])/;
+const LEGACY_CONTROL_KEYS = new Map([
+    ["\r", { input: "", key: { return: true } }],
+    ["\n", { input: "", key: { return: true } }],
+    ["\t", { input: "", key: { tab: true } }],
+    ["\u0003", { input: "c", key: { ctrl: true } }],
+    ["\u0008", { input: "", key: { backspace: true } }],
+    ["\u007f", { input: "", key: { backspace: true } }],
+    ["\u001b", { input: "", key: { escape: true } }],
+]);
+export function splitKeyboardInput(input, key) {
+    const parts = input.split(LEGACY_CONTROL_PATTERN).filter((part) => part !== "");
+    const text = parts.map((part) => (LEGACY_CONTROL_KEYS.has(part) ? " " : part)).join("");
+    // Kitty 的文本码点已有事件边界；未知控制字符和快捷键继续交给原有规则整块处理。
+    if (key.eventType !== undefined || !isTextInputEvent(text, key))
+        return [{ input, key }];
+    return parts.map((part) => {
+        const control = LEGACY_CONTROL_KEYS.get(part);
+        return control === undefined
+            ? { input: part, key }
+            : { input: control.input, key: { ...key, shift: false, ...control.key } };
+    });
+}
+export function deleteLastGrapheme(value) {
+    const lastGrapheme = graphemeSegmenter.segment(value).containing(value.length - 1);
+    return lastGrapheme === undefined ? "" : value.slice(0, lastGrapheme.index);
+}
+export function isTextInputEvent(input, key) {
+    return (input.length > 0 &&
+        !hasUnsafeTerminalControlCharacters(input) &&
+        key.eventType !== "release" &&
+        !key.ctrl &&
+        !key.meta &&
+        !key.super &&
+        !key.hyper &&
+        !key.upArrow &&
+        !key.downArrow &&
+        !key.leftArrow &&
+        !key.rightArrow &&
+        !key.pageUp &&
+        !key.pageDown &&
+        !key.home &&
+        !key.end &&
+        !key.tab &&
+        !key.return &&
+        !key.escape &&
+        !key.backspace &&
+        !key.delete);
+}

package/dist/ui/use-keyboard-input.js

@@ -0,0 +1,12 @@
+import { useInput } from "ink";
+import { splitKeyboardInput } from "./text-input.js";
+export function useKeyboardInput(onInput, options) {
+    useInput((input, key) => {
+        // 同一按键的释放可能到达下一个视图，必须在确认、取消、导航和删除之前丢弃。
+        if (key.eventType === "release")
+            return;
+        // 同步交付给本次视图的回调，不能把剩余按键排队到下一页。
+        for (const event of splitKeyboardInput(input, key))
+            onInput(event.input, event.key);
+    }, options);
+}

package/dist/ui/use-paste-aware-input.js

@@ -0,0 +1,7 @@
+import { usePaste } from "ink";
+import { useKeyboardInput } from "./use-keyboard-input.js";
+export function usePasteAwareInput({ onInput, onPaste, isInputActive = true, isPasteActive = true, }) {
+    // 原始会话按顺序交付完整粘贴；此 hook 不承担恢复或授予执行权限的职责。
+    useKeyboardInput(onInput, { isActive: isInputActive });
+    usePaste(onPaste, { isActive: isPasteActive });
+}

package/dist/user-visible-error.js

@@ -0,0 +1,19 @@
+import { renderTerminalSafeText } from "./terminal-text.js";
+const AUTHORIZATION_CREDENTIAL_PATTERN = /((?<![-\w])a[�␍␊]*u[�␍␊]*t[�␍␊]*h[�␍␊]*o[�␍␊]*r[�␍␊]*i[�␍␊]*z[�␍␊]*a[�␍␊]*t[�␍␊]*i[�␍␊]*o[�␍␊]*n["'\s:=�␍␊]+)([\s\S]*)$/i;
+const AUTHORIZATION_ASSIGNMENT_PATTERN = /((?<!\w)(?:--)?[\w-]*a[�␍␊]*u[�␍␊]*t[�␍␊]*h[�␍␊]*o[�␍␊]*r[�␍␊]*i[�␍␊]*z[�␍␊]*a[�␍␊]*t[�␍␊]*i[�␍␊]*o[�␍␊]*n["'\s�␍␊]*[:=]["'\s:=�␍␊]*)([\s\S]*)$/i;
+const API_KEY_CREDENTIAL_PATTERN = /((?<![-\w])a[�␍␊]*p[�␍␊]*i[�␍␊]*(?:[-_ ][�␍␊]*)?k[�␍␊]*e[�␍␊]*y["'\s:=�␍␊]+)([\s\S]*)$/i;
+const API_KEY_ASSIGNMENT_PATTERN = /((?<!\w)(?:--)?[\w-]*a[�␍␊]*p[�␍␊]*i[�␍␊]*(?:[-_ ][�␍␊]*)?k[�␍␊]*e[�␍␊]*y["'\s�␍␊]*[:=]["'\s:=�␍␊]*)([\s\S]*)$/i;
+const BEARER_CREDENTIAL_PATTERN = /((?<![-\w])b[�␍␊]*e[�␍␊]*a[�␍␊]*r[�␍␊]*e[�␍␊]*r[\s�␍␊]+)([\s\S]*)$/i;
+const URL_PATTERN = /(?<![-\w])h[�␍␊]*t[�␍␊]*t[�␍␊]*p[�␍␊]*s?[�␍␊]*:[�␍␊]*\/[�␍␊]*\/([\s\S]*)$/i;
+export function sanitizeUserVisibleErrorMessage(message) {
+    const terminalSafe = renderTerminalSafeText(message);
+    const singleLine = terminalSafe.replace(/\s+/g, " ").trim();
+    const redacted = singleLine
+        .replace(URL_PATTERN, "[redacted URL]")
+        .replace(AUTHORIZATION_ASSIGNMENT_PATTERN, "$1[redacted]")
+        .replace(API_KEY_ASSIGNMENT_PATTERN, "$1[redacted]")
+        .replace(AUTHORIZATION_CREDENTIAL_PATTERN, "$1[redacted]")
+        .replace(API_KEY_CREDENTIAL_PATTERN, "$1[redacted]")
+        .replace(BEARER_CREDENTIAL_PATTERN, "Bearer [redacted]");
+    return redacted.length > 220 ? `${redacted.slice(0, 217)}...` : redacted;
+}

package/dist/validation/ai-response.js

@@ -1,3 +1,4 @@
+import { hasUnsafeTerminalControlCharacters } from "../terminal-text.js";
 export class AiResponseValidationError extends Error {
     constructor(message) {
         super(message);
@@ -17,7 +18,7 @@ function parseJsonObject(rawText) {
     try {
         return JSON.parse(rawText);
     }
-    catch (_a) {
+    catch {
         throw new AiResponseValidationError("AI response is not valid JSON");
     }
 }
@@ -68,20 +69,23 @@ function validatePlaceholder(value, path) {
 }
 function validatePlaceholderReferences(command, placeholders, candidatePath) {
     const declaredNames = new Set(placeholders.map((placeholder) => placeholder.name));
+    if (declaredNames.size !== placeholders.length) {
+        throw new AiResponseValidationError(`${candidatePath}.placeholders must have unique names`);
+    }
     const usedNames = new Set();
     for (const match of command.matchAll(PLACEHOLDER_REFERENCE_PATTERN)) {
         const name = match[1];
         if (!PLACEHOLDER_NAME_PATTERN.test(name)) {
-            throw new AiResponseValidationError(`${candidatePath}.command contains invalid placeholder reference {{${name}}}`);
+            throw new AiResponseValidationError(`${candidatePath}.command contains an invalid placeholder reference`);
         }
         if (!declaredNames.has(name)) {
-            throw new AiResponseValidationError(`${candidatePath}.command references undeclared placeholder {{${name}}}`);
+            throw new AiResponseValidationError(`${candidatePath}.command references an undeclared placeholder`);
         }
         usedNames.add(name);
     }
     for (const declaredName of declaredNames) {
         if (!usedNames.has(declaredName)) {
-            throw new AiResponseValidationError(`${candidatePath}.placeholders declares unused placeholder ${declaredName}`);
+            throw new AiResponseValidationError(`${candidatePath}.placeholders contains an unused placeholder`);
         }
     }
 }
@@ -89,6 +93,9 @@ function readNonEmptyString(value, path) {
     if (typeof value !== "string") {
         throw new AiResponseValidationError(`${path} must be a string`);
     }
+    if (hasUnsafeTerminalControlCharacters(value)) {
+        throw new AiResponseValidationError(`${path} must not contain terminal control characters other than CR or LF`);
+    }
     if (value.trim() === "") {
         throw new AiResponseValidationError(`${path} must be a non-empty string`);
     }

package/dist/validation/command-tool.js

@@ -1,8 +1,7 @@
 import { accessSync, constants } from "fs";
 import { delimiter, isAbsolute, join } from "path";
+import { isShellExecutable, parseShellCommand, resolveCommandPrefix, } from "../shell/command-analysis.js";
 import { AiResponseValidationError } from "./ai-response.js";
-const ENV_ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=.*$/;
-const SHELL_WRAPPERS = new Set(["sh", "bash", "zsh", "fish", "csh", "ksh"]);
 export function checkCommandInPath(command, env = process.env) {
     const candidates = buildPathCandidates(command, env);
     for (const candidate of candidates) {
@@ -24,32 +23,41 @@ export function validateUseCommandCandidates(response, useCommand) {
         return;
     }
     response.commands.forEach((candidate, index) => {
-        if (!candidateUsesRequestedCommand(candidate.command, useCommand)) {
+        if (!candidateUsesRequestedCommand(candidate.command, useCommand, candidate.placeholders.map((placeholder) => placeholder.name))) {
             throw new AiResponseValidationError(`commands[${index}].command must use ${useCommand} as the first executable token after optional environment assignments, sudo, or env`);
         }
     });
 }
-export function candidateUsesRequestedCommand(commandText, requestedCommand) {
-    const tokens = tokenizeShellPrefix(commandText);
-    if (tokens === undefined || tokens.length === 0) {
+export function candidateUsesRequestedCommand(commandText, requestedCommand, declaredPlaceholderNames = []) {
+    const declaredNames = new Set(declaredPlaceholderNames);
+    const placeholders = [];
+    // 仅修改分析副本，等长替身让解析结果的位置仍对应原始模板。
+    const analysisText = commandText.replace(/{{([A-Za-z0-9_-]+)}}/g, (reference, name, start) => {
+        if (!declaredNames.has(name))
+            return reference;
+        placeholders.push({ start, end: start + reference.length });
+        return "x".repeat(reference.length);
+    });
+    const parsed = parseShellCommand(analysisText);
+    if (parsed.kind === "unsupported")
         return false;
-    }
-    const executable = findFirstExecutableToken(tokens);
-    if (executable === undefined) {
+    const firstCommand = parsed.commands[0];
+    if (firstCommand === undefined)
         return false;
-    }
-    if (SHELL_WRAPPERS.has(executable)) {
+    const prefix = resolveCommandPrefix(firstCommand.words);
+    if (prefix.kind === "unsupported" || isShellExecutable(prefix.executable.value))
         return false;
-    }
-    return executable === requestedCommand;
+    // 首工具本身及之前的模板可能改变前缀边界，不能靠替身证明工具身份。
+    if (placeholders.some((placeholder) => placeholder.start < prefix.executable.end))
+        return false;
+    return prefix.executable.value === requestedCommand;
 }
 function buildPathCandidates(command, env) {
-    var _a, _b;
     if (command.includes("/") || isAbsolute(command)) {
         return [command];
     }
-    const pathValue = (_a = env.PATH) !== null && _a !== void 0 ? _a : "";
-    const pathExt = process.platform === "win32" ? ((_b = env.PATHEXT) !== null && _b !== void 0 ? _b : ".EXE;.CMD;.BAT;.COM") : "";
+    const pathValue = env.PATH ?? "";
+    const pathExt = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM") : "";
     const extensions = process.platform === "win32" ? pathExt.split(";").filter(Boolean) : [""];
     const candidates = [];
     for (const directory of pathValue.split(delimiter)) {
@@ -69,117 +77,7 @@ function isExecutable(path) {
         accessSync(path, constants.X_OK);
         return true;
     }
-    catch (_a) {
+    catch {
         return false;
     }
 }
-function findFirstExecutableToken(tokens) {
-    let index = 0;
-    while (index < tokens.length && ENV_ASSIGNMENT_PATTERN.test(tokens[index])) {
-        index += 1;
-    }
-    while (index < tokens.length) {
-        const token = tokens[index];
-        if (token === "sudo") {
-            index = skipSudo(tokens, index + 1);
-            continue;
-        }
-        if (token === "env") {
-            index = skipEnv(tokens, index + 1);
-            continue;
-        }
-        if (ENV_ASSIGNMENT_PATTERN.test(token)) {
-            index += 1;
-            continue;
-        }
-        return token;
-    }
-    return undefined;
-}
-function skipSudo(tokens, startIndex) {
-    let index = startIndex;
-    while (index < tokens.length && tokens[index].startsWith("-")) {
-        index += 1;
-    }
-    return index;
-}
-function skipEnv(tokens, startIndex) {
-    let index = startIndex;
-    while (index < tokens.length) {
-        const token = tokens[index];
-        if (ENV_ASSIGNMENT_PATTERN.test(token)) {
-            index += 1;
-            continue;
-        }
-        if (token.startsWith("-")) {
-            index += 1;
-            if ((token === "-u" || token === "--unset") && index < tokens.length) {
-                index += 1;
-            }
-            continue;
-        }
-        return index;
-    }
-    return index;
-}
-function tokenizeShellPrefix(commandText) {
-    const tokens = [];
-    let current = "";
-    let quote;
-    for (let index = 0; index < commandText.length; index += 1) {
-        const character = commandText[index];
-        if (quote !== undefined) {
-            if (character === quote) {
-                quote = undefined;
-            }
-            else if (character === "\\" && quote === '"' && index + 1 < commandText.length) {
-                index += 1;
-                current += commandText[index];
-            }
-            else {
-                current += character;
-            }
-            continue;
-        }
-        if (character === '"' || character === "'") {
-            quote = character;
-            continue;
-        }
-        if (character === "\\") {
-            if (index + 1 >= commandText.length) {
-                return undefined;
-            }
-            index += 1;
-            current += commandText[index];
-            continue;
-        }
-        if (/\s/.test(character)) {
-            if (current !== "") {
-                tokens.push(current);
-                current = "";
-            }
-            continue;
-        }
-        if (isShellControlOperator(character)) {
-            if (current !== "") {
-                tokens.push(current);
-            }
-            break;
-        }
-        current += character;
-    }
-    if (quote !== undefined) {
-        return undefined;
-    }
-    if (current !== "") {
-        tokens.push(current);
-    }
-    return tokens;
-}
-function isShellControlOperator(character) {
-    return (character === "|" ||
-        character === ";" ||
-        character === "&" ||
-        character === "(" ||
-        character === ")");
-}

package/dist/validation/generated-commands.js

@@ -1,19 +1,8 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import { parseAndValidateAiResponse } from "./ai-response.js";
 import { validateUseCommandCandidates } from "./command-tool.js";
-export function generateValidatedCommandCandidates(provider, request) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const result = yield provider.generateCommands(request);
-        const response = parseAndValidateAiResponse(result.rawText);
-        validateUseCommandCandidates(response, request.useCommand);
-        return response.commands;
-    });
+export async function generateValidatedCommandCandidates(provider, request, signal) {
+    const result = await provider.generateCommands(request, signal);
+    const response = parseAndValidateAiResponse(result.rawText);
+    validateUseCommandCandidates(response, request.useCommand);
+    return response.commands;
 }

package/dist/version.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function readPackageVersion() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        let content;
+        try {
+            content = readFileSync(join(directory, "package.json"), "utf8");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+                throw new Error("failed to read package version", { cause: error });
+            }
+            const parentDirectory = dirname(directory);
+            if (parentDirectory === directory) {
+                throw new Error("package.json not found", { cause: error });
+            }
+            directory = parentDirectory;
+            continue;
+        }
+        let metadata;
+        try {
+            metadata = JSON.parse(content);
+        }
+        catch {
+            throw new Error("package.json is not valid JSON");
+        }
+        if (typeof metadata !== "object" ||
+            metadata === null ||
+            !("version" in metadata) ||
+            typeof metadata.version !== "string" ||
+            metadata.version.trim() === "") {
+            throw new Error("package.json must contain a version string");
+        }
+        return metadata.version;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unscientificjszhai/howto",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Use AI to quickly find commands within the terminal.",
   "license": "MIT",
@@ -21,7 +21,9 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "npm run clean:dist && tsc",
+    "clean:dist": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "clean:dist-test": "node -e \"require('node:fs').rmSync('dist-test', { recursive: true, force: true })\"",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
     "lint": "eslint .",
@@ -29,25 +31,26 @@
     "lint:staged": "lint-staged",
     "prepare": "husky",
     "test": "npm run test:unit",
-    "test:unit": "tsc -p tsconfig.test.json && node --test dist-test/tests/unit/*.test.js dist-test/tests/unit/**/*.test.js"
+    "test:unit": "npm run clean:dist-test && tsc -p tsconfig.test.json && node --test dist-test/tests/unit/*.test.js dist-test/tests/unit/**/*.test.js"
   },
   "dependencies": {
-    "@google/genai": "^2.6.0",
-    "ink": "^7.0.4",
-    "openai": "^6.39.0",
-    "react": "^19.2.6"
+    "@google/genai": "^2.18.0",
+    "ink": "^7.1.1",
+    "openai": "^7.5.0",
+    "react": "^19.2.8",
+    "string-width": "^8.2.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "eslint": "^10.4.0",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "eslint": "^10.9.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.4.0",
-    "prettier": "^3.8.3",
-    "typescript": "^5.5.3",
-    "typescript-eslint": "^8.59.4"
+    "lint-staged": "^17.3.0",
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0"
   },
   "lint-staged": {
     "*.{ts,tsx}": [