@unscientificjszhai/howto 1.0.0-alpha.2

package/dist/ui/confirm.js

@@ -0,0 +1,117 @@
+"use strict";
+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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmFinalCommand = confirmFinalCommand;
+exports.confirmDangerousCommand = confirmDangerousCommand;
+exports.formatFinalCommandConfirmation = formatFinalCommandConfirmation;
+exports.formatDangerousCommandConfirmation = formatDangerousCommandConfirmation;
+const readline_1 = __importDefault(require("readline"));
+const interactive_1 = require("./interactive");
+const key_input_1 = require("./key-input");
+function confirmFinalCommand(command_1) {
+    return __awaiter(this, arguments, void 0, function* (command, streams = {}) {
+        var _a, _b;
+        const input = (_a = streams.input) !== null && _a !== void 0 ? _a : process.stdin;
+        const output = (_b = streams.output) !== null && _b !== void 0 ? _b : process.stdout;
+        (0, interactive_1.ensureInteractiveTty)(input, output);
+        return new Promise((resolve, reject) => {
+            let cleanupKeypressSession;
+            const cleanup = () => {
+                cleanupKeypressSession === null || cleanupKeypressSession === void 0 ? void 0 : cleanupKeypressSession();
+                cleanupKeypressSession = undefined;
+            };
+            const finish = () => {
+                cleanup();
+                resolve();
+            };
+            const cancel = () => {
+                cleanup();
+                reject(new interactive_1.InteractionCancelledError("Final command confirmation cancelled"));
+            };
+            const onKeypress = (_inputText, key = {}) => {
+                if (key.ctrl === true && key.name === "c") {
+                    cancel();
+                    return;
+                }
+                if (key.name === "escape") {
+                    cancel();
+                    return;
+                }
+                if (key.name === "return" || key.name === "enter") {
+                    finish();
+                }
+            };
+            output.write(formatFinalCommandConfirmation(command));
+            cleanupKeypressSession = (0, key_input_1.beginKeypressSession)(input, onKeypress);
+        });
+    });
+}
+function confirmDangerousCommand(command_1, match_1) {
+    return __awaiter(this, arguments, void 0, function* (command, match, streams = {}) {
+        var _a, _b;
+        const input = (_a = streams.input) !== null && _a !== void 0 ? _a : process.stdin;
+        const output = (_b = streams.output) !== null && _b !== void 0 ? _b : process.stdout;
+        (0, interactive_1.ensureInteractiveTty)(input, output);
+        const rl = readline_1.default.createInterface({
+            input,
+            output,
+            terminal: input.isTTY === true && output.isTTY === true,
+        });
+        try {
+            output.write(formatDangerousCommandConfirmation(command, match));
+            const answer = yield readConfirmationLine(rl, input);
+            if (answer !== "EXECUTE") {
+                throw new interactive_1.InteractionCancelledError("Dangerous command confirmation cancelled");
+            }
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+function formatFinalCommandConfirmation(command) {
+    return `\nFinal command:\n${command}\n\nPress Enter to execute, Esc or Ctrl+C to cancel.\n`;
+}
+function formatDangerousCommandConfirmation(command, match) {
+    return [
+        "\nDangerous command detected.",
+        `Rule: ${match.rule}`,
+        `Risk: ${match.reason}`,
+        "",
+        "Final command:",
+        command,
+        "",
+        'Type EXECUTE to continue, or anything else to cancel.',
+        "> ",
+    ].join("\n");
+}
+function readConfirmationLine(rl, input) {
+    input.resume();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            rl.off("line", onLine);
+            rl.off("SIGINT", onSigint);
+        };
+        const onLine = (line) => {
+            cleanup();
+            resolve(line);
+        };
+        const onSigint = () => {
+            cleanup();
+            reject(new interactive_1.InteractionCancelledError("Dangerous command confirmation cancelled"));
+        };
+        rl.on("line", onLine);
+        rl.on("SIGINT", onSigint);
+    });
+}

package/dist/ui/interactive.js

@@ -0,0 +1,115 @@
+"use strict";
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractionCancelledError = exports.InteractiveTtyError = void 0;
+exports.selectCommandCandidate = selectCommandCandidate;
+exports.ensureInteractiveTty = ensureInteractiveTty;
+exports.formatCandidateSelection = formatCandidateSelection;
+const key_input_1 = require("./key-input");
+class InteractiveTtyError extends Error {
+    constructor(message = "Interactive mode requires a TTY. Run howto in an interactive terminal or use --print.") {
+        super(message);
+        this.name = "InteractiveTtyError";
+    }
+}
+exports.InteractiveTtyError = InteractiveTtyError;
+class InteractionCancelledError extends Error {
+    constructor(message = "Interactive selection cancelled") {
+        super(message);
+        this.name = "InteractionCancelledError";
+    }
+}
+exports.InteractionCancelledError = InteractionCancelledError;
+function selectCommandCandidate(candidates_1) {
+    return __awaiter(this, arguments, void 0, function* (candidates, streams = {}) {
+        var _a, _b;
+        const input = (_a = streams.input) !== null && _a !== void 0 ? _a : process.stdin;
+        const output = (_b = streams.output) !== null && _b !== void 0 ? _b : process.stdout;
+        ensureInteractiveTty(input, output);
+        return new Promise((resolve, reject) => {
+            let activeIndex = 0;
+            let renderedLineCount = 0;
+            let cleanupKeypressSession;
+            const clearRenderedSelection = () => {
+                if (renderedLineCount > 0) {
+                    output.write(`\x1B[${renderedLineCount}A\x1B[J`);
+                    renderedLineCount = 0;
+                }
+            };
+            const cleanup = () => {
+                cleanupKeypressSession === null || cleanupKeypressSession === void 0 ? void 0 : cleanupKeypressSession();
+                cleanupKeypressSession = undefined;
+                clearRenderedSelection();
+                output.write("\x1B[?25h");
+            };
+            const finish = (candidate) => {
+                cleanup();
+                resolve(candidate);
+            };
+            const cancel = () => {
+                cleanup();
+                reject(new InteractionCancelledError());
+            };
+            const render = () => {
+                const text = formatCandidateSelection(candidates, activeIndex);
+                clearRenderedSelection();
+                output.write(`\x1B[?25l${text}\n`);
+                renderedLineCount = text.split("\n").length + 1;
+            };
+            const onKeypress = (_inputText, key = {}) => {
+                if (key.ctrl === true && key.name === "c") {
+                    cancel();
+                    return;
+                }
+                if (key.name === "escape") {
+                    cancel();
+                    return;
+                }
+                if (key.name === "return" || key.name === "enter") {
+                    finish(candidates[activeIndex]);
+                    return;
+                }
+                if (key.name === "up") {
+                    activeIndex = (activeIndex - 1 + candidates.length) % candidates.length;
+                    render();
+                    return;
+                }
+                if (key.name === "down") {
+                    activeIndex = (activeIndex + 1) % candidates.length;
+                    render();
+                }
+            };
+            cleanupKeypressSession = (0, key_input_1.beginKeypressSession)(input, onKeypress);
+            render();
+        });
+    });
+}
+function ensureInteractiveTty(input, output) {
+    if (input.isTTY !== true || output.isTTY !== true) {
+        throw new InteractiveTtyError();
+    }
+}
+function formatCandidateSelection(candidates, activeIndex) {
+    const lines = ["? Select a command", ""];
+    candidates.forEach((candidate, index) => {
+        const prefix = index === activeIndex ? ">" : " ";
+        const titleLine = `${prefix} ${candidate.title}`;
+        lines.push(index === activeIndex ? `\x1B[7m${titleLine}\x1B[0m` : titleLine);
+        lines.push(`  ${candidate.command}`);
+        lines.push(`  ${candidate.description}`);
+        if (index < candidates.length - 1) {
+            lines.push("");
+        }
+    });
+    lines.push("");
+    lines.push("Use Up/Down to move, Enter to select, Esc or Ctrl+C to cancel.");
+    return lines.join("\n");
+}

package/dist/ui/key-input.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beginKeypressSession = beginKeypressSession;
+const readline_1 = __importDefault(require("readline"));
+function beginKeypressSession(input, onKeypress) {
+    const wasRaw = input.isRaw === true;
+    readline_1.default.emitKeypressEvents(input);
+    input.on("keypress", onKeypress);
+    if (typeof input.setRawMode === "function") {
+        input.setRawMode(true);
+    }
+    input.resume();
+    return () => {
+        input.off("keypress", onKeypress);
+        if (typeof input.setRawMode === "function" && !wasRaw) {
+            input.setRawMode(false);
+        }
+        input.pause();
+    };
+}

package/dist/ui/loading.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiLoadingIndicator = createAiLoadingIndicator;
+const FRAMES = ["|", "/", "-", "\\"];
+const MESSAGE = "Waiting for AI response...";
+function createAiLoadingIndicator(options) {
+    var _a, _b;
+    const output = (_a = options.output) !== null && _a !== void 0 ? _a : process.stdout;
+    const intervalMs = (_b = options.intervalMs) !== null && _b !== void 0 ? _b : 120;
+    let timer;
+    let frameIndex = 0;
+    let running = false;
+    const shouldRender = () => options.enabled && output.isTTY === true;
+    const render = () => {
+        const frame = FRAMES[frameIndex % FRAMES.length];
+        frameIndex += 1;
+        output.write(`\r${frame} ${MESSAGE}`);
+    };
+    return {
+        start() {
+            if (!shouldRender() || running) {
+                return;
+            }
+            running = true;
+            render();
+            timer = setInterval(render, intervalMs);
+        },
+        stop() {
+            if (!running) {
+                return;
+            }
+            if (timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+            running = false;
+            output.write("\r\x1B[2K");
+        },
+    };
+}

package/dist/ui/placeholder-logic.js

@@ -0,0 +1,19 @@
+const UNRESOLVED_PLACEHOLDER_PATTERN = /{{[^{}]*}}/;
+export class PlaceholderResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlaceholderResolutionError";
+    }
+}
+export function replaceCommandPlaceholders(command, values) {
+    let resolvedCommand = command;
+    for (const [name, value] of values) {
+        resolvedCommand = resolvedCommand.split(`{{${name}}}`).join(value);
+    }
+    return resolvedCommand;
+}
+export function assertNoUnresolvedPlaceholders(command) {
+    if (UNRESOLVED_PLACEHOLDER_PATTERN.test(command)) {
+        throw new PlaceholderResolutionError("final command contains unresolved placeholders");
+    }
+}

