cli-guru 0.2.0__py3-none-any.whl

cli_guru/__init__.py

@@ -0,0 +1,3 @@
+"""cli-guru — plain-language shell commands from a local ollama model."""
+
+__version__ = "0.2.0"

cli_guru/backend.py

@@ -0,0 +1,127 @@
+"""Model I/O. The ONLY module that talks to a model.
+
+Everything else (context, man parsing, sanitising, shell adapters) must not
+import this or know it exists — see CLAUDE.md "The seam that keeps this
+reversible". Swapping in another provider means writing one more class here.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Optional, Tuple
+
+
+class BackendError(Exception):
+    """User-facing failure. The message is printed verbatim to stderr."""
+
+
+# A real reply is a few KB: ask is capped at 160 predicted tokens, explain at
+# 700. This bound exists for the case where the host is not what we think it is
+# — `$OLLAMA_HOST` may point across a LAN, over plain HTTP — so a hostile or
+# broken endpoint cannot stream until the process runs out of memory.
+MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+
+def _read_capped(resp) -> bytes:
+    data = resp.read(MAX_RESPONSE_BYTES + 1)
+    if len(data) > MAX_RESPONSE_BYTES:
+        raise BackendError(
+            f"ollama sent more than {MAX_RESPONSE_BYTES // (1024 * 1024)}MB — refusing it"
+        )
+    return data
+
+
+class OllamaBackend:
+    def __init__(
+        self, host: str, model: str, timeout: int = 20, keep_alive: str = "8h"
+    ) -> None:
+        self.host = host.rstrip("/")
+        self.model = model
+        self.timeout = timeout
+        self.keep_alive = keep_alive
+
+    def chat(
+        self, system: str, user: str, *, think: bool = False, num_predict: int = 160
+    ) -> Tuple[str, Optional[str]]:
+        """Return (content, thinking). `thinking` is for --debug only, never output.
+
+        `num_predict` is deliberately tight for ask: this model can degenerate
+        into a repetition loop (observed: `--quiet --quiet --quiet ...` for 20s
+        until the token cap). A low cap bounds the damage; repeat_penalty makes
+        it rarer.
+        """
+        payload = {
+            "model": self.model,
+            "stream": False,
+            "think": think,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            # Keeps the model resident so the next keypress is warm.
+            "keep_alive": self.keep_alive,
+            "options": {
+                "temperature": 0.1,
+                "num_predict": num_predict,
+                "repeat_penalty": 1.15,
+            },
+        }
+        req = urllib.request.Request(
+            f"{self.host}/api/chat",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = json.loads(_read_capped(resp).decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            detail = ""
+            try:
+                detail = json.loads(_read_capped(exc).decode("utf-8")).get("error", "")
+            except Exception:
+                pass
+            if exc.code == 404 or "not found" in detail.lower():
+                raise BackendError(
+                    f"model {self.model!r} not found (pull it with: ollama pull {self.model})"
+                ) from exc
+            raise BackendError(f"ollama returned HTTP {exc.code}: {detail or exc.reason}") from exc
+        except urllib.error.URLError as exc:
+            reason = getattr(exc, "reason", exc)
+            if isinstance(reason, TimeoutError) or "timed out" in str(reason).lower():
+                raise BackendError(
+                    f"timed out after {self.timeout}s — try a smaller model or raise timeout"
+                ) from exc
+            raise BackendError(
+                f"no ollama at {self.host} (start it with: ollama serve, "
+                f"or set OLLAMA_HOST)"
+            ) from exc
+        except TimeoutError as exc:
+            raise BackendError(f"timed out after {self.timeout}s — try a smaller model") from exc
+        except json.JSONDecodeError as exc:
+            raise BackendError("ollama returned a malformed response") from exc
+
+        msg = body.get("message") or {}
+        # Thinking models return `thinking` alongside `content`. Read content ONLY:
+        # concatenating them would paste the model's reasoning into a live prompt.
+        return msg.get("content") or "", msg.get("thinking")
+
+    def check(self) -> str:
+        """Verify reachability and that the model is pulled. Returns a status line."""
+        try:
+            with urllib.request.urlopen(f"{self.host}/api/tags", timeout=self.timeout) as resp:
+                tags = json.loads(_read_capped(resp).decode("utf-8"))
+        except urllib.error.URLError as exc:
+            raise BackendError(
+                f"no ollama at {self.host} (start it with: ollama serve, or set OLLAMA_HOST)"
+            ) from exc
+        names = [m.get("name", "") for m in tags.get("models", [])]
+        if self.model not in names:
+            available = ", ".join(names) or "none"
+            raise BackendError(
+                f"model {self.model!r} not pulled (available: {available}; "
+                f"get it with: ollama pull {self.model})"
+            )
+        return f"ok: {self.host} reachable, model {self.model} present"

cli_guru/cli.py

@@ -0,0 +1,288 @@
+"""Command-line entry point.
+
+`ask` stdout is pasted straight into a live shell prompt, so it prints the
+command and NOTHING else. Every diagnostic goes to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__, config, context, danger, install, manpage, prompts, sanitise
+from .backend import BackendError, OllamaBackend
+
+
+def _err(msg: str) -> None:
+    print(f"cli-guru: {msg}", file=sys.stderr)
+
+
+def _backend(cfg, timeout_key: str = "timeout") -> OllamaBackend:
+    timeout = int(cfg.get(timeout_key, cfg["timeout"]))
+    return OllamaBackend(
+        cfg["host"], cfg["model"], timeout, str(cfg.get("keep_alive", "8h"))
+    )
+
+
+def _joined(parts: List[str]) -> str:
+    """Join the trailing words into one line.
+
+    argparse.REMAINDER is used for these positionals so that `cli-guru explain ls -la`
+    works: with nargs="*", argparse claims `-la` as an unknown option and exits 2.
+    A leading `--` (which the shell widget always passes) is dropped here.
+    """
+    parts = list(parts)
+    if parts and parts[0] == "--":
+        parts = parts[1:]
+    return " ".join(parts).strip()
+
+
+def _read_question() -> Optional[str]:
+    """Ask for a question interactively, NEVER writing the prompt to stdout.
+
+    stdout is the readline buffer: the shell widget runs this as `out=$(...)`,
+    so a prompt printed there is swallowed by the capture and the terminal
+    appears to hang, blocked on input the user cannot see they owe. stderr is no
+    better — the adapter redirects it to a temp file and only prints it after
+    the command exits. The controlling terminal is the only channel the user is
+    actually looking at, so ask there.
+
+    Returns None when there is no terminal to ask on, so the caller can say so
+    instead of blocking forever.
+    """
+    if sys.stdout.isatty():
+        try:
+            return input("cli-guru> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            return ""
+    try:
+        # Two handles, not one "r+": /dev/tty is a character device and is not
+        # seekable, so r+ raises io.UnsupportedOperation (an OSError subclass,
+        # so it would be swallowed below and look like "no terminal").
+        # No /dev/tty on Windows, and none in a container or some ssh/tmux
+        # sessions; OSError there means "cannot ask", not "user said nothing".
+        with open("/dev/tty", "w") as tty_out, open("/dev/tty", "r") as tty_in:
+            tty_out.write("cli-guru> ")
+            tty_out.flush()
+            return (tty_in.readline() or "").strip()
+    except (OSError, KeyboardInterrupt):
+        return None
+
+
+def cmd_ask(args, cfg) -> int:
+    question = _joined(args.text)
+    if not question:
+        typed = _read_question()
+        if typed is None:
+            _err("nothing to ask — type your question on the line first, then press the key")
+            return 1
+        question = typed
+    if not question:
+        return 1
+
+    ctx = context.collect(cfg)
+    user = prompts.ask_user(question, context.render(ctx, bool(cfg.get("include_tools"))))
+    if args.debug:
+        print(f"--- system ---\n{prompts.ASK_SYSTEM}\n--- user ---\n{user}", file=sys.stderr)
+
+    try:
+        raw, thinking = _backend(cfg).chat(
+            prompts.ASK_SYSTEM, user, think=bool(cfg["think"]), num_predict=160
+        )
+    except BackendError as exc:
+        _err(str(exc))
+        return 1
+
+    if args.debug and thinking:
+        print(f"--- thinking ---\n{thinking}", file=sys.stderr)
+
+    command = sanitise.command(raw)
+    if not command:
+        _err("model returned no usable command")
+        return 1
+    # The command goes to stdout (the readline buffer); the warning goes to
+    # stderr, which the shell widget prints above the prompt. Deterministic, so
+    # it does not depend on the model having noticed.
+    warning = danger.banner(command)
+    if warning:
+        print(warning, file=sys.stderr)
+    print(command)
+    return 0
+
+
+def cmd_explain(args, cfg) -> int:
+    line = _joined(args.text)
+    if not line:
+        _err("nothing to explain")
+        return 1
+
+    cmd, sub = manpage.base_command(line)
+    # Opt-in only: fetching docs must not execute the command under explanation.
+    run_help = bool(getattr(args, "run_help", False)) or bool(cfg.get("explain_run_help"))
+    doc, source = manpage.fetch(cmd, sub, run_help=run_help)
+    if doc:
+        doc = manpage.truncate(doc, int(cfg["max_man_chars"]))
+
+    user = prompts.explain_user(line, doc, source)
+    if args.debug:
+        print(f"--- source: {source} ({len(doc or '')} chars) ---", file=sys.stderr)
+
+    try:
+        raw, thinking = _backend(cfg, "timeout_explain").chat(
+            prompts.EXPLAIN_SYSTEM, user, think=bool(cfg["think_explain"]), num_predict=700
+        )
+    except BackendError as exc:
+        _err(str(exc))
+        return 1
+
+    if args.debug and thinking:
+        print(f"--- thinking ---\n{thinking}", file=sys.stderr)
+
+    text = sanitise.prose(raw)
+    if not text:
+        _err("model returned no explanation")
+        return 1
+    # cli-guru owns the warning, not the model: qwen2.5-coder:3b missed 12 of 15
+    # destructive commands when this was left to the prompt.
+    warning = danger.banner(line)
+    if warning:
+        print(warning)
+        # Drop a duplicate warning line the model may have produced anyway.
+        stripped = [ln for ln in text.splitlines() if not ln.upper().lstrip().startswith("WARNING")]
+        text = "\n".join(stripped).strip()
+    print(text)
+    if source == "none":
+        _err("no local man page found — answer is from general knowledge")
+    return 0
+
+
+def cmd_check(args, cfg) -> int:
+    try:
+        print(_backend(cfg).check())
+    except BackendError as exc:
+        _err(str(exc))
+        return 1
+    ctx = context.collect(cfg)
+    print(f"shell: {ctx['shell']}  userland: {ctx['userland']}  os: {ctx['os']}")
+    return 0
+
+
+def _script_for(shell: str) -> Path:
+    """Adapters live inside the package, so an installed wheel finds them too."""
+    name, _ = install.SHELL_FILES[shell]
+    return Path(__file__).resolve().parent / "shell" / name
+
+
+def cmd_install(args, cfg) -> int:
+    shell = args.shell or install.detect_shell()
+    if shell not in install.SHELL_FILES:
+        _err(f"unsupported shell {shell!r} (expected bash, zsh or powershell)")
+        return 1
+    script = _script_for(shell)
+    if not script.exists():
+        _err(f"shell integration file not found: {script}")
+        return 1
+    try:
+        rc, current, new = install.plan(shell, script)
+    except ValueError as exc:
+        _err(str(exc))
+        return 1
+
+    if current == new:
+        print(f"already installed in {rc} (nothing to do)")
+        return 0
+    if args.dry_run:
+        print(install.diff(rc, current, new))
+        print("\n(dry run — nothing written)")
+        return 0
+
+    bak = install.write(rc, current, new)
+    print(f"installed cli-guru ({shell}) in {rc}")
+    if bak:
+        print(f"backup: {bak}")
+    print("keys: Ctrl-X Ctrl-A = ask, Ctrl-X Ctrl-H = explain")
+    print(f"start a new shell, or run:  . {rc}")
+    return 0
+
+
+def cmd_uninstall(args, cfg) -> int:
+    shell = args.shell or install.detect_shell()
+    if shell not in install.SHELL_FILES:
+        _err(f"unsupported shell {shell!r}")
+        return 1
+    try:
+        rc, current, new = install.uninstall_plan(shell)
+    except ValueError as exc:
+        _err(str(exc))
+        return 1
+    if current == new:
+        print(f"cli-guru is not installed in {rc}")
+        return 0
+    if args.dry_run:
+        print(install.diff(rc, current, new))
+        print("\n(dry run — nothing written)")
+        return 0
+    install.write(rc, current, new, backup=False)
+    print(f"removed cli-guru block from {rc}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cli-guru",
+        description="Plain-language shell commands from a local ollama model.",
+    )
+    parser.add_argument("--version", action="version", version=f"cli-guru {__version__}")
+    parser.add_argument("--debug", action="store_true",
+                        help="dump prompt and model reasoning to stderr")
+    parser.add_argument("--model", help="override the model")
+    parser.add_argument("--host", help="override the ollama host")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_ask = sub.add_parser("ask", help="plain language -> one shell command")
+    p_ask.add_argument("text", nargs=argparse.REMAINDER)
+    p_ask.set_defaults(func=cmd_ask)
+
+    p_exp = sub.add_parser("explain", help="explain a command using its man page")
+    p_exp.add_argument("--run-help", action="store_true",
+                       help="if no man page exists, RUN `<cmd> --help` to get its docs")
+    p_exp.add_argument("text", nargs=argparse.REMAINDER)
+    p_exp.set_defaults(func=cmd_explain)
+
+    p_chk = sub.add_parser("check", help="verify ollama is reachable and the model is pulled")
+    p_chk.set_defaults(func=cmd_check)
+
+    p_ins = sub.add_parser("install", help="add the cli-guru block to your shell rc file")
+    p_ins.add_argument("--shell", choices=sorted(install.SHELL_FILES))
+    p_ins.add_argument("--dry-run", action="store_true", help="print the diff, write nothing")
+    p_ins.set_defaults(func=cmd_install)
+
+    p_uni = sub.add_parser("uninstall", help="remove the cli-guru block from your shell rc file")
+    p_uni.add_argument("--shell", choices=sorted(install.SHELL_FILES))
+    p_uni.add_argument("--dry-run", action="store_true")
+    p_uni.set_defaults(func=cmd_uninstall)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # `cli-guru --check` is documented alongside the `check` subcommand.
+    argv = ["check" if a == "--check" else a for a in argv]
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    cfg = config.load({"model": args.model, "host": args.host})
+    try:
+        return int(args.func(args, cfg))
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cli_guru/config.py

@@ -0,0 +1,152 @@
+"""Configuration: defaults, file, environment. Stdlib only."""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+from pathlib import Path
+from typing import Any, Dict
+
+DEFAULTS: Dict[str, Any] = {
+    # Measured on a CPU-only host, each model alone (bench/eval_ask.py and
+    # bench/eval_hard.py; 5+ repeats per case, hard set run twice):
+    #   model               easy  hard   median  resident
+    #   qwen2.5-coder:1.5b   92%   64%    202ms    2.12G
+    #   qwen2.5-coder:3b     83%   46%    489ms    3.37G
+    #   qwen2.5-coder:7b     92%   79%    702ms    6.92G
+    #   nemotron-3-nano:4b   80%    -     911ms    3.78G
+    # 1.5b beats 3b on BOTH sets while being smaller and 2x faster, so 3b has
+    # no niche. Default to 1.5b; 7b is the accuracy option for harder requests.
+    "model": "qwen2.5-coder:1.5b",
+    "host": "http://localhost:11434",
+    "think": False,          # ask: measured 7x slower, no accuracy gain
+    # explain: thinking generated 383 extra tokens -> 14.9s vs 3.7s, and the
+    # non-thinking answer was already correct. The man page does the grounding.
+    "think_explain": False,
+    # Ollama unloads an idle model after 5 minutes by default, so the first
+    # keypress after a break pays the cold-load penalty. Keeping it resident is
+    # the difference between a snappy key and a visible stall.
+    # "30m", "8h", or -1 to pin it in RAM until ollama restarts.
+    "keep_alive": "8h",
+    "timeout": 20,           # ask: a keypress must not hang the prompt
+    "timeout_explain": 45,   # explain: a man page is a much larger prompt
+    "history_lines": 10,
+    "max_files": 50,
+    # Listing available tools MEASURABLY hurts small models: qwen2.5-coder:3b
+    # went from 25% to 75% on a four-case probe when the list was removed. It
+    # sees `rg` and forces it into every answer with invented flags. Off by
+    # default; enable only if your model is shown to benefit.
+    "include_tools": False,
+    # 12000 chars was ~3100 prompt tokens on a 4B model. 6000 keeps explain
+    # responsive while still carrying the whole OPTIONS section for most tools.
+    "max_man_chars": 6000,
+    # When no man page exists, fall back to running `<cmd> --help`. OFF by
+    # default: explain is what you reach for BEFORE running something, so it
+    # must not run it for you. Opt in only if you trust what you paste.
+    "explain_run_help": False,
+}
+
+_BOOL = {"true": True, "false": False, "yes": True, "no": False, "1": True, "0": False}
+
+
+def config_dir() -> Path:
+    """Per-platform config location. Ten lines, so no platformdirs dependency."""
+    if platform.system() == "Windows":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "cli-guru"
+        return Path.home() / "AppData" / "Roaming" / "cli-guru"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "cli-guru"
+    return Path.home() / ".config" / "cli-guru"
+
+
+def _parse_simple_toml(text: str) -> Dict[str, Any]:
+    """Flat key = value subset of TOML.
+
+    Used only when tomllib is unavailable (Python < 3.11). The config is flat
+    scalars by design, so this is sufficient and keeps us stdlib-only on 3.9/3.10.
+    """
+    out: Dict[str, Any] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("["):
+            continue
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key, val = key.strip(), val.strip()
+        # strip trailing inline comment outside of quotes
+        if not val.startswith(('"', "'")):
+            val = val.split("#", 1)[0].strip()
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in "\"'":
+            out[key] = val[1:-1]
+        elif val.lower() in _BOOL:
+            out[key] = _BOOL[val.lower()]
+        elif re.fullmatch(r"-?\d+", val):
+            out[key] = int(val)
+        elif val:
+            out[key] = val
+    return out
+
+
+def _load_file(path: Path) -> Dict[str, Any]:
+    try:
+        raw = path.read_bytes()
+    except (OSError, ValueError):
+        return {}
+    try:
+        import tomllib  # Python 3.11+
+        return dict(tomllib.loads(raw.decode("utf-8")))
+    except ImportError:
+        return _parse_simple_toml(raw.decode("utf-8", "replace"))
+    except Exception:
+        return {}
+
+
+def _coerce(key: str, value: str) -> Any:
+    default = DEFAULTS.get(key)
+    if isinstance(default, bool):
+        return _BOOL.get(str(value).lower(), default)
+    if isinstance(default, int):
+        try:
+            return int(value)
+        except ValueError:
+            return default
+    return value
+
+
+def load(overrides: Dict[str, Any] | None = None) -> Dict[str, Any]:
+    """Precedence: CLI flag > env > config file > default."""
+    cfg = dict(DEFAULTS)
+    cfg.update(_load_file(config_dir() / "config.toml"))
+
+    env_map = {
+        "model": "CLI_GURU_MODEL",
+        "host": "OLLAMA_HOST",
+        "timeout": "CLI_GURU_TIMEOUT",
+        "think": "CLI_GURU_THINK",
+    }
+    for key, env in env_map.items():
+        val = os.environ.get(env)
+        if val:
+            cfg[key] = _coerce(key, val)
+
+    for key, val in (overrides or {}).items():
+        if val is not None:
+            cfg[key] = val
+
+    cfg["host"] = normalise_host(str(cfg["host"]))
+    return cfg
+
+
+def normalise_host(host: str) -> str:
+    """Accept `1.2.3.4:11434` as well as a full URL — OLLAMA_HOST is used both ways."""
+    host = host.strip().rstrip("/")
+    if not host.startswith(("http://", "https://")):
+        host = "http://" + host
+    if not re.search(r":\d+$", host):
+        host += ":11434"
+    return host