@shubhamcodess/whatcmd 0.0.0-stage → 0.1.0

package/dist/ground.js

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cacheDir } from "./config.js";
+import { run, which } from "./util.js";
+// Words that are ordinary English in requests (some are also program names).
+const STOP = new Set(("a an the and or but if of to in on at by for with from into onto out up down over under about than then " +
+    "this that these those it its is are was were be been do does did done can could should would will shall " +
+    "i me my mine you your we our they them their he she his her what which who whom whose where when why how " +
+    "all any each every some many much more most less least few no not only just also very too so here there " +
+    "please show list display print get give find search look see check tell make create new delete remove " +
+    "count number size sizes big bigger biggest large larger largest small smaller latest last first lines line " +
+    "file files folder folders directory directories dir dirs current recursively recursive inside within " +
+    "named called using use used run running start stop restart open close install installed update upgrade " +
+    "version info details process processes port ports memory disk space usage free used total time today " +
+    "week day days hour hours minute minutes ago older newer old word words text string contains containing " +
+    "between same different every everything something nothing all one two three ten hidden human readable " +
+    "format convert change rename move copy kill want need like way ok thanks hi hello mb gb kb").split(" "));
+// Tools every model knows well; grounding them costs prompt time for no gain.
+const COMMON = new Set(("ls cd cp mv rm mkdir rmdir find grep sed awk cat head tail sort uniq wc cut tr xargs tar gzip gunzip zip " +
+    "unzip chmod chown ln touch echo printf ps kill pkill killall top free df du date ssh scp curl wget git " +
+    "ping which whoami id env export less more diff stat mount umount sudo apt apt-get yum dnf brew pacman " +
+    "man history clear sh bash zsh").split(" "));
+// Never execute these with --help (some ignore it and act). Their man pages are still used.
+const NO_EXEC = new Set(("reboot shutdown halt poweroff init telinit rm dd shred wipefs kill killall pkill fdisk parted sudo su " +
+    "login passwd yes cat tee sh bash zsh fish dash python python3 node perl ruby nc telnet ssh").split(" "));
+export function candidates(ask) {
+    const toks = ask.toLowerCase().match(/[a-z0-9][a-z0-9._+-]*/g) ?? [];
+    const out = [];
+    for (let t of toks) {
+        t = t.replace(/\.+$/, "");
+        if (t.length < 2 || STOP.has(t) || COMMON.has(t) || /^\d+[a-z]{0,2}$/.test(t))
+            continue;
+        if (!out.includes(t))
+            out.push(t);
+    }
+    return out;
+}
+function stems(text) {
+    const s = new Set();
+    for (const w of text.toLowerCase().match(/[a-z][a-z0-9]{2,}/g) ?? [])
+        if (!STOP.has(w))
+            s.add(w.slice(0, 5));
+    return s;
+}
+/** Keep the description, the usage line, and the option lines that match the request. */
+export function relevantExcerpt(doc, ask, maxChars = 900) {
+    const lines = doc.replace(/.\x08/g, "").split("\n");
+    const after = (re) => {
+        const i = lines.findIndex((l) => re.test(l.trim()));
+        return i >= 0 ? (lines.slice(i + 1).find((l) => l.trim()) ?? "").trim() : "";
+    };
+    const description = after(/^NAME$/);
+    const usage = after(/^SYNOPSIS$/) || (lines.find((l) => /^\s*usage:/i.test(l)) ?? "").trim();
+    const chunks = [];
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const opt = /^(\s*)-{1,2}[A-Za-z0-9]/.exec(l);
+        const sub = /^(\s{2,})[a-z][a-z0-9-]+\s{2,}\S/.exec(l); // "  ps        List containers"
+        const m = opt ?? sub;
+        if (!m)
+            continue;
+        const indent = m[1].length;
+        let text = l.trim();
+        for (let j = i + 1; j < lines.length && j <= i + 3; j++) {
+            const n = lines[j];
+            if (!n.trim() || /^\s*-{1,2}[A-Za-z0-9]/.test(n))
+                break;
+            if (n.length - n.trimStart().length <= indent)
+                break;
+            text += " " + n.trim();
+        }
+        chunks.push({ i, text: text.replace(/\s+/g, " ") });
+    }
+    const want = stems(ask);
+    const scored = chunks
+        .map((c) => ({ ...c, score: [...stems(c.text)].filter((s) => want.has(s)).length }))
+        .filter((c) => c.score > 0)
+        .sort((a, b) => b.score - a.score || a.i - b.i)
+        .slice(0, 8)
+        .sort((a, b) => a.i - b.i);
+    const picked = scored.length ? scored : chunks.slice(0, 6);
+    const parts = [description || (usage ? "" : (lines.find((l) => l.trim()) ?? "").trim()), usage && `Usage: ${usage.replace(/^usage:\s*/i, "")}`]
+        .filter(Boolean)
+        .concat(picked.map((c) => c.text));
+    let out = "";
+    for (const p of parts) {
+        if (out.length + p.length + 1 > maxChars)
+            break;
+        out += (out ? "\n" : "") + p;
+    }
+    return out;
+}
+function cacheFile(name, binPath) {
+    let key = `v2-${name}`; // bump the version to invalidate caches when doc extraction changes
+    try {
+        key += "-" + Math.floor(fs.statSync(binPath).mtimeMs);
+    }
+    catch { }
+    return path.join(cacheDir(), "docs", key.replace(/[^a-zA-Z0-9._+-]/g, "_") + ".txt");
+}
+/** Local docs for a program: man page first (no execution), else `--help`. Cached per binary version. */
+export function docFor(name, binPath, notes = []) {
+    const file = cacheFile(name, binPath);
+    try {
+        const cached = fs.readFileSync(file, "utf8");
+        if (!cached) {
+            notes.push(`${name}: cached as "no docs" (${file})`);
+            return null;
+        }
+        const nl = cached.indexOf("\n");
+        return { source: cached.slice(0, nl), text: cached.slice(nl + 1) };
+    }
+    catch { }
+    let found = null;
+    let timedOut = false;
+    if (which("man")) {
+        const r = run("man", ["-P", "cat", name], { timeoutMs: 3000, env: { MANWIDTH: "100", LANG: "C", MAN_KEEP_FORMATTING: "" } });
+        // Minimized distro images print a stub instead of the page, so require real man sections.
+        if (r.ok && /^(NAME|SYNOPSIS|DESCRIPTION)\s*$/m.test(r.stdout.replace(/.\x08/g, "")))
+            found = { source: "man", text: r.stdout };
+    }
+    if (!found && !NO_EXEC.has(name) && !/^mkfs/.test(name)) {
+        for (const flag of ["--help", "-h"]) {
+            // First runs of big binaries can be slow (macOS verifies them), so allow 3 s.
+            const r = run(binPath, [flag], { timeoutMs: 3000, env: { LANG: "C", NO_COLOR: "1" } });
+            timedOut ||= r.timedOut;
+            if (r.timedOut)
+                notes.push(`${name}: ${flag} timed out after 3000 ms`);
+            const text = r.stdout.length > r.stderr.length ? r.stdout : r.stderr;
+            if (text.trim().length > 40) {
+                found = { source: "help", text };
+                break;
+            }
+        }
+    }
+    // Never cache a timeout as "no docs": the next request should try again.
+    if (found || !timedOut) {
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, found ? `${found.source}\n${found.text}` : "");
+        }
+        catch { }
+    }
+    return found;
+}
+const binsFrom = (list) => [...new Set(list.split("\n").filter((l) => /\/s?bin\/[^/]+$/.test(l.trim())).map((l) => path.basename(l.trim())))];
+/** Metadata of an installed system package, or null if it isn't installed. */
+export function packageInfo(name, pm) {
+    const t = { timeoutMs: 800 };
+    if (pm === "apt") {
+        const r = run("dpkg-query", ["-W", "-f=${Status}\t${Version}\t${binary:Summary}", name], t);
+        if (!r.ok || !r.stdout.includes("install ok installed"))
+            return null;
+        const [, version = "", summary = ""] = r.stdout.split("\t");
+        return { version, summary, bins: binsFrom(run("dpkg", ["-L", name], t).stdout) };
+    }
+    if (pm === "dnf" || pm === "yum" || pm === "zypper") {
+        const r = run("rpm", ["-q", "--qf", "%{VERSION}\t%{SUMMARY}", name], t);
+        if (!r.ok)
+            return null;
+        const [version = "", summary = ""] = r.stdout.split("\t");
+        return { version, summary, bins: binsFrom(run("rpm", ["-ql", name], t).stdout) };
+    }
+    if (pm === "pacman") {
+        const r = run("pacman", ["-Qi", name], t);
+        if (!r.ok)
+            return null;
+        const field = (k) => new RegExp(`^${k}\\s*:\\s*(.*)$`, "m").exec(r.stdout)?.[1]?.trim() ?? "";
+        return { version: field("Version"), summary: field("Description"), bins: binsFrom(run("pacman", ["-Qlq", name], t).stdout) };
+    }
+    if (pm === "apk") {
+        if (!run("apk", ["info", "-e", name], t).ok)
+            return null;
+        const d = run("apk", ["info", "-d", name], t).stdout.split("\n").slice(1).join(" ").trim();
+        return { version: "", summary: d, bins: binsFrom(run("apk", ["info", "-L", name], t).stdout) };
+    }
+    return null; // brew/nix: too slow to query on every request; installed commands are still grounded via docs
+}
+/** `notes` (optional) collects one line per candidate explaining what happened, for --debug. */
+export function ground(ask, profile, maxRefs = 2, notes = []) {
+    const refs = [];
+    let lookups = 0;
+    for (const cand of candidates(ask)) {
+        if (refs.length >= maxRefs)
+            break;
+        const bin = which(cand);
+        if (bin) {
+            const t = performance.now();
+            const doc = docFor(cand, bin, notes);
+            if (doc)
+                refs.push({ name: cand, source: doc.source, text: relevantExcerpt(doc.text, ask) });
+            notes.push(`${cand}: ${bin} -> ${doc ? `docs from ${doc.source}` : "no docs"} (${Math.round(performance.now() - t)} ms)`);
+            continue;
+        }
+        if (!profile?.packageManager || lookups >= 4 || !/^[a-z][a-z0-9+-]+$/.test(cand)) {
+            notes.push(`${cand}: not on PATH`);
+            continue;
+        }
+        lookups++;
+        const pkg = packageInfo(cand, profile.packageManager);
+        if (!pkg) {
+            notes.push(`${cand}: not on PATH, not an installed ${profile.packageManager} package`);
+            continue;
+        }
+        let text = `Installed package ${cand}${pkg.version ? ` ${pkg.version}` : ""}: ${pkg.summary}`;
+        if (pkg.bins.length)
+            text += `\nProvides commands: ${pkg.bins.slice(0, 12).join(", ")}`;
+        const main = pkg.bins.includes(cand) ? cand : pkg.bins[0];
+        const mainBin = main ? which(main) : null;
+        if (main && mainBin) {
+            const doc = docFor(main, mainBin);
+            if (doc)
+                text += `\n${relevantExcerpt(doc.text, ask, 700)}`;
+        }
+        refs.push({ name: cand, source: "package", text });
+    }
+    return refs;
+}

