@shubhamcodess/whatcmd 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shubhamcodess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+# whatcmd
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Type plain English at your shell prompt, get a real command back.**
+
+whatcmd runs a small language model **on your own machine** through [Ollama](https://ollama.com). No API keys, no accounts, and your requests never leave your computer.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D21-brightgreen)
+![Status](https://img.shields.io/badge/status-0.1.0%20pre--release-orange)
+
+```text
+$ /w find files bigger than 100MB            ← press Enter
+$ find . -type f -size +100M                 ← your line is replaced; press Enter again to run it
+```
+
+## Why
+
+Most of the time you know what you want to do but not the exact flags. whatcmd turns the request into one command, puts it on your prompt, and lets you decide.
+
+- **It never runs anything by itself.** The command appears on your prompt. You read it, edit it, or press Enter.
+- **It knows your system.** It detects your OS, distro, shell, package manager and installed tools, so it writes BSD flags on macOS (`sed -i ''`, `stat -f`) and avoids tools you don't have.
+- **It reads your docs.** If your request names an installed program (`jq`, `ffmpeg`, `lsof`, …) or a package, it reads that tool's man page or `--help` and gives the relevant lines to the model.
+- **It stays quiet when it should.** "tell me a joke" or "what is the capital of France" produce nothing.
+- **It warns before you hurt yourself.** `rm -r`, `dd`, `mkfs`, `curl | sh`, `git push --force`, `chmod 777` and placeholders like `/path/to/…` are flagged on your prompt.
+
+## Install
+
+Requirements: Node.js 21 or newer, macOS or Linux, and bash or zsh for the shortcut (any shell can use `whatcmd <request>`).
+
+Choose one of the two options. Both install the same `whatcmd` command.
+
+### Option 1: npm
+
+```bash
+npm install -g @shubhamcodess/whatcmd
+whatcmd init
+```
+
+### Option 2: release tarball
+
+Every release attaches the installable package to its GitHub release. Download it from the [releases page](https://github.com/shubhamcodess/cmdkit/releases), then install the file:
+
+```bash
+npm install -g ./shubhamcodess-whatcmd-0.1.0.tgz
+whatcmd init
+```
+
+Replace `0.1.0` with the version you downloaded. The tarball is the same file CI builds and tests, so it works without npm access.
+
+### Then: first-time setup
+
+`whatcmd init` walks you through setup:
+
+1. Detects your system and saves it to your profile.
+2. Checks Ollama. If it's missing, it shows the install command for your OS and offers to run it. If it's installed but stopped, it offers to start it.
+3. Lets you pick a model (recommended ones, any model you already have, or any name from the [Ollama library](https://ollama.com/library)) and downloads it.
+4. Runs a test request and shows how fast it is.
+5. Adds the `/w` shortcut to your `~/.zshrc` (or `~/.bashrc`).
+
+Open a new terminal and type `/w <request>`.
+
+### Development: clone and install from source
+
+```bash
+git clone https://github.com/shubhamcodess/cmdkit whatcmd
+cd whatcmd
+npm ci                    # installs dependencies and builds dist/
+npm test                  # 30 unit tests
+npm install -g .          # installs the whatcmd command from this checkout
+```
+
+To change the code and see it immediately, run `npm run build` after each edit, or use `npm link` instead of `npm install -g .` and remember to `npm unlink -g @shubhamcodess/whatcmd` when you're done. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## Use
+
+| You type | What happens |
+| --- | --- |
+| `/w <request>` then Enter | Your line is replaced by the command. Press Enter again to run it. |
+| `whatcmd <request>` | Prints the command and asks "Run it? [y/N]". |
+| `whatcmd --raw -- <request>` | Prints only the command, for scripts. Exit code `2` if the request isn't a shell task. |
+
+Quotes are not needed, even with `'`, `>` or `*` in the request: the shortcut reads your line before the shell parses it.
+
+```bash
+whatcmd "what's using port 8080"
+whatcmd --raw -- list the 5 biggest folders in this directory
+```
+
+## Commands
+
+```text
+whatcmd init                 first-time setup
+whatcmd doctor               check Ollama, model, speed and shortcut; offers fixes
+whatcmd use <model>          switch model (downloads it if needed)
+whatcmd models               list downloaded models
+whatcmd config               show settings
+whatcmd config set <key> <value> | get <key> | unset <key> | path | reset
+whatcmd profile [--refresh]  show (or re-detect) the system info given to the model
+whatcmd shell bash|zsh       print the shell hook, to add it yourself
+whatcmd uninstall            remove the shortcut from your shell config
+```
+
+Flags: `--debug` (grounding, prompts and timings), `--model=NAME` (one request with another model), `--yes` (non-interactive `init` and `doctor`), `--raw` (command only).
+
+## Settings
+
+Stored in `~/.config/whatcmd/config.json`. Run `whatcmd config` to see the effective values.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `model` | `qwen2.5-coder:1.5b` | Any Ollama model. |
+| `host` | `http://127.0.0.1:11434` | Ollama server. Also reads `OLLAMA_HOST`. |
+| `prefix` | `/w` | What you type before a request, e.g. `config set prefix ,`. |
+| `grounding` | `true` | Read local docs of the tools you mention. |
+| `notes` | *(empty)* | Extra instructions, e.g. `"prefer ripgrep over grep"`. |
+| `keepAlive` | `2h` | How long Ollama keeps the model loaded (`-1` = forever). |
+| `temperature` | `0` | Keep at `0` for repeatable answers. |
+| `timeoutMs` | `30000` | Time limit for one model call. |
+
+Environment variables override the file: `WHATCMD_MODEL`, `WHATCMD_HOST`, `WHATCMD_CONFIG_DIR`, `WHATCMD_CACHE_DIR`. `NO_COLOR` turns off colours.
+
+## Measurements
+
+All numbers below come from the benchmark and eval runs described in [EVALS.md](EVALS.md). Hardware: Apple M4 Pro, 14 cores, 48 GB RAM, macOS 15.6.1, Node 22.16, Ollama 0.40.14, zsh 5.9. The final benchmark ran on commit `47e6b47`.
+
+**Accuracy: 500-case benchmark, config A (`qwen2.5-coder:1.5b`, grounding on)**
+
+| Area | Result | Target |
+| --- | --- | --- |
+| Overall | **92.7%** (454 / 490 scored) | — |
+| Generation (plain-English → command) | **84.7%** (127 / 150) | 85% (one case short) |
+| Refusal (non-shell requests produce nothing) | **98.8%** (79 / 80) | 93.8% |
+| Grounding, invented flags on fake tools | 85% (17 / 20) | — |
+| Grounding, real installed tools | 90% (27 / 30) | — |
+| Risk warnings (model + deterministic) | 95% (38 / 40) | — |
+| Missing tools (named tool not installed) | 100% (30 / 30) | — |
+| Gate, risk, config and CLI unit-style checks | 100% (60 / 60, 30 / 30, 20 / 20) | — |
+| Shell hook, zsh (10 scenarios) | 10 / 10 | — |
+
+**Other sizes, same run**
+
+| Config | Model | Grounding | Result |
+| --- | --- | --- | --- |
+| A | qwen2.5-coder:1.5b (default) | on | 92.7% overall, all 500 cases |
+| B | qwen2.5-coder:1.5b | off | 77.7% of model cases (grounding cases cannot pass without docs) |
+| C | qwen2.5-coder:0.5b | on | 68% of model cases; generation 66% |
+
+**Eval (`npm run eval`, 83 requests, same model and commit)**
+
+- Valid requests answered correctly: **35 / 48**.
+- Non-shell requests blocked: **34 / 35**.
+- Latency p50 105 ms, p90 218 ms, max 645 ms.
+
+**Speed (config A, benchmark run)**
+
+| Measure | Value |
+| --- | --- |
+| Model call, p50 / p90 / p99 | 121 ms / 422 ms / 739 ms |
+| Whole command end-to-end (`whatcmd --raw`), p50 / p90 | 217 ms / 330 ms |
+| First request after the model unloads | about 0.8 s |
+| Repeatability: 50 random cases run 3 times | 50 / 50 gave identical output |
+
+Numbers vary with hardware, model, and whether the model is already loaded.
+
+## How it works
+
+```text
+request ─► grounding ─► local model ─► gate ─► your prompt line
+           man / --help    system profile     NONE? not a command?
+           package db      + examples         not installed? → retry once
+                                              risky? → warning
+```
+
+1. **Profile.** OS, distro, shell, package manager, GNU/BSD/BusyBox userland, and which common tools are installed. Detected once and stored.
+2. **Grounding.** Words in your request that name an installed program or system package pull in that tool's usage and matching option lines. The man page is read first, `--help` is the fallback, and dangerous programs are never run with `--help`. Results are cached per binary version.
+3. **Generation.** The model gets the profile, a few examples and the docs. It must answer with one command or `NONE`.
+4. **Gate.** Output is dropped when it is `NONE`, doesn't parse as shell, is chat text, repeats the request, copies an example, or loops.
+5. **Retries (at most 3 model calls).**
+   - **Second chance:** a request that is clearly about the computer (files, git, ports, docker, paths…) gets one more attempt with a prompt that has no `NONE` option. Arithmetic, text and prompt-injection answers are still filtered out.
+   - **Fix-up:** if the command uses a program that isn't installed, GNU-only flags on macOS, or repeats the request, the model gets one specific hint. For example: "on macOS use `vm_stat` instead of `free`".
+   - **Auto-fix:** on macOS, `sed -i 's/…'` becomes `sed -i '' 's/…'`.
+
+## Known limits
+
+- **Small models make mistakes.** The eval and the benchmark both show wrong flags, wrong tools and dropped filters. Read every command before you press Enter.
+- **Generation is just under target.** 84.7% against an 85% goal on the 500-case benchmark. Measured, not fixed.
+- **Only zsh was verified end to end.** The bash shortcut needs bash 4 or newer. macOS ships bash 3.2, so on a Mac use zsh (the default) or `brew install bash`. `whatcmd init` detects the old bash and says so. The bash hook scenarios were skipped in the benchmark.
+- **Benchmarks ran on one machine** (Apple Silicon, macOS 15.6.1, Ollama 0.40.14). Linux is supported by design but not covered by the benchmark.
+- **Slow first `--help` calls** can time out, and then that tool gets no docs for that request. Later calls work. The benchmark's kubectl case hit this once.
+- **Math and text requests** can still come back as `bc` or `echo` commands in some cases.
+- **Conflicts:** the shortcut rebinds Enter in bash (via `bind`) and wraps `accept-line` in zsh. It may conflict with tools that do the same, such as ble.sh.
+- **No shortcut yet** for fish or Windows shells. Use `whatcmd <request>`.
+- **Homebrew packages** are not looked up in the package database (too slow per request). Installed commands are still read via man page or `--help`.
+
+## Documentation
+
+| File | What it covers |
+| --- | --- |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to set up, test and send a change. |
+| [TESTING.md](TESTING.md) | Unit tests, what they cover, and how to run them. |
+| [EVALS.md](EVALS.md) | The eval and the 500-case benchmark: design, results, and how to reproduce. |
+| [benchmarks/README.md](benchmarks/README.md) | The raw benchmark files: cases, harness, results per run. |
+| [CHANGELOG.md](CHANGELOG.md) | What changed in each release. |
+| [SECURITY.md](SECURITY.md) | Supported versions and how to report a vulnerability. |
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Expected behaviour in this project. |
+| [LICENSE](LICENSE) | MIT. |
+
+## Development
+
+```bash
+npm ci
+npm test          # build + 30 unit tests
+npm run eval      # end-to-end eval against your local Ollama
+npm run eval -- --model=qwen2.5-coder:0.5b --no-grounding
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before you open a pull request.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { ConfigError, DEFAULTS, SETTABLE, configPath, loadConfig, readStored, saveStored, setKey, unsetKey, writeStored, } from "./config.js";
+import { OllamaError } from "./ollama.js";
+import { bold, canPrompt, confirm, cyan, dim, err, red, yellow } from "./ui.js";
+const VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+const HELP = `${bold("whatcmd")} — plain English in, shell command out. Runs locally on Ollama.
+
+${bold("Usage")}
+  /w <request>          at any bash/zsh prompt (after \`whatcmd init\`): the command
+                             replaces your line; press Enter again to run it
+  whatcmd <request>           print the command and offer to run it
+  whatcmd init                first-time setup: checks Ollama, picks a model, adds /w
+  whatcmd doctor              check everything works (Ollama, model, speed, shell shortcut)
+  whatcmd use <model>         switch model (downloads it if needed)
+  whatcmd models              list downloaded Ollama models
+  whatcmd config              show settings
+  whatcmd config set <key> <value> | get <key> | unset <key> | path | reset
+  whatcmd profile [--refresh] show (or re-detect) the system info given to the model
+  whatcmd shell bash|zsh      print the shell hook (to add it yourself)
+  whatcmd uninstall           remove the /w shortcut from your shell config
+
+${bold("Options")}
+  --raw          print only the command (for scripts and the shell hook)
+  --debug        show grounding, prompts and timings
+  --yes, -y      accept defaults without asking (doctor/init)
+  --model=NAME   use this model for one request (or with doctor/init: switch to it)
+  --             everything after this is the request
+
+${bold("Environment")}
+  WHATCMD_MODEL, WHATCMD_HOST (or OLLAMA_HOST), WHATCMD_CONFIG_DIR, NO_COLOR
+
+${bold("Examples")}
+  whatcmd find files bigger than 100MB
+  whatcmd "what's using port 8080"
+  whatcmd config set model qwen2.5-coder:0.5b
+  whatcmd config set notes "prefer ripgrep over grep"
+`;
+function parseArgs(argv) {
+    const flags = new Set();
+    const values = {};
+    const rest = [];
+    let literal = false;
+    for (const a of argv) {
+        if (literal)
+            rest.push(a);
+        else if (a === "--")
+            literal = true;
+        else if (/^--[a-z-]+=/.test(a)) {
+            const i = a.indexOf("=");
+            values[a.slice(2, i)] = a.slice(i + 1);
+        }
+        else if (/^(--[a-z-]+|-[hvy])$/.test(a))
+            flags.add(a);
+        else
+            rest.push(a);
+    }
+    return { flags, values, rest, literal };
+}
+/** Subcommands only match their exact shape, so "whatcmd init a git repo" is still a request. */
+function subcommand(rest) {
+    const [a, b] = rest;
+    const n = rest.length;
+    if (["init", "doctor", "models", "profile", "uninstall"].includes(a) && n === 1)
+        return a;
+    if (a === "config" && (n === 1 || ["list", "get", "set", "unset", "path", "reset"].includes(b)))
+        return a;
+    if (a === "use" && n === 2)
+        return a;
+    if (a === "shell" && n === 2 && ["bash", "zsh"].includes(b))
+        return a;
+    return null;
+}
+function explainOllamaError(e, model) {
+    if (e.code === "unreachable")
+        return `${e.message}. Is Ollama running? Run: whatcmd doctor`;
+    if (e.code === "model_missing")
+        return `${e.message}. Run: whatcmd use ${model}`;
+    return e.message;
+}
+async function runRequest(ask, opts) {
+    const { generate } = await import("./generate.js");
+    const cfg = loadConfig();
+    if (opts.model)
+        cfg.model = opts.model;
+    let res;
+    try {
+        res = await generate(ask, cfg);
+    }
+    catch (e) {
+        if (e instanceof OllamaError) {
+            err(`whatcmd: ${explainOllamaError(e, cfg.model)}`);
+            return 1;
+        }
+        throw e;
+    }
+    if (opts.debug) {
+        err(dim(`model: ${cfg.model}  timings: ${JSON.stringify(res.debug.timings)}`));
+        for (const n of res.debug.groundNotes)
+            err(dim(`grounding: ${n}`));
+        for (const r of res.debug.refs)
+            err(dim(`grounding [${r.name} via ${r.source}]:\n${r.text}`));
+        if (res.debug.retries.length)
+            err(dim(`retries: ${res.debug.retries.join(", ")}`));
+        err(dim(`raw outputs: ${JSON.stringify(res.debug.outputs)}`));
+    }
+    if (res.kind === "rejected") {
+        const why = res.reason === "empty" ? "empty request" : "not a shell task, nothing generated";
+        err(opts.raw ? `whatcmd: ${why}` : yellow(`whatcmd: ${why}`));
+        return 2;
+    }
+    if (opts.raw) {
+        process.stdout.write(res.command + "\n");
+        for (const w of res.warnings)
+            err(`whatcmd: ⚠ ${w}`);
+        return 0;
+    }
+    process.stdout.write(bold(cyan(res.command, process.stdout), process.stdout) + "\n");
+    for (const w of res.warnings)
+        err(yellow(`⚠ ${w}`));
+    if (!canPrompt() || !process.stdout.isTTY)
+        return 0;
+    if (!(await confirm("Run it?", false)))
+        return 0;
+    const shell = process.env.SHELL || "/bin/sh";
+    return spawnSync(shell, ["-c", res.command], { stdio: "inherit" }).status ?? 1;
+}
+async function configCommand(rest) {
+    const [, action = "list", key, ...valueParts] = rest;
+    const value = valueParts.join(" ");
+    if (action === "path") {
+        process.stdout.write(configPath() + "\n");
+        return 0;
+    }
+    if (action === "list") {
+        const cfg = loadConfig();
+        const stored = readStored();
+        err(dim(`# ${configPath()}`));
+        for (const k of Object.keys(SETTABLE)) {
+            const src = process.env[`WHATCMD_${k.toUpperCase()}`] ? "env" : k in stored ? "" : "default";
+            process.stdout.write(`${k} = ${JSON.stringify(cfg[k])}${src ? dim(`  (${src})`, process.stdout) : ""}\n`);
+        }
+        return 0;
+    }
+    if (action === "get") {
+        if (!key || !SETTABLE[key])
+            throw new ConfigError(`Usage: whatcmd config get <${Object.keys(SETTABLE).join("|")}>`);
+        process.stdout.write(String(loadConfig()[key]) + "\n");
+        return 0;
+    }
+    if (action === "set") {
+        if (!key || !valueParts.length)
+            throw new ConfigError("Usage: whatcmd config set <key> <value>");
+        setKey(key, value);
+        if (key === "prefix")
+            (await import("./shell.js")).refreshHookFiles(value);
+        err(`${key} = ${JSON.stringify(loadConfig()[key])}`);
+        if (key === "prefix")
+            err(dim("Open a new terminal for the new prefix to take effect."));
+        if (key === "model") {
+            const { listModels, hasModel } = await import("./ollama.js");
+            try {
+                if (!hasModel(await listModels(loadConfig().host), value))
+                    err(yellow(`${value} is not downloaded yet. Run: whatcmd use ${value}`));
+            }
+            catch { }
+        }
+        return 0;
+    }
+    if (action === "unset") {
+        if (!key)
+            throw new ConfigError("Usage: whatcmd config unset <key>");
+        unsetKey(key);
+        err(`${key} reset to default (${JSON.stringify(DEFAULTS[key])})`);
+        return 0;
+    }
+    if (action === "reset") {
+        const { profile } = readStored();
+        writeStored(profile ? { profile } : {});
+        err("Settings reset to defaults (system profile kept).");
+        return 0;
+    }
+    return 1;
+}
+async function main(argv) {
+    const { flags, values, rest, literal } = parseArgs(argv);
+    if (flags.has("--version") || flags.has("-v")) {
+        process.stdout.write(VERSION + "\n");
+        return 0;
+    }
+    const sub = literal ? null : subcommand(rest);
+    if (!sub && (flags.has("--help") || flags.has("-h") || rest.length === 0)) {
+        process.stdout.write(HELP);
+        return rest.length === 0 && !flags.has("--help") && !flags.has("-h") ? 1 : 0;
+    }
+    const yes = flags.has("--yes") || flags.has("-y");
+    switch (sub) {
+        case "init":
+        case "doctor": {
+            const d = await import("./doctor.js");
+            const opts = { yes, model: values.model, refreshProfile: flags.has("--refresh") };
+            return (await (sub === "init" ? d.init(opts) : d.doctor(opts))) ? 0 : 1;
+        }
+        case "config":
+            return configCommand(rest);
+        case "use": {
+            const model = rest[1];
+            const { listModels, hasModel } = await import("./ollama.js");
+            const cfg = loadConfig();
+            if (!hasModel(await listModels(cfg.host), model)) {
+                if (!yes && canPrompt() && !(await confirm(`${model} is not downloaded. Download it now?`, true)))
+                    return 1;
+                await (await import("./doctor.js")).downloadModel(cfg.host, model);
+            }
+            saveStored({ model });
+            err(`Now using ${cyan(model)}`);
+            return 0;
+        }
+        case "models": {
+            const { listModels, sameModel } = await import("./ollama.js");
+            const { formatBytes } = await import("./ui.js");
+            const cfg = loadConfig();
+            const models = await listModels(cfg.host);
+            if (!models.length)
+                err("No models downloaded. Run: whatcmd doctor");
+            for (const m of models)
+                process.stdout.write(`${sameModel(m.name, cfg.model) ? "*" : " "} ${m.name.padEnd(28)} ${formatBytes(m.size)}\n`);
+            return 0;
+        }
+        case "profile": {
+            const { detectProfile, profilePrompt } = await import("./env.js");
+            let profile = loadConfig().profile;
+            if (!profile || flags.has("--refresh")) {
+                profile = detectProfile();
+                saveStored({ profile });
+            }
+            process.stdout.write(profilePrompt(profile) + "\n");
+            err(dim(`detected ${profile.detectedAt}; re-detect with: whatcmd profile --refresh`));
+            return 0;
+        }
+        case "shell": {
+            const { hookScript } = await import("./shell.js");
+            process.stdout.write(hookScript(rest[1], loadConfig().prefix));
+            return 0;
+        }
+        case "uninstall": {
+            const { uninstallHook } = await import("./shell.js");
+            const { detectProfile } = await import("./env.js");
+            const osName = (loadConfig().profile ?? detectProfile()).os;
+            const removed = ["bash", "zsh"].filter((s) => uninstallHook(s, osName));
+            err(removed.length ? `Removed the shortcut from your ${removed.join(" and ")} config.` : "No shortcut was installed.");
+            err(dim("To remove whatcmd itself: npm uninstall -g whatcmd"));
+            return 0;
+        }
+    }
+    return runRequest(rest.join(" "), { raw: flags.has("--raw"), debug: flags.has("--debug"), model: values.model });
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    if (e instanceof ConfigError)
+        err(`whatcmd: ${e.message}`);
+    else if (e instanceof OllamaError)
+        err(`whatcmd: ${explainOllamaError(e, loadConfig().model)}`);
+    else
+        err(red(`whatcmd: ${e?.stack ?? e}`));
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_MODEL = "qwen2.5-coder:1.5b";
+export const DEFAULTS = {
+    model: DEFAULT_MODEL,
+    host: "http://127.0.0.1:11434",
+    temperature: 0,
+    keepAlive: "2h",
+    timeoutMs: 30000,
+    prefix: "/w",
+    grounding: true,
+    notes: "",
+};
+export const SETTABLE = {
+    model: { type: "string", help: "Ollama model to use" },
+    host: { type: "string", help: "Ollama server URL" },
+    temperature: { type: "number", help: "0 = deterministic (recommended)" },
+    keepAlive: { type: "string", help: 'keep model loaded: "2h", "30m", "-1" = forever' },
+    timeoutMs: { type: "number", help: "max time for one model call" },
+    prefix: { type: "string", help: "shell trigger, default /w" },
+    grounding: { type: "boolean", help: "use local docs of tools you mention" },
+    notes: { type: "string", help: "extra instructions added to every prompt" },
+};
+export function configDir() {
+    return (process.env.WHATCMD_CONFIG_DIR ||
+        path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "whatcmd"));
+}
+export function cacheDir() {
+    return (process.env.WHATCMD_CACHE_DIR ||
+        path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "whatcmd"));
+}
+export const configPath = () => path.join(configDir(), "config.json");
+/** Accepts the same forms as OLLAMA_HOST: "host", "host:port", ":port", "http(s)://host[:port]". */
+export function normalizeHost(raw) {
+    let s = raw.trim().replace(/\/+$/, "");
+    const hadScheme = /^https?:\/\//i.test(s);
+    if (!hadScheme)
+        s = "http://" + (s.startsWith(":") ? "127.0.0.1" + s : s);
+    const u = new URL(s);
+    if (u.hostname === "0.0.0.0" || u.hostname === "")
+        u.hostname = "127.0.0.1";
+    if (!hadScheme && !u.port)
+        u.port = "11434";
+    return u.toString().replace(/\/+$/, "");
+}
+export function readStored() {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeStored(next) {
+    fs.mkdirSync(configDir(), { recursive: true });
+    fs.writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n");
+}
+export function saveStored(patch) {
+    writeStored({ ...readStored(), ...patch });
+}
+/** Effective config: defaults < config file < environment variables. */
+export function loadConfig() {
+    const stored = readStored();
+    const c = { ...DEFAULTS, ...stored };
+    if (!stored.host && process.env.OLLAMA_HOST)
+        c.host = process.env.OLLAMA_HOST;
+    if (process.env.WHATCMD_HOST)
+        c.host = process.env.WHATCMD_HOST;
+    if (process.env.WHATCMD_MODEL)
+        c.model = process.env.WHATCMD_MODEL;
+    try {
+        c.host = normalizeHost(c.host);
+    }
+    catch {
+        c.host = DEFAULTS.host;
+    }
+    return c;
+}
+export class ConfigError extends Error {
+}
+export function coerce(key, raw) {
+    const spec = SETTABLE[key];
+    if (!spec)
+        throw new ConfigError(`Unknown key "${key}". Keys: ${Object.keys(SETTABLE).join(", ")}`);
+    if (spec.type === "number") {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new ConfigError(`${key} must be a number`);
+        if (key === "temperature" && (n < 0 || n > 2))
+            throw new ConfigError("temperature must be between 0 and 2");
+        if (key === "timeoutMs" && n < 500)
+            throw new ConfigError("timeoutMs must be at least 500");
+        return n;
+    }
+    if (spec.type === "boolean") {
+        if (/^(true|on|yes|1)$/i.test(raw))
+            return true;
+        if (/^(false|off|no|0)$/i.test(raw))
+            return false;
+        throw new ConfigError(`${key} must be true or false`);
+    }
+    if (key === "host")
+        return normalizeHost(raw);
+    if (key === "prefix" && !/^[^\s'"\\`$]+$/.test(raw))
+        throw new ConfigError("prefix must be one word without spaces, quotes, $ or backslashes");
+    if (key === "model" && !raw.trim())
+        throw new ConfigError("model cannot be empty");
+    return raw;
+}
+export function setKey(key, raw) {
+    saveStored({ [key]: coerce(key, raw) });
+}
+export function unsetKey(key) {
+    if (!SETTABLE[key])
+        throw new ConfigError(`Unknown key "${key}"`);
+    const s = readStored();
+    delete s[key];
+    writeStored(s);
+}