package/dist/ui/placeholders.js

@@ -0,0 +1,168 @@
+"use strict";
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaceholderSelectionBackError = exports.PlaceholderResolutionError = void 0;
+exports.resolveCommandPlaceholders = resolveCommandPlaceholders;
+exports.promptPlaceholderValues = promptPlaceholderValues;
+exports.replaceCommandPlaceholders = replaceCommandPlaceholders;
+exports.assertNoUnresolvedPlaceholders = assertNoUnresolvedPlaceholders;
+exports.formatPlaceholderPrompt = formatPlaceholderPrompt;
+const interactive_1 = require("./interactive");
+const key_input_1 = require("./key-input");
+class PlaceholderResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlaceholderResolutionError";
+    }
+}
+exports.PlaceholderResolutionError = PlaceholderResolutionError;
+class PlaceholderSelectionBackError extends Error {
+    constructor(message = "Return to command selection") {
+        super(message);
+        this.name = "PlaceholderSelectionBackError";
+    }
+}
+exports.PlaceholderSelectionBackError = PlaceholderSelectionBackError;
+const UNRESOLVED_PLACEHOLDER_PATTERN = /{{[^{}]*}}/;
+function resolveCommandPlaceholders(candidate_1) {
+    return __awaiter(this, arguments, void 0, function* (candidate, streams = {}) {
+        var _a, _b;
+        const input = (_a = streams.input) !== null && _a !== void 0 ? _a : process.stdin;
+        const output = (_b = streams.output) !== null && _b !== void 0 ? _b : process.stdout;
+        const values = yield promptPlaceholderValues(candidate.placeholders, { input, output });
+        const command = replaceCommandPlaceholders(candidate.command, values);
+        assertNoUnresolvedPlaceholders(command);
+        return command;
+    });
+}
+function promptPlaceholderValues(placeholders, streams) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (placeholders.length === 0) {
+            return new Map();
+        }
+        return readPlaceholderValuesWithRawInput(placeholders, streams);
+    });
+}
+function replaceCommandPlaceholders(command, values) {
+    let resolvedCommand = command;
+    for (const [name, value] of values) {
+        resolvedCommand = resolvedCommand.split(`{{${name}}}`).join(value);
+    }
+    return resolvedCommand;
+}
+function assertNoUnresolvedPlaceholders(command) {
+    if (UNRESOLVED_PLACEHOLDER_PATTERN.test(command)) {
+        throw new PlaceholderResolutionError("final command contains unresolved placeholders");
+    }
+}
+function readPlaceholderValuesWithRawInput(placeholders, streams) {
+    const { input, output } = streams;
+    return new Promise((resolve, reject) => {
+        let activeIndex = 0;
+        let renderedLineCount = 0;
+        const values = placeholders.map(() => "");
+        let buffer = "";
+        let cleanupKeypressSession;
+        const clearRenderedPrompt = () => {
+            if (renderedLineCount > 0) {
+                output.write(`\x1B[${renderedLineCount}A\x1B[J`);
+                renderedLineCount = 0;
+            }
+        };
+        const cleanup = () => {
+            cleanupKeypressSession === null || cleanupKeypressSession === void 0 ? void 0 : cleanupKeypressSession();
+            cleanupKeypressSession = undefined;
+            clearRenderedPrompt();
+        };
+        const finish = () => {
+            cleanup();
+            resolve(new Map(placeholders.map((placeholder, index) => [placeholder.name, values[index]])));
+        };
+        const cancel = () => {
+            cleanup();
+            reject(new interactive_1.InteractionCancelledError("Placeholder input cancelled"));
+        };
+        const backToSelection = () => {
+            cleanup();
+            reject(new PlaceholderSelectionBackError());
+        };
+        const render = () => {
+            const text = formatPlaceholderPrompt(placeholders, values, activeIndex, buffer);
+            clearRenderedPrompt();
+            output.write(`${text}\n`);
+            renderedLineCount = text.split("\n").length + 1;
+        };
+        const onKeypress = (inputText, key = {}) => {
+            if (key.ctrl === true && key.name === "c") {
+                cancel();
+                return;
+            }
+            if (key.name === "escape") {
+                if (activeIndex === 0) {
+                    values[0] = "";
+                    buffer = "";
+                    render();
+                    backToSelection();
+                    return;
+                }
+                values[activeIndex] = "";
+                activeIndex -= 1;
+                buffer = values[activeIndex];
+                render();
+                return;
+            }
+            if (key.name === "return" || key.name === "enter") {
+                values[activeIndex] = buffer;
+                if (activeIndex === placeholders.length - 1) {
+                    render();
+                    finish();
+                    return;
+                }
+                activeIndex += 1;
+                buffer = values[activeIndex];
+                render();
+                return;
+            }
+            if (key.name === "backspace") {
+                buffer = Array.from(buffer).slice(0, -1).join("");
+                render();
+                return;
+            }
+            if (isPrintableInput(inputText)) {
+                buffer += inputText;
+                render();
+            }
+        };
+        cleanupKeypressSession = (0, key_input_1.beginKeypressSession)(input, onKeypress);
+        render();
+    });
+}
+function formatPlaceholderPrompt(placeholders, values, activeIndex, buffer) {
+    const lines = ["", "? Fill command placeholders", ""];
+    placeholders.slice(0, activeIndex + 1).forEach((placeholder, index) => {
+        lines.push(`${placeholder.name}: ${placeholder.description}`);
+        if (index < activeIndex) {
+            lines.push(`> ${values[index]}`);
+        }
+        else if (index === activeIndex) {
+            lines.push(`> ${buffer}`);
+        }
+        if (index <= activeIndex && index < placeholders.length - 1) {
+            lines.push("");
+        }
+    });
+    lines.push("");
+    lines.push("Press Enter for next value, Esc to go back, Ctrl+C to cancel.");
+    return lines.join("\n");
+}
+function isPrintableInput(inputText) {
+    return inputText.length > 0 && !/[\x00-\x1F\x7F]/.test(inputText);
+}

