@shubhamcodess/whatcmd 0.0.0-stage → 0.1.0

package/dist/doctor.js

@@ -0,0 +1,224 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { cacheDir, DEFAULT_MODEL, loadConfig, saveStored } from "./config.js";
+import { detectProfile, profileHeadline } from "./env.js";
+import { generate } from "./generate.js";
+import { docFor } from "./ground.js";
+import { getVersion, hasModel, isUp, listModels, pull } from "./ollama.js";
+import { bashTooOld, installHook, isHookInstalled, isHookShell, rcFile } from "./shell.js";
+import { ask, bold, canPrompt, confirm, cyan, dim, err, fail, formatBytes, green, info, ok, warn } from "./ui.js";
+import { clearWhichCache, which } from "./util.js";
+export const RECOMMENDED = [
+    { name: DEFAULT_MODEL, size: "~1.0 GB", note: "recommended: most accurate in our tests, ~0.5 s per command on a laptop CPU" },
+    { name: "qwen2.5-coder:0.5b", size: "~0.4 GB", note: "fastest, but much less accurate (62% vs 85% in our 500-case test); not recommended" },
+    { name: "qwen2.5-coder:3b", size: "~1.9 GB", note: "for a GPU or fast CPU; slower, not benchmarked yet" },
+];
+const BASH_TOO_OLD = "Your bash is older than 4.0 (macOS ships 3.2), which can't host the /w shortcut. " +
+    "Use zsh (the macOS default), or install a newer bash: brew install bash. You can still run: whatcmd <request>";
+function installCommand(p) {
+    if (p.os === "linux")
+        return "curl -fsSL https://ollama.com/install.sh | sh";
+    if (p.os === "macos" && which("brew"))
+        return "brew install ollama";
+    return null;
+}
+async function waitUp(host, ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        if (await isUp(host))
+            return true;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return false;
+}
+function startServer(bin) {
+    fs.mkdirSync(cacheDir(), { recursive: true });
+    const log = path.join(cacheDir(), "ollama.log");
+    const fd = fs.openSync(log, "a");
+    spawn(bin, ["serve"], { detached: true, stdio: ["ignore", fd, fd] }).unref();
+    return log;
+}
+async function chooseModel(installed, current) {
+    err(bold("\nChoose a model for whatcmd:"));
+    const options = [];
+    for (const r of RECOMMENDED) {
+        options.push(r.name);
+        const have = hasModel(installed, r.name) ? green("downloaded") : r.size;
+        err(`  ${options.length}) ${cyan(r.name.padEnd(20))} ${have.padEnd(12)} ${dim(r.note)}`);
+    }
+    for (const m of installed) {
+        if (RECOMMENDED.some((r) => r.name === m.name) || /embed/i.test(m.name))
+            continue;
+        options.push(m.name);
+        err(`  ${options.length}) ${cyan(m.name.padEnd(20))} ${green("downloaded")}  ${dim(formatBytes(m.size))}`);
+    }
+    err(`  ${options.length + 1}) Type another Ollama model name`);
+    const def = Math.max(1, options.indexOf(current) + 1);
+    for (;;) {
+        const a = await ask(`Choice [${def}]: `);
+        if (!a)
+            return options[def - 1];
+        const n = Number(a);
+        if (n >= 1 && n <= options.length)
+            return options[n - 1];
+        if (n === options.length + 1) {
+            const name = await ask("Model name (see https://ollama.com/library): ");
+            if (name)
+                return name;
+        }
+        else if (!/^\d+$/.test(a))
+            return a; // they typed a model name directly
+    }
+}
+export async function downloadModel(host, model) {
+    err(`Downloading ${cyan(model)} …`);
+    let last = "";
+    await pull(host, model, (status, completed, total) => {
+        const line = total && completed !== undefined ? `  ${status.slice(0, 30)} ${Math.floor((completed / total) * 100)}% of ${formatBytes(total)}` : `  ${status}`;
+        if (line === last)
+            return;
+        last = line;
+        if (process.stderr.isTTY)
+            process.stderr.write(`\r\x1b[K${line}`);
+    });
+    if (process.stderr.isTTY)
+        process.stderr.write("\r\x1b[K");
+    ok(`Downloaded ${model}`);
+}
+/** Returns true when everything needed to generate commands works. */
+export async function doctor(opts) {
+    let cfg = loadConfig();
+    const firstRun = !cfg.profile; // first run: let the user pick a model even if the default exists
+    const interactive = canPrompt() && !opts.yes;
+    err(bold("whatcmd doctor\n"));
+    // 1. System profile: goes into every prompt so commands fit this OS and its installed tools.
+    let profile = cfg.profile;
+    if (!profile || opts.refreshProfile) {
+        profile = detectProfile();
+        saveStored({ profile });
+    }
+    ok(`System: ${profileHeadline(profile)}`);
+    info(`installed tools the model may use: ${profile.installed.join(", ") || "none detected"}`);
+    // 2. Ollama installed and running?
+    let up = await isUp(cfg.host);
+    let bin = which("ollama");
+    if (!up && !bin) {
+        fail("Ollama is not installed. whatcmd runs models locally through Ollama.");
+        const cmd = installCommand(profile);
+        if (cmd)
+            info(`install it with:  ${cmd}`);
+        info("or download it from https://ollama.com/download");
+        if (cmd && interactive && (await confirm(`Run "${cmd}" now?`, false))) {
+            spawnSync("sh", ["-c", cmd], { stdio: "inherit" });
+            clearWhichCache();
+            bin = which("ollama");
+            up = await waitUp(cfg.host, 8000);
+        }
+        if (!bin && !up) {
+            info("then run `whatcmd doctor` again.");
+            return false;
+        }
+    }
+    if (!up && bin) {
+        warn(`Ollama is installed but not running at ${cfg.host}`);
+        if (opts.yes || (interactive && (await confirm("Start it in the background now?", true)))) {
+            const log = startServer(bin);
+            up = await waitUp(cfg.host, 10000);
+            if (!up)
+                fail(`Ollama did not start; see ${log}`);
+        }
+        else
+            info("start it with:  ollama serve");
+        if (!up)
+            return false;
+    }
+    ok(`Ollama ${await getVersion(cfg.host)} is running at ${cfg.host}`);
+    // 3. Model downloaded?
+    const installed = await listModels(cfg.host);
+    let model = opts.model ?? cfg.model;
+    if (!hasModel(installed, model) || (interactive && firstRun && !opts.model)) {
+        if (!hasModel(installed, model))
+            warn(`Model ${model} is not downloaded yet`);
+        if (interactive)
+            model = await chooseModel(installed, model);
+        else if (!opts.yes) {
+            info(`download it with:  whatcmd use ${model}   (or run \`whatcmd doctor\` in a terminal to pick one)`);
+            return false;
+        }
+        if (!hasModel(installed, model))
+            await downloadModel(cfg.host, model);
+    }
+    if (model !== cfg.model)
+        saveStored({ model });
+    cfg = loadConfig();
+    ok(`Model ${model} is ready`);
+    // Pre-load docs of installed tools so the first request never waits on a slow `--help`.
+    let docs = 0;
+    for (const tool of profile.installed) {
+        const p = which(tool);
+        if (p && docFor(tool, p))
+            docs++;
+    }
+    ok(`Cached local docs for ${docs} installed tools`);
+    // 4. Real test request (first one also loads the model into memory).
+    let t = performance.now();
+    const r = await generate("list files in this folder", cfg);
+    const loadMs = Math.round(performance.now() - t);
+    t = performance.now();
+    const r2 = await generate("show free disk space", cfg);
+    const ms = Math.round(performance.now() - t);
+    if (r.kind === "command" && r2.kind === "command") {
+        ok(`Test request answered in ${ms} ms ${dim(`(first call, incl. loading the model: ${loadMs} ms)`)}`);
+        info(`"show free disk space" → ${r2.command}`);
+    }
+    else
+        warn(`Model answered, but the test output was rejected (${r.kind === "rejected" ? r.reason : r2.kind === "rejected" ? r2.reason : ""}). Try another model with \`whatcmd use\`.`);
+    // 5. Shell shortcut.
+    if (opts.fromInit)
+        return true;
+    if (profile.shell === "bash" && bashTooOld())
+        warn(BASH_TOO_OLD);
+    else if (isHookShell(profile.shell)) {
+        if (isHookInstalled(profile.shell, profile.os))
+            ok(`Shell shortcut is set up: type ${cyan(`${cfg.prefix} <request>`)} at any prompt`);
+        else
+            warn(`Shell shortcut not set up yet. Run \`whatcmd init\` to enable ${cfg.prefix} <request>`);
+    }
+    else
+        warn(`${profile.shell} has no ${cfg.prefix} shortcut yet (bash and zsh do). Use: whatcmd <request>`);
+    return true;
+}
+/** First-time setup: doctor + shell shortcut. */
+export async function init(opts) {
+    const ready = await doctor({ ...opts, refreshProfile: true, fromInit: true });
+    const cfg = loadConfig();
+    const profile = cfg.profile ?? detectProfile();
+    const shell = profile.shell;
+    err("");
+    if (!isHookShell(shell)) {
+        warn(`The ${cfg.prefix} shortcut supports bash and zsh; your shell is ${shell}. You can still run: whatcmd <request>`);
+        return ready;
+    }
+    if (shell === "bash" && bashTooOld()) {
+        warn(BASH_TOO_OLD);
+        return ready;
+    }
+    const rc = rcFile(shell, profile.os);
+    if (isHookInstalled(shell, profile.os)) {
+        installHook(shell, cfg.prefix, profile.os); // refresh the hook file
+        ok(`Shell shortcut already in ${rc}`);
+    }
+    else if (opts.yes || !canPrompt() || (await confirm(`Add the ${cfg.prefix} shortcut to ${rc}?`, true))) {
+        installHook(shell, cfg.prefix, profile.os);
+        ok(`Added the shortcut to ${rc}`);
+    }
+    else {
+        info(`Skipped. To add it yourself, put this in ${rc}:  eval "$(whatcmd shell ${shell})"`);
+        return ready;
+    }
+    err(`\n${bold("Done.")} Open a new terminal (or run ${cyan(`source ${rc}`)}), then type:`);
+    err(`  ${cyan(`${cfg.prefix} find files bigger than 100MB`)}   and press Enter`);
+    err(dim("  The command appears on your prompt. Press Enter again to run it, or edit it first."));
+    return ready;
+}

