nlsh-cli 0.1.0__tar.gz

nlsh_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # hatch-vcs derives the version from git history/tags
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (locked)
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -q
+
+  lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - name: Verify lockfile is up to date
+        run: uv lock --check

nlsh_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+# Push a tag like v0.1.0 to build and publish that version to PyPI.
+# The version is derived from the tag by hatch-vcs — no manual version bump.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history so hatch-vcs sees the tag
+      - uses: astral-sh/setup-uv@v6
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Configure a "pypi" environment on the repo and register this workflow as a
+    # PyPI Trusted Publisher — no API token needed.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+      - name: Publish to PyPI (trusted publishing)
+        run: uv publish --trusted-publishing always

nlsh_cli-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# Version file generated by hatch-vcs at build time
+nlsh/_version.py
+
+# Virtual env (recreate with `uv sync`)
+.venv/
+
+# uv's managed Python downloads (not committed)
+.uv/
+
+# Local config / secrets
+.env
+config.toml
+
+# OS
+.DS_Store

nlsh_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,124 @@
+# 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/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_cli-0.1.0/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