cli-guru 0.2.0__py3-none-any.whl

cli_guru/context.py

@@ -0,0 +1,244 @@
+"""Assemble cheap, bounded context about where the user is standing.
+
+Never reads file contents. Never reads the process environment. Every
+subprocess is capped with a timeout so a keypress cannot hang.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# Presence-checked allowlist, so the model only suggests tools that exist here.
+# Allowlist only — never enumerate $PATH.
+TOOLS = [
+    "rg", "fd", "jq", "git", "docker", "kubectl", "systemctl", "ss", "curl",
+    "wget", "tar", "zip", "unzip", "rsync", "ffmpeg", "python3", "node", "awk",
+]
+
+# (pattern, replacement) pairs. Order matters: forms that carry a VALUE come
+# first so the value is consumed too — a pattern matching only the key name
+# leaves the secret sitting in the text.
+_SECRET_PATTERNS = [
+    # Authorization headers: redact the whole value, WHATEVER the scheme. Basic
+    # is base64 of user:password, which is encoding, not protection.
+    (re.compile(r"authorization\s*:\s*\w+\s+\S+", re.IGNORECASE), "Authorization: <redacted>"),
+    # A bare `Bearer <token>` with no header name in front of it.
+    (re.compile(r"\bbearer\s+\S+", re.IGNORECASE), "<redacted>"),
+    # curl -u user:pass / --user user:pass. The negative lookahead keeps
+    # `docker run -u 1000:1000` (a uid:gid, not a credential) intact.
+    (re.compile(r"(--?u(?:ser)?)(?:[=\s]+)(?![\d.:\[\]]+(?:\s|$))\S*:\S+", re.IGNORECASE),
+     r"\1=<redacted>"),
+    # openssl-style `pass:SECRET`, `env:VAR`, `file:path` argument forms.
+    (re.compile(r"\bpass:\S+", re.IGNORECASE), "pass:<redacted>"),
+    # KEY=value / KEY: value, where the key name looks secret-ish.
+    (re.compile(
+        r"\b([\w.-]*(?:password|passwd|secret|token|api[_-]?key|access[_-]?key"
+        r"|private[_-]?key|credential)[\w.-]*)\s*[=:]\s*\S+",
+        re.IGNORECASE), r"\1=<redacted>"),
+    # --password=x, --token x, --api-key x
+    (re.compile(r"(--?(?:password|passwd|token|api[_-]?key|secret)[\w-]*)(?:[=\s]+\S+)?",
+                re.IGNORECASE), r"\1=<redacted>"),
+    # mysql-style attached password: -pSECRET (no space, so `-p 5432` is left alone).
+    (re.compile(r"(-p)\S{6,}"), r"\1<redacted>"),
+    # The spaced form `-p SECRET` (docker login, psql). Purely numeric or
+    # colon-separated values are ports or port maps — `-p 8080:80` survives.
+    (re.compile(r"(-p)\s+(?![\d.:\[\]]+(?:\s|$))(\S{6,})"), r"\1 <redacted>"),
+    # Bare AWS access key ids.
+    (re.compile(r"\bAKIA[0-9A-Z]{12,}\b"), "<redacted>"),
+]
+
+
+# A repository carries its own .git/config, and git will happily run commands
+# named in it — `core.fsmonitor` fires on `git status`. Since context is
+# assembled wherever the user is standing, cd'ing into an untrusted checkout
+# (one unpacked from an archive, say — `git clone` does not copy config) would
+# execute it on the next keypress. Disable it explicitly; `safe.directory` does
+# not help, because it only guards repositories owned by somebody else.
+_GIT = ["git", "-c", "core.fsmonitor="]
+
+
+def _run(cmd: List[str], timeout: float = 2.0, cwd: Optional[str] = None) -> str:
+    try:
+        res = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout, cwd=cwd,
+            env={**os.environ, "LANG": "C", "LC_ALL": "C"},
+        )
+        return res.stdout.strip() if res.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def redact(text: str) -> str:
+    """Blank out secret-shaped fragments, INCLUDING their values, before they
+    can enter a prompt."""
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def listing(cwd: Path, max_files: int) -> str:
+    try:
+        entries = sorted(
+            os.scandir(cwd), key=lambda e: (not e.is_dir(follow_symlinks=False), e.name.lower())
+        )
+    except OSError:
+        return "(unreadable)"
+    names: List[str] = []
+    for entry in entries:
+        if len(names) >= max_files:
+            names.append(f"... {len(entries) - max_files} more")
+            break
+        try:
+            names.append(entry.name + "/" if entry.is_dir(follow_symlinks=False) else entry.name)
+        except OSError:
+            names.append(entry.name)
+    return "  ".join(names) if names else "(empty)"
+
+
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".tox",
+              "target", "dist", "build", ".mypy_cache", ".pytest_cache"}
+
+
+def file_types(cwd: Path, max_entries: int = 2000) -> str:
+    """Recursive extension histogram.
+
+    A top-level listing alone leaves the model blind: asked to "count lines of
+    python in this project" with only `src/ tests/ CLAUDE.md` visible, it
+    grepped CLAUDE.md. This is bounded and cheap, and fixes that class of miss.
+    """
+    counts: Dict[str, int] = {}
+    seen = 0
+    for root, dirs, files in os.walk(cwd):
+        dirs[:] = [d for d in dirs if d not in _SKIP_DIRS and not d.startswith(".")]
+        for name in files:
+            seen += 1
+            if seen > max_entries:
+                break
+            ext = Path(name).suffix.lower() or "(no ext)"
+            counts[ext] = counts.get(ext, 0) + 1
+        if seen > max_entries:
+            break
+    if not counts:
+        return ""
+    top = sorted(counts.items(), key=lambda kv: -kv[1])[:10]
+    return " ".join(f"{n} {ext}" for ext, n in top)
+
+
+def git_info(cwd: Path) -> str:
+    if not _run(_GIT + ["rev-parse", "--is-inside-work-tree"], cwd=str(cwd)) == "true":
+        return ""
+    branch = _run(_GIT + ["rev-parse", "--abbrev-ref", "HEAD"], cwd=str(cwd)) or "?"
+    # `git config user.name` used to go in here. It is the user's real name, it
+    # is no help in writing a shell command, and it was not in the documented
+    # context list. Do not put it back.
+    porcelain = _run(_GIT + ["status", "--porcelain"], cwd=str(cwd))
+    if not porcelain:
+        return f"git: on {branch}, clean"
+    staged = untracked = modified = 0
+    for line in porcelain.splitlines():
+        if line.startswith("??"):
+            untracked += 1
+        elif line[:1] not in (" ", ""):
+            staged += 1
+        else:
+            modified += 1
+    return (
+        f"git: on {branch}, {staged} staged, {modified} modified, "
+        f"{untracked} untracked"
+    )
+
+
+def coreutils_flavour() -> str:
+    """GNU vs BSD changes real flags (`sed -i`, `date`, `stat`, `find`).
+
+    A command correct on Linux and silently wrong on macOS is this tool's most
+    likely quality bug, so the flavour goes in the prompt.
+    """
+    if platform.system() == "Windows":
+        return "windows"
+    try:
+        res = subprocess.run(
+            ["sed", "--version"], capture_output=True, text=True, timeout=2.0
+        )
+        if res.returncode == 0 and "GNU" in res.stdout:
+            return "GNU coreutils"
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return "BSD userland (macOS)" if platform.system() == "Darwin" else "non-GNU userland"
+
+
+def os_name() -> str:
+    system = platform.system()
+    if system == "Linux":
+        try:
+            for line in Path("/etc/os-release").read_text().splitlines():
+                if line.startswith("PRETTY_NAME="):
+                    return line.split("=", 1)[1].strip().strip('"')
+        except OSError:
+            pass
+        return "Linux"
+    if system == "Darwin":
+        ver = _run(["sw_vers", "-productVersion"])
+        return f"macOS {ver}".strip()
+    if system == "Windows":
+        return "Windows " + (platform.win32_ver()[0] or "")
+    return system or "unknown"
+
+
+def history(limit: int) -> str:
+    """Read from $CLI_GURU_HISTORY only.
+
+    The shell adapter captures this with `fc -ln`, because a subprocess reading
+    $HISTFILE sees a stale file that the interactive shell has not flushed.
+    """
+    raw = os.environ.get("CLI_GURU_HISTORY", "")
+    if not raw:
+        return ""
+    lines = [ln.strip() for ln in raw.splitlines() if ln.strip()]
+    return "\n".join(redact(ln) for ln in lines[-limit:])
+
+
+def collect(cfg: Dict) -> Dict[str, str]:
+    cwd = Path.cwd()
+    try:
+        display = "~/" + str(cwd.relative_to(Path.home()))
+    except ValueError:
+        display = str(cwd)
+    present = [t for t in TOOLS if shutil.which(t)]
+    return {
+        "cwd": str(cwd),
+        "cwd_display": display,
+        "files": listing(cwd, int(cfg.get("max_files", 50))),
+        "file_types": file_types(cwd),
+        "git": git_info(cwd),
+        "history": history(int(cfg.get("history_lines", 10))),
+        "os": os_name(),
+        "kernel": platform.release(),
+        "shell": Path(os.environ.get("SHELL", "")).name or "unknown",
+        "userland": coreutils_flavour(),
+        "tools": " ".join(present),
+    }
+
+
+def render(ctx: Dict[str, str], include_tools: bool = False) -> str:
+    parts = [
+        f"System: {ctx['os']} (kernel {ctx['kernel']}), {ctx['userland']}, shell {ctx['shell']}",
+        f"Working directory: {ctx['cwd_display']}",
+        f"Files here: {ctx['files']}",
+    ]
+    if ctx.get("file_types"):
+        parts.append(f"File types in tree: {ctx['file_types']}")
+    if ctx.get("git"):
+        parts.append(ctx["git"])
+    # Off by default — see config.include_tools for the measurement.
+    if include_tools and ctx.get("tools"):
+        parts.append(f"Available tools: {ctx['tools']}")
+    if ctx.get("history"):
+        parts.append("Recent commands:\n" + ctx["history"])
+    return "\n".join(parts)

cli_guru/danger.py

@@ -0,0 +1,174 @@
+"""Deterministic detection of destructive commands.
+
+This is a SAFETY feature, so it must not depend on the model noticing. Measured:
+qwen2.5-coder:3b missed 12 of 15 destructive commands when the warning was left
+to the prompt, including `rm -rf /var/log/*`. cli-guru decides this itself and
+prints the banner; the model only writes the explanation underneath.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+# (pattern, what is lost). Ordered most-specific first.
+_RULES: List[Tuple[re.Pattern, str]] = [
+    (re.compile(r":\s*\(\s*\)\s*\{.*\|\s*:\s*&.*\}\s*;\s*:"),
+     "fork bomb — this will hang the machine until it is rebooted"),
+    (re.compile(r"\bmkfs(\.\w+)?\b"),
+     "formats the filesystem — every file on that device is destroyed"),
+    (re.compile(r"\bdd\b[^|]*\bof=/dev/"),
+     "writes directly over a block device — its entire contents are destroyed"),
+    (re.compile(r"\bshred\b"), "overwrites files so they cannot be recovered"),
+    (re.compile(r"\brm\b[^|]*\s-[a-zA-Z]*[rR][a-zA-Z]*f|\brm\b[^|]*\s-[a-zA-Z]*f[a-zA-Z]*[rR]"),
+     "recursively deletes without prompting — there is no undo and no trash"),
+    (re.compile(r"\brm\b(?![^|]*\s-[a-zA-Z]*i)"),
+     "deletes files permanently — there is no trash"),
+    (re.compile(r"\bgit\s+reset\s+--hard\b"),
+     "discards all uncommitted changes in the working tree"),
+    (re.compile(r"\bgit\s+clean\b[^|]*-[a-zA-Z]*f"),
+     "deletes untracked files, which are not recoverable from git"),
+    (re.compile(r"\bgit\s+push\b[^|]*(--force(?!-with-lease)|\s-f\b)"),
+     "overwrites the remote branch — commits on it can be lost for everyone"),
+    (re.compile(r"\btruncate\b[^|]*-s\s*0"), "empties the file — its contents are lost"),
+    (re.compile(r"\bfind\b[^|]*-delete\b"), "deletes every matching file"),
+    (re.compile(r"\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b", re.I),
+     "drops database objects and the data in them"),
+    (re.compile(r"\bdocker\s+(system\s+prune|volume\s+rm)\b"),
+     "removes docker data, including volumes that may hold the only copy"),
+    (re.compile(r"\b(chmod|chown)\b[^|]*\s-[a-zA-Z]*R[a-zA-Z]*\s+[^|]*\s/(?:\s|$)"),
+     "recursively changes ownership or permissions from the filesystem root"),
+    (re.compile(r"(?<![>\d])>(?!>)\s*(?!/dev/null)[\w./~-]+"),
+     "the `>` redirect truncates the target file before writing"),
+    (re.compile(r"\bmv\b[^|]*\s-[a-zA-Z]*f"), "overwrites the destination without prompting"),
+]
+
+# Commands that only read. The exemption is withdrawn the moment the line also
+# does something destructive: `find . -exec rm {} +` is a delete wearing a
+# read-only command's name.
+_SAFE = re.compile(
+    r"^\s*(?:sudo\s+|env\s+\S+=\S+\s+)*"
+    r"(?:ls|ll|cat|less|more|head|tail|grep|rg|find|df|du|ps|top|"
+    r"git\s+(?:log|status|diff|show|branch)|tar\s+-[a-zA-Z]*t|echo|printf|which|man)\b"
+)
+# Withdraws the _SAFE exemption WITHIN a single segment: `find . -exec rm {} +`
+# starts with an allowlisted command but is a delete. Cross-command cases like
+# `ls; rm -rf ~` are handled by segmenting instead, not here.
+_ALWAYS_UNSAFE = re.compile(
+    r">(?!>)\s*(?!/dev/null)|(?<![\w-])-delete\b|-exec\s+(?:rm|shred|truncate)\b|"
+    r"\bxargs\s+(?:-\S+\s+)*(?:rm|shred)\b"
+)
+
+# Separators that end one command and begin another. `>` is deliberately absent:
+# a redirect is part of the command it belongs to.
+_SEPARATORS = ";\n&|"
+
+
+def _read_substitution(line: str, start: int, closer: str) -> Tuple[str, int]:
+    """Read a command substitution body, returning (body, index after closer)."""
+    depth = 1
+    out: List[str] = []
+    i = start
+    while i < len(line):
+        ch = line[i]
+        if closer == ")" and ch == "(":
+            depth += 1
+        elif ch == closer:
+            depth -= 1
+            if depth == 0:
+                return "".join(out), i + 1
+        out.append(ch)
+        i += 1
+    return "".join(out), i
+
+
+def segments(line: str) -> List[str]:
+    """Split a command line into independently-judged commands.
+
+    A warning must never be suppressed because the line merely *starts* with
+    something read-only: `sudo ls; rm -rf /` is a delete, and judging the line
+    as a whole silently cleared it. Substitutions are judged too, so the `rm` in
+    `ls $(rm -rf ~)` is seen. Quoted text is never split, so `echo "a; b"` stays
+    one command.
+    """
+    out: List[str] = []
+    buf: List[str] = []
+    quote = ""
+    i, n = 0, len(line)
+    while i < n:
+        ch = line[i]
+        # Single quotes are literal in shell: nothing expands inside them.
+        if quote == "'":
+            if ch == quote:
+                quote = ""
+            buf.append(ch)
+            i += 1
+            continue
+        if ch == "\\" and i + 1 < n:
+            buf.append(ch)
+            buf.append(line[i + 1])
+            i += 2
+            continue
+        # Substitutions expand even inside double quotes, so these are checked
+        # before the quote state: `echo "`rm -rf ~`"` really does delete.
+        if ch == "`":
+            body, i = _read_substitution(line, i + 1, "`")
+            out.extend(segments(body))
+            continue
+        if ch in "$<>" and i + 1 < n and line[i + 1] == "(":
+            body, i = _read_substitution(line, i + 2, ")")
+            out.extend(segments(body))
+            continue
+        if quote == '"':
+            if ch == quote:
+                quote = ""
+            buf.append(ch)
+            i += 1
+            continue
+        if ch in "'\"":
+            quote = ch
+            buf.append(ch)
+            i += 1
+            continue
+        if ch in _SEPARATORS:
+            out.append("".join(buf))
+            buf = []
+            i += 2 if i + 1 < n and line[i + 1] == ch else 1  # && and || are one separator
+            continue
+        buf.append(ch)
+        i += 1
+    out.append("".join(buf))
+    return [s.strip() for s in out if s.strip()]
+
+
+def _check_segment(segment: str) -> Optional[str]:
+    for pattern, harm in _RULES:
+        if not pattern.search(segment):
+            continue
+        # A read-only command that merely contains a scary word is not a risk,
+        # but a redirect or an explicit delete always is. Keep looking rather
+        # than clearing the segment: an exemption earned against one rule must
+        # not mask a different rule that also fires.
+        if _SAFE.match(segment) and not _ALWAYS_UNSAFE.search(segment):
+            continue
+        return harm
+    return None
+
+
+def check(command: str) -> Optional[str]:
+    """Return a warning sentence for a destructive command, else None.
+
+    Every segment of the line is judged separately — see `segments`.
+    """
+    if not command or not command.strip():
+        return None
+    for segment in segments(command):
+        harm = _check_segment(segment)
+        if harm:
+            return harm
+    return None
+
+
+def banner(command: str) -> Optional[str]:
+    harm = check(command)
+    return f"WARNING: {harm}" if harm else None