package/dist/env.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { run, which } from "./util.js";
+/** Tools the model often reaches for; knowing which exist avoids "command not found". */
+export const NOTABLE_TOOLS = [
+    "ss", "netstat", "lsof", "fuser", "ip", "ifconfig", "curl", "wget", "dig", "nc",
+    "rg", "fd", "fzf", "jq", "tree", "rsync", "zip", "unzip", "7z",
+    "git", "docker", "podman", "kubectl", "systemctl", "journalctl",
+    "python3", "node", "ffmpeg", "magick", "htop",
+];
+const PACKAGE_MANAGERS = [
+    ["brew", "brew"], ["apt-get", "apt"], ["dnf", "dnf"], ["yum", "yum"], ["pacman", "pacman"],
+    ["zypper", "zypper"], ["apk", "apk"], ["nix-env", "nix"],
+];
+export function parseOsRelease(text) {
+    const get = (k) => {
+        const m = new RegExp(`^${k}=(?:"([^"]*)"|(.*))$`, "m").exec(text);
+        return m ? (m[1] ?? m[2] ?? "").trim() : "";
+    };
+    return get("PRETTY_NAME") || [get("NAME"), get("VERSION_ID")].filter(Boolean).join(" ");
+}
+export function detectProfile() {
+    const plat = process.platform;
+    const osName = plat === "linux" ? "linux" : plat === "darwin" ? "macos" : plat === "win32" ? "windows" : "other";
+    let distro = "";
+    let wsl = false;
+    if (osName === "linux") {
+        try {
+            distro = parseOsRelease(fs.readFileSync("/etc/os-release", "utf8"));
+        }
+        catch { }
+        try {
+            wsl = /microsoft/i.test(fs.readFileSync("/proc/version", "utf8"));
+        }
+        catch { }
+    }
+    else if (osName === "macos") {
+        const r = run("sw_vers", ["-productVersion"], { timeoutMs: 1000 });
+        distro = r.ok ? `macOS ${r.stdout.trim()}` : "macOS";
+    }
+    let userland = "unknown";
+    if (osName === "macos")
+        userland = "bsd";
+    else if (osName === "linux") {
+        const ls = which("ls");
+        let real = "";
+        try {
+            real = ls ? fs.realpathSync(ls) : "";
+        }
+        catch { }
+        if (/busybox/.test(real))
+            userland = "busybox";
+        else if (/GNU/.test(run("ls", ["--version"], { timeoutMs: 1000 }).stdout))
+            userland = "gnu";
+    }
+    const packageManager = PACKAGE_MANAGERS.find(([bin]) => which(bin))?.[1] ?? null;
+    const installed = NOTABLE_TOOLS.filter((t) => which(t));
+    const missing = NOTABLE_TOOLS.filter((t) => !installed.includes(t));
+    return {
+        os: osName,
+        distro,
+        wsl,
+        arch: os.arch(),
+        shell: path.basename(process.env.SHELL || "") || "sh",
+        packageManager,
+        userland,
+        installed,
+        missing,
+        detectedAt: new Date().toISOString(),
+    };
+}
+export function profileHeadline(p) {
+    const name = p.distro || p.os;
+    return `${name}${p.wsl ? " (WSL)" : ""}, ${p.arch}, ${p.shell}${p.packageManager ? `, ${p.packageManager}` : ""}`;
+}
+/** The lines added to the model's system prompt. */
+export function profilePrompt(p) {
+    const lines = [
+        `Target system: ${p.distro || p.os}${p.wsl ? " running in WSL" : ""} (${p.os}, ${p.arch}). Shell: ${p.shell}.` +
+            (p.packageManager ? ` Package manager: ${p.packageManager}.` : ""),
+    ];
+    if (p.userland === "bsd")
+        lines.push("Use macOS/BSD command flags (e.g. sed -i '', stat -f, date -v), not GNU-only flags.");
+    else if (p.userland === "busybox")
+        lines.push("Commands are BusyBox versions with limited flags.");
+    else if (p.userland === "gnu")
+        lines.push("Commands are GNU versions.");
+    if (p.installed.length)
+        lines.push(`Installed tools: ${p.installed.join(", ")}.`);
+    if (p.missing.length)
+        lines.push(`Not installed (avoid): ${p.missing.join(", ")}.`);
+    return lines.join("\n");
+}

