@unscientificjszhai/howto 1.0.0-alpha.3 → 1.0.1

package/dist/init/InitializationApp.js

@@ -1,19 +1,41 @@
-import React, { useState } from "react";
-import { Box, Text, useInput } from "ink";
+import React, { useRef, useState } from "react";
+import { Box, Text } from "ink";
+import { getUserVisibleErrorMessage } from "../errors.js";
+import { usePhysicalStdoutRows } from "../ui/resize-safe-output.js";
+import { toSingleLinePreview } from "../ui/single-line-preview.js";
+import { useInteractiveSession } from "../ui/InteractiveSessionProvider.js";
+import { usePasteAwareInput } from "../ui/use-paste-aware-input.js";
 import { applyInitializationInput, createInitialInitializationState, getProviderOptions, } from "./state.js";
+const RICH_LAYOUT_MIN_ROWS = 15;
 export const InitializationApp = ({ onSubmit, onComplete, onCancel, onError }) => {
+    const session = useInteractiveSession();
+    const rows = usePhysicalStdoutRows();
     const [state, setState] = useState(createInitialInitializationState);
+    const stateRef = useRef(state);
     const [submitStatus, setSubmitStatus] = useState("editing");
+    const submitStatusRef = useRef(submitStatus);
     const [errorMessage, setErrorMessage] = useState("");
-    useInput((input, key) => {
-        const update = applyInitializationInput(state, { input, key });
+    const frameRows = Math.max(0, rows - 1);
+    const handleInput = (event) => {
+        if (frameRows === 0) {
+            return;
+        }
+        if (submitStatusRef.current !== "editing") {
+            return;
+        }
+        const update = applyInitializationInput(stateRef.current, event);
+        stateRef.current = update.state;
         setState(update.state);
         if (update.cancelled) {
+            session.suspendViewInput();
+            submitStatusRef.current = "cancelled";
             setSubmitStatus("cancelled");
             onCancel();
             return;
         }
         if (update.completedValues !== undefined) {
+            session.suspendViewInput();
+            submitStatusRef.current = "saving";
             setSubmitStatus("saving");
             onSubmit(update.completedValues)
                 .then((config) => {
@@ -21,33 +43,72 @@ export const InitializationApp = ({ onSubmit, onComplete, onCancel, onError }) =
             })
                 .catch((error) => {
                 const appError = normalizeError(error);
-                setErrorMessage(appError.message);
+                setErrorMessage(getUserVisibleErrorMessage(appError));
+                submitStatusRef.current = "error";
                 setSubmitStatus("error");
                 onError(appError);
             });
         }
-    }, { isActive: submitStatus === "editing" });
+    };
+    usePasteAwareInput({
+        onInput: (input, key) => {
+            handleInput({ type: "keyboard", input, key });
+        },
+        onPaste: (input) => {
+            handleInput({ type: "paste", input });
+        },
+        isInputActive: frameRows === 0 || submitStatus === "editing",
+        isPasteActive: frameRows > 0 && submitStatus === "editing",
+    });
+    let content;
     if (submitStatus === "saving") {
-        return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
-            React.createElement(Text, { color: "green" }, "Saving howto configuration...")));
+        content = (React.createElement(InitializationStatusLine, { frameRows: frameRows, message: "Saving howto configuration...", color: "green" }));
+    }
+    else if (submitStatus === "error") {
+        content = (React.createElement(InitializationStatusLine, { frameRows: frameRows, message: `Error: ${errorMessage}`, color: "red" }));
     }
-    if (submitStatus === "error") {
-        return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
-            React.createElement(Text, { color: "red" },
-                "Error: ",
-                errorMessage)));
+    else if (submitStatus === "cancelled") {
+        content = (React.createElement(InitializationStatusLine, { frameRows: frameRows, message: "Initialization cancelled.", dimColor: true }));
     }
-    if (submitStatus === "cancelled") {
-        return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
-            React.createElement(Text, { dimColor: true }, "Initialization cancelled.")));
+    else if (state.step === "provider") {
+        content = React.createElement(ProviderStep, { selectedIndex: state.selectedIndex, frameRows: frameRows });
     }
