lex-the-hacker 0.1.0__tar.gz

lex_the_hacker-0.1.0/.claude/skills/dev/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dev
+description: Development commands and workflow for the lex-the-hacker project — running the CLI, running tests (including a single test), and managing dependencies with uv. Use when working on this repo and you need the project's build/test/run commands.
+---
+
+# lex-the-hacker dev workflow
+
+This project is a [Click](https://click.palletsprojects.com/) CLI managed with [`uv`](https://docs.astral.sh/uv/) (Python >=3.13). All commands run through `uv`, which manages the virtual environment automatically — there's no need to activate `.venv` manually.
+
+## Tests
+
+- Run all tests: `uv run pytest`
+- Verbose: `uv run pytest -v`
+- Run a single file: `uv run pytest tests/test_cli.py`
+- Run a single test: `uv run pytest tests/test_cli.py::test_version`
+- Run tests matching a keyword: `uv run pytest -k version`
+
+Tests live in `tests/` and use Click's `CliRunner` to invoke the command in-process.
+
+## Running the CLI
+
+- Show help: `uv run lex --help`
+- Show version: `uv run lex --version`
+
+The `lex` command is defined as a console script in `pyproject.toml` (`[project.scripts]` → `lex = "lex_the_hacker.cli:cli"`).
+
+## Dependencies
+
+- Add a runtime dependency: `uv add <package>`
+- Add a dev-only dependency: `uv add --dev <package>`
+- Remove a dependency: `uv remove <package>`
+- Sync the environment from the lockfile: `uv sync`
+
+## Layout
+
+- `lex_the_hacker/cli.py` — the Click command (the CLI entry point).
+- `lex_the_hacker/__init__.py` — holds `__version__` (the single source of truth for the version, wired into `--version`).
+- `tests/` — pytest tests.
+
+## Version bumps
+
+The version lives in two places that must stay in sync: `__version__` in `lex_the_hacker/__init__.py` and `version` in `pyproject.toml`. Update both when releasing.

lex_the_hacker-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

lex_the_hacker-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

lex_the_hacker-0.1.0/CLAUDE.md

@@ -0,0 +1,24 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project state
+
+Early-stage [`uv`](https://docs.astral.sh/uv/) project (Python >=3.13). It's a [Click](https://click.palletsprojects.com/) CLI exposing a `lex` command group: `lex "<description>"` generates a shell command via an LLM (any OpenAI-compatible API, configured through `LEX_MODEL` / `LEX_API_KEY` / `LEX_BASE_URL`), shows an explanation, offers the command in a [questionary](https://questionary.readthedocs.io/) select (choosing it copies it to the clipboard), and puts it on the user's prompt without running it; `lex shell` shows the detected shell (plus `--version` / `--help`).
+
+## Layout
+
+- `lex_the_hacker/cli.py` — the Click command group and its subcommands; entry point is `lex = "lex_the_hacker.cli:cli"` (see `[project.scripts]` in `pyproject.toml`). The UI ([rich](https://rich.readthedocs.io/) spinner and command/explanation panel) renders on stderr; the questionary select (interactive terminals only — see `_can_prompt`) draws on stdout; clipboard copy is pyperclip with an OSC 52 terminal-escape fallback.
+- `lex_the_hacker/agent.py` — the [pydantic-ai](https://ai.pydantic.dev/) agents: a gate agent that rejects non-command requests, and a generate agent returning a command plus explanation. Model is built per run from the `LEX_*` env vars.
+- `lex_the_hacker/buffer.py` — puts the generated command on the user's prompt via the `TIOCSTI` ioctl; returns False (silently — the panel already shows the command) when it can't, and never injects a newline (that would execute the command).
+- `lex_the_hacker/shell.py` — shell detection via [`shellingham`](https://pypi.org/project/shellingham/); exposes `ShellInfo`, `detect()`, and `config_path_for()`, and backs `lex shell`.
+- `lex_the_hacker/__init__.py` — holds `__version__`, the single source of truth for the version (wired into `--version`).
+- `tests/` — pytest, using Click's `CliRunner` to invoke the command. CLI tests use the `_ask` helper to stub `cli._copy_to_clipboard` (so the suite never touches the real clipboard) and `cli._can_prompt` / `cli._chose_command` (questionary needs a real terminal).
+
+## Commands
+
+- Run the CLI: `uv run lex --help`
+- Run tests: `uv run pytest`
+- Run a single test: `uv run pytest tests/test_cli.py::test_version`
+- Add a dependency: `uv add <package>` (dev-only: `uv add --dev <package>`)
+- Sync the environment from the lockfile: `uv sync`

lex_the_hacker-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: lex-the-hacker
+Version: 0.1.0
+Summary: An AI CLI that writes shell commands for you — and never runs them.
+Requires-Python: >=3.13
+Requires-Dist: click>=8.5.0
+Requires-Dist: pydantic-ai-slim[openai]>=2.35.0
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: shellingham>=1.5.4
+Description-Content-Type: text/markdown
+
+# lex the hacker
+
+> *I prefer to be called a hacker.*
+
+![It's a UNIX system! I know this!](docs/images/lex.jpeg)
+
+Describe what you want in plain English, and `lex` writes the shell command for you.
+
+```
+$ lex "search the dir for 'xyz'"
+```
+
+```
+$ grep -rn 'xyz' .
+```
+
+While `lex` thinks, you get a spinner. Then it shows the command with a short
+explanation of how it works, and offers it to you — pick it (just press Enter)
+to copy it to your clipboard:
+
+```
+╭──────────────────────────────────────────────────╮
+│ grep -rn 'xyz' .                                 │
+│                                                  │
+│ Searches every file under the current directory  │
+│ for the text "xyz", printing each match with its │
+│ file name and line number.                       │
+╰──────────────────────────────────────────────────╯
+? copy to clipboard? (Use arrow keys)
+ » grep -rn 'xyz' .
+   skip
+
+✓ copied to clipboard
+```
+
+Either way, the command also lands on your command line, ready to run.
+
+It **never executes anything itself**. You always read the command and press
+Enter (or edit it, or throw it away). Nothing runs without you.
+
+> **On typing.** Putting text on your prompt uses the `TIOCSTI` ioctl, which
+> current Linux kernels disable by default (`dev.tty.legacy_tiocsti = 0`)
+> because it was a privilege-escalation vector. When it's unavailable — a
+> hardened kernel, no terminal, a pipe — or when the command spans more than
+> one line, the command simply doesn't land on your prompt. That's a normal
+> outcome, not an error: it's still right there in the panel, and on your
+> clipboard. Either way, `lex` never presses Enter for you.
+
+## Install
+
+```
+pip install lex-the-hacker
+```
+
+This gives you the `lex` command.
+
+## Configuration
+
+`lex` talks to any OpenAI-compatible chat API — hosted OpenAI, or a local
+[Ollama](https://ollama.com) server. Point it at one with three environment
+variables:
+
+| Variable | Required | What it is |
+| --- | --- | --- |
+| `LEX_MODEL` | yes | The model name to request, e.g. `gpt-4o-mini` or `llama3.1`. |
+| `LEX_API_KEY` | yes | The API key. Ollama ignores it, but the client still requires a non-empty value — `ollama` works fine. |
+| `LEX_BASE_URL` | no | Base URL of the endpoint. Defaults to OpenAI's hosted API. |
+
+Hosted OpenAI:
+
+```
+export LEX_MODEL=gpt-4o-mini
+export LEX_API_KEY=sk-...
+```
+
+A local Ollama server:
+
+```
+export LEX_MODEL=llama3.1
+export LEX_API_KEY=ollama
+export LEX_BASE_URL=http://localhost:11434/v1
+```
+
+`lex` also tells the model which shell you're in, so the command it writes
+matches your shell's syntax. Run `lex shell` to see what it detected.
+
+> **Clipboard on Linux.** Copying first tries your system clipboard via
+> [pyperclip](https://pypi.org/project/pyperclip/), which on Linux needs one of
+> `xclip`, `xsel`, or `wl-clipboard` installed. Without one, `lex` falls back
+> to OSC 52 — asking your terminal itself to set the clipboard, no install
+> needed — which modern terminals
+> (VS Code, kitty, alacritty, WezTerm, iTerm2, foot, …) support, even over
+> SSH. If neither route works, the copy is skipped quietly.
+
+## Usage
+
+Call `lex` with a description of what you want to do, in quotes:
+
+```
+$ lex "find every python file changed in the last week"
+```
+
+`lex` puts its best guess on your prompt:
+
+```
+$ find . -name '*.py' -mtime -7
+```
+
+From there it's your command like any other — run it, tweak it, or clear the line and try a different description.
+
+More examples:
+
+```
+$ lex "undo my last git commit but keep the changes"
+$ git reset --soft HEAD~1
+
+$ lex "compress this folder into a tar.gz"
+$ tar -czf folder.tar.gz folder/
+
+$ lex "show what's listening on port 8080"
+$ lsof -i :8080
+```
+
+## Why you're always safe
+
+`lex` only ever *writes* a command to your shell. It doesn't run it, and it can't run it — executing is up to you. So if a suggestion looks wrong, you'll see it before anything happens.

lex_the_hacker-0.1.0/README.md

@@ -0,0 +1,126 @@
+# lex the hacker
+
+> *I prefer to be called a hacker.*
+
+![It's a UNIX system! I know this!](docs/images/lex.jpeg)
+
+Describe what you want in plain English, and `lex` writes the shell command for you.
+
+```
+$ lex "search the dir for 'xyz'"
+```
+
+```
+$ grep -rn 'xyz' .
+```
+
+While `lex` thinks, you get a spinner. Then it shows the command with a short
+explanation of how it works, and offers it to you — pick it (just press Enter)
+to copy it to your clipboard:
+
+```
+╭──────────────────────────────────────────────────╮
+│ grep -rn 'xyz' .                                 │
+│                                                  │
+│ Searches every file under the current directory  │
+│ for the text "xyz", printing each match with its │
+│ file name and line number.                       │
+╰──────────────────────────────────────────────────╯
+? copy to clipboard? (Use arrow keys)
+ » grep -rn 'xyz' .
+   skip
+
+✓ copied to clipboard
+```
+
+Either way, the command also lands on your command line, ready to run.
+
+It **never executes anything itself**. You always read the command and press
+Enter (or edit it, or throw it away). Nothing runs without you.
+
+> **On typing.** Putting text on your prompt uses the `TIOCSTI` ioctl, which
+> current Linux kernels disable by default (`dev.tty.legacy_tiocsti = 0`)
+> because it was a privilege-escalation vector. When it's unavailable — a
+> hardened kernel, no terminal, a pipe — or when the command spans more than
+> one line, the command simply doesn't land on your prompt. That's a normal
+> outcome, not an error: it's still right there in the panel, and on your
+> clipboard. Either way, `lex` never presses Enter for you.
+
+## Install
+
+```
+pip install lex-the-hacker
+```
+
+This gives you the `lex` command.
+
+## Configuration
+
+`lex` talks to any OpenAI-compatible chat API — hosted OpenAI, or a local
+[Ollama](https://ollama.com) server. Point it at one with three environment
+variables:
+
+| Variable | Required | What it is |
+| --- | --- | --- |
+| `LEX_MODEL` | yes | The model name to request, e.g. `gpt-4o-mini` or `llama3.1`. |
+| `LEX_API_KEY` | yes | The API key. Ollama ignores it, but the client still requires a non-empty value — `ollama` works fine. |
+| `LEX_BASE_URL` | no | Base URL of the endpoint. Defaults to OpenAI's hosted API. |
+
+Hosted OpenAI:
+
+```
+export LEX_MODEL=gpt-4o-mini
+export LEX_API_KEY=sk-...
+```
+
+A local Ollama server:
+
+```
+export LEX_MODEL=llama3.1
+export LEX_API_KEY=ollama
+export LEX_BASE_URL=http://localhost:11434/v1
+```
+
+`lex` also tells the model which shell you're in, so the command it writes
+matches your shell's syntax. Run `lex shell` to see what it detected.
+
+> **Clipboard on Linux.** Copying first tries your system clipboard via
+> [pyperclip](https://pypi.org/project/pyperclip/), which on Linux needs one of
+> `xclip`, `xsel`, or `wl-clipboard` installed. Without one, `lex` falls back
+> to OSC 52 — asking your terminal itself to set the clipboard, no install
+> needed — which modern terminals
+> (VS Code, kitty, alacritty, WezTerm, iTerm2, foot, …) support, even over
+> SSH. If neither route works, the copy is skipped quietly.
+
+## Usage
+
+Call `lex` with a description of what you want to do, in quotes:
+
+```
+$ lex "find every python file changed in the last week"
+```
+
+`lex` puts its best guess on your prompt:
+
+```
+$ find . -name '*.py' -mtime -7
+```
+
+From there it's your command like any other — run it, tweak it, or clear the line and try a different description.
+
+More examples:
+
+```
+$ lex "undo my last git commit but keep the changes"
+$ git reset --soft HEAD~1
+
+$ lex "compress this folder into a tar.gz"
+$ tar -czf folder.tar.gz folder/
+
+$ lex "show what's listening on port 8080"
+$ lsof -i :8080
+```
+
+## Why you're always safe
+
+`lex` only ever *writes* a command to your shell. It doesn't run it, and it can't run it — executing is up to you. So if a suggestion looks wrong, you'll see it before anything happens.

lex_the_hacker-0.1.0/docs/adr/0001-command-buffer-injection.md

@@ -0,0 +1,53 @@
+# ADR 0001 — How the generated command reaches the command line
+
+Status: accepted
+Date: 2026-08-26
+
+## Context
+
+lex's core promise is that the generated command lands *on your command line*,
+pre-typed and ready to run, without lex executing anything. The spec
+(`docs/specs/command-agent.md`) names the `TIOCSTI` ioctl as the mechanism:
+it pushes bytes into the controlling terminal's input queue, so the shell
+reads them as if they had been typed.
+
+`TIOCSTI` was a long-standing local privilege-escalation vector (any process
+sharing a TTY can inject input into another's shell). Linux 6.2 added the
+`dev.tty.legacy_tiocsti` sysctl and distributions ship it **off** by default.
+On the current development machine (kernel 7.0):
+
+    $ sysctl dev.tty.legacy_tiocsti
+    dev.tty.legacy_tiocsti = 0
+
+With that setting the ioctl fails with `EPERM` for every caller. So on a
+default modern Linux desktop, injection will **never** succeed — the fallback
+path is the path users actually get.
+
+## Decision
+
+Keep `TIOCSTI` as the injection mechanism, isolated in
+`lex_the_hacker/buffer.py`, and treat the stdout fallback (`command: <cmd>`)
+as a first-class, expected outcome rather than an error case:
+
+- `buffer.put()` attempts injection and returns whether it succeeded; every
+  failure mode (no controlling TTY, missing `termios`/`fcntl`, missing
+  `TIOCSTI` constant, `OSError` from the ioctl) falls back to printing.
+- No warning or error is emitted on fallback. Printing the command is a
+  useful, complete outcome on its own — the user can copy or pipe it.
+- lex still never executes the command; injection puts text on the line, it
+  does not press Enter.
+
+## Consequences
+
+- On hardened/modern kernels lex prints the command instead of typing it.
+  That is correct behaviour, not a bug, and tests assert the fallback works.
+- Users who want real injection can opt in with
+  `sudo sysctl -w dev.tty.legacy_tiocsti=1`, with the understanding that they
+  are re-enabling a known privilege-escalation primitive. We do not
+  recommend it in the README.
+- The durable fix is shell integration rather than a kernel ioctl — a `zsh`
+  widget using `print -z`, a bash `READLINE_LINE` binding, or a shell
+  function wrapper that runs `lex` and feeds the result back. The existing
+  `lex shell` command (shell name + config file path) is deliberately the
+  groundwork for installing such a hook. That is future work, out of scope
+  for this spec.

lex_the_hacker-0.1.0/docs/specs/command-agent.md

@@ -0,0 +1,130 @@
+# Spec: LLM command-generation agent
+
+## What to build
+
+Implement the AI-command-generation behavior the README already promises but
+that doesn't exist yet (per `CLAUDE.md`: "the AI-command-generation behavior
+described in the README is not implemented yet"). Concretely:
+
+1. **A [pydantic-ai](https://ai.pydantic.dev/) agent** (e.g.
+   `lex_the_hacker/agent.py`) that talks to an OpenAI-compatible chat
+   completions API. "OpenAI-compatible" is the key property — it's what lets
+   the same code talk to real OpenAI *or* a local Ollama server (Ollama
+   serves an OpenAI-compatible endpoint), without provider-specific branching.
+
+   - Configure the agent's model/provider from environment variables, not
+     hardcoded values:
+     - `LEX_MODEL` — the model name to request (e.g. `gpt-4o-mini`,
+       `llama3.1`). Required.
+     - `LEX_API_KEY` — API key sent to the provider. Required for real
+       OpenAI; for Ollama this can be any non-empty placeholder value since
+       Ollama doesn't validate it, but the underlying OpenAI client still
+       requires the field to be set.
+     - `LEX_BASE_URL` — base URL of the OpenAI-compatible endpoint.
+       Optional; when unset, use the provider's default (OpenAI's hosted
+       API). Set to something like `http://localhost:11434/v1` to target a
+       local Ollama instance instead.
+   - If a required env var is missing when the agent is invoked, fail with a
+     clear, user-facing message (no stack trace) rather than letting the
+     underlying HTTP client raise.
+
+2. **A two-step gate → generate flow**, run for each user request:
+   - **Gate**: decide whether the request plausibly describes something
+     achievable as a single shell command (e.g. "find every python file
+     changed in the last week" passes; "write me a poem" or "what's the
+     weather" does not).
+   - **Generate**: if the gate passes, produce the shell command text for
+     the request. If the gate fails, produce a short message telling the
+     user lex can't help with that — and do not attempt generation or touch
+     the buffer.
+   - The gate and generate steps should be distinguishable in the code (not
+     necessarily two separate LLM calls if one call can reliably do both,
+     but the pass/fail decision and the "can't help" message must be
+     reachable and testable independently of whether generation succeeds).
+
+3. **Buffer output**: when generation succeeds, the resulting command must
+   land on the user's shell command line, ready to run but not executed —
+   this is the tool's existing core promise ("lex drops the command straight
+   onto your command line ... it never executes anything itself").
+   - Implement this as a small, isolated function (e.g.
+     `lex_the_hacker/buffer.py`) that injects the command text into the
+     current terminal's input queue (on Linux, the standard mechanism for
+     this is the `TIOCSTI` ioctl) so it appears pre-typed at the next
+     prompt.
+   - If buffer injection isn't possible — no controlling TTY, running
+     non-interactively, unsupported platform, or the ioctl is
+     rejected/unsupported on the current system — fall back to printing the
+     command to stdout with a clear label (e.g. `command: <cmd>`) instead of
+     crashing.
+
+4. **CLI wiring**: invoking `lex` with a free-text description and no
+   subcommand (e.g. `lex "search the dir for 'xyz'"`) runs the flow above.
+   `lex shell`, `lex --version`, and `lex --help` must keep working exactly
+   as they do today.
+
+5. **README updates**: document `LEX_MODEL`, `LEX_API_KEY`, and
+   `LEX_BASE_URL` — what each does, which are required, and example values
+   for both hosted OpenAI and a local Ollama server — so a new user can
+   actually connect the tool to a model.
+
+## Acceptance criteria
+
+- `pydantic-ai` (or the appropriate `pydantic-ai-slim[...]` extra) is added
+  via `uv add` and appears in `pyproject.toml` / `uv.lock`.
+- The agent module builds its model/provider from `LEX_MODEL`,
+  `LEX_API_KEY`, and `LEX_BASE_URL` at call time (not import time), so tests
+  can set/unset them per-test.
+- Missing `LEX_MODEL` or `LEX_API_KEY` produces a clear `click.ClickException`
+  (or equivalent user-facing error) — no unhandled traceback.
+- The gate correctly distinguishes at least a few representative
+  command-shaped requests from non-command-shaped requests in tests, using a
+  mocked/stubbed model (e.g. pydantic-ai's `TestModel`/`FunctionModel`, or an
+  injected fake) — **no real network calls in the test suite**.
+- When the gate rejects a request, the user sees a "can't help with that"
+  style message and the buffer-write function is never called.
+- When the gate accepts a request, the generated command string is passed to
+  the buffer-write function.
+- The buffer-write function is isolated enough to be mocked in tests (CI has
+  no real interactive TTY) and has an explicit, tested fallback path (prints
+  to stdout) for when injection isn't possible.
+- Running `lex "<description>"` end-to-end against a real local Ollama
+  server (`LEX_BASE_URL=http://localhost:11434/v1`, `LEX_MODEL=<a locally
+  pulled model>`, `LEX_API_KEY=ollama`) produces a command on the line, and
+  running it against a request lex can't help with prints the "can't help"
+  message — both verified manually since this depends on a live model.
+- `lex shell`, `lex --version`, and `lex --help` still work and existing
+  tests for them still pass.
+- README documents all three env vars, marks which are required vs.
+  optional, and gives one example configuration for OpenAI and one for
+  Ollama.
+- `uv run pytest` passes, including new tests for the gate, the generate
+  path, the buffer fallback, and the missing-env-var error path.
+
+## Out of scope
+
+- Any change to the safety model of the tool — lex still never executes a
+  generated command itself; no new execution path is being added.
+- Multi-turn conversation, follow-up refinement, or conversation history.
+- Buffer injection on Windows or non-TTY-based terminals — Unix-like TTYs
+  only (Linux is the primary target; best-effort elsewhere is fine but not
+  required).
+- Installing, pulling, or managing local Ollama models — the agent only
+  connects to an already-running endpoint.
+- Prompt engineering polish beyond a reasonable first pass (few-shot tuning,
+  chain-of-thought, etc. can follow later based on real usage).
+- Command preview/explanation UI beyond what's already described in the
+  README.
+- Shell-specific command dialects (e.g. tailoring output to the shell
+  detected by the existing `lex shell` command) — that integration can come
+  later; this spec generates a generic POSIX-shell command.
+
+## Sequencing
+
+One cohesive deliverable — the gate, generation, buffer output, and CLI
+entry point only make sense together as a single working feature — but
+build in this order to keep it reviewable:
+
+1. Env var configuration + the pydantic-ai agent (gate and generate).
+2. The buffer-injection module with its stdout fallback.
+3. CLI wiring of the two above into `lex "<description>"`, plus the README
+   env var documentation.

lex_the_hacker-0.1.0/docs/specs/detect-shell.md

@@ -0,0 +1,80 @@
+# Spec: Shell detection + `lex shell` command
+
+## What to build
+
+`lex` should be able to detect which shell it's running under (bash, zsh,
+fish, etc.) so that future command-suggestion features can tailor output to
+the user's actual shell. This spec covers the detection capability itself
+plus a new `lex shell` command that surfaces what was detected, for the user
+and for debugging.
+
+1. **Shell detection module** (`lex_the_hacker/shell.py` or similar):
+   - Use the [`shellingham`](https://pypi.org/project/shellingham/) library
+     (the de facto standard for this — used by pip, poetry, pipx, etc.) to
+     detect the running shell's name and executable path. Add it as a
+     dependency via `uv add shellingham`.
+   - `shellingham.detect_shell()` returns `(name, path)` (e.g.
+     `("zsh", "/bin/zsh")`) but raises `shellingham.ShellDetectionFailed` if
+     it can't determine the shell (e.g. non-interactive/unknown parent
+     process). Handle that case explicitly rather than letting it propagate.
+   - Given a detected shell name, resolve its primary config/rc file path
+     using `$HOME` and standard per-shell conventions:
+     - `bash` → `~/.bashrc`
+     - `zsh` → `~/.zshrc`
+     - `fish` → `~/.config/fish/config.fish`
+     - other known shells: use reasonable, documented defaults (e.g. `ksh` →
+       `~/.kshrc`, `csh`/`tcsh` → `~/.cshrc`)
+     - unrecognized shell name → no config path (`None`), not an error
+   - This module should expose a small, testable function/data structure
+     (e.g. a `ShellInfo` dataclass with `name`, `path`, `config_path` fields)
+     rather than printing directly, so `lex shell` and any future callers
+     can reuse it.
+
+2. **`lex shell` command**:
+   - Add as a new Click command in `lex_the_hacker/cli.py` (or a subcommand
+     module if that becomes unwieldy — for this scope, adding directly to
+     `cli.py` is fine).
+   - On success, prints the detected shell name, its executable path, and
+     its config file path (or a note that the config file convention is
+     unknown for that shell).
+   - On detection failure, prints a clear message that the shell could not
+     be detected (not a stack trace) and exits non-zero.
+
+## Acceptance criteria
+
+- `uv add shellingham` has been run and `shellingham` appears in
+  `pyproject.toml` dependencies / `uv.lock`.
+- A shell-detection function exists, is unit-testable without needing an
+  actual shell subprocess (i.e. `shellingham.detect_shell` is mockable via
+  `unittest.mock.patch` or equivalent), and returns shell name, executable
+  path, and resolved config file path.
+- Config file resolution covers at minimum: bash, zsh, fish. Falls back
+  gracefully (no exception) for any shell name not in the known list.
+- Running `lex shell` in a normal terminal session prints the detected shell
+  name, path, and config file path, and exits 0.
+- When detection fails (simulated via mocking `shellingham.detect_shell` to
+  raise `ShellDetectionFailed`), `lex shell` prints a user-friendly error
+  message and exits with a non-zero status code — no unhandled traceback.
+- `lex --help` lists `shell` as an available command.
+- New tests in `tests/` cover: successful detection + config resolution for
+  at least bash/zsh/fish, an unrecognized-shell case (config path is
+  `None`/absent but no crash), and the detection-failure path for the CLI
+  command. All existing and new tests pass under `uv run pytest`.
+
+## Out of scope
+
+- Actually using the detected shell to generate or format AI-suggested
+  commands (the README's broader AI-command-generation feature) — this spec
+  only covers detection and the inspection command.
+- Shell config *editing* (e.g. auto-appending an alias or PATH entry to the
+  detected rc file) — detection and reporting only.
+- Supporting shells beyond common Unix shells (no Windows `cmd.exe`/
+  PowerShell-specific config resolution required, though `shellingham` may
+  detect them by name).
+- Caching or persisting the detected shell across invocations.
+
+## Sequencing
+
+Single cohesive unit of work: the detection module is a prerequisite for the
+command, but both are small enough, and tightly coupled enough, to implement
+and review together as one deliverable.

lex_the_hacker-0.1.0/lex_the_hacker/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"