@unscientificjszhai/howto 1.0.0-alpha.3 → 1.0.1

package/dist/config-file.js

@@ -1,16 +1,6 @@
-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 { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { userInfo } from "node:os";
 import { ConfigError } from "./config.js";
 const CONFIG_FILE_FIELDS = new Set([
     "aiProvider",
@@ -21,54 +11,110 @@ const CONFIG_FILE_FIELDS = new Set([
     "openaiModel",
     "structuredOutput",
 ]);
-export function getConfigFilePath(env = process.env) {
-    var _a;
-    return join((_a = env.HOME) !== null && _a !== void 0 ? _a : homedir(), ".howto", "config.json");
+export function getConfigFilePath(env = process.env, getSystemHomeDirectory = () => userInfo().homedir) {
+    const configuredHome = env.HOME;
+    let homeDirectory;
+    if (configuredHome === undefined || configuredHome.trim() === "") {
+        try {
+            homeDirectory = getSystemHomeDirectory();
+        }
+        catch {
+            throw new ConfigError("failed to resolve user home directory");
+        }
+        if (typeof homeDirectory !== "string" ||
+            homeDirectory.trim() === "" ||
+            !isAbsolute(homeDirectory)) {
+            throw new ConfigError("failed to resolve user home directory");
+        }
+    }
+    else {
+        homeDirectory = configuredHome;
+    }
+    const configDirectory = join(homeDirectory, ".howto");
+    assertAbsoluteConfigDirectory(configDirectory);
+    return join(configDirectory, "config.json");
 }
-export function readUserConfigFile() {
-    return __awaiter(this, arguments, void 0, function* (path = getConfigFilePath()) {
-        if (!existsSync(path)) {
+export async function readUserConfigFile(path = getConfigFilePath()) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
             return {};
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(yield readFile(path, "utf8"));
+        throw new ConfigError("failed to read user config file");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new ConfigError("user config file is not valid JSON");
+    }
+    if (!isPlainObject(parsed)) {
+        throw new ConfigError("user config file must contain a JSON object");
+    }
+    const config = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        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;
         }
-        catch (error) {
-            throw new ConfigError(`failed to read config file ${path}: ${getParseErrorMessage(error)}`);
+        if (typeof value !== "string") {
+            throw new ConfigError(`config file field ${key} must be a string`);
         }
-        if (!isPlainObject(parsed)) {
-            throw new ConfigError(`config file ${path} must contain a JSON object`);
+        config[key] = value;
+    }
+    return config;
+}
+export async function writeUserConfigFile(config, path = getConfigFilePath()) {
+    const configDirectory = dirname(path);
+    assertAbsoluteConfigDirectory(configDirectory);
+    const serializedConfig = `${JSON.stringify(config, null, 2)}\n`;
+    let temporaryDirectory;
+    try {
+        await mkdir(configDirectory, { recursive: true });
+        temporaryDirectory = await mkdtemp(join(configDirectory, `.${basename(path)}-`));
+    }
+    catch {
+        throw new ConfigError("failed to save user config file");
+    }
+    const temporaryPath = join(temporaryDirectory, basename(path));
+    try {
+        await writeFile(temporaryPath, serializedConfig, { encoding: "utf8", mode: 0o600 });
+        await rename(temporaryPath, path);
+    }
+    catch {
+        try {
+            await rm(temporaryDirectory, { recursive: true, force: true });
         }
-        const config = {};
-        for (const [key, value] of Object.entries(parsed)) {
-            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`);
-            }
-            config[key] = value;
+        catch {
+            throw new ConfigError("failed to save user config file and remove temporary config data");
         }
-        return config;
-    });
+        throw new ConfigError("failed to save user config file");
+    }
+    try {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+    catch {
+        // 配置已经通过原子重命名提交；空临时目录清理失败不能把成功写入报告为失败。
+    }
 }
-export function writeUserConfigFile(config_1) {
-    return __awaiter(this, arguments, void 0, function* (config, path = getConfigFilePath()) {
-        yield mkdir(dirname(path), { recursive: true });
-        yield writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    });
+function assertAbsoluteConfigDirectory(path) {
+    if (!isAbsolute(path)) {
+        throw new ConfigError("config directory must be an absolute path");
+    }
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function getParseErrorMessage(error) {
-    return error instanceof Error ? error.message : "invalid JSON";
+function isFileNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
 }

package/dist/config.js

@@ -11,7 +11,6 @@ export function hasExplicitAiProvider(options, env, fileConfig = {}) {
     return (pickConfigValue(options.aiProvider, env.HOWTO_AI_PROVIDER, fileConfig.aiProvider) !== undefined);
 }
 export function loadConfig(options, env, fileConfig = {}) {
-    var _a, _b, _c;
     const aiProviderValue = pickConfigValue(options.aiProvider, env.HOWTO_AI_PROVIDER, fileConfig.aiProvider);
     if (aiProviderValue === undefined) {
         throw new ConfigError("AI provider is not configured. Set --ai-provider or HOWTO_AI_PROVIDER, or run howto in an interactive terminal to initialize it.");
@@ -21,11 +20,14 @@ export function loadConfig(options, env, fileConfig = {}) {
         aiProvider,
         gemini: {
             apiKey: pickConfigValue(options.geminiApiKey, env.HOWTO_GEMINI_API_KEY, fileConfig.geminiApiKey),
-            model: (_a = pickConfigValue(options.geminiModel, env.HOWTO_GEMINI_MODEL, fileConfig.geminiModel)) !== null && _a !== void 0 ? _a : DEFAULT_GEMINI_MODEL,
+            model: pickConfigValue(options.geminiModel, env.HOWTO_GEMINI_MODEL, fileConfig.geminiModel) ??
+                DEFAULT_GEMINI_MODEL,
         },
         openai: {
-            apiKey: (_b = pickConfigValue(options.openaiApiKey, env.HOWTO_OPENAI_API_KEY, fileConfig.openaiApiKey)) !== null && _b !== void 0 ? _b : "",
-            model: (_c = pickConfigValue(options.openaiModel, env.HOWTO_OPENAI_MODEL, fileConfig.openaiModel)) !== null && _c !== void 0 ? _c : DEFAULT_OPENAI_MODEL,
+            apiKey: pickConfigValue(options.openaiApiKey, env.HOWTO_OPENAI_API_KEY, fileConfig.openaiApiKey) ??
+                "",
+            model: pickConfigValue(options.openaiModel, env.HOWTO_OPENAI_MODEL, fileConfig.openaiModel) ??
+                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)),
@@ -36,8 +38,7 @@ export function loadConfig(options, env, fileConfig = {}) {
     return config;
 }
 function pickConfigValue(cliValue, envValue, fileValue) {
-    var _a;
-    return (_a = cliValue !== null && cliValue !== void 0 ? cliValue : envValue) !== null && _a !== void 0 ? _a : fileValue;
+    return cliValue ?? envValue ?? fileValue;
 }
 function parseAiProvider(value) {
     if (value === "openai" || value === "gemini") {

package/dist/errors.js

@@ -4,7 +4,16 @@ import { ConfigError } from "./config.js";
 import { AiResponseValidationError } from "./validation/ai-response.js";
 import { InteractionCancelledError, InteractiveTtyError } from "./ui/tty.js";
 import { PlaceholderResolutionError } from "./ui/placeholder-logic.js";
+import { sanitizeUserVisibleErrorMessage } from "./user-visible-error.js";
+export { sanitizeUserVisibleErrorMessage };
+export function getUserVisibleErrorMessage(error) {
+    if (error instanceof AiProviderError) {
+        return `AI provider request failed (provider: ${error.provider}, model: ${sanitizeUserVisibleErrorMessage(error.model)})`;
+    }
+    return sanitizeUserVisibleErrorMessage(error.message);
+}
 export class AppError extends Error {
+    exitCode;
     constructor(message, exitCode) {
         super(message);
         this.name = "AppError";
@@ -13,30 +22,30 @@ export class AppError extends Error {
 }
 export function toAppError(error) {
     if (error instanceof AppError) {
-        return error;
+        return new AppError(sanitizeUserVisibleErrorMessage(error.message), error.exitCode);
     }
     if (error instanceof CliParseError) {
-        return new AppError(`Error: ${error.message}\n${USAGE}`, 2);
+        return new AppError(`Error: ${sanitizeUserVisibleErrorMessage(error.message)}\n${USAGE}`, 2);
     }
     if (error instanceof ConfigError) {
-        return new AppError(`Configuration error: ${error.message}`, 2);
+        return new AppError(`Configuration error: ${sanitizeUserVisibleErrorMessage(error.message)}`, 2);
     }
     if (error instanceof AiProviderError) {
-        return new AppError(error.message, 1);
+        return new AppError(getUserVisibleErrorMessage(error), 1);
     }
     if (error instanceof AiResponseValidationError) {
-        return new AppError(`AI response format error: ${error.message}`, 2);
+        return new AppError(`AI response format error: ${sanitizeUserVisibleErrorMessage(error.message)}`, 2);
     }
     if (error instanceof InteractiveTtyError) {
-        return new AppError(`Error: ${error.message}`, 2);
+        return new AppError(`Error: ${sanitizeUserVisibleErrorMessage(error.message)}`, 2);
     }
     if (error instanceof PlaceholderResolutionError) {
-        return new AppError(`Error: ${error.message}`, 2);
+        return new AppError(`Error: ${sanitizeUserVisibleErrorMessage(error.message)}`, 2);
     }
     if (error instanceof InteractionCancelledError) {
         return new AppError("", 130);
     }
-    return new AppError(`Error: ${sanitizeErrorMessage(getErrorMessage(error))}`, 1);
+    return new AppError(`Error: ${sanitizeUserVisibleErrorMessage(getErrorMessage(error))}`, 1);
 }
 function getErrorMessage(error) {
     if (error instanceof Error && error.message.trim() !== "") {
@@ -47,11 +56,3 @@ function getErrorMessage(error) {
     }
     return "unknown error";
 }
-function sanitizeErrorMessage(message) {
-    const singleLine = message.replace(/\s+/g, " ").trim();
-    const redacted = singleLine
-        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
-        .replace(/(api[-_ ]?key["'\s:=]+)[A-Za-z0-9._~+/=-]+/gi, "$1[redacted]")
-        .replace(/(authorization["'\s:=]+)[A-Za-z0-9._~+/=-]+/gi, "$1[redacted]");
-    return redacted.length > 220 ? `${redacted.slice(0, 217)}...` : redacted;
-}

package/dist/execute.js

@@ -1,38 +1,25 @@
-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 { spawn } from "child_process";
 import { constants as osConstants } from "os";
-export function executeCommand(command_1) {
-    return __awaiter(this, arguments, void 0, function* (command, options = {}) {
-        var _a, _b, _c;
-        const env = (_a = options.env) !== null && _a !== void 0 ? _a : process.env;
-        const platform = (_b = options.platform) !== null && _b !== void 0 ? _b : process.platform;
-        const spawnCommand = (_c = options.spawnCommand) !== null && _c !== void 0 ? _c : spawnCommandWithNodeSpawn;
-        const child = platform === "win32"
-            ? spawnCommand(command, { shell: env.SHELL || true, stdio: "inherit" }, { stdio: "inherit" })
-            : spawnCommand(resolveShell(env), ["-lc", `exec ${command}`], { stdio: "inherit" });
-        return new Promise((resolve, reject) => {
-            child.once("error", reject);
-            child.once("close", (code, signal) => {
-                resolve(resolveProcessExitCode(code, signal));
-            });
+export async function executeCommand(command, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const spawnCommand = options.spawnCommand ?? spawnCommandWithNodeSpawn;
+    const child = platform === "win32"
+        ? spawnCommand(command, { shell: env.SHELL || true, stdio: "inherit" }, { stdio: "inherit" })
+        : spawnCommand(resolveShell(env), ["-c", command], { stdio: "inherit" });
+    return new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code, signal) => {
+            resolve(resolveProcessExitCode(code, signal));
         });
     });
 }
 export function resolveProcessExitCode(code, signal) {
-    var _a;
     if (typeof code === "number") {
         return code;
     }
     if (signal !== null) {
-        return 128 + ((_a = osConstants.signals[signal]) !== null && _a !== void 0 ? _a : 1);
+        return 128 + (osConstants.signals[signal] ?? 1);
     }
     return 1;
 }

package/dist/index.js

@@ -1,122 +1,110 @@
 #!/usr/bin/env node
-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 React from "react";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { render } from "ink";
 import { CliParseError, parseCliArgs } from "./cli.js";
 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";
-import { App } from "./ui/App.js";
+import { createInteractiveSession } from "./ui/interactive-session.js";
+import { runInteractiveCommand } from "./ui/run-interactive-command.js";
 import { initializeConfig } from "./init/index.js";
-function run(argv) {
-    return __awaiter(this, void 0, void 0, function* () {
-        try {
-            const parsedCli = parseCliArgs(argv);
-            if (parsedCli.options.init) {
-                ensureInteractiveTty(process.stdin, process.stdout);
-                yield initializeConfig({
-                    cliOptions: parsedCli.options,
-                    env: process.env,
-                    input: process.stdin,
-                    output: process.stdout,
-                });
-                return { exitCode: 0 };
-            }
-            const fileConfig = yield readUserConfigFile();
-            if (parsedCli.question === undefined) {
-                throw new CliParseError("missing question");
-            }
-            if (!hasExplicitAiProvider(parsedCli.options, process.env, fileConfig)) {
-                if (parsedCli.options.print) {
-                    throw new ConfigError("AI provider is not configured. --print cannot run initialization; run howto --init or set --ai-provider, HOWTO_AI_PROVIDER, or ~/.howto/config.json.");
-                }
-                ensureInteractiveTty(process.stdin, process.stdout);
-            }
-            const config = hasExplicitAiProvider(parsedCli.options, process.env, fileConfig)
-                ? loadConfig(parsedCli.options, process.env, fileConfig)
-                : yield initializeConfig({
-                    cliOptions: parsedCli.options,
-                    env: process.env,
-                    input: process.stdin,
-                    output: process.stdout,
-                });
-            const useCommandPathCheck = parsedCli.useCommand === undefined
-                ? undefined
-                : checkCommandInPath(parsedCli.useCommand, process.env);
-            if (!parsedCli.options.print) {
-                ensureInteractiveTty(process.stdin, process.stdout);
-            }
-            const promptRequest = createProviderPromptRequest({
-                question: parsedCli.question,
-                arguments: parsedCli.arguments,
-                useCommand: parsedCli.useCommand,
-                structuredOutput: config.structuredOutput,
+import { renderTerminalSafeText } from "./terminal-text.js";
+import { readPackageVersion } from "./version.js";
+async function run(argv) {
+    let session;
+    const getSession = () => {
+        ensureInteractiveTty(process.stdin, process.stdout);
+        session ??= createInteractiveSession({ input: process.stdin, output: process.stdout });
+        return session;
+    };
+    try {
+        const parsedCli = parseCliArgs(argv);
+        if (parsedCli.options.version) {
+            console.log(readPackageVersion());
+            return { exitCode: 0 };
+        }
+        if (parsedCli.options.init) {
+            ensureInteractiveTty(process.stdin, process.stdout);
+            await initializeConfig({
+                cliOptions: parsedCli.options,
+                env: process.env,
+                session: getSession(),
             });
-            const { systemPrompt, userPrompt } = buildCommandGenerationPrompt(promptRequest);
-            const provider = createCommandProvider(config);
+            return { exitCode: 0 };
+        }
+        const fileConfig = await readUserConfigFile();
+        if (parsedCli.question === undefined) {
+            throw new CliParseError("missing question");
+        }
+        if (!hasExplicitAiProvider(parsedCli.options, process.env, fileConfig)) {
             if (parsedCli.options.print) {
-                const aiResult = yield provider.generateCommands(Object.assign(Object.assign({}, promptRequest), { systemPrompt,
-                    userPrompt }));
-                const aiResponse = parseAndValidateAiResponse(aiResult.rawText);
-                aiResponse.commands.forEach((candidate) => {
-                    console.log(candidate.command);
-                });
-                return { exitCode: 0 };
-            }
-            if (useCommandPathCheck !== undefined && !useCommandPathCheck.found) {
-                console.error(`Warning: requested command "${useCommandPathCheck.command}" was not found in PATH. Review before executing any generated command.`);
+                throw new ConfigError("AI provider is not configured. --print cannot run initialization; run howto --init or set --ai-provider, HOWTO_AI_PROVIDER, or ~/.howto/config.json.");
             }
-            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) => {
-                    finalCommand = command;
-                    clear();
-                    unmount();
-                }, onError: (error) => {
-                    appError = error;
-                    clear();
-                    unmount();
-                } }));
-            yield waitUntilExit();
-            if (appError) {
-                throw appError;
-            }
-            if (finalCommand === undefined) {
-                return { exitCode: 1 };
-            }
-            const exitCode = yield executeCommand(finalCommand);
-            return { exitCode };
+            ensureInteractiveTty(process.stdin, process.stdout);
         }
-        catch (error) {
-            const appError = toAppError(error);
-            if (appError.message !== "") {
-                console.error(appError.message);
-            }
-            return { exitCode: appError.exitCode };
+        const config = hasExplicitAiProvider(parsedCli.options, process.env, fileConfig)
+            ? loadConfig(parsedCli.options, process.env, fileConfig)
+            : await initializeConfig({
+                cliOptions: parsedCli.options,
+                env: process.env,
+                session: getSession(),
+            });
+        const useCommandPathCheck = parsedCli.useCommand === undefined
+            ? undefined
+            : checkCommandInPath(parsedCli.useCommand, process.env);
+        if (!parsedCli.options.print) {
+            ensureInteractiveTty(process.stdin, process.stdout);
         }
-    });
+        const promptRequest = createProviderPromptRequest({
+            question: parsedCli.question,
+            arguments: parsedCli.arguments,
+            useCommand: parsedCli.useCommand,
+            structuredOutput: config.structuredOutput,
+        });
+        const { systemPrompt, userPrompt } = buildCommandGenerationPrompt(promptRequest);
+        const provider = createCommandProvider(config);
+        if (parsedCli.options.print) {
+            const candidates = await generateValidatedCommandCandidates(provider, {
+                ...promptRequest,
+                systemPrompt,
+                userPrompt,
+            });
+            candidates.forEach((candidate) => {
+                console.log(candidate.command);
+            });
+            return { exitCode: 0 };
+        }
+        if (useCommandPathCheck !== undefined && !useCommandPathCheck.found) {
+            console.error(`Warning: requested command "${renderTerminalSafeText(useCommandPathCheck.command)}" was not found in PATH. Review before executing any generated command.`);
+        }
+        const exitCode = await runInteractiveCommand({
+            session: getSession(),
+            provider,
+            request: { ...promptRequest, systemPrompt, userPrompt },
+        });
+        return { exitCode };
+    }
+    catch (error) {
+        const appError = toAppError(error);
+        if (appError.message !== "") {
+            console.error(appError.message);
+        }
+        return { exitCode: appError.exitCode };
+    }
+    finally {
+        session?.dispose();
+    }
 }
 function resolveEntrypointPath(path) {
     try {
         return realpathSync(path);
     }
-    catch (_a) {
+    catch {
         return path;
     }
 }