-    if (state.step === "provider") {
-        return React.createElement(ProviderStep, { selectedIndex: state.selectedIndex });
+    else {
+        content = React.createElement(InputStep, { state: state, frameRows: frameRows });
     }
-    return React.createElement(InputStep, { state: state });
+    return (React.createElement(Box, { display: frameRows > 0 ? "flex" : "none", flexDirection: "column", maxHeight: frameRows, overflowX: "hidden", overflowY: "hidden" }, content));
 };
-const ProviderStep = ({ selectedIndex }) => {
+const ClippedLine = ({ children, color, dimColor = false, prefix, prefixWidth }) => (React.createElement(Box, { width: "100%", height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" }, prefix === undefined ? (React.createElement(Text, { color: color, dimColor: dimColor }, children)) : (React.createElement(React.Fragment, null,
+    React.createElement(Box, { width: prefixWidth, flexShrink: 0 },
+        React.createElement(Text, { color: color, dimColor: dimColor }, prefix)),
+    React.createElement(Box, { flexGrow: 1, flexShrink: 1, minWidth: 1, height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+        React.createElement(Text, { color: color, dimColor: dimColor }, children))))));
+const ProviderStep = ({ selectedIndex, frameRows, }) => {
     const providers = getProviderOptions();
+    const selectedProvider = selectedIndex === null ? undefined : providers[selectedIndex];
+    const providerSelectionLine = selectedProvider === "openai"
+        ? "> openai 2 gemini"
+        : selectedProvider === "gemini"
+            ? "1 openai > gemini"
+            : "1 openai 2 gemini";
+    if (frameRows < RICH_LAYOUT_MIN_ROWS) {
+        if (frameRows === 1) {
+            const compactSelection = selectedProvider === "openai" ? "O" : selectedProvider === "gemini" ? "G" : "-";
+            return (React.createElement(Box, { height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+                React.createElement(Text, null, `O/G:${compactSelection} UD Ent 1/2 Esc`)));
+        }
+        if (frameRows <= 3) {
+            return (React.createElement(Box, { flexDirection: "column", height: frameRows, maxHeight: frameRows, overflowX: "hidden", overflowY: "hidden" },
+                frameRows === 3 && React.createElement(Text, { color: "green" }, "? Choose provider"),
+                React.createElement(ClippedLine, null, providerSelectionLine),
+                React.createElement(Text, { dimColor: true }, "UD Enter 1/2 Esc")));
+        }
+        return (React.createElement(Box, { flexDirection: "column", maxHeight: 4, overflowX: "hidden", overflowY: "hidden" },
+            React.createElement(ClippedLine, null, "howto needs an AI provider before it can call AI."),
+            React.createElement(ClippedLine, { color: "green" }, "? Choose provider"),
+            React.createElement(ClippedLine, null, providerSelectionLine),
+            React.createElement(ClippedLine, { dimColor: true }, "UD Enter 1/2 Esc")));
+    }
     return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
         React.createElement(Text, null, "howto needs an AI provider before it can call AI."),
         React.createElement(Box, { height: 1 },
@@ -65,27 +126,109 @@ const ProviderStep = ({ selectedIndex }) => {
         React.createElement(Box, { flexShrink: 0, marginTop: 1 },
             React.createElement(Text, { dimColor: true }, "Use Up/Down or 1/2 to choose, Enter to continue, Esc or Ctrl+C to cancel."))));
 };
-const InputStep = ({ state, }) => {
+const InputStep = ({ state, frameRows }) => {
     const currentField = state.fields[state.fieldIndex];
+    const shortLabel = getShortFieldLabel(currentField);
+    if (frameRows < RICH_LAYOUT_MIN_ROWS) {
+        const fieldValue = getFieldValuePreview(currentField);
+        const fieldLine = `${shortLabel}: ${fieldValue}`;
+        const statusLine = state.errorMessage === undefined ? fieldLine : `! ${shortLabel} required`;
+        if (frameRows === 1) {
+            const compactField = state.errorMessage === undefined
+                ? `${shortLabel}:${getCompactFieldValuePreview(currentField)}`
+                : `!${shortLabel}:req`;
+            return (React.createElement(Box, { height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+                React.createElement(Box, { flexGrow: 1, flexShrink: 1, minWidth: 1, height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+                    React.createElement(Text, null, compactField)),
+                React.createElement(Box, { flexShrink: 0 },
+                    React.createElement(Text, { dimColor: true }, " Ent Esc ^C"))));
+        }
+        if (frameRows <= 3) {
+            return (React.createElement(Box, { flexDirection: "column", height: frameRows, maxHeight: frameRows, overflowX: "hidden", overflowY: "hidden" },
+                frameRows === 3 && (React.createElement(ClippedLine, { color: state.errorMessage === undefined ? "green" : "red" }, state.errorMessage === undefined ? `? Configure ${state.provider}` : statusLine)),
+                frameRows === 3 || state.errorMessage === undefined ? (React.createElement(ClippedLine, { prefix: `${shortLabel}:`, prefixWidth: shortLabel.length + 2 }, fieldValue)) : (React.createElement(ClippedLine, null, statusLine)),
+                React.createElement(Text, { dimColor: true }, "Ent next Esc back ^C")));
+        }
+        const defaultPreview = currentField.defaultValue !== undefined && currentField.value === ""
+            ? `Default: ${toSingleLinePreview(currentField.defaultValue)}`
+            : undefined;
+        const guidance = defaultPreview ?? getFullFieldGuidance(currentField);
+        return (React.createElement(Box, { flexDirection: "column", maxHeight: 4, overflowX: "hidden", overflowY: "hidden" },
+            React.createElement(ClippedLine, { color: state.errorMessage === undefined ? "green" : "red" }, state.errorMessage === undefined ? `? Configure ${state.provider}` : statusLine),
+            React.createElement(ClippedLine, { prefix: `${shortLabel}:`, prefixWidth: shortLabel.length + 2 }, fieldValue),
+            guidance !== undefined && React.createElement(ClippedLine, { dimColor: true }, guidance),
+            React.createElement(ClippedLine, { dimColor: true }, "Ent next Esc back ^C")));
+    }
     return (React.createElement(Box, { flexDirection: "column", marginY: 1 },
         React.createElement(Text, { color: "green" },
             "? Configure ",
             state.provider),
         React.createElement(Box, { flexDirection: "column", marginTop: 1 }, state.fields.map((field, index) => (React.createElement(FieldRow, { key: field.name, field: field, isActive: index === state.fieldIndex })))),
-        currentField.defaultValue !== undefined && currentField.value === "" && (React.createElement(Text, { dimColor: true },
-            "Default: ",
-            currentField.defaultValue)),
-        state.errorMessage !== undefined && React.createElement(Text, { color: "red" }, state.errorMessage),
+        getFullFieldGuidance(currentField) !== undefined && (React.createElement(ClippedLine, { dimColor: true }, getFullFieldGuidance(currentField))),
+        currentField.defaultValue !== undefined && currentField.value === "" && (React.createElement(ClippedLine, { dimColor: true, prefix: "Default:", prefixWidth: 9 }, toSingleLinePreview(currentField.defaultValue))),
+        state.errorMessage !== undefined && (React.createElement(ClippedLine, { color: "red" }, toSingleLinePreview(state.errorMessage))),
         React.createElement(Box, { flexShrink: 0, marginTop: 1 },
             React.createElement(Text, { dimColor: true }, "Press Enter for next value, Esc to go back, Ctrl+C to cancel."))));
 };
-const FieldRow = ({ field, isActive, }) => (React.createElement(Box, null,
-    React.createElement(Text, { color: isActive ? "cyan" : undefined }, isActive ? "> " : "  "),
-    React.createElement(Text, null,
-        field.label,
-        ": "),
-    React.createElement(Text, null, field.value),
-    isActive && React.createElement(Text, { backgroundColor: "white" }, " ")));
+const FieldRow = ({ field, isActive, }) => {
+    const shortLabel = getShortFieldLabel(field);
+    return (React.createElement(Box, { height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+        React.createElement(Box, { width: 2, flexShrink: 0 },
+            React.createElement(Text, { color: isActive ? "cyan" : undefined }, isActive ? "> " : "  ")),
+        React.createElement(Box, { width: shortLabel.length + 2, flexShrink: 0 },
+            React.createElement(Text, null,
+                shortLabel,
+                ":")),
+        React.createElement(Box, { flexShrink: 1, minWidth: 1, height: 1, maxHeight: 1, overflowX: "hidden", overflowY: "hidden" },
+            React.createElement(Text, null, toSingleLinePreview(field.value))),
+        isActive && (React.createElement(Box, { width: 1, flexShrink: 0 },
+            React.createElement(Text, { backgroundColor: "white" }, " ")))));
+};
+const InitializationStatusLine = ({ frameRows, message, color, dimColor = false }) => {
+    const status = (React.createElement(ClippedLine, { color: color, dimColor: dimColor }, toSingleLinePreview(message)));
+    if (frameRows < 4) {
+        return status;
+    }
+    return (React.createElement(Box, { flexDirection: "column", marginY: 1 }, status));
+};
+function getShortFieldLabel(field) {
+    switch (field.name) {
+        case "apiKey":
+            return "Key";
+        case "model":
+            return "Model";
+        case "openaiBaseUrl":
+            return "URL";
+    }
+}
+function getFullFieldGuidance(field) {
+    switch (field.name) {
+        case "apiKey":
+            return field.required ? "Required." : "Optional; empty allowed.";
+        case "model":
+            return undefined;
+        case "openaiBaseUrl":
+            return "Empty uses official OpenAI URL.";
+    }
+}
+function getFieldValuePreview(field) {
+    if (field.value !== "") {
+        return toSingleLinePreview(field.value);
+    }
+    if (field.defaultValue !== undefined) {
+        return toSingleLinePreview(field.defaultValue);
+    }
+    return field.required ? "<required>" : "<empty>";
+}
+function getCompactFieldValuePreview(field) {
+    if (field.value !== "") {
+        return toSingleLinePreview(field.value);
+    }
+    if (field.defaultValue !== undefined) {
+        return toSingleLinePreview(field.defaultValue);
+    }
+    return field.required ? "req" : "-";
+}
 function normalizeError(error) {
     if (error instanceof Error) {
         return error;

package/dist/init/index.js

@@ -1,37 +1,30 @@
-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 { render } from "ink";
 import { loadConfig } from "../config.js";
 import { getConfigFilePath, writeUserConfigFile } from "../config-file.js";
+import { InteractiveSessionProvider } from "../ui/InteractiveSessionProvider.js";
 import { InteractionCancelledError } from "../ui/tty.js";
 import { InitializationApp } from "./InitializationApp.js";
-export function initializeConfig(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ cliOptions, env, input, output, }) {
-        return yield new Promise((resolve, reject) => {
-            let settled = false;
-            const settle = (result) => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                instance.clear();
-                instance.unmount();
-                void instance.waitUntilExit().then(result, result);
-            };
-            const instance = render(React.createElement(InitializationApp, { onSubmit: (values) => __awaiter(this, void 0, void 0, function* () {
-                    const fileConfig = createFileConfig(values);
-                    const configFilePath = getConfigFilePath(env);
-                    yield writeUserConfigFile(fileConfig, configFilePath);
-                    return loadConfig(cliOptions, env, fileConfig);
-                }), onComplete: (config) => {
+export async function initializeConfig({ cliOptions, env, session, }) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let unsubscribe = () => { };
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            session.suspendViewInput();
+            unsubscribe();
+            const exitPromise = instance.waitUntilExit();
+            instance.clear();
+            instance.unmount();
+            void exitPromise.then(result, result);
+        };
+        const instance = render(React.createElement(InteractiveSessionProvider, { session: session },
+            React.createElement(InitializationApp, { onSubmit: async (values) => {
+                    return validateAndPersistInitializationConfig(values, cliOptions, env);
+                }, onComplete: (config) => {
                     settle(() => {
                         resolve(config);
                     });
@@ -43,14 +36,23 @@ export function initializeConfig(_a) {
                     settle(() => {
                         reject(error);
                     });
-                } }), {
-                stdin: input,
-                stdout: output,
-                exitOnCtrlC: false,
-            });
+                } })), {
+            stdin: session.input,
+            stdout: session.output,
+            exitOnCtrlC: false,
+            // 会话已确认 TTY，避免 CI 环境关闭 Ink 的实时渲染。
+            interactive: true,
         });
+        unsubscribe = session.subscribeFailure((error) => settle(() => reject(error)));
     });
 }
+export async function validateAndPersistInitializationConfig(values, cliOptions, env) {
+    const fileConfig = createFileConfig(values);
+    const config = loadConfig(cliOptions, env, fileConfig);
+    const configFilePath = getConfigFilePath(env);
+    await writeUserConfigFile(fileConfig, configFilePath);
+    return config;
+}
 export function clearInitializationOutput(output, rows) {
     if (output.isTTY) {
         output.write(erasePreviousTerminalRows(rows));

package/dist/init/state.js

@@ -1,4 +1,6 @@
 import { DEFAULT_GEMINI_MODEL, DEFAULT_OPENAI_MODEL } from "../config.js";
+import { hasUnsafeTerminalControlCharacters } from "../terminal-text.js";
+import { deleteLastGrapheme, isTextInputEvent } from "../ui/text-input.js";
 const PROVIDERS = ["openai", "gemini"];
 export function createInitialInitializationState() {
     return {
@@ -10,6 +12,14 @@ export function getProviderOptions() {
     return PROVIDERS;
 }
 export function applyInitializationInput(state, event) {
+    if (event.type === "paste") {
+        if (state.step !== "input" || hasUnsafeTerminalControlCharacters(event.input)) {
+            return { state };
+        }
+        return updateCurrentField(state, (value) => value + event.input);
+    }
+    if (event.key.eventType === "release")
+        return { state };
     if (event.key.ctrl && event.input === "c") {
         return { state, cancelled: true };
     }
@@ -22,7 +32,9 @@ function applyProviderInput(state, event) {
     if (event.key.escape) {
         return { state, cancelled: true };
     }
-    const numericSelection = getNumericProviderSelection(event.input);
+    const numericSelection = isTextInputEvent(event.input, event.key)
+        ? getNumericProviderSelection(event.input)
+        : null;
     if (numericSelection !== null) {
         return {
             state: createInputState(PROVIDERS[numericSelection]),
@@ -30,14 +42,20 @@ function applyProviderInput(state, event) {
     }
     if (event.key.upArrow) {
         return {
-            state: Object.assign(Object.assign({}, state), { selectedIndex: state.selectedIndex === null
+            state: {
+                ...state,
+                selectedIndex: state.selectedIndex === null
                     ? PROVIDERS.length - 1
-                    : (state.selectedIndex - 1 + PROVIDERS.length) % PROVIDERS.length }),
+                    : (state.selectedIndex - 1 + PROVIDERS.length) % PROVIDERS.length,
+            },
         };
     }
     if (event.key.downArrow) {
         return {
-            state: Object.assign(Object.assign({}, state), { selectedIndex: state.selectedIndex === null ? 0 : (state.selectedIndex + 1) % PROVIDERS.length }),
+            state: {
+                ...state,
+                selectedIndex: state.selectedIndex === null ? 0 : (state.selectedIndex + 1) % PROVIDERS.length,
+            },
         };
     }
     if (event.key.return && state.selectedIndex !== null) {
@@ -64,7 +82,10 @@ function applyFieldInput(state, event) {
         const validationError = validateCurrentField(state);
         if (validationError !== undefined) {
             return {
-                state: Object.assign(Object.assign({}, state), { errorMessage: validationError }),
+                state: {
+                    ...state,
+                    errorMessage: validationError,
+                },
             };
         }
         if (state.fieldIndex === state.fields.length - 1) {
@@ -74,26 +95,21 @@ function applyFieldInput(state, event) {
             };
         }
         return {
-            state: Object.assign(Object.assign({}, state), { fieldIndex: state.fieldIndex + 1, errorMessage: undefined }),
+            state: {
+                ...state,
+                fieldIndex: state.fieldIndex + 1,
+                errorMessage: undefined,
+            },
         };
     }
     if (event.key.backspace || event.key.delete) {
-        return updateCurrentField(state, (value) => value.slice(0, -1));
+        return updateCurrentField(state, deleteLastGrapheme);
     }
-    if (event.input !== "" && !hasControlKey(event)) {
+    if (isTextInputEvent(event.input, event.key)) {
         return updateCurrentField(state, (value) => value + event.input);
     }
     return { state };
 }
-function hasControlKey(event) {
-    return (event.key.upArrow ||
-        event.key.downArrow ||
-        event.key.return ||
-        event.key.escape ||
-        event.key.ctrl ||
-        event.key.backspace ||
-        event.key.delete);
-}
 function createInputState(provider) {
     return {
         step: "input",
@@ -140,8 +156,16 @@ function createInputState(provider) {
 }
 function updateCurrentField(state, updateValue) {
     return {
-        state: Object.assign(Object.assign({}, state), { fields: state.fields.map((field, index) => index === state.fieldIndex
-                ? Object.assign(Object.assign({}, field), { value: updateValue(field.value) }) : field), errorMessage: undefined }),
+        state: {
+            ...state,
+            fields: state.fields.map((field, index) => index === state.fieldIndex
+                ? {
+                    ...field,
+                    value: updateValue(field.value),
+                }
+                : field),
+            errorMessage: undefined,
+        },
     };
 }
 function validateCurrentField(state) {
@@ -152,20 +176,19 @@ function validateCurrentField(state) {
     return undefined;
 }
 function createInitializationValues(state) {
-    var _a, _b, _c;
     const fieldValues = new Map(state.fields.map((field) => [field.name, field.value]));
-    const modelValue = (_a = fieldValues.get("model")) === null || _a === void 0 ? void 0 : _a.trim();
+    const modelValue = fieldValues.get("model")?.trim();
     if (state.provider === "gemini") {
         return {
             provider: "gemini",
-            apiKey: (_b = fieldValues.get("apiKey")) !== null && _b !== void 0 ? _b : "",
+            apiKey: fieldValues.get("apiKey") ?? "",
             model: modelValue === "" || modelValue === undefined ? DEFAULT_GEMINI_MODEL : modelValue,
         };
     }
     const baseUrl = fieldValues.get("openaiBaseUrl");
     return {
         provider: "openai",
-        apiKey: (_c = fieldValues.get("apiKey")) !== null && _c !== void 0 ? _c : "",
+        apiKey: fieldValues.get("apiKey") ?? "",
         model: modelValue === "" || modelValue === undefined ? DEFAULT_OPENAI_MODEL : modelValue,
         openaiBaseUrl: baseUrl === undefined || baseUrl.trim() === "" ? undefined : baseUrl,
     };

package/dist/prompt.js

@@ -17,10 +17,13 @@ The JSON object must match this schema:
 }
 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.`;
+Do not include terminal control characters in string fields. CR and LF are the only allowed control characters.
+Use placeholders in commands only as {{name}}, and declare every placeholder in the placeholders array. Each placeholder name must be declared exactly once per candidate; multiple references to the same name share one input value. 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.`;
+Do not include terminal control characters in string fields. CR and LF are the only allowed control characters.
+Use placeholders in commands only as {{name}}, and declare every placeholder in the placeholders array. Each placeholder name must be declared exactly once per candidate; multiple references to the same name share one input value. 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.
 When a task could involve deletion, overwrite, privilege escalation, network download, or executing downloaded content, prefer a safer alternative or inspection command when possible.
 Do not include safety metadata or claim that a command is safe; the local CLI will perform its own validation and dangerous-command checks.`;