package/dist/lint.js

@@ -0,0 +1,122 @@
+const BSD_RULES = [
+    [/\bdate\b[^|;&]*\s(-d|--date)\b/, { warning: "uses GNU date -d (macOS date uses -v)", hint: "macOS date has no -d; use -v, e.g. date -v-30d +%F" }],
+    [/\bstat\s+(-[a-zA-Z]+\s+)*(-c|--format)\b/, { warning: "uses GNU stat -c (macOS stat uses -f)", hint: "macOS stat has no -c; use stat -f, e.g. stat -f %z file" }],
+    [/\bgrep\s+(-[a-zA-Z]*\s+)*-[a-zA-Z]*P/, { warning: "uses grep -P (not on macOS)", hint: "macOS grep has no -P; use grep -E" }],
+    [/\bxargs\s+(-[a-zA-Z]*\s+)*-r\b/, { warning: "uses GNU xargs -r", hint: "macOS xargs has no -r; drop it" }],
+    [/\bfind\b[^|;&]*\s-printf\b/, { warning: "uses GNU find -printf", hint: "macOS find has no -printf; use -exec stat -f ... or -print" }],
+    [/\b(ls|du|df|sort)\b[^|;&]*\s--[a-z]/, { warning: "uses GNU long options", hint: "macOS ls/du/df/sort take short options only (no --long-options)" }],
+];
+/** Equivalents to suggest when a tool is missing. */
+const ALTERNATIVES = {
+    macos: {
+        free: "vm_stat, or: top -l 1 | grep PhysMem, or: sysctl hw.memsize",
+        lsblk: "diskutil list",
+        lscpu: "sysctl -n machdep.cpu.brand_string, sysctl hw.ncpu",
+        nproc: "sysctl -n hw.ncpu",
+        lsusb: "system_profiler SPUSBDataType",
+        systemctl: "brew services (list|start|stop|restart) NAME, or launchctl",
+        service: "brew services, or launchctl",
+        journalctl: "log show --last 1h",
+        ip: "ifconfig, or: route -n get default",
+        "xdg-open": "open",
+        xclip: "pbcopy / pbpaste",
+        xsel: "pbcopy / pbpaste",
+        pidof: "pgrep",
+        ss: "lsof -iTCP -sTCP:LISTEN -n -P",
+        netstat: "lsof -i -n -P",
+        sha256sum: "shasum -a 256",
+        md5sum: "md5",
+        tac: "tail -r",
+        apt: "brew",
+        "apt-get": "brew",
+    },
+    linux: {
+        netstat: "ss (e.g. ss -tulpn)",
+        ifconfig: "ip addr",
+        route: "ip route",
+        traceroute: "tracepath",
+        nslookup: "getent hosts, or dig",
+        open: "xdg-open",
+        pbcopy: "xclip -selection clipboard",
+        pbpaste: "xclip -selection clipboard -o",
+        sw_vers: "cat /etc/os-release",
+        diskutil: "lsblk",
+        "system_profiler": "lscpu / lsusb / lspci",
+        brew: "the system package manager",
+    },
+};
+export function lint(cmd, profile) {
+    if (profile?.userland !== "bsd")
+        return [];
+    return BSD_RULES.filter(([re]) => re.test(cmd)).map(([, issue]) => issue);
+}
+/** Safe, deterministic rewrites. Today: `sed -i 's/…'` → `sed -i '' 's/…'` on macOS. */
+export function autofix(cmd, profile) {
+    if (profile?.userland !== "bsd")
+        return cmd;
+    return cmd.replace(/\bsed\s+-i\s+(?=['"]?(s|y)[^a-z]|-e\b|['"]?\d|['"]?\/)/g, "sed -i '' ");
+}
+export function alternativeFor(tool, profile) {
+    if (!profile)
+        return null;
+    return ALTERNATIVES[profile.os]?.[tool] ?? null;
+}
+/**
+ * Signals that a request is about this computer. When the model answers NONE to such a
+ * request, it gets a second chance; requests without these signals keep the NONE.
+ */
+const SHELL_WORDS = new RegExp("\\b(" +
+    [
+        "files?", "folders?", "director(y|ies)", "disk space", "drives?", "partitions?", "mounted",
+        "pid", "ports?", "dns", "ip address", "hostname", "ping", "wifi", "network",
+        "cpu", "ram", "swap", "uptime", "kernel", "battery", "usb",
+        "permissions?", "logged in", "sudo", "user \\w+ (to|from|in) (the )?\\w+ group", "groups (am i|i'?m) in",
+        "password (of|for) (the )?user", "users on this", "owner of",
+        "git", "commits?", "branch(es)?", "repo(sitory)?", "stash", "docker", "containers?",
+        "cron", "daemon", "env(ironment)? var(iable)?s?",
+        "archive", "zip", "tar", "unzip",
+        "shell", "terminal", "bash", "zsh", "my (computer|machine|mac|laptop)", "this (computer|machine|mac|laptop)",
+    ].join("|") +
+    ")\\b", "i");
+/** Prompt-injection phrasing: never treat as a task. */
+export function isInjection(ask) {
+    return /\b(ignore|disregard|forget)\b.{0,40}\b(instructions?|prompt|rules|above)\b/i.test(ask);
+}
+/**
+ * Commands that only do arithmetic or transform literal text ("echo 60/1.5 | bc", "echo hello | tr …")
+ * are the model answering a question, unless the user asked for it in the shell.
+ */
+export function isCalculatorAnswer(original, ask) {
+    let cmd = original;
+    if (/\b(shell|terminal|bash|zsh|command line|bc|awk|calculate in)\b/i.test(ask))
+        return false;
+    // Inline arithmetic like "$(echo 240*15/100 | bc)" or "$((2+2))" counts as literal text.
+    let prev = "";
+    while (prev !== cmd) {
+        prev = cmd;
+        cmd = cmd.replace(/\$\(\s*(echo|printf)\s+[^$()`|]*\|\s*bc(\s+-l)?\s*\)/g, "N").replace(/\$\(\([^()]*\)\)/g, "N");
+    }
+    if (/^(echo|printf)\s+[^|$`<>]*$/.test(cmd) && cmd !== original)
+        return true;
+    if (/^expr\s/.test(cmd))
+        return true;
+    // echo/printf of literal text (no variables or files) into calculators or text filters only
+    const m = /^(echo|printf)\s+([^|$`<>]*?)\s*((\|\s*(bc|bc -l|tr|sed|awk|rev|cut|wc|python3?|perl)\b[^|<>]*)+)$/.exec(cmd);
+    return Boolean(m && !/[$`]/.test(m[3]));
+}
+export function looksLikeShellTask(ask) {
+    if (isInjection(ask))
+        return false;
+    return (SHELL_WORDS.test(ask) ||
+        /\b[\w-]*[a-z][\w-]*\.[a-z][a-z0-9]{0,4}\b/i.test(ask) || // a filename like report.pdf (not "1.5")
+        /(^|\s)[~/.][\w./-]*/.test(ask) || // a path
+        /\b\d{1,3}(\.\d{1,3}){3}\b/.test(ask) || // an IP address
+        /https?:\/\//.test(ask));
+}
+/** Small models sometimes loop: "photos photos photos …" or "Rational::Rational::…". */
+export function isDegenerate(cmd) {
+    const toks = cmd.split(/[^A-Za-z0-9_]+/).filter(Boolean);
+    if (toks.length < 16)
+        return false;
+    return new Set(toks).size / toks.length < 0.35;
+}

package/dist/ollama.js

@@ -0,0 +1,92 @@
+export class OllamaError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+async function request(host, p, init, timeoutMs) {
+    try {
+        return await fetch(host + p, {
+            ...init,
+            headers: { "content-type": "application/json" },
+            signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined,
+        });
+    }
+    catch (e) {
+        const name = e?.name;
+        if (name === "TimeoutError" || name === "AbortError")
+            throw new OllamaError(`Ollama did not answer within ${timeoutMs} ms (the model may still be loading from disk; try again in a moment)`, "timeout");
+        throw new OllamaError(`Cannot reach Ollama at ${host}`, "unreachable");
+    }
+}
+export async function getVersion(host, timeoutMs = 1500) {
+    const r = await request(host, "/api/version", {}, timeoutMs);
+    if (!r.ok)
+        throw new OllamaError(`Ollama answered HTTP ${r.status}`, "http");
+    return (await r.json()).version;
+}
+export async function isUp(host) {
+    try {
+        await getVersion(host);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listModels(host) {
+    const r = await request(host, "/api/tags", {}, 5000);
+    if (!r.ok)
+        throw new OllamaError(`Ollama answered HTTP ${r.status}`, "http");
+    const j = (await r.json());
+    return (j.models ?? []).map((m) => ({ name: m.name, size: m.size }));
+}
+const norm = (m) => (m.includes(":") ? m : `${m}:latest`);
+export const sameModel = (a, b) => norm(a) === norm(b);
+export const hasModel = (models, name) => models.some((m) => sameModel(m.name, name));
+function keepAliveValue(v) {
+    return /^-?\d+$/.test(v) ? Number(v) : v;
+}
+export async function chat(host, o) {
+    const r = await request(host, "/api/chat", {
+        method: "POST",
+        body: JSON.stringify({
+            model: o.model,
+            messages: o.messages,
+            stream: false,
+            keep_alive: keepAliveValue(o.keepAlive),
+            options: { temperature: o.temperature, num_predict: 96, stop: ["\n\n", "\n```\n"] },
+        }),
+    }, o.timeoutMs);
+    if (!r.ok) {
+        const body = await r.text();
+        if (r.status === 404 && /not found/i.test(body))
+            throw new OllamaError(`Model "${o.model}" is not downloaded`, "model_missing");
+        throw new OllamaError(`Ollama error ${r.status}: ${body.slice(0, 200)}`, "http");
+    }
+    const j = (await r.json());
+    return j.message?.content ?? "";
+}
+/** Download a model, reporting progress. */
+export async function pull(host, model, onProgress) {
+    const r = await request(host, "/api/pull", { method: "POST", body: JSON.stringify({ model, stream: true }) });
+    if (!r.ok || !r.body)
+        throw new OllamaError(`Pull failed: HTTP ${r.status} ${await r.text()}`, "http");
+    const dec = new TextDecoder();
+    let buf = "";
+    for await (const chunk of r.body) {
+        buf += dec.decode(chunk, { stream: true });
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, i).trim();
+            buf = buf.slice(i + 1);
+            if (!line)
+                continue;
+            const j = JSON.parse(line);
+            if (j.error)
+                throw new OllamaError(j.error, "http");
+            onProgress(j.status ?? "", j.completed, j.total);
+        }
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,67 @@
+import { profilePrompt } from "./env.js";
+const RULES = `You convert a request into ONE shell command for the user's system. Output only the command, no explanation, no backticks.
+If the request is not a task that can be done with a shell command on this computer, output exactly: NONE`;
+/** Few-shot turns. Includes NONE examples so the model learns to refuse non-shell requests. */
+export const SHOTS = [
+    ["list all files including hidden ones", "ls -la"],
+    ["write a haiku about cats", "NONE"],
+    ["find python files modified in the last day", "find . -name '*.py' -mtime -1"],
+    ["what is the capital of Japan", "NONE"],
+    ["show disk usage of current folder in human readable form", "du -sh ."],
+];
+/**
+ * Extra examples for the second-chance prompt, which has no NONE option. It only runs when
+ * looksLikeShellTask() says the request is about this computer; arithmetic/text answers and
+ * prompt injections are filtered afterwards, so non-shell questions still produce nothing.
+ */
+const SECOND_SHOTS = [
+    ["how long has this machine been up", "uptime"],
+    ["show who changed each line of main.c", "git blame main.c"],
+    ["what are the name servers for example.org", "dig NS example.org"],
+];
+const COMMON_WORDS = new Set("the and for with all show list this that from into what are how has who each your".split(" "));
+const contentWords = (s) => new Set((s.toLowerCase().match(/[a-z0-9]{3,}/g) ?? []).filter((w) => !COMMON_WORDS.has(w)));
+/**
+ * Small models sometimes answer with an example's command verbatim ("ls -la" for anything).
+ * That's a copy, not an answer, when the request shares no content word with that example.
+ */
+export function copiesExample(command, ask) {
+    const askWords = contentWords(ask);
+    return SHOTS.some(([q, a]) => a !== "NONE" && a === command && ![...contentWords(q)].some((w) => askWords.has(w)));
+}
+export function systemPrompt(profile, notes) {
+    const parts = [RULES];
+    if (profile)
+        parts.push(profilePrompt(profile));
+    if (notes.trim())
+        parts.push(`User preferences: ${notes.trim()}`);
+    return parts.join("\n\n");
+}
+/**
+ * System prompt + shots stay identical between requests so Ollama can reuse its prompt cache;
+ * per-request references go into the final user message only.
+ */
+export function buildMessages(ask, profile, refs, notes, secondChance = false) {
+    const system = systemPrompt(profile, notes);
+    const messages = [
+        { role: "system", content: secondChance ? system.replace(/\nIf the request is not a task[^\n]*NONE/, "") : system },
+    ];
+    const shots = secondChance ? [...SHOTS.filter(([, a]) => a !== "NONE"), ...SECOND_SHOTS] : SHOTS;
+    for (const [u, a] of shots)
+        messages.push({ role: "user", content: u }, { role: "assistant", content: a });
+    let content = ask.trim();
+    if (refs.length) {
+        const docs = refs.map((r) => `[${r.name} — from this computer's ${r.source === "package" ? "package database" : r.source === "man" ? "man page" : "--help"}]\n${r.text}`);
+        content = `Local documentation:\n${docs.join("\n\n")}\n\nRequest: ${content}`;
+    }
+    messages.push({ role: "user", content });
+    return messages;
+}
+export function missingHint(missing, profile) {
+    const list = missing.join(", ");
+    const pm = profile?.packageManager;
+    return (`${list} ${missing.length > 1 ? "are" : "is"} not installed on this computer. ` +
+        `Answer again with a command that uses installed tools only` +
+        (pm ? `, or if the task truly needs it, the ${pm} command that installs it.` : ".") +
+        ` If the request is not a shell task, output exactly: NONE`);
+}

package/dist/shell.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { configDir } from "./config.js";
+import { run } from "./util.js";
+export const isHookShell = (s) => s === "bash" || s === "zsh";
+const START = "# >>> whatcmd >>>";
+const END = "# <<< whatcmd <<<";
+/**
+ * Bash: Enter is rebound to run our hook first. If the line starts with the prefix, the hook
+ * replaces it with the generated command and swallows that Enter, so nothing runs until
+ * the user presses Enter again. The raw line never reaches the shell parser, so
+ * apostrophes, ">" and "*" in the request are safe.
+ */
+export function bashHook(prefix) {
+    return `# whatcmd shell hook for bash — generated by \`whatcmd shell bash\`
+[[ $- == *i* ]] || return 0
+__whatcmd_prefix='${prefix}'
+__whatcmd_hook() {
+  if [[ $READLINE_LINE == "$__whatcmd_prefix "* ]]; then
+    local ask=\${READLINE_LINE#"$__whatcmd_prefix "} out
+    if ! command -v whatcmd >/dev/null 2>&1; then
+      printf 'whatcmd: not found on PATH\\n' >&2
+    else
+      out=$(command whatcmd --raw -- "$ask")
+      if [[ -n $out ]]; then
+        READLINE_LINE=$out
+        READLINE_POINT=\${#READLINE_LINE}
+      fi
+    fi
+    bind '"\\C-x\\C-j": ""'
+  else
+    bind '"\\C-x\\C-j": accept-line'
+  fi
+}
+for __whatcmd_map in emacs vi-insert; do
+  bind -m "$__whatcmd_map" -x '"\\C-x\\C-k": __whatcmd_hook'
+  bind -m "$__whatcmd_map" '"\\C-m": "\\C-x\\C-k\\C-x\\C-j"'
+done
+unset __whatcmd_map
+`;
+}
+/** Zsh: wrap the accept-line widget. Messages are shown with `zle -M` under the prompt. */
+export function zshHook(prefix) {
+    return `# whatcmd shell hook for zsh — generated by \`whatcmd shell zsh\`
+[[ -o interactive ]] || return 0
+typeset -g __whatcmd_prefix='${prefix}'
+__whatcmd_accept_line() {
+  if [[ $BUFFER == "$__whatcmd_prefix "* ]]; then
+    local ask=\${BUFFER#"$__whatcmd_prefix "} out msg
+    local errf="\${TMPDIR:-/tmp}/w.$$.err"
+    if (( ! $+commands[whatcmd] )); then
+      zle -M "whatcmd: not found on PATH"
+      return 0
+    fi
+    out=$(command whatcmd --raw -- "$ask" 2>"$errf")
+    msg=$(<"$errf"); rm -f "$errf"
+    if [[ -n $out ]]; then
+      BUFFER=$out
+      CURSOR=\${#BUFFER}
+    fi
+    zle redisplay
+    [[ -n $msg ]] && zle -M "$msg"
+    return 0
+  fi
+  zle .accept-line
+}
+zle -N accept-line __whatcmd_accept_line
+`;
+}
+export function hookScript(shell, prefix) {
+    return shell === "bash" ? bashHook(prefix) : zshHook(prefix);
+}
+export function hookFile(shell) {
+    return path.join(configDir(), `hook.${shell}`);
+}
+export function rcFile(shell, osName) {
+    const home = os.homedir();
+    if (shell === "zsh")
+        return path.join(process.env.ZDOTDIR || home, ".zshrc");
+    // macOS Terminal opens login shells, which read .bash_profile rather than .bashrc
+    return path.join(home, osName === "macos" ? ".bash_profile" : ".bashrc");
+}
+export function isHookInstalled(shell, osName) {
+    try {
+        return fs.readFileSync(rcFile(shell, osName), "utf8").includes(START);
+    }
+    catch {
+        return false;
+    }
+}
+/** (Re)write the hook file for each shell that has it installed. Used when the prefix changes. */
+export function refreshHookFiles(prefix) {
+    for (const shell of ["bash", "zsh"]) {
+        if (fs.existsSync(hookFile(shell)))
+            fs.writeFileSync(hookFile(shell), hookScript(shell, prefix));
+    }
+}
+export function installHook(shell, prefix, osName) {
+    const hook = hookFile(shell);
+    fs.mkdirSync(path.dirname(hook), { recursive: true });
+    fs.writeFileSync(hook, hookScript(shell, prefix));
+    const rc = rcFile(shell, osName);
+    if (isHookInstalled(shell, osName))
+        return { rc, hook, added: false };
+    const home = os.homedir();
+    const shown = hook.startsWith(home + path.sep) ? `$HOME${hook.slice(home.length)}` : hook;
+    const block = `\n${START}\n[ -f "${shown}" ] && . "${shown}"\n${END}\n`;
+    fs.appendFileSync(rc, block);
+    return { rc, hook, added: true };
+}
+export function uninstallHook(shell, osName) {
+    const rc = rcFile(shell, osName);
+    let text;
+    try {
+        text = fs.readFileSync(rc, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const re = new RegExp(`\\n?${START}[\\s\\S]*?${END}\\n?`, "g");
+    if (!re.test(text))
+        return false;
+    fs.writeFileSync(rc, text.replace(re, "\n"));
+    try {
+        fs.unlinkSync(hookFile(shell));
+    }
+    catch { }
+    return true;
+}
+/** The bash shortcut needs bash 4+ (READLINE_LINE). macOS ships bash 3.2. */
+export function bashTooOld(bashPath = process.env.SHELL && /bash$/.test(process.env.SHELL) ? process.env.SHELL : "bash") {
+    const r = run(bashPath, ["-c", "echo ${BASH_VERSINFO[0]}"], { timeoutMs: 2000 });
+    const major = Number(r.stdout.trim());
+    return r.ok && Number.isFinite(major) && major < 4;
+}

package/dist/ui.js

@@ -0,0 +1,39 @@
+import readline from "node:readline/promises";
+const colorOn = (s) => Boolean(s.isTTY) && !process.env.NO_COLOR;
+function paint(code, text, stream = process.stderr) {
+    return colorOn(stream) ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+export const bold = (t, s) => paint("1", t, s);
+export const dim = (t, s) => paint("2", t, s);
+export const red = (t, s) => paint("31", t, s);
+export const green = (t, s) => paint("32", t, s);
+export const yellow = (t, s) => paint("33", t, s);
+export const cyan = (t, s) => paint("36", t, s);
+export const err = (line) => process.stderr.write(line + "\n");
+export const ok = (line) => err(`${green("✔")} ${line}`);
+export const warn = (line) => err(`${yellow("!")} ${line}`);
+export const fail = (line) => err(`${red("✘")} ${line}`);
+export const info = (line) => err(`  ${dim(line)}`);
+export const canPrompt = () => Boolean(process.stdin.isTTY && process.stderr.isTTY);
+export async function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function confirm(question, def) {
+    const a = (await ask(`${question} ${def ? "[Y/n]" : "[y/N]"} `)).toLowerCase();
+    if (!a)
+        return def;
+    return a === "y" || a === "yes";
+}
+export function formatBytes(n) {
+    if (n >= 1e9)
+        return `${(n / 1e9).toFixed(1)} GB`;
+    if (n >= 1e6)
+        return `${Math.round(n / 1e6)} MB`;
+    return `${Math.round(n / 1e3)} KB`;
+}