package/dist/gate.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { which } from "./util.js";
+/**
+ * The gate decides whether model output is a real, usable shell command.
+ * Anything that is not (a NONE answer, chat text, unparseable output) produces nothing.
+ */
+export const BUILTINS = new Set(("alias bg bind break builtin caller cd command compgen complete continue declare dirs disown echo enable " +
+    "eval exec exit export false fc fg getopts hash help history jobs kill let local logout mapfile popd printf " +
+    "pushd pwd read readarray readonly return set shift shopt source suspend test times trap true type typeset " +
+    "ulimit umask unalias unset wait . : [ [[ ]] if then else elif fi for while until do done case esac in " +
+    "function select time { } ! coproc").split(" "));
+/** Prefixes that run another command; we skip them to find the real one. */
+const WRAPPERS = new Set(["sudo", "doas", "env", "nohup", "nice", "ionice", "command", "exec", "builtin", "time"]);
+/** Wrapper options that take a value, e.g. `nice -n 10 cmd`, `sudo -u bob cmd`. */
+const WRAPPER_FLAGS_WITH_ARG = {
+    sudo: new Set(["-u", "-g", "-h", "-p", "-C", "-D", "-U", "-r", "-t"]),
+    doas: new Set(["-u", "-C"]),
+    nice: new Set(["-n", "--adjustment"]),
+    ionice: new Set(["-c", "-n", "-p", "-t"]),
+    env: new Set(["-u", "--unset", "-C", "--chdir", "-S"]),
+    time: new Set(["-f", "-o", "--format", "--output"]),
+    exec: new Set(["-a"]),
+};
+/** Pull the command out of model output: drop code fences, "$ " prompts and stray backticks. */
+export function extractCommand(raw) {
+    const line = raw
+        .split("\n")
+        .map((s) => s.trim())
+        .find((s) => s && !s.startsWith("```"));
+    if (!line)
+        return "";
+    return line
+        .replace(/^(command|cmd)\s*:\s*/i, "")
+        .replace(/^\$\s+/, "")
+        .replace(/^`+|`+$/g, "")
+        .trim();
+}
+/** Split a command line into pipeline/list segments, respecting quotes. */
+export function splitSegments(cmd) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const ch = cmd[i];
+        if (quote) {
+            cur += ch;
+            if (ch === "\\" && quote === '"' && i + 1 < cmd.length)
+                cur += cmd[++i];
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            cur += ch;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < cmd.length) {
+            cur += ch + cmd[++i];
+            continue;
+        }
+        if (ch === "|" || ch === ";" || ch === "&" || ch === "\n") {
+            // keep redirections like 2>&1, >&2, &> intact
+            if (ch === "&" && (/[<>]$/.test(cur) || cmd[i + 1] === ">")) {
+                cur += ch;
+                continue;
+            }
+            out.push(cur);
+            cur = "";
+            if (cmd[i + 1] === ch || (ch === "|" && cmd[i + 1] === "&"))
+                i++;
+            continue;
+        }
+        cur += ch;
+    }
+    out.push(cur);
+    return out.map((s) => s.trim()).filter(Boolean);
+}
+function tokenize(segment) {
+    return segment.match(/(?:[^\s'"]+|'[^']*'|"(?:\\.|[^"\\])*")+/g) ?? [];
+}
+/** The program each segment runs (after skipping sudo/env/VAR=x and similar). */
+export function commandWords(cmd) {
+    const words = [];
+    for (const seg of splitSegments(cmd)) {
+        const toks = tokenize(seg.replace(/^[({!\s]+/, ""));
+        let i = 0;
+        while (i < toks.length) {
+            const t = toks[i];
+            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) {
+                i++;
+                continue;
+            }
+            if (WRAPPERS.has(t)) {
+                words.push(t);
+                i++;
+                while (i < toks.length && (toks[i].startsWith("-") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i]))) {
+                    if (WRAPPER_FLAGS_WITH_ARG[t]?.has(toks[i]))
+                        i++;
+                    i++;
+                }
+                continue;
+            }
+            words.push(t.replace(/^['"]|['"]$/g, ""));
+            break; // for xargs/timeout/watch only the wrapper itself is checked
+        }
+    }
+    return words;
+}
+export function parses(cmd) {
+    const sh = which("bash") ? "bash" : which("sh") ? "sh" : null;
+    if (!sh)
+        return true;
+    const r = spawnSync(sh, ["-n", "-c", cmd], { stdio: "ignore", timeout: 1000 });
+    return r.status === 0;
+}
+export function commandExists(word) {
+    if (BUILTINS.has(word))
+        return true;
+    if (word.startsWith("~"))
+        return true; // user path; can't resolve reliably
+    if (word.includes("/")) {
+        try {
+            fs.accessSync(word);
+            return true;
+        }
+        catch {
+            return word.startsWith("./") || word.startsWith("../"); // a script the user may be about to create
+        }
+    }
+    return which(word) !== null;
+}
+const RISKS = [
+    [/\brm\s+(-[a-zA-Z]*\s+)*-[a-zA-Z]*[rR][a-zA-Z]*\s+(-[a-zA-Z]*\s+)*(\/|~|\$HOME|\/\*)(\s|$)/, "deletes your whole system or home folder"],
+    [/\brm\s+(-[a-zA-Z]*\s+)*(-[a-zA-Z]*[rR]|--recursive)/, "deletes files recursively"],
+    [/\bdd\b[^|;&]*\bof=/, "dd overwrites the target file or disk"],
+    [/\bmkfs(\.\w+)?\b|\bwipefs\b|\bfdisk\b|\bparted\b/, "formats or repartitions a disk"],
+    [/>\s*\/dev\/(sd|nvme|hd|disk|mmcblk)/, "writes directly to a disk device"],
+    [/:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, "fork bomb: will freeze the machine"],
+    [/\bchmod\s+(-[a-zA-Z]+\s+)*([0-7]?[0-7]{2}[2367]\b|[ugoa]*[ao][ugoa]*\+[rwxXst]*w)/, "makes files writable by everyone"],
+    [/\bch(own|mod)\s+(-[a-zA-Z]*R|--recursive)/, "changes ownership/permissions recursively"],
+    [/\b(shutdown|reboot|halt|poweroff)\b/, "shuts down or restarts the machine"],
+    [/\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|da)?sh\b|\b(ba|z|da)?sh\s+-c\s+["']?\$\(\s*(curl|wget)\b|(\b(ba|z|da)?sh|\bsource|^\.)\s+<\(\s*(curl|wget)\b/, "runs a script downloaded from the internet"],
+    [/\bgit\s+(push\b[^|;&]*(--force|-f)\b|reset\s+--hard|clean\s+-[a-z]*f)/, "discards git history or local changes"],
+    [/\bkill(all)?\s+(-9|-KILL)\s+-1\b/, "kills all your processes"],
+    [/\bsudo\b/, "runs as root"],
+    [/\/path\/to\b|<[a-z_-]+>|\b(YOUR|your)_[A-Za-z_]+|\bPID\b|\byour-[a-z-]+/, "contains a placeholder: edit it before running"],
+];
+export function riskWarnings(cmd) {
+    const out = [];
+    for (const [re, msg] of RISKS) {
+        if (!re.test(cmd))
+            continue;
+        if (msg === "deletes files recursively" && out.includes("deletes your whole system or home folder"))
+            continue;
+        out.push(msg);
+    }
+    return out;
+}
+export function check(raw, exists = commandExists) {
+    const command = extractCommand(raw);
+    if (!command)
+        return { ok: false, reason: "empty" };
+    if (/^NONE\b/i.test(command))
+        return { ok: false, reason: "not-a-shell-task" };
+    if (!parses(command))
+        return { ok: false, reason: "unparseable" };
+    const words = commandWords(command);
+    const segments = splitSegments(command);
+    if (segments.length === 1 && /^(echo|printf)$/.test(words[0] ?? "") && !/[$`>]/.test(command))
+        return { ok: false, reason: "chat-reply" };
+    const missing = [...new Set(words.filter((w) => !exists(w)))];
+    return { ok: true, command, missing, risks: riskWarnings(command) };
+}
+/** A missing first word that doesn't even look like a program name is prose, not a command. */
+export function looksLikeProgramName(word) {
+    return /^[a-z][a-z0-9._+-]*$/.test(word);
+}

package/dist/generate.js

@@ -0,0 +1,120 @@
+import { detectProfile } from "./env.js";
+import { check, looksLikeProgramName } from "./gate.js";
+import { ground } from "./ground.js";
+import { alternativeFor, autofix, isCalculatorAnswer, isDegenerate, isInjection, lint, looksLikeShellTask } from "./lint.js";
+import { chat } from "./ollama.js";
+import { buildMessages, copiesExample, missingHint } from "./prompt.js";
+const MAX_CALLS = 3;
+const since = (t) => Math.round(performance.now() - t);
+const normWords = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+/** The model sometimes just repeats the request ("zorbctl set the level to 5"). */
+export function echoesRequest(cmd, ask) {
+    if (normWords(cmd) === normWords(ask))
+        return true;
+    if (/[-./|>$=<'"`*]/.test(cmd))
+        return false;
+    const words = normWords(cmd).split(" ");
+    if (words.length < 4)
+        return false;
+    const askWords = new Set(normWords(ask).split(" "));
+    return words.filter((w) => askWords.has(w)).length / words.length >= 0.8;
+}
+function evaluate(raw, ask, profile) {
+    const verdict = check(raw);
+    if (!verdict.ok)
+        return { verdict, issues: [], echoed: false };
+    if (isDegenerate(verdict.command))
+        return { verdict: { ok: false, reason: "unparseable" }, issues: [], echoed: false };
+    if (isCalculatorAnswer(verdict.command, ask))
+        return { verdict: { ok: false, reason: "chat-reply" }, issues: [], echoed: false };
+    const command = autofix(verdict.command, profile);
+    const fixed = command === verdict.command ? verdict : { ...verdict, command };
+    const echoed = echoesRequest(command, ask) || copiesExample(command, ask);
+    return { verdict: fixed, issues: lint(command, profile), echoed };
+}
+/** Lower is better: used to keep the better of two attempts. */
+function badness(c) {
+    if (!c.verdict.ok)
+        return 100;
+    return (c.echoed ? 10 : 0) + c.verdict.missing.length * 2 + c.issues.length;
+}
+function fixHint(c, profile) {
+    if (!c.verdict.ok)
+        return "";
+    const parts = [];
+    if (c.echoed)
+        parts.push("That repeats the request instead of giving a command. Use the program's real options (see the documentation above if given).");
+    if (c.verdict.missing.length) {
+        const alts = c.verdict.missing.map((m) => [m, alternativeFor(m, profile)]).filter(([, a]) => a);
+        parts.push(missingHint(c.verdict.missing, profile));
+        for (const [m, a] of alts)
+            parts.push(`Instead of ${m}, use: ${a}.`);
+    }
+    for (const i of c.issues)
+        parts.push(i.hint + ".");
+    return parts.join(" ");
+}
+export async function generate(ask, cfg) {
+    const debug = { refs: [], groundNotes: [], outputs: [], retries: [], timings: {}, messages: [] };
+    if (!/[a-z0-9]/i.test(ask))
+        return { kind: "rejected", reason: "empty", debug };
+    if (isInjection(ask))
+        return { kind: "rejected", reason: "not-a-shell-task", debug };
+    const profile = cfg.profile ?? detectProfile();
+    const t = performance.now();
+    debug.refs = cfg.grounding ? ground(ask, profile, 2, debug.groundNotes) : [];
+    debug.timings.groundMs = since(t);
+    let messages = buildMessages(ask, profile, debug.refs, cfg.notes);
+    debug.messages = messages;
+    const call = async () => {
+        const t0 = performance.now();
+        const out = await chat(cfg.host, { model: cfg.model, messages, temperature: cfg.temperature, keepAlive: cfg.keepAlive, timeoutMs: cfg.timeoutMs });
+        debug.timings[`llm${debug.outputs.length + 1}Ms`] = since(t0);
+        debug.outputs.push(out);
+        return out;
+    };
+    const retry = async (prev, hint, why) => {
+        debug.retries.push(why);
+        messages.push({ role: "assistant", content: prev }, { role: "user", content: hint });
+        return evaluate(await call(), ask, profile);
+    };
+    let best = evaluate(await call(), ask, profile);
+    // Second chance for a NONE on a request that is clearly about this computer.
+    if (!best.verdict.ok && best.verdict.reason === "not-a-shell-task" && looksLikeShellTask(ask)) {
+        // A fresh prompt without the NONE option (small models refuse too eagerly when it's offered).
+        // Safe because looksLikeShellTask is narrow and calculator/injection answers are filtered.
+        debug.retries.push("second-chance");
+        messages = buildMessages(ask, profile, debug.refs, cfg.notes, true);
+        debug.messages = messages;
+        const again = evaluate(await call(), ask, profile);
+        if (again.verdict.ok && !again.echoed)
+            best = again;
+    }
+    // One fix-up retry for missing tools, OS-specific mistakes or an echoed request.
+    if (best.verdict.ok && badness(best) > 0 && debug.outputs.length < MAX_CALLS) {
+        const prev = best.verdict.command;
+        const again = await retry(prev, fixHint(best, profile), "fix");
+        if (again.verdict.ok) {
+            if (badness(again) <= badness(best))
+                best = again;
+        }
+        else if (!/\s/.test(prev)) {
+            // A bare word like "hi" that the model then calls NONE was a chat reply, not a command.
+            return { kind: "rejected", reason: again.verdict.reason, debug };
+        }
+    }
+    const v = best.verdict;
+    if (!v.ok)
+        return { kind: "rejected", reason: v.reason, debug };
+    if (best.echoed)
+        return { kind: "rejected", reason: "chat-reply", debug };
+    const first = v.missing[0];
+    if (first && !looksLikeProgramName(first))
+        return { kind: "rejected", reason: "chat-reply", debug };
+    const warnings = [
+        ...v.missing.map((m) => `${m} is not installed on this system`),
+        ...best.issues.map((i) => i.warning),
+        ...v.risks,
+    ];
+    return { kind: "command", command: v.command, warnings, debug };
+}