@unscientificjszhai/howto 1.0.0 → 1.0.2

package/dist/ui/resize-safe-output.js

@@ -0,0 +1,73 @@
+import { useEffect, useState } from "react";
+import { useStdout } from "ink";
+const SAFE_INK_ROWS = Number.MAX_SAFE_INTEGER;
+const DEFAULT_PHYSICAL_ROWS = 24;
+const physicalToProxy = new WeakMap();
+const proxyToPhysical = new WeakMap();
+export function toResizeSafeOutput(output) {
+    if (proxyToPhysical.has(output)) {
+        return output;
+    }
+    const existingProxy = physicalToProxy.get(output);
+    if (existingProxy) {
+        return existingProxy;
+    }
+    const wrappedFunctions = new Map();
+    const proxy = new Proxy(output, {
+        get(target, property) {
+            if (property === "rows") {
+                return SAFE_INK_ROWS;
+            }
+            if (property === "constructor") {
+                const constructor = Reflect.get(target, property, target);
+                return constructor;
+            }
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== "function") {
+                return value;
+            }
+            if (wrappedFunctions.has(property)) {
+                return wrappedFunctions.get(property);
+            }
+            // Stream 方法必须绑定物理流，确保 EventEmitter 的 this 与监听移除语义保持不变。
+            const streamMethod = value;
+            const wrappedFunction = (...arguments_) => {
+                const result = Reflect.apply(streamMethod, target, arguments_);
+                return result === target ? proxy : result;
+            };
+            wrappedFunctions.set(property, wrappedFunction);
+            return wrappedFunction;
+        },
+    });
+    physicalToProxy.set(output, proxy);
+    proxyToPhysical.set(proxy, output);
+    return proxy;
+}
+export function unwrapResizeSafeOutput(output) {
+    return proxyToPhysical.get(output) ?? output;
+}
+export function usePhysicalStdoutRows() {
+    const { stdout } = useStdout();
+    const physicalStdout = unwrapResizeSafeOutput(stdout);
+    const [rows, setRows] = useState(() => readPhysicalRows(physicalStdout));
+    useEffect(() => {
+        const updateRows = () => {
+            setRows(readPhysicalRows(physicalStdout));
+        };
+        physicalStdout.on("resize", updateRows);
+        updateRows();
+        return () => {
+            physicalStdout.off("resize", updateRows);
+        };
+    }, [physicalStdout]);
+    return rows;
+}
+export function normalizePhysicalRows(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_PHYSICAL_ROWS;
+    }
+    return Math.max(0, Math.floor(value));
+}
+function readPhysicalRows(output) {
+    return normalizePhysicalRows(output.rows);
+}

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,22 @@
+import { useEffect, useState } from "react";
+import { useInput, useStdin } from "ink";
+import { splitKeyboardInput } from "./text-input.js";
+export function useKeyboardInput(onInput, options) {
+    const { isRawModeSupported } = useStdin();
+    // renderToString 没有真实输入订阅，应保留同步静态渲染。
+    const [ready, setReady] = useState(!isRawModeSupported);
+    useInput((input, key) => {
+        if (!ready)
+            return;
+        // 同一按键的释放可能到达下一个视图，必须在确认、取消、导航和删除之前丢弃。
+        if (key.eventType === "release")
+            return;
+        // 同步交付给本次视图的回调，不能把剩余按键排队到下一页。
+        for (const event of splitKeyboardInput(input, key))
+            onInput(event.input, event.key);
+    }, options);
+    // Ink 在被动 effect 中注册输入。先完成订阅，再允许调用方显示可交互帧；
+    // 否则立即写出的新页面可能先于它自己的按键监听器接受用户输入。
+    useEffect(() => setReady(true), []);
+    return ready;
+}

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

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

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");
     }
 }
@@ -38,12 +39,16 @@ function validateCommandCandidate(value, index) {
     const title = readNonEmptyString(candidate.title, `${path}.title`);
     const command = readNonEmptyString(candidate.command, `${path}.command`);
     const description = readNonEmptyString(candidate.description, `${path}.description`);
+    const dangerous = readBoolean(candidate.dangerous, `${path}.dangerous`);
+    const dangerReason = readDangerReason(candidate.dangerReason, dangerous, `${path}.dangerReason`);
     const placeholders = readPlaceholders(candidate.placeholders, path);
     validatePlaceholderReferences(command, placeholders, path);
     return {
         title,
         command,
         description,
+        dangerous,
+        dangerReason,
         placeholders,
     };
 }
@@ -68,29 +73,52 @@ 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`);
         }
     }
 }
+function readBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw new AiResponseValidationError(`${path} must be a boolean`);
+    }
+    return value;
+}
+function readDangerReason(value, dangerous, path) {
+    const reason = dangerous ? readNonEmptyString(value, path) : readString(value, path);
+    if (!dangerous && reason !== "") {
+        throw new AiResponseValidationError(`${path} must be empty when dangerous is false`);
+    }
+    return reason;
+}
 function readNonEmptyString(value, path) {
+    const text = readString(value, path);
+    if (text.trim() === "") {
+        throw new AiResponseValidationError(`${path} must be a non-empty string`);
+    }
+    return text;
+}
+function readString(value, path) {
     if (typeof value !== "string") {
         throw new AiResponseValidationError(`${path} must be a string`);
     }
-    if (value.trim() === "") {
-        throw new AiResponseValidationError(`${path} must be a non-empty string`);
+    if (hasUnsafeTerminalControlCharacters(value)) {
+        throw new AiResponseValidationError(`${path} must not contain terminal control characters other than CR or LF`);
     }
     return value;
 }

package/dist/validation/command-tool.js

@@ -1,8 +1,7 @@
-import { accessSync, constants } from "fs";
+import { accessSync, constants, statSync } 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,38 +23,48 @@ 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;
+    // 未设置 PATH 时 shell 会选择默认路径，不能将其当作当前目录。
+    if (pathValue === undefined) {
+        return [];
+    }
+    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)) {
-        if (directory === "") {
-            continue;
-        }
         for (const extension of extensions) {
             candidates.push(command.toLowerCase().endsWith(extension.toLowerCase())
                 ? join(directory, command)
@@ -67,119 +76,9 @@ function buildPathCandidates(command, env) {
 function isExecutable(path) {
     try {
         accessSync(path, constants.X_OK);
-        return true;
+        return statSync(path).isFile();
     }
-    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;
+    }
+}