package/dist/ui/tty.js

@@ -0,0 +1,17 @@
+export class InteractiveTtyError extends Error {
+    constructor(message = "Interactive mode requires a TTY. Run howto in an interactive terminal or use --print.") {
+        super(message);
+        this.name = "InteractiveTtyError";
+    }
+}
+export class InteractionCancelledError extends Error {
+    constructor(message = "Interactive selection cancelled") {
+        super(message);
+        this.name = "InteractionCancelledError";
+    }
+}
+export function ensureInteractiveTty(input, output) {
+    if (input.isTTY !== true || output.isTTY !== true) {
+        throw new InteractiveTtyError();
+    }
+}

package/dist/validation/ai-response.js

@@ -0,0 +1,102 @@
+export class AiResponseValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AiResponseValidationError";
+    }
+}
+const PLACEHOLDER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const PLACEHOLDER_REFERENCE_PATTERN = /{{([^{}]*)}}/g;
+export function parseAndValidateAiResponse(rawText) {
+    const parsed = parseJsonObject(rawText);
+    const commands = readCommands(parsed);
+    return {
+        commands: commands.map((command, index) => validateCommandCandidate(command, index)),
+    };
+}
+function parseJsonObject(rawText) {
+    try {
+        return JSON.parse(rawText);
+    }
+    catch (_a) {
+        throw new AiResponseValidationError("AI response is not valid JSON");
+    }
+}
+function readCommands(value) {
+    const root = asRecord(value, "AI response root must be a JSON object");
+    const commands = root.commands;
+    if (!Array.isArray(commands)) {
+        throw new AiResponseValidationError("AI response must contain a commands array");
+    }
+    if (commands.length < 1 || commands.length > 3) {
+        throw new AiResponseValidationError("commands array must contain 1 to 3 items");
+    }
+    return commands;
+}
+function validateCommandCandidate(value, index) {
+    const path = `commands[${index}]`;
+    const candidate = asRecord(value, `${path} must be an object`);
+    const title = readNonEmptyString(candidate.title, `${path}.title`);
+    const command = readNonEmptyString(candidate.command, `${path}.command`);
+    const description = readNonEmptyString(candidate.description, `${path}.description`);
+    const placeholders = readPlaceholders(candidate.placeholders, path);
+    validatePlaceholderReferences(command, placeholders, path);
+    return {
+        title,
+        command,
+        description,
+        placeholders,
+    };
+}
+function readPlaceholders(value, candidatePath) {
+    const path = `${candidatePath}.placeholders`;
+    if (!Array.isArray(value)) {
+        throw new AiResponseValidationError(`${path} must be an array`);
+    }
+    return value.map((placeholder, index) => validatePlaceholder(placeholder, `${path}[${index}]`));
+}
+function validatePlaceholder(value, path) {
+    const placeholder = asRecord(value, `${path} must be an object`);
+    const name = readNonEmptyString(placeholder.name, `${path}.name`);
+    const description = readNonEmptyString(placeholder.description, `${path}.description`);
+    if (!PLACEHOLDER_NAME_PATTERN.test(name)) {
+        throw new AiResponseValidationError(`${path}.name may contain only letters, numbers, underscores, or hyphens`);
+    }
+    return {
+        name,
+        description,
+    };
+}
+function validatePlaceholderReferences(command, placeholders, candidatePath) {
+    const declaredNames = new Set(placeholders.map((placeholder) => placeholder.name));
+    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}}}`);
+        }
+        if (!declaredNames.has(name)) {
+            throw new AiResponseValidationError(`${candidatePath}.command references undeclared placeholder {{${name}}}`);
+        }
+        usedNames.add(name);
+    }
+    for (const declaredName of declaredNames) {
+        if (!usedNames.has(declaredName)) {
+            throw new AiResponseValidationError(`${candidatePath}.placeholders declares unused placeholder ${declaredName}`);
+        }
+    }
+}
+function readNonEmptyString(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`);
+    }
+    return value;
+}
+function asRecord(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new AiResponseValidationError(message);
+    }
+    return value;
+}