cli_guru/install.py

@@ -0,0 +1,115 @@
+"""Dotfile integration.
+
+A subcommand rather than a shell script, so it can be tested. Dotfile edits
+happen ONLY here and only when the user runs `cli-guru install` — never as a side
+effect of another command.
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import Optional, Tuple
+
+BEGIN = "# >>> cli-guru >>>"
+END = "# <<< cli-guru <<<"
+
+SHELL_FILES = {
+    "bash": ("cli-guru.bash", "~/.bashrc"),
+    "zsh": ("cli-guru.zsh", "~/.zshrc"),
+    "powershell": ("cli-guru.ps1", None),  # resolved from $PROFILE
+}
+
+
+def detect_shell() -> str:
+    if platform.system() == "Windows":
+        return "powershell"
+    name = Path(os.environ.get("SHELL", "")).name
+    if name in ("zsh", "bash"):
+        return name
+    if platform.system() == "Darwin":
+        return "zsh"  # macOS default since Catalina
+    return "bash"
+
+
+def rc_path(shell: str) -> Optional[Path]:
+    if shell == "powershell":
+        profile = os.environ.get("PROFILE")
+        if profile:
+            return Path(profile)
+        return Path.home() / "Documents" / "PowerShell" / "Microsoft.PowerShell_profile.ps1"
+    _, rc = SHELL_FILES[shell]
+    return Path(rc).expanduser() if rc else None
+
+
+def block_for(shell: str, script: Path) -> str:
+    if shell == "powershell":
+        body = f'if (Test-Path "{script}") {{ . "{script}" }}'
+    else:
+        body = f'[ -f "{script}" ] && . "{script}"'
+    return f"{BEGIN}\n{body}\n{END}\n"
+
+
+def strip_block(text: str) -> str:
+    """Remove an existing cli-guru block. Idempotent; leaves everything else byte-identical."""
+    out = []
+    skipping = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if stripped == BEGIN:
+            skipping = True
+            continue
+        if stripped == END:
+            skipping = False
+            continue
+        if not skipping:
+            out.append(line)
+    return "".join(out)
+
+
+def plan(shell: str, script: Path) -> Tuple[Path, str, str]:
+    """Return (rc_file, current_text, new_text) without writing anything."""
+    rc = rc_path(shell)
+    if rc is None:
+        raise ValueError(f"no rc file known for shell {shell!r}")
+    current = rc.read_text(encoding="utf-8", errors="replace") if rc.exists() else ""
+    stripped = strip_block(current)
+    if stripped and not stripped.endswith("\n"):
+        stripped += "\n"
+    new = stripped + block_for(shell, script)
+    return rc, current, new
+
+
+def diff(rc: Path, current: str, new: str) -> str:
+    return "".join(
+        difflib.unified_diff(
+            current.splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            fromfile=str(rc),
+            tofile=str(rc) + " (after)",
+        )
+    ) or "(no change)"
+
+
+def write(rc: Path, current: str, new: str, backup: bool = True) -> Optional[Path]:
+    """Write `new`, backing up the original once. Returns the backup path if made."""
+    made: Optional[Path] = None
+    if backup and rc.exists():
+        bak = rc.with_suffix(rc.suffix + ".cli-guru.bak")
+        if not bak.exists():
+            shutil.copy2(rc, bak)
+            made = bak
+    rc.parent.mkdir(parents=True, exist_ok=True)
+    rc.write_text(new, encoding="utf-8")
+    return made
+
+
+def uninstall_plan(shell: str) -> Tuple[Path, str, str]:
+    rc = rc_path(shell)
+    if rc is None:
+        raise ValueError(f"no rc file known for shell {shell!r}")
+    current = rc.read_text(encoding="utf-8", errors="replace") if rc.exists() else ""
+    return rc, current, strip_block(current)