nlsh-cli 0.1.0__py3-none-any.whl

nlsh/__init__.py

@@ -0,0 +1,8 @@
+"""nlsh — natural language to shell command CLI."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("nlsh-cli")  # PyPI distribution name (command is `nlsh`)
+except PackageNotFoundError:  # not installed (e.g. running from a source tree)
+    __version__ = "0+unknown"

nlsh/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

nlsh/cli.py

@@ -0,0 +1,349 @@
+"""Command-line interface for nlsh."""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import subprocess
+import sys
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.text import Text
+
+from . import __version__
+from .config import (
+    PRO_MODEL,
+    config_path,
+    load_config,
+    save_config,
+)
+from .llm import LLMError, Suggestion, suggest_command
+
+run_app = typer.Typer(
+    add_completion=False,
+    help="Describe what you want in natural language; nlsh proposes a shell "
+    "command and asks before running it. Run `nlsh config set-key` to store "
+    "your API key.",
+)
+config_app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Manage nlsh configuration (~/.config/nlsh/config.toml).",
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+# --------------------------------------------------------------------------- #
+# Dangerous-command detection
+# --------------------------------------------------------------------------- #
+# Each entry: (compiled pattern, human-readable reason). A match means the
+# command needs an explicit typed "yes" before it runs.
+_RISK_PATTERNS = [
+    (re.compile(r"\brm\s+-\w*[rf]\w*\s+(/|/\*|~|\$HOME)(\s|/|$)"),
+     "递归删除根目录或家目录 (rm -rf /)"),
+    (re.compile(r"\brm\s+-\w*[rf]"),
+     "强制/递归删除文件，可能不可恢复 (rm -rf)"),
+    (re.compile(r"\bdd\b[^|;&]*\bof=/dev/"),
+     "用 dd 直接写入磁盘设备，会覆盖数据"),
+    (re.compile(r"\bmkfs\b"),
+     "格式化文件系统 (mkfs)，会清空目标"),
+    (re.compile(r">\s*/dev/(sd|nvme|hd|vd|disk|mmcblk)"),
+     "重定向写入块设备，会破坏磁盘"),
+    (re.compile(r":\s*\(\s*\)\s*\{"),
+     "疑似 fork 炸弹，会耗尽系统资源"),
+    (re.compile(r"\bchmod\s+-R\b"),
+     "递归修改权限 (chmod -R)，影响面大"),
+    (re.compile(r"\bchown\s+-R\b"),
+     "递归修改属主 (chown -R)，影响面大"),
+    (re.compile(r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba)?sh\b"),
+     "下载脚本直接执行 (curl | sh)，来源不可信"),
+    (re.compile(r"\b(shutdown|reboot|halt|poweroff)\b|\binit\s+0\b"),
+     "关机/重启系统"),
+    (re.compile(r"\bsudo\b"),
+     "以 root 权限执行"),
+]
+
+
+def risk_check(command: str) -> List[str]:
+    """Return a list of reasons the command looks dangerous (empty if safe)."""
+    return [reason for pattern, reason in _RISK_PATTERNS if pattern.search(command)]
+
+
+# --------------------------------------------------------------------------- #
+# Environment detection
+# --------------------------------------------------------------------------- #
+def _detect_shell() -> str:
+    shell = os.environ.get("SHELL", "")
+    return os.path.basename(shell) if shell else "sh"
+
+
+def _detect_os() -> str:
+    system = platform.system()
+    if system == "Linux":
+        # Add distro hint when available for better command targeting.
+        try:
+            with open("/etc/os-release", encoding="utf-8") as fh:
+                for line in fh:
+                    if line.startswith("PRETTY_NAME="):
+                        name = line.split("=", 1)[1].strip().strip('"')
+                        return f"Linux ({name})"
+        except OSError:
+            pass
+        return "Linux"
+    if system == "Darwin":
+        return f"macOS {platform.mac_ver()[0]}".strip()
+    return system or "unknown"
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"nlsh {__version__}")
+        raise typer.Exit()
+
+
+def _run_command(command: str) -> int:
+    """Run the command in the user's shell, inheriting the terminal."""
+    shell_path = os.environ.get("SHELL") or "/bin/sh"
+    try:
+        completed = subprocess.run([shell_path, "-c", command])
+        return completed.returncode
+    except KeyboardInterrupt:
+        return 130
+    except OSError as exc:
+        err_console.print(f"[red]Failed to run command:[/red] {exc}")
+        return 1
+
+
+# --------------------------------------------------------------------------- #
+# Rendering
+# --------------------------------------------------------------------------- #
+def _render_suggestion(suggestion: Suggestion, command: str) -> None:
+    body = Text()
+    body.append("$ ", style="dim")
+    body.append(command, style="bold cyan")
+    if suggestion.explanation:
+        body.append("\n\n")
+        body.append(suggestion.explanation, style="dim")
+    console.print(
+        Panel(body, title="proposed command", border_style="cyan", expand=False)
+    )
+
+    if len(suggestion.steps) > 1:
+        steps = Text()
+        for i, (part, explain) in enumerate(suggestion.steps, 1):
+            steps.append(f"{i}. ", style="bold")
+            steps.append(part, style="cyan")
+            if explain:
+                steps.append(f"\n   {explain}", style="dim")
+            if i < len(suggestion.steps):
+                steps.append("\n")
+        console.print(Panel(steps, title="步骤分解", border_style="dim", expand=False))
+
+
+def _render_risks(risks: List[str]) -> None:
+    warn = Text()
+    warn.append("⚠ 危险操作检测\n", style="bold red")
+    for reason in risks:
+        warn.append(f"  • {reason}\n", style="red")
+    console.print(Panel(warn, border_style="red", expand=False))
+
+
+def _confirm_dangerous() -> bool:
+    """Require the user to type the full word 'yes'."""
+    typed = Prompt.ask(
+        "[bold red]此命令被标记为危险，输入完整的 'yes' 才执行[/bold red]",
+        default="",
+        show_default=False,
+    )
+    return typed.strip() == "yes"
+
+
+# --------------------------------------------------------------------------- #
+# Main run command (default, no subcommand name)
+# --------------------------------------------------------------------------- #
+@run_app.command()
+def run(
+    query: Optional[List[str]] = typer.Argument(
+        None, help="Natural language description of what you want to do."
+    ),
+    pro: bool = typer.Option(
+        False, "--pro", help=f"Use the stronger model ({PRO_MODEL}) for this request."
+    ),
+    model: Optional[str] = typer.Option(
+        None, "--model", "-m", help="Override the model id for this request."
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Run without confirmation (dangerous commands still prompt)."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Only print the command; never run it."
+    ),
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show version and exit."
+    ),
+) -> None:
+    """Translate QUERY into a shell command and confirm before running."""
+    if not query:
+        err_console.print(
+            "[yellow]Usage:[/yellow] nlsh <what you want to do>\n"
+            "Example: nlsh find the 5 largest files under this directory\n"
+            "First time? Run:  nlsh config set-key"
+        )
+        raise typer.Exit(code=2)
+
+    request = " ".join(query).strip()
+    cfg = load_config()
+    if not cfg.has_key:
+        err_console.print(
+            "[red]No DeepSeek API key found.[/red]\n"
+            "Set one with:  [bold]nlsh config set-key[/bold]\n"
+            "or:           [bold]export DEEPSEEK_API_KEY=sk-...[/bold]"
+        )
+        raise typer.Exit(code=1)
+
+    # Model override precedence: --model > --pro > configured default.
+    if model:
+        cfg.model = model
+    elif pro:
+        cfg.model = PRO_MODEL
+
+    shell = _detect_shell()
+    os_name = _detect_os()
+    cwd = os.getcwd()
+
+    try:
+        with console.status(
+            f"[dim]Asking DeepSeek ({cfg.model})…[/dim]", spinner="dots"
+        ):
+            suggestion = suggest_command(
+                request, cfg, os_name=os_name, shell=shell, cwd=cwd
+            )
+    except LLMError as exc:
+        err_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    if not suggestion.command:
+        msg = suggestion.explanation or "无法为该请求生成命令。"
+        console.print(
+            Panel(Text(msg, style="yellow"), title="no command",
+                  border_style="yellow", expand=False)
+        )
+        raise typer.Exit(code=1)
+
+    command = suggestion.command
+    _render_suggestion(suggestion, command)
+
+    if dry_run:
+        return
+
+    # --yes auto-runs only safe commands; dangerous ones still require a typed yes.
+    if yes:
+        risks = risk_check(command)
+        if risks:
+            _render_risks(risks)
+            if not _confirm_dangerous():
+                console.print("[dim]Cancelled.[/dim]")
+                raise typer.Exit(code=130)
+        raise typer.Exit(code=_run_command(command))
+
+    # Interactive confirm loop (re-checks risk after an edit).
+    while True:
+        risks = risk_check(command)
+        if risks:
+            _render_risks(risks)
+
+        choice = Prompt.ask(
+            "[bold]Run it?[/bold]", choices=["y", "n", "e"], default="n"
+        )
+
+        if choice == "n":
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit(code=130)
+
+        if choice == "e":
+            edited = None
+            try:
+                edited = typer.edit(command + "\n")
+            except Exception:  # editor not available
+                edited = None
+            if edited is None:
+                edited = Prompt.ask("Edit command", default=command)
+            command = edited.strip()
+            if not command:
+                console.print("[dim]Empty command, cancelled.[/dim]")
+                raise typer.Exit(code=130)
+            console.print(f"[dim]$ {command}[/dim]")
+            continue  # re-loop: re-check risk and re-prompt on the edited command
+
+        # choice == "y"
+        if risks and not _confirm_dangerous():
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit(code=130)
+        break
+
+    raise typer.Exit(code=_run_command(command))
+
+
+# --------------------------------------------------------------------------- #
+# `nlsh config ...` subcommands
+# --------------------------------------------------------------------------- #
+@config_app.command("set-key")
+def config_set_key(
+    model: Optional[str] = typer.Option(
+        None, "--model", "-m", help="Also set the default model."
+    ),
+) -> None:
+    """Store your DeepSeek API key in the config file (mode 0600)."""
+    key = Prompt.ask("DeepSeek API key", password=True)
+    key = (key or "").strip()
+    if not key:
+        err_console.print("[yellow]No key entered, nothing changed.[/yellow]")
+        raise typer.Exit(code=1)
+    path = save_config({"api_key": key, "model": model})
+    console.print(f"[green]Saved[/green] to {path}")
+
+
+@config_app.command("set-model")
+def config_set_model(
+    model: str = typer.Argument(..., help="Model id, e.g. deepseek-v4-pro."),
+) -> None:
+    """Set the default model in the config file."""
+    path = save_config({"model": model})
+    console.print(f"[green]Saved[/green] model = {model}  ({path})")
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show the resolved configuration (the API key is masked)."""
+    cfg = load_config()
+    masked = "—"
+    if cfg.api_key:
+        k = cfg.api_key
+        masked = f"{k[:4]}…{k[-4:]}" if len(k) > 8 else "set"
+    console.print(f"config file : {config_path()}")
+    console.print(f"api_key     : {masked}")
+    console.print(f"base_url    : {cfg.base_url}")
+    console.print(f"model       : {cfg.model}")
+
+
+# --------------------------------------------------------------------------- #
+# Entry point: route `nlsh config ...` to config_app, everything else to run.
+# --------------------------------------------------------------------------- #
+def app() -> None:
+    argv = sys.argv[1:]
+    if argv and argv[0] == "config":
+        config_app(args=argv[1:], prog_name="nlsh config")
+    else:
+        run_app(args=argv, prog_name="nlsh")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

nlsh/config.py

@@ -0,0 +1,114 @@
+"""Configuration loading for nlsh.
+
+Resolution order for every setting:
+  1. Environment variable
+  2. Config file (~/.config/nlsh/config.toml or $NLSH_CONFIG)
+  3. Built-in default
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - fallback for 3.9/3.10
+    tomllib = None
+
+
+DEFAULT_BASE_URL = "https://api.deepseek.com"
+# deepseek-chat / deepseek-reasoner are deprecated on 2026-07-24;
+# v4 models are the current generation (…-flash is the cheaper/faster tier).
+FLASH_MODEL = "deepseek-v4-flash"
+PRO_MODEL = "deepseek-v4-pro"
+DEFAULT_MODEL = FLASH_MODEL
+
+# Keys we own in the config file and are allowed to (re)write.
+WRITABLE_KEYS = ("api_key", "base_url", "model")
+
+
+def config_path() -> Path:
+    override = os.environ.get("NLSH_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME", "~/.config")
+    return Path(base).expanduser() / "nlsh" / "config.toml"
+
+
+def _load_file() -> dict:
+    path = config_path()
+    if not path.is_file() or tomllib is None:
+        return {}
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (OSError, ValueError):
+        return {}
+    # Accept either top-level keys or a [deepseek] table.
+    section = data.get("deepseek", {})
+    merged = {**data, **section}
+    return merged
+
+
+@dataclass
+class Config:
+    api_key: str | None
+    base_url: str
+    model: str
+
+    @property
+    def has_key(self) -> bool:
+        return bool(self.api_key)
+
+
+def load_config() -> Config:
+    file_cfg = _load_file()
+    api_key = (
+        os.environ.get("DEEPSEEK_API_KEY")
+        or os.environ.get("NLSH_API_KEY")
+        or file_cfg.get("api_key")
+    )
+    base_url = (
+        os.environ.get("DEEPSEEK_BASE_URL")
+        or file_cfg.get("base_url")
+        or DEFAULT_BASE_URL
+    )
+    model = (
+        os.environ.get("NLSH_MODEL")
+        or file_cfg.get("model")
+        or DEFAULT_MODEL
+    )
+    return Config(api_key=api_key, base_url=base_url.rstrip("/"), model=model)
+
+
+def _toml_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def save_config(updates: dict) -> Path:
+    """Merge `updates` into the config file and write it back (mode 0600).
+
+    Only WRITABLE_KEYS are persisted; values of None are ignored. The file is
+    rewritten as flat top-level keys, which the loader also accepts.
+    """
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    current = {k: v for k, v in _load_file().items() if k in WRITABLE_KEYS}
+    for key, value in updates.items():
+        if key in WRITABLE_KEYS and value is not None:
+            current[key] = value
+
+    lines = ["# nlsh configuration\n"]
+    for key in WRITABLE_KEYS:
+        value = current.get(key)
+        if value:
+            lines.append(f'{key} = "{_toml_escape(str(value))}"\n')
+    path.write_text("".join(lines), encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path

nlsh/llm.py

@@ -0,0 +1,131 @@
+"""DeepSeek client: turn a natural language request into a shell command.
+
+The DeepSeek API is OpenAI-compatible, so this is a single chat-completions
+call constrained to JSON output.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import List, Tuple
+
+import httpx
+
+from .config import Config
+
+SYSTEM_PROMPT = """\
+You are nlsh, a tool that translates a user's natural language request into a \
+single shell command for their terminal.
+
+Rules:
+- ALWAYS return exactly ONE concrete, runnable command. Never reply with a
+  question and never refuse just because a detail (filename, path, pattern) is
+  missing.
+- When a value is unknown, fill in a clear placeholder the user can edit, such
+  as path/to/folder, FILENAME, or "pattern". Do NOT use angle brackets <...> or
+  other shell metacharacters in placeholders (they would break the shell). Say
+  in the explanation what to replace.
+- Map the intent faithfully: "强制"/"force" -> add -f; "递归"/"recursive" -> -r;
+  and so on. Chain stages with pipes, && or ; when needed.
+- Target the user's OS and shell given in the context.
+- Prefer safe, idiomatic, widely-available commands. Do not invent flags.
+- Do NOT wrap the command in markdown fences or backticks.
+- Keep "explanation" to one short sentence in the user's language.
+- If the command has multiple stages (joined by pipes |, && or ;), break it
+  down: list each stage in "steps" with the exact segment and what it does.
+  For a single simple command, return an empty "steps" array.
+- Only set "command" to an empty string if the request genuinely cannot be a
+  shell command at all (not merely under-specified); then explain why.
+
+Respond ONLY with a JSON object of the form:
+{
+  "command": "<the command>",
+  "explanation": "<one short sentence in the user's language>",
+  "steps": [{"part": "<command segment>", "explain": "<what this stage does>"}]
+}
+"""
+
+
+@dataclass
+class Suggestion:
+    command: str
+    explanation: str
+    steps: List[Tuple[str, str]] = field(default_factory=list)
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+def _user_message(query: str, os_name: str, shell: str, cwd: str) -> str:
+    return (
+        f"OS: {os_name}\n"
+        f"Shell: {shell}\n"
+        f"Current directory: {cwd}\n\n"
+        f"Request: {query}"
+    )
+
+
+def suggest_command(
+    query: str,
+    cfg: Config,
+    *,
+    os_name: str,
+    shell: str,
+    cwd: str,
+    timeout: float = 30.0,
+) -> Suggestion:
+    if not cfg.has_key:
+        raise LLMError("No API key configured.")
+
+    payload = {
+        "model": cfg.model,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": _user_message(query, os_name, shell, cwd)},
+        ],
+        "temperature": 0.0,
+        "response_format": {"type": "json_object"},
+        "stream": False,
+    }
+    headers = {
+        "Authorization": f"Bearer {cfg.api_key}",
+        "Content-Type": "application/json",
+    }
+
+    try:
+        resp = httpx.post(
+            f"{cfg.base_url}/chat/completions",
+            json=payload,
+            headers=headers,
+            timeout=timeout,
+        )
+    except httpx.HTTPError as exc:
+        raise LLMError(f"Request to DeepSeek failed: {exc}") from exc
+
+    if resp.status_code != 200:
+        detail = resp.text.strip()
+        raise LLMError(f"DeepSeek returned HTTP {resp.status_code}: {detail[:300]}")
+
+    try:
+        content = resp.json()["choices"][0]["message"]["content"]
+        data = json.loads(content)
+    except (KeyError, IndexError, ValueError) as exc:
+        raise LLMError(f"Could not parse DeepSeek response: {exc}") from exc
+
+    command = str(data.get("command", "")).strip()
+    explanation = str(data.get("explanation", "")).strip()
+
+    steps: List[Tuple[str, str]] = []
+    raw_steps = data.get("steps")
+    if isinstance(raw_steps, list):
+        for item in raw_steps:
+            if not isinstance(item, dict):
+                continue
+            part = str(item.get("part", "")).strip()
+            explain = str(item.get("explain", "")).strip()
+            if part:
+                steps.append((part, explain))
+
+    return Suggestion(command=command, explanation=explanation, steps=steps)

nlsh_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: nlsh-cli
+Version: 0.1.0
+Summary: Turn natural language into shell commands via the DeepSeek API, with a confirm-before-run step.
+Project-URL: Homepage, https://github.com/decajoin/nlsh
+Project-URL: Repository, https://github.com/decajoin/nlsh
+Author: Yiqi Yang
+License: MIT
+Keywords: cli,deepseek,llm,natural-language,shell,terminal
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# nlsh
+
+Describe what you want to do in plain language; `nlsh` asks the DeepSeek API for
+the matching shell command, shows it with a short explanation, and waits for your
+confirmation before running it.
+
+```
+$ nlsh find the 5 largest files under this directory
+╭─ proposed command ───────────────────────────────────────╮
+│ $ du -ah . | sort -rh | head -n 5                         │
+│                                                           │
+│ Lists files by size and shows the five largest.          │
+╰───────────────────────────────────────────────────────────╯
+Run it? [y/n/e] (n):
+```
+
+`y` runs it, `n` cancels, `e` opens the command in your `$EDITOR` first.
+
+## Install
+
+Once published to PyPI, install it as a standalone tool (the package is
+`nlsh-cli`; the command it installs is `nlsh`):
+
+```sh
+uv tool install nlsh-cli     # or: pipx install nlsh-cli
+```
+
+### From source
+
+One command sets up the virtual environment and all dependencies from the
+lockfile:
+
+```sh
+uv sync
+```
+
+This creates `.venv/` and installs `nlsh`. Run it with `uv run nlsh ...`, or
+activate the env first (`source .venv/bin/activate`) and just call `nlsh`.
+
+Plain pip (no uv) works too:
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Configure
+
+Easiest — store the key interactively (written to `~/.config/nlsh/config.toml`,
+mode 0600):
+
+```sh
+nlsh config set-key
+nlsh config set-model deepseek-v4-pro   # optional, change default model
+nlsh config show                        # show resolved config (key masked)
+```
+
+Or via environment variable:
+
+```sh
+export DEEPSEEK_API_KEY=sk-...
+```
+
+or edit `~/.config/nlsh/config.toml` directly:
+
+```toml
+api_key  = "sk-..."
+model    = "deepseek-v4-flash"        # optional (also: deepseek-v4-pro)
+base_url = "https://api.deepseek.com" # optional
+```
+
+Resolution order for each setting is: environment variable → config file → default.
+
+## Usage
+
+```sh
+nlsh <natural language request>
+
+  -y, --yes        run without confirmation (dangerous commands still prompt)
+  -n, --dry-run    only print the command, never run it
+      --pro        use the stronger model (deepseek-v4-pro) for this request
+  -m, --model ID   override the model id for this request
+      --version    show version
+```
+
+At the confirmation prompt: `y` runs, `n` cancels, `e` edits first. Commands
+that match risky patterns (`rm -rf`, `dd of=/dev/…`, `mkfs`, fork bombs,
+`curl … | sh`, `sudo`, …) are flagged in red and require typing the full word
+`yes` before they run — even under `--yes`. Multi-stage commands (pipes, `&&`)
+are shown with a per-step breakdown.
+
+## Development
+
+```sh
+uv sync                 # installs deps + dev tools (pytest, ruff)
+uv run pytest -q        # run the test suite
+uv run ruff check .     # lint
+```
+
+CI (GitHub Actions) runs ruff + pytest across Python 3.9–3.13 and checks the
+lockfile on every push and PR.
+
+### Releasing
+
+The version is derived from the git tag by `hatch-vcs`, so a release is just a
+tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `Publish` workflow builds the sdist/wheel and uploads them to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (configure a
+`pypi` environment on the repo and register the workflow as a trusted publisher
+— no API token stored).
+
+## How it works
+
+`nlsh` sends your request plus context (OS, shell, current directory) to the
+DeepSeek chat API constrained to JSON output, parses `{command, explanation}`,
+and runs the chosen command through your `$SHELL` so aliases and the working
+directory behave as expected.

nlsh_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nlsh/__init__.py,sha256=bbgIL4bdvKleZdziso75uWneZy--qCiMdcLZR1Z9el4,316
+nlsh/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+nlsh/cli.py,sha256=w1VOkxCBR2zfDhJ1AlCVEroLZYt5l9tN84ErjoXjBEU,12051
+nlsh/config.py,sha256=j6ZhmorE-BXHik73XkawO90Oy47b502mkZQE6DHq7do,3140
+nlsh/llm.py,sha256=WlQobVFp36oEBce9fg_5o3XDQSumSfyaa_eZ-kVLbgg,4253
+nlsh_cli-0.1.0.dist-info/METADATA,sha256=jorfoPHrhplu2FCXAsBiuZW2vEoKOel8VOBv5CBsms4,4539
+nlsh_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nlsh_cli-0.1.0.dist-info/entry_points.txt,sha256=LCi5FJkY2FKOmsqxbm3g_2qbzKZx2tJBPv1uN8-tL0k,38
+nlsh_cli-0.1.0.dist-info/RECORD,,

nlsh_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

nlsh_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nlsh = nlsh.cli:app