@unscientificjszhai/howto 1.0.0-alpha.2 → 1.0.0-alpha.3

package/README.CN.md

@@ -0,0 +1,203 @@
+# howto
+
+_在终端中用 AI 快速找到可执行命令。_
+
+![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)
+
+[English](README.md) | 简体中文
+
+[功能](#功能) • [安装](#安装) • [使用](#使用) • [配置](#配置) • [开发](#开发) • [故障排查](#故障排查)
+
+`howto` 是一个 TypeScript CLI工具，使用自然语言向它提问，它会给你候选命令供你选择。它不会直接运行 AI 输出：你需要在终端中选择候选命令，填写占位符（如有），检查最终命令，然后确认执行。
+
+> [!IMPORTANT]
+> `howto` 是命令生成助手，不是沙箱。执行前请检查每一条命令，尤其是会修改文件、安装包、变更权限或使用提权操作的命令。
+
+## 功能
+
+- **自然语言生成命令** - 描述任务后获得简洁的 shell 命令候选项。
+- **指定工具模式** - 使用 `howto use <command>` 要求候选项围绕某个 CLI 工具生成。
+- **交互式确认流程** - 选择候选项、填写占位符，并在执行前确认最终命令。
+- **非交互打印模式** - 使用 `--print` 输出候选命令，不进入 TTY 交互，也不执行命令。
+- **支持 OpenAI 和 Gemini** - 可通过 CLI 参数、环境变量或 `~/.howto/config.json` 配置 provider。
+- **本地优先校验** - 本地校验 AI JSON 输出、占位符引用、`use <command>` 候选项以及明显危险命令。
+
+## 安装
+
+全局安装 CLI 包：
+
+```bash
+npm install -g @unscientificjszhai/howto
+```
+
+也可以从克隆的仓库中运行：
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+之后即可使用 `howto` 命令。
+
+## 快速开始
+
+初始化 AI provider 配置：
+
+```bash
+howto --init
+```
+
+初始化程序会把用户级配置写入 `~/.howto/config.json`。
+
+> [!NOTE]
+> OpenAI API key 可以为空，以支持本地 OpenAI 兼容服务。Gemini 必须提供非空 API key。
+
+询问一个命令：
+
+```bash
+howto 找到最近7天修改的文件 .
+```
+
+限制候选项必须使用某个工具：
+
+```bash
+howto use git 看看上周的提交
+```
+
+不进入交互 UI，只打印候选命令：
+
+```bash
+howto --print 列出最大的文件 /var/log
+```
+
+## 使用
+
+```text
+howto [options] [use <command>] <question> [<argument>...]
+howto --init
+```
+
+示例：
+
+```bash
+howto 找到当前目录的package.json
+howto use find 寻找特定文件名的文件 package.json
+howto 解释这个命令 -- --force
+howto --ai-provider openai --print 列出监听的端口
+```
+
+参数：
+
+- `--init` - 启动交互式 provider 配置，并保存 `~/.howto/config.json`。
+- `--print` - 打印已校验的命令候选项并退出，不执行命令。
+- `--ai-provider <openai|gemini>` - 选择 AI provider。
+- `--gemini-api-key <key>` - 提供 Gemini API key。
+- `--gemini-model <model>` - 覆盖 Gemini 模型。
+- `--openai-api-url <url>` - 使用自定义 OpenAI 兼容 base URL。
+- `--openai-api-key <key>` - 提供 OpenAI API key。
+- `--openai-model <model>` - 覆盖 OpenAI 模型。
+- `--structured-output <true|false>` - 启用 SDK 级 schema 结构化输出；默认 `true`。
+
+### 参数解析
+
+`question` 是一个 shell 参数。包含空格时需要加引号：
+
+```bash
+howto "find recently changed files" /tmp
+```
+
+`question` 后面的内容会作为 `argument[]` 传给 AI。如果参数以 `--` 开头，请使用 `--` 结束 option 解析：
+
+```bash
+howto "explain this flag" -- --force
+```
+
+## 配置
+
+配置按以下优先级解析：
+
+1. CLI 参数
+2. 环境变量
+3. `~/.howto/config.json`
+4. 内置默认值
+
+对每个配置项，优先级中第一个已配置的来源生效：
+
+- `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` 或 `gemini`；无默认值。
+- `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key；Gemini 必填。
+- `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini 模型；默认 `gemini-3.1-flash-lite`。
+- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI 兼容 base URL；默认使用 OpenAI SDK 默认值。
+- `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key；默认为空字符串以支持本地服务。
+- `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI 模型；默认 `gpt-5.4-mini`。
+- `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - 使用 provider schema 结构化输出；默认 `true`。
+
+示例：
+
+```bash
+HOWTO_AI_PROVIDER=openai \
+HOWTO_OPENAI_MODEL=gpt-5.4-mini \
+howto --print "show current branch"
+```
+
+## 安全模型
+
+`howto` 将 AI 输出视为不可信数据。在进入执行前，CLI 会检查：
+
+- AI 响应是符合命令 schema 的有效 JSON；
+- 响应包含一到三个候选项；
+- 所有占位符使用 `{{name}}` 语法，并且声明与引用一致；
+- `use <command>` 候选项在保守处理前缀后，明确以指定工具开头；
+- 明显危险的命令需要输入 `EXECUTE` 才能继续执行。
+
+危险命令检测当前覆盖递归破坏性 `rm`、磁盘和文件系统操作、大范围递归权限变更、下载脚本后直接交给 shell 执行、高影响包管理器操作以及服务变更等高风险模式。
+
+> [!WARNING]
+> 未被标记为危险并不表示命令一定安全。本地检查只会对已知高风险模式增加确认步骤，并不能证明命令安全。
+
+## 开发
+
+本项目使用 TypeScript、React、Ink、OpenAI SDK、Gemini GenAI SDK 和 Node 内置测试运行器构建。
+
+```bash
+npm install
+npm run build
+npm test
+npm run lint
+npm run format:check
+```
+
+常用路径：
+
+- `src/index.tsx` - CLI 编排和执行流程。
+- `src/cli.ts` - 参数解析。
+- `src/config.ts` - 配置合并和 provider 校验。
+- `src/prompt.ts` - prompt 和 AI 输出契约。
+- `src/validation/` - AI 响应和命令工具校验。
+- `src/safety/` - 危险命令规则。
+- `src/ui/` - 基于 Ink 的终端 UI。
+- `tests/unit/` - CLI、配置、校验、执行、UI 和安全逻辑的单元测试。
+
+## 故障排查
+
+### AI provider 未配置
+
+运行：
+
+```bash
+howto --init
+```
+
+`--print` 会有意跳过初始化流程。请先配置 provider，或传入对应 CLI 参数/环境变量。
+
+### 非交互终端错误
+
+默认模式需要交互式 TTY 来选择和确认命令。在脚本或 CI 中请使用 `--print`：
+
+```bash
+howto --print "show disk usage"
+```
+
+### Gemini key 必填
+
+Gemini 不能在没有 API key 的情况下运行。请设置 `HOWTO_GEMINI_API_KEY`，传入 `--gemini-api-key`，或重新运行 `howto --init`。

package/README.md

@@ -0,0 +1,203 @@
+# howto
+
+_Use AI to quickly find commands within the terminal._
+
+![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)
+
+English | [简体中文](README.CN.md)
+
+[Features](#features) • [Install](#install) • [Usage](#usage) • [Configuration](#configuration) • [Development](#development) • [Troubleshooting](#troubleshooting)
+
+`howto` is a TypeScript CLI that turns a natural-language question into up to three executable command candidates. It never runs AI output directly: you choose a command in the terminal, fill any placeholders, review the final command, and confirm before execution.
+
+> [!IMPORTANT]
+> `howto` is an assistant for generating shell commands, not a sandbox. Review every command before running it, especially commands that modify files, install packages, change permissions, or use elevated privileges.
+
+## Features
+
+- **Natural language to commands** - ask for a task and get concise shell command candidates.
+- **Tool-constrained mode** - use `howto use <command>` to require candidates around a specific CLI tool.
+- **Interactive review flow** - select a candidate, resolve placeholders, and confirm the final command before execution.
+- **Non-interactive print mode** - use `--print` to output candidates without TTY interaction or command execution.
+- **OpenAI and Gemini support** - configure either provider from CLI flags, environment variables, or `~/.howto/config.json`.
+- **Local validation first** - AI JSON output, placeholder references, `use <command>` candidates, and obvious dangerous commands are checked locally.
+
+## Install
+
+Install the CLI package globally:
+
+```bash
+npm install -g @unscientificjszhai/howto
+```
+
+Or run it from a cloned repository:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+You can then call the executable as `howto`.
+
+## Getting Started
+
+Initialize your AI provider configuration:
+
+```bash
+howto --init
+```
+
+The initializer writes a user-level config file at `~/.howto/config.json`.
+
+> [!NOTE]
+> OpenAI API keys may be empty for local OpenAI-compatible services. Gemini requires a non-empty API key.
+
+Ask for a command:
+
+```bash
+howto "find files modified in the last 7 days" .
+```
+
+Limit candidates to a specific tool:
+
+```bash
+howto use git "show commits from last week"
+```
+
+Print command candidates without entering the interactive UI:
+
+```bash
+howto --print "list the largest files" /var/log
+```
+
+## Usage
+
+```text
+howto [options] [use <command>] <question> [<argument>...]
+howto --init
+```
+
+Examples:
+
+```bash
+howto "find package.json under the current directory"
+howto use find "find a filename" package.json
+howto "explain this option" -- --force
+howto --ai-provider openai --print "show listening ports"
+```
+
+Options:
+
+- `--init` - start interactive provider setup and save `~/.howto/config.json`.
+- `--print` - print validated command candidates and exit without executing.
+- `--ai-provider <openai|gemini>` - select the AI provider.
+- `--gemini-api-key <key>` - provide a Gemini API key.
+- `--gemini-model <model>` - override the Gemini model.
+- `--openai-api-url <url>` - use a custom OpenAI-compatible base URL.
+- `--openai-api-key <key>` - provide an OpenAI API key.
+- `--openai-model <model>` - override the OpenAI model.
+- `--structured-output <true|false>` - enable SDK-level schema structured output; default `true`.
+
+### Argument Parsing
+
+`question` is one shell argument. Quote it when it contains spaces:
+
+```bash
+howto "find recently changed files" /tmp
+```
+
+Everything after the question is passed to the AI as `argument[]`. Use `--` when an argument starts with `--`:
+
+```bash
+howto "explain this flag" -- --force
+```
+
+## Configuration
+
+Configuration is resolved in this order:
+
+1. CLI options
+2. Environment variables
+3. `~/.howto/config.json`
+4. Built-in defaults
+
+For each setting, the first configured source in that order wins:
+
+- `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` or `gemini`; no default.
+- `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key; required for Gemini.
+- `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini model; default `gemini-3.1-flash-lite`.
+- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI-compatible base URL; defaults to the OpenAI SDK default.
+- `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key; defaults to an empty string for local services.
+- `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI model; default `gpt-5.4-mini`.
+- `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - use provider schema structured output; default `true`.
+
+Example:
+
+```bash
+HOWTO_AI_PROVIDER=openai \
+HOWTO_OPENAI_MODEL=gpt-5.4-mini \
+howto --print "show current branch"
+```
+
+## Safety Model
+
+`howto` treats AI output as untrusted data. Before anything reaches execution, the CLI checks that:
+
+- the AI response is valid JSON matching the required command schema;
+- 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.
+
+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.
+
+> [!WARNING]
+> A command not flagged as dangerous is not guaranteed to be safe. The local checks add friction for known high-risk patterns; they do not prove command safety.
+
+## Development
+
+This project is built with TypeScript, React, Ink, OpenAI SDK, Gemini GenAI SDK, and Node's built-in test runner.
+
+```bash
+npm install
+npm run build
+npm test
+npm run lint
+npm run format:check
+```
+
+Useful paths:
+
+- `src/index.tsx` - CLI orchestration and execution flow.
+- `src/cli.ts` - argument parsing.
+- `src/config.ts` - config merging and provider validation.
+- `src/prompt.ts` - prompt and AI output contract.
+- `src/validation/` - AI response and command-tool validation.
+- `src/safety/` - dangerous command rules.
+- `src/ui/` - Ink-based terminal UI.
+- `tests/unit/` - unit tests for CLI, config, validation, execution, UI, and safety logic.
+
+## Troubleshooting
+
+### AI provider is not configured
+
+Run:
+
+```bash
+howto --init
+```
+
+For `--print`, initialization is intentionally skipped. Configure the provider first or pass the relevant CLI flags/environment variables.
+
+### Non-interactive terminal error
+
+The default mode needs an interactive TTY for selection and confirmation. Use `--print` in scripts or CI:
+
+```bash
+howto --print "show disk usage"
+```
+
+### Gemini key is required
+
+Gemini cannot run without an API key. Set `HOWTO_GEMINI_API_KEY`, pass `--gemini-api-key`, or rerun `howto --init`.

package/dist/ai/command-schema.js

@@ -0,0 +1,42 @@
+export const COMMAND_GENERATION_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["commands"],
+    properties: {
+        commands: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["title", "command", "description", "placeholders"],
+                properties: {
+                    title: {
+                        type: "string",
+                    },
+                    command: {
+                        type: "string",
+                    },
+                    description: {
+                        type: "string",
+                    },
+                    placeholders: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            additionalProperties: false,
+                            required: ["name", "description"],
+                            properties: {
+                                name: {
+                                    type: "string",
+                                },
+                                description: {
+                                    type: "string",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/ai/gemini.js

@@ -8,6 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { GoogleGenAI } from "@google/genai";
+import { COMMAND_GENERATION_SCHEMA } from "./command-schema.js";
 import { AiProviderError } from "./errors.js";
 export class GeminiCommandProvider {
     constructor(config) {
@@ -17,14 +18,7 @@ export class GeminiCommandProvider {
     generateCommands(request) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                const response = yield this.client.models.generateContent({
-                    model: this.model,
-                    contents: request.userPrompt,
-                    config: {
-                        systemInstruction: request.systemPrompt,
-                        responseMimeType: "application/json",
-                    },
-                });
+                const response = yield this.client.models.generateContent(buildGeminiGenerateContentRequest(this.model, request));
                 const rawText = response.text;
                 if (rawText === undefined || rawText.trim() === "") {
                     throw new Error("provider returned an empty response");
@@ -37,3 +31,10 @@ export class GeminiCommandProvider {
         });
     }
 }
+export function buildGeminiGenerateContentRequest(model, request) {
+    return {
+        model,
+        contents: request.userPrompt,
+        config: Object.assign({ systemInstruction: request.systemPrompt, responseMimeType: "application/json" }, (request.structuredOutput ? { responseJsonSchema: COMMAND_GENERATION_SCHEMA } : {})),
+    };
+}

package/dist/ai/openai.js

@@ -8,27 +8,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import OpenAI from "openai";
+import { COMMAND_GENERATION_SCHEMA } from "./command-schema.js";
 import { AiProviderError } from "./errors.js";
 export class OpenAiCommandProvider {
     constructor(config) {
         this.model = config.model;
-        this.client = new OpenAI({
-            apiKey: config.apiKey,
-            baseURL: config.baseUrl,
-        });
+        this.client = new OpenAI(buildOpenAiClientOptions(config));
     }
     generateCommands(request) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             try {
-                const response = yield this.client.chat.completions.create({
-                    model: this.model,
-                    messages: [
-                        { role: "system", content: request.systemPrompt },
-                        { role: "user", content: request.userPrompt },
-                    ],
-                    response_format: { type: "json_object" },
-                });
+                const response = yield this.client.chat.completions.create(buildOpenAiChatCompletionRequest(this.model, request));
                 const rawText = (_b = (_a = response.choices[0]) === null || _a === void 0 ? void 0 : _a.message) === null || _b === void 0 ? void 0 : _b.content;
                 if (rawText === undefined || rawText === null || rawText.trim() === "") {
                     throw new Error("provider returned an empty response");
@@ -41,3 +32,38 @@ export class OpenAiCommandProvider {
         });
     }
 }
+export function buildOpenAiClientOptions(config) {
+    if (config.apiKey.trim() !== "") {
+        return {
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl,
+        };
+    }
+    return {
+        apiKey: "howto-empty-api-key",
+        baseURL: config.baseUrl,
+        defaultHeaders: {
+            Authorization: null,
+        },
+    };
+}
+export function buildOpenAiChatCompletionRequest(model, request) {
+    return {
+        model,
+        messages: [
+            { role: "system", content: request.systemPrompt },
+            { role: "user", content: request.userPrompt },
+        ],
+        response_format: request.structuredOutput
+            ? {
+                type: "json_schema",
+                json_schema: {
+                    name: "command_generation",
+                    description: "Shell command candidates generated for howto.",
+                    schema: COMMAND_GENERATION_SCHEMA,
+                    strict: true,
+                },
+            }
+            : { type: "json_object" },
+    };
+}

package/dist/cli.js

@@ -11,6 +11,7 @@ const VALUE_OPTIONS = new Set([
     "--openai-api-url",
     "--openai-api-key",
     "--openai-model",
+    "--structured-output",
 ]);
 const BOOLEAN_OPTIONS = new Set(["--print", "--init"]);
 export const USAGE = `Usage: howto [options] [use <command>] <question> [<argument>...]
@@ -25,6 +26,7 @@ Options:
   --openai-api-url <url>
   --openai-api-key <key>
   --openai-model <model>
+  --structured-output <true|false>
 
 Try: howto "list files changed today"`;
 export function parseCliArgs(argv) {
@@ -89,6 +91,9 @@ function assignOptionValue(options, optionName, value) {
         case "--openai-model":
             options.openaiModel = value;
             return;
+        case "--structured-output":
+            options.structuredOutput = value;
+            return;
         default:
             throw new CliParseError(`unsupported option: ${optionName}`);
     }

package/dist/config-file.js

@@ -19,6 +19,7 @@ const CONFIG_FILE_FIELDS = new Set([
     "openaiApiUrl",
     "openaiApiKey",
     "openaiModel",
+    "structuredOutput",
 ]);
 export function getConfigFilePath(env = process.env) {
     var _a;
@@ -44,6 +45,13 @@ export function readUserConfigFile() {
             if (!CONFIG_FILE_FIELDS.has(key)) {
                 continue;
             }
+            if (key === "structuredOutput") {
+                if (typeof value !== "string" && typeof value !== "boolean") {
+                    throw new ConfigError(`config file field ${key} must be a boolean or string`);
+                }
+                config.structuredOutput = value;
+                continue;
+            }
             if (typeof value !== "string") {
                 throw new ConfigError(`config file field ${key} must be a string`);
             }

package/dist/config.js

@@ -28,6 +28,7 @@ export function loadConfig(options, env, fileConfig = {}) {
             model: (_c = pickConfigValue(options.openaiModel, env.HOWTO_OPENAI_MODEL, fileConfig.openaiModel)) !== null && _c !== void 0 ? _c : DEFAULT_OPENAI_MODEL,
             baseUrl: pickConfigValue(options.openaiApiUrl, env.HOWTO_OPENAI_API_URL, fileConfig.openaiApiUrl),
         },
+        structuredOutput: parseStructuredOutput(pickConfigValue(options.structuredOutput, env.HOWTO_STRUCTURED_OUTPUT, fileConfig.structuredOutput)),
     };
     if (config.aiProvider === "gemini" && isBlank(config.gemini.apiKey)) {
         throw new ConfigError("Gemini provider requires --gemini-api-key or HOWTO_GEMINI_API_KEY");
@@ -47,3 +48,18 @@ function parseAiProvider(value) {
 function isBlank(value) {
     return value === undefined || value.trim() === "";
 }
+function parseStructuredOutput(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    throw new ConfigError("invalid structuredOutput value; expected true or false");
+}

package/dist/index.js

@@ -66,6 +66,7 @@ function run(argv) {
                 question: parsedCli.question,
                 arguments: parsedCli.arguments,
                 useCommand: parsedCli.useCommand,
+                structuredOutput: config.structuredOutput,
             });
             const { systemPrompt, userPrompt } = buildCommandGenerationPrompt(promptRequest);
             const provider = createCommandProvider(config);