@unscientificjszhai/howto 1.0.0-alpha.3 → 1.0.0

package/README.CN.md

@@ -2,7 +2,10 @@
 
 _在终端中用 AI 快速找到可执行命令。_
 
-![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)
+[![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)](https://www.npmjs.com/package/@unscientificjszhai/howto)
+[![GitHub Actions Test Status](https://github.com/UnscientificJsZhai/HowTo/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/UnscientificJsZhai/HowTo/actions)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![License](https://img.shields.io/github/license/UnscientificJsZhai/HowTo)](LICENSE)
 
 [English](README.md) | 简体中文
 
@@ -148,7 +151,7 @@ howto --print "show current branch"
 - 响应包含一到三个候选项；
 - 所有占位符使用 `{{name}}` 语法，并且声明与引用一致；
 - `use <command>` 候选项在保守处理前缀后，明确以指定工具开头；
-- 明显危险的命令需要输入 `EXECUTE` 才能继续执行。
+- 明显危险的命令需要输入 `EXECUTE` 才能继续执行；大小写不敏感。
 
 危险命令检测当前覆盖递归破坏性 `rm`、磁盘和文件系统操作、大范围递归权限变更、下载脚本后直接交给 shell 执行、高影响包管理器操作以及服务变更等高风险模式。
 

package/README.md

@@ -2,7 +2,10 @@
 
 _Use AI to quickly find commands within the terminal._
 
-![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)
+[![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)](https://www.npmjs.com/package/@unscientificjszhai/howto)
+[![GitHub Actions Test Status](https://github.com/UnscientificJsZhai/HowTo/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/UnscientificJsZhai/HowTo/actions)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![License](https://img.shields.io/github/license/UnscientificJsZhai/HowTo)](LICENSE)
 
 English | [简体中文](README.CN.md)
 
@@ -148,7 +151,7 @@ howto --print "show current branch"
 - the response contains between one and three candidates;
 - all placeholders use `{{name}}` syntax and are declared consistently;
 - `use <command>` candidates clearly start with the requested tool after conservative prefix handling;
-- obvious dangerous patterns require typing `EXECUTE` before they can run.
+- obvious dangerous patterns require typing `EXECUTE` before they can run; matching is case-insensitive.
 
 Dangerous-command detection currently covers high-risk patterns such as recursive destructive `rm`, disk and filesystem operations, broad recursive permission changes, downloaded scripts piped into a shell, high-impact package manager operations, and service changes.
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-Party Notices
+
+This project depends on third-party packages that are installed by npm as separate packages.
+Each dependency is distributed under its own license.
+
+## Runtime Dependencies
+
+| Package         | Version  | License    |
+| --------------- | -------- | ---------- |
+| `@google/genai` | `2.6.0`  | Apache-2.0 |
+| `ink`           | `7.0.4`  | MIT        |
+| `openai`        | `6.39.0` | Apache-2.0 |
+| `react`         | `19.2.6` | MIT        |
+
+The package versions above reflect the installed dependency set at the time this notice
+was prepared. See each package's published npm artifact for its complete license text and
+any package-specific notices.

package/dist/ai/command-schema.js

@@ -5,6 +5,8 @@ export const COMMAND_GENERATION_SCHEMA = {
     properties: {
         commands: {
             type: "array",
+            minItems: 1,
+            maxItems: 3,
             items: {
                 type: "object",
                 additionalProperties: false,

package/dist/index.js

@@ -17,8 +17,8 @@ import { ConfigError, hasExplicitAiProvider, loadConfig } from "./config.js";
 import { readUserConfigFile } from "./config-file.js";
 import { createCommandProvider } from "./ai/index.js";
 import { buildCommandGenerationPrompt, createProviderPromptRequest } from "./prompt.js";
-import { parseAndValidateAiResponse } from "./validation/ai-response.js";
 import { checkCommandInPath } from "./validation/command-tool.js";
+import { generateValidatedCommandCandidates } from "./validation/generated-commands.js";
 import { ensureInteractiveTty } from "./ui/tty.js";
 import { executeCommand } from "./execute.js";
 import { toAppError } from "./errors.js";
@@ -71,10 +71,9 @@ function run(argv) {
             const { systemPrompt, userPrompt } = buildCommandGenerationPrompt(promptRequest);
             const provider = createCommandProvider(config);
             if (parsedCli.options.print) {
-                const aiResult = yield provider.generateCommands(Object.assign(Object.assign({}, promptRequest), { systemPrompt,
+                const candidates = yield generateValidatedCommandCandidates(provider, Object.assign(Object.assign({}, promptRequest), { systemPrompt,
                     userPrompt }));
-                const aiResponse = parseAndValidateAiResponse(aiResult.rawText);
-                aiResponse.commands.forEach((candidate) => {
+                candidates.forEach((candidate) => {
                     console.log(candidate.command);
                 });
                 return { exitCode: 0 };
@@ -84,7 +83,7 @@ function run(argv) {
             }
             let finalCommand;
             let appError;
-            const { waitUntilExit, unmount, clear } = render(React.createElement(App, { provider: provider, request: Object.assign(Object.assign({}, promptRequest), { systemPrompt, userPrompt }), useCommand: parsedCli.useCommand, onSuccess: (command) => {
+            const { waitUntilExit, unmount, clear } = render(React.createElement(App, { provider: provider, request: Object.assign(Object.assign({}, promptRequest), { systemPrompt, userPrompt }), onSuccess: (command) => {
                     finalCommand = command;
                     clear();
                     unmount();

package/dist/prompt.js

@@ -19,6 +19,7 @@ The commands array must contain 1 to 3 items. Do not return more than 3 candidat
 Detect the primary natural language of the user's question. Return title, description, and placeholders[].description in that language. Keep placeholder name values English-compatible ASCII using only letters, numbers, underscores, or hyphens.
 Use placeholders in commands only as {{name}}, and declare every placeholder in the placeholders array. User may provide argument. If the user's intent is clear, try to use the provided arguments as parameters in the generated commands instead of placeholders. If the intent is unclear, do not fill them.`;
 export const STRUCTURED_OUTPUT_CONTRACT = `Return only the JSON object requested by the response schema. Do not include a natural-language body, markdown, or code fences.
+The commands array must contain 1 to 3 items. Do not return more than 3 candidate commands.
 Detect the primary natural language of the user's question. Return title, description, and placeholders[].description in that language. Keep placeholder name values English-compatible ASCII using only letters, numbers, underscores, or hyphens.
 Use placeholders in commands only as {{name}}, and declare every placeholder in the placeholders array. User may provide argument. If the user's intent is clear, try to use the provided arguments as parameters in the generated commands instead of placeholders. If the intent is unclear, do not fill them.`;
 export const SAFETY_CONSTRAINTS = `Prefer read-only, reversible, and low-risk commands.

package/dist/ui/App.js

@@ -4,12 +4,11 @@ import { LoadingView } from "./LoadingView.js";
 import { SelectCommandView } from "./SelectCommandView.js";
 import { ResolvePlaceholdersView } from "./ResolvePlaceholdersView.js";
 import { ConfirmView } from "./ConfirmView.js";
-import { parseAndValidateAiResponse } from "../validation/ai-response.js";
-import { validateUseCommandCandidates } from "../validation/command-tool.js";
+import { generateValidatedCommandCandidates } from "../validation/generated-commands.js";
 import { detectDangerousCommand } from "../safety/dangerous-command.js";
-import { replaceCommandPlaceholders } from "./placeholder-logic.js";
+import { resolveCandidatePlaceholders } from "./placeholder-logic.js";
 import { InteractionCancelledError } from "./tty.js";
-export const App = ({ provider, request, useCommand, onSuccess, onError }) => {
+export const App = ({ provider, request, onSuccess, onError }) => {
     const { rows } = useWindowSize();
     const [status, setStatus] = useState("loading");
     const [candidates, setCandidates] = useState([]);
@@ -20,12 +19,9 @@ export const App = ({ provider, request, useCommand, onSuccess, onError }) => {
     const [errorMessage, setErrorMessage] = useState("");
     useEffect(() => {
         if (status === "loading") {
-            provider
-                .generateCommands(request)
-                .then((result) => {
-                const aiResponse = parseAndValidateAiResponse(result.rawText);
-                validateUseCommandCandidates(aiResponse, useCommand);
-                setCandidates(aiResponse.commands);
+            generateValidatedCommandCandidates(provider, request)
+                .then((generatedCandidates) => {
+                setCandidates(generatedCandidates);
                 setStatus("selecting");
             })
                 .catch((error) => {
@@ -35,7 +31,7 @@ export const App = ({ provider, request, useCommand, onSuccess, onError }) => {
                 onError(appError);
             });
         }
-    }, [status, provider, request, useCommand, onError]);
+    }, [status, provider, request, onError]);
     const handleSelect = (candidate) => {
         setSelectedCandidate(candidate);
         setResolvedValues(new Map());
@@ -43,19 +39,27 @@ export const App = ({ provider, request, useCommand, onSuccess, onError }) => {
             setStatus("resolving");
         }
         else {
-            const command = candidate.command;
-            setFinalCommand(command);
-            setDanger(detectDangerousCommand(command));
-            setStatus("confirming");
+            try {
+                const resolved = resolveCandidatePlaceholders(candidate, new Map());
+                setFinalCommand(resolved.command);
+                setResolvedValues(resolved.values);
+                setDanger(detectDangerousCommand(resolved.command));
+                setStatus("confirming");
+            }
+            catch (error) {
+                const appError = normalizeError(error);
+                setErrorMessage(appError.message);
+                setStatus("error");
+                onError(appError);
+            }
         }
     };
-    const handleResolve = (values) => {
+    const handleResolve = (resolved) => {
         if (!selectedCandidate)
             return;
-        setResolvedValues(values);
-        const command = replaceCommandPlaceholders(selectedCandidate.command, values);
-        setFinalCommand(command);
-        setDanger(detectDangerousCommand(command));
+        setResolvedValues(resolved.values);
+        setFinalCommand(resolved.command);
+        setDanger(detectDangerousCommand(resolved.command));
         setStatus("confirming");
     };
     useEffect(() => {
@@ -76,8 +80,8 @@ export const App = ({ provider, request, useCommand, onSuccess, onError }) => {
     return (React.createElement(Box, { flexDirection: "column", maxHeight: maxFrameRows, 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, placeholders: selectedCandidate.placeholders, onResolve: handleResolve, onBack: handleBackToSelection, onCancel: handleCancel })),
-        (status === "confirming" || status === "done") && selectedCandidate && (React.createElement(ConfirmView, { candidate: selectedCandidate, resolvedValues: resolvedValues, danger: danger, onConfirm: handleConfirm, onCancel: handleCancel, isDone: status === "done" })),
+        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 === "error" && React.createElement(Text, { color: "red" },
             "Error: ",
             errorMessage)));

package/dist/ui/ConfirmView.js

@@ -1,7 +1,10 @@
 import React, { useState } from "react";
 import { Box, Text, useInput } from "ink";
 import { SelectedCommandDisplay } from "./SelectedCommandDisplay.js";
-export const ConfirmView = ({ candidate, resolvedValues, danger, onConfirm, onCancel, isDone = false, }) => {
+export function isDangerConfirmationInput(input) {
+    return input.toUpperCase() === "EXECUTE";
+}
+export const ConfirmView = ({ candidate, command, resolvedValues, danger, onConfirm, onCancel, isDone = false, }) => {
     const [buffer, setBuffer] = useState("");
     useInput((input, key) => {
         if (isDone)
@@ -16,7 +19,7 @@ export const ConfirmView = ({ candidate, resolvedValues, danger, onConfirm, onCa
         }
         if (danger) {
             if (key.return) {
-                if (buffer === "EXECUTE") {
+                if (isDangerConfirmationInput(buffer)) {
                     onConfirm();
                 }
                 else {
@@ -48,7 +51,10 @@ export const ConfirmView = ({ candidate, resolvedValues, danger, onConfirm, onCa
                 "Risk: ",
                 danger.reason),
             React.createElement(Box, { marginTop: 1, flexDirection: "column" },
-                React.createElement(SelectedCommandDisplay, { candidate: candidate, resolvedValues: resolvedValues })),
+                React.createElement(SelectedCommandDisplay, { candidate: candidate, resolvedValues: resolvedValues }),
+                React.createElement(Text, null,
+                    "Final command: ",
+                    React.createElement(Text, { color: "yellow" }, command))),
             !isDone && (React.createElement(React.Fragment, null,
                 React.createElement(Box, { marginTop: 1 },
                     React.createElement(Text, null,
@@ -62,6 +68,9 @@ export const ConfirmView = ({ candidate, resolvedValues, danger, onConfirm, onCa
     }
     return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
         React.createElement(SelectedCommandDisplay, { candidate: candidate, resolvedValues: resolvedValues }),
+        React.createElement(Text, null,
+            "Final command: ",
+            React.createElement(Text, { color: "yellow" }, command)),
         !isDone && (React.createElement(Box, { marginTop: 1 },
             React.createElement(Text, null,
                 "Press ",

package/dist/ui/ResolvePlaceholdersView.js

@@ -1,80 +1,59 @@
-import React, { useState, useMemo } from "react";
+import React, { useState } from "react";
 import { Box, Text, useInput } from "ink";
 import { SelectedCommandDisplay } from "./SelectedCommandDisplay.js";
-export const ResolvePlaceholdersView = ({ candidate, placeholders, onResolve, onBack, onCancel, }) => {
-    const [activeIndex, setActiveIndex] = useState(0);
-    const [values, setValues] = useState(placeholders.map(() => ""));
-    const [buffer, setBuffer] = useState("");
-    const resolvedValuesMap = useMemo(() => {
-        const map = new Map();
-        placeholders.forEach((p, i) => {
-            if (i < activeIndex) {
-                map.set(p.name, values[i]);
-            }
-        });
-        return map;
-    }, [placeholders, activeIndex, values]);
-    const currentBuffer = useMemo(() => ({
-        name: placeholders[activeIndex].name,
-        value: buffer,
-    }), [placeholders, activeIndex, buffer]);
+import { applyPlaceholderResolutionInput, createPlaceholderResolution, getPlaceholderResolutionView, } from "./placeholder-logic.js";
+export const ResolvePlaceholdersView = ({ candidate, onResolve, onBack, onCancel, }) => {
+    const [resolutionState, setResolutionState] = useState(() => createPlaceholderResolution(candidate));
+    const { currentPlaceholder, currentBuffer, resolvedValues } = getPlaceholderResolutionView(resolutionState);
     useInput((input, key) => {
         if (key.ctrl && input === "c") {
             onCancel();
             return;
         }
-        if (key.escape) {
-            if (activeIndex === 0) {
-                onBack();
-            }
-            else {
-                const newValues = [...values];
-                newValues[activeIndex] = "";
-                setValues(newValues);
-                setActiveIndex((prev) => prev - 1);
-                setBuffer(values[activeIndex - 1]);
-            }
-            return;
-        }
-        if (key.return) {
-            const newValues = [...values];
-            newValues[activeIndex] = buffer;
-            setValues(newValues);
-            if (activeIndex === placeholders.length - 1) {
-                const resultMap = new Map();
-                placeholders.forEach((p, i) => {
-                    resultMap.set(p.name, newValues[i]);
-                });
-                onResolve(resultMap);
-            }
-            else {
-                setActiveIndex((prev) => prev + 1);
-                setBuffer(values[activeIndex + 1]);
-            }
+        const resolutionInput = toPlaceholderResolutionInput(input, key);
+        if (!resolutionInput) {
             return;
         }
-        if (key.backspace || key.delete) {
-            setBuffer((prev) => prev.slice(0, -1));
-            return;
-        }
-        if (input && !Object.values(key).some(Boolean)) {
-            setBuffer((prev) => prev + input);
+        const transition = applyPlaceholderResolutionInput(resolutionState, resolutionInput);
+        switch (transition.type) {
+            case "editing":
+                setResolutionState(transition.state);
+                return;
+            case "back-to-selection":
+                onBack();
+                return;
+            case "complete":
+                onResolve(transition.resolved);
+                return;
         }
-        // Handle space and other printable characters that might be in key but not in input if needed
-        // However ink's useInput input is usually the string.
     });
     return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
-        React.createElement(SelectedCommandDisplay, { candidate: candidate, resolvedValues: resolvedValuesMap, currentBuffer: currentBuffer }),
+        React.createElement(SelectedCommandDisplay, { candidate: candidate, resolvedValues: resolvedValues, currentBuffer: currentBuffer }),
         React.createElement(Text, { color: "green" }, "? Fill command placeholders"),
         React.createElement(Box, { flexDirection: "column", marginTop: 1 },
             React.createElement(Box, { flexDirection: "column", marginBottom: 1 },
                 React.createElement(Text, null,
-                    placeholders[activeIndex].name,
+                    currentPlaceholder.name,
                     ": ",
-                    placeholders[activeIndex].description),
+                    currentPlaceholder.description),
                 React.createElement(Box, null,
                     React.createElement(Text, { color: "cyan" }, "> "),
-                    React.createElement(Text, null, buffer),
+                    React.createElement(Text, null, currentBuffer.value),
                     React.createElement(Text, { backgroundColor: "white" }, " ")))),
         React.createElement(Text, { dimColor: true }, "Press Enter for next value, Esc to go back, Ctrl+C to cancel.")));
 };
+function toPlaceholderResolutionInput(input, key) {
+    if (key.escape) {
+        return { type: "escape" };
+    }
+    if (key.return) {
+        return { type: "commit" };
+    }
+    if (key.backspace || key.delete) {
+        return { type: "delete" };
+    }
+    if (input && !Object.values(key).some(Boolean)) {
+        return { type: "append", value: input };
+    }
+    return undefined;
+}

package/dist/ui/placeholder-logic.js

@@ -5,6 +5,64 @@ export class PlaceholderResolutionError extends Error {
         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: Object.assign(Object.assign({}, state), { buffer: state.buffer + input.value }),
+            };
+        case "delete":
+            return {
+                type: "editing",
+                state: Object.assign(Object.assign({}, state), { buffer: state.buffer.slice(0, -1) }),
+            };
+        case "escape":
+            return applyEscape(state);
+        case "commit":
+            return applyCommit(state);
+    }
+}
+export function resolveCandidatePlaceholders(candidate, values) {
+    const command = replaceCommandPlaceholders(candidate.command, values);
+    assertNoUnresolvedPlaceholders(command);
+    return {
+        candidate,
+        values,
+        command,
+    };
+}
 export function replaceCommandPlaceholders(command, values) {
     let resolvedCommand = command;
     for (const [name, value] of values) {
@@ -17,3 +75,34 @@ export function assertNoUnresolvedPlaceholders(command) {
         throw new PlaceholderResolutionError("final command contains unresolved placeholders");
     }
 }
+function applyEscape(state) {
+    if (state.activeIndex === 0) {
+        return { type: "back-to-selection" };
+    }
+    const previousIndex = state.activeIndex - 1;
+    const values = [...state.values];
+    values[state.activeIndex] = "";
+    return {
+        type: "editing",
+        state: Object.assign(Object.assign({}, state), { activeIndex: previousIndex, values, buffer: values[previousIndex] }),
+    };
+}
+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: Object.assign(Object.assign({}, state), { activeIndex: nextIndex, values, buffer: values[nextIndex] }),
+    };
+}

package/dist/validation/generated-commands.js

@@ -0,0 +1,19 @@
+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;
+    });
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@unscientificjszhai/howto",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0",
   "type": "module",
   "description": "Use AI to quickly find commands within the terminal.",
+  "license": "MIT",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -16,7 +17,8 @@
     "howto": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "build": "tsc",