tempest-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to **tempest-cli** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-08-15
+
+### Added
+
+- **`tc`, the short alias.** The package now installs a second console
+  script pointing at the same entry point, so `tc check` is `tempest-cli
+  check`. While the installing environment is on `PATH`, `tc` shadows
+  iproute2's `tc(8)`; call the traffic controller as `/usr/sbin/tc` when
+  you need it.
+
+### Fixed
+
+- **The gate no longer runs a dead pyenv/asdf shim.** `tempest-cli fix`
+  in a project whose environment has no ruff answered `pyenv: ruff:
+  command not found` and exited 127 — the lookup took the first `PATH`
+  hit, and on a version-manager machine that hit is a shim that exists
+  for every tool any installed interpreter ever provided. The lookup now
+  searches the environments that belong to the run first (the CLI's own
+  interpreter directory, `$VIRTUAL_ENV`, the nearest `.venv`), accepts a
+  shim only after `<tool> --version` proves it dispatches, and applies
+  the same check to `uv` itself.
+
+- **The `uv` fallback stopped leaking back to `PATH`.** It ran `uv run
+  <tool>`, which falls back to `PATH` when the project environment has
+  no such tool — landing on the very shim that had just been rejected.
+  It is now `uv run --with <tool> <tool>`, so the tool is always present
+  in the run's overlay; a version pinned by the project still wins,
+  since uv resolves the overlay against the project's requirements.
+
+- **The 127 message names the fix.** It now says what to install
+  (`uv add --dev ruff`, or `"tempest-cli[tools]"` for the set) instead
+  of only reporting that `PATH` and `uv` came up empty.
+
 ## [0.1.0] — 2026-08-15
 
 First release. Extracted from

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Framework-agnostic quality gate for Python projects: ruff + mypy + pytest behind one command, with a typing-strictness dial and a PR-description prompt generator.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-cli
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-cli
@@ -50,6 +50,8 @@ uv add --dev tempest-cli
 tempest-cli check          # lint + fmt-check + type + test, in order, stops at the first failure
 tempest-cli fix            # every ruff autofix, then format
 tempest-cli type -s strict # override the configured strictness for one run
+
+tc check                   # `tc` is the short alias for the same program
 ```
 
 ## Why it exists
@@ -142,8 +144,16 @@ register_commands(cli)
 ## Installing the tools
 
 `tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. To
-install them alongside it:
+finds — it does not pin them, so your project chooses the versions. The
+lookup runs in this order:
+
+1. the environments of the run — the interpreter's own directory, then
+   `$VIRTUAL_ENV`, then the nearest `.venv` up the tree;
+2. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+3. `uv run --with <tool> <tool>`, when `uv` is available.
+
+To install the three alongside it:
 
 ```bash
 uv add --dev "tempest-cli[tools]"

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/README.md

@@ -19,6 +19,8 @@ uv add --dev tempest-cli
 tempest-cli check          # lint + fmt-check + type + test, in order, stops at the first failure
 tempest-cli fix            # every ruff autofix, then format
 tempest-cli type -s strict # override the configured strictness for one run
+
+tc check                   # `tc` is the short alias for the same program
 ```
 
 ## Why it exists
@@ -111,8 +113,16 @@ register_commands(cli)
 ## Installing the tools
 
 `tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. To
-install them alongside it:
+finds — it does not pin them, so your project chooses the versions. The
+lookup runs in this order:
+
+1. the environments of the run — the interpreter's own directory, then
+   `$VIRTUAL_ENV`, then the nearest `.venv` up the tree;
+2. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+3. `uv run --with <tool> <tool>`, when `uv` is available.
+
+To install the three alongside it:
 
 ```bash
 uv add --dev "tempest-cli[tools]"

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/changelog.en.md

@@ -3,6 +3,29 @@
 The full history lives in the repository's
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
 
+## [0.2.0] — 2026-08-15
+
+### Added
+
+- **`tc`**, a short alias installed next to `tempest-cli` — the same
+  program. While the installing environment is on `PATH` it shadows
+  iproute2's `tc(8)` (call `/usr/sbin/tc` for the network one).
+
+### Fixed
+
+- **The gate no longer runs a dead pyenv/asdf shim.** `tempest-cli fix`
+  in a project without ruff answered `pyenv: ruff: command not found`
+  and exited 127. The lookup now searches the run's own environments
+  first (the CLI's interpreter directory, `$VIRTUAL_ENV`, the nearest
+  `.venv`) and accepts a shim only after `<tool> --version` proves it
+  dispatches — the same check applies to `uv` itself.
+- **The `uv` fallback stopped leaking back to `PATH`.** It was `uv run
+  <tool>`, which falls back to `PATH` when the project environment has
+  no such tool — landing on the shim just rejected. It is now `uv run
+  --with <tool> <tool>`.
+- **The 127 message names the fix** (`uv add --dev ruff`, or
+  `"tempest-cli[tools]"` for the set).
+
 ## [0.1.0] — 2026-08-15
 
 First release. Extracted from

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/changelog.md

@@ -4,6 +4,29 @@ O histórico completo vive no
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
 do repositório.
 
+## [0.2.0] — 2026-08-15
+
+### Adicionado
+
+- **`tc`**, apelido curto instalado ao lado de `tempest-cli` — mesmo
+  programa. Enquanto o ambiente instalador estiver no `PATH`, ele
+  sombreia o `tc(8)` do iproute2 (chame `/usr/sbin/tc` para o de rede).
+
+### Corrigido
+
+- **O gate não roda mais um shim morto do pyenv/asdf.** `tempest-cli
+  fix` num projeto sem ruff respondia `pyenv: ruff: command not found` e
+  saía 127. A busca agora tenta primeiro os ambientes da execução
+  (diretório do interpretador da CLI, `$VIRTUAL_ENV`, `.venv` mais
+  próximo) e só aceita um shim depois que `<ferramenta> --version` prova
+  que ele despacha — o mesmo vale para o próprio `uv`.
+- **O fallback do `uv` parou de vazar para o `PATH`.** Era `uv run
+  <ferramenta>`, que cai no `PATH` quando o ambiente do projeto não tem
+  a ferramenta — voltando ao shim recém-rejeitado. Agora é `uv run
+  --with <ferramenta> <ferramenta>`.
+- **A mensagem do 127 diz o que instalar** (`uv add --dev ruff`, ou
+  `"tempest-cli[tools]"` para as três).
+
 ## [0.1.0] — 2026-08-15
 
 Primeira versão. Extraída do

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/commands.en.md

@@ -14,6 +14,11 @@ tool's exit code.
 | `check` | the four above, in order, stopping at the first failure |
 | `pr-prompt` | builds the PR-description prompt — [its own page](pr-prompt.md) |
 
+!!! tip "`tc` is the short form"
+    The package installs `tempest-cli` and `tc` pointing at the same
+    program. The examples use the long name; `tc check`, `tc fix` and
+    `tc type -s strict` work exactly the same.
+
 ## The full gate
 
 ```bash
@@ -63,8 +68,11 @@ The exit code is the tool's own, untranslated:
 tempest-cli lint; echo "exited $?"
 ```
 
-There is exactly one code of its own: **127**, when the tool is not on
-`PATH` and `uv` is not either — the message then names what was missing.
+There is exactly one code of its own: **127**, when the tool is in none
+of the places the CLI looks — the run's environment, `PATH`, `uv run
+--with` — and the message then names what was missing and how to install
+it. The lookup order is in
+[Installation](installation.md#where-ruff-mypy-and-pytest-come-from).
 
 ## Recap
 

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/commands.md

@@ -14,6 +14,11 @@ saída da ferramenta por baixo.
 | `check` | os quatro acima, em ordem, parando na primeira falha |
 | `pr-prompt` | monta o prompt da descrição do PR — [página própria](pr-prompt.md) |
 
+!!! tip "`tc` é a forma curta"
+    O pacote instala `tempest-cli` e `tc` apontando para o mesmo
+    programa. Os exemplos usam o nome longo; `tc check`, `tc fix` e
+    `tc type -s strict` funcionam igual.
+
 ## O gate completo
 
 ```bash
@@ -63,8 +68,10 @@ O código de saída é o da ferramenta, sem tradução:
 tempest-cli lint; echo "saiu $?"
 ```
 
-Só há um código próprio: **127**, quando a ferramenta não está no `PATH`
-e o `uv` também não — aí a mensagem diz qual faltou.
+Só há um código próprio: **127**, quando a ferramenta não está em nenhum
+dos lugares onde a CLI procura — ambiente da execução, `PATH`, `uv run
+--with` — e aí a mensagem diz qual faltou e como instalá-la. A ordem de
+busca está em [Instalação](installation.md#de-onde-vem-o-ruff-o-mypy-e-o-pytest).
 
 ## Recap
 

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/index.en.md

@@ -10,6 +10,7 @@ library, a script. The only runtime dependency is `typer`.
 ```bash
 uv add --dev tempest-cli
 tempest-cli check
+tc check          # the same, through the short alias
 ```
 
 ```console

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/docs/index.md

@@ -10,6 +10,7 @@ uma biblioteca, um script. A única dependência de runtime é o `typer`.
 ```bash
 uv add --dev tempest-cli
 tempest-cli check
+tc check          # o mesmo, pelo apelido curto
 ```
 
 ```console

tempest_cli-0.2.0/docs/installation.en.md

@@ -0,0 +1,90 @@
+# Installation
+
+```bash
+uv add --dev tempest-cli
+```
+
+Or with pip:
+
+```bash
+pip install tempest-cli
+```
+
+Requires **Python 3.11+**. The only runtime dependency is `typer`.
+
+It installs **two executables**: `tempest-cli` and the short alias `tc`.
+They are the same program — everything in these docs applies to both.
+
+```bash
+tc check        # identical to tempest-cli check
+```
+
+!!! warning "`tc` is also iproute2's `tc(8)`"
+    While the environment that installed the package is on `PATH`, `tc`
+    resolves to this CLI. For Linux traffic control, call it by absolute
+    path (`/usr/sbin/tc`) — or use `tempest-cli` and leave `tc` alone.
+
+## Where ruff, mypy and pytest come from
+
+`tempest-cli` does **not** pin any of the three: it runs whatever it
+finds, in this order:
+
+1. **the environments of the run** — the directory of the interpreter
+   running the CLI (where the `[tools]` extra installs all three), then
+   `$VIRTUAL_ENV`, then the nearest `.venv` up the tree;
+2. **`PATH`** — skipping a version-manager shim that dispatches nowhere
+   (see below);
+3. **`uv run --with <tool> <tool>`** when `uv` is available — the
+   project's environment plus the tool, with no activation and no prior
+   `uv sync` required.
+
+If nothing resolves, the command exits with **127**, naming the missing
+tool and how to install it, instead of raising a traceback.
+
+!!! info "Why `PATH` does not come first"
+    On a pyenv/asdf machine the `shims` directory is on `PATH`
+    globally and holds a stub for every tool any installed version ever
+    provided. Looking up `ruff` there finds `~/.pyenv/shims/ruff` even
+    when the project has no ruff at all — and running it prints
+    `pyenv: ruff: command not found`. So the run's own environment wins
+    over `PATH`, and a shim is only accepted after proving it dispatches
+    (`<tool> --version` exiting `0`).
+
+!!! tip "Why the versions are not pinned"
+    A ruff version pinned here would become the ceiling for every
+    project installing this package — and upgrading the linter is a
+    decision for whoever writes the code, not for whoever packages the
+    gate.
+
+If you would rather install all three alongside:
+
+```bash
+uv add --dev "tempest-cli[tools]"
+```
+
+## Verifying
+
+```bash
+tempest-cli --version
+tc --version          # the same program
+tempest-cli check --help
+```
+
+## In CI
+
+Every command returns the underlying tool's exit code, so the job reads
+it exactly as it would read `ruff` directly:
+
+```yaml
+- name: Quality gate
+  run: uv run tempest-cli check
+```
+
+## Recap
+
+- `uv add --dev tempest-cli`, Python 3.11+, `typer` as the only
+  dependency.
+- Two executables: `tempest-cli` and the `tc` alias.
+- Tools come from the run's environment, from `PATH` (never a dead
+  shim), or through `uv run --with`.
+- A missing tool means exit 127 with a message, not a traceback.

tempest_cli-0.2.0/docs/installation.md

@@ -0,0 +1,89 @@
+# Instalação
+
+```bash
+uv add --dev tempest-cli
+```
+
+Ou com pip:
+
+```bash
+pip install tempest-cli
+```
+
+Requer **Python 3.11+**. A única dependência de runtime é o `typer`.
+
+Ficam instalados **dois executáveis**: `tempest-cli` e o apelido curto
+`tc`. São o mesmo programa — tudo nesta documentação vale para os dois.
+
+```bash
+tc check        # idêntico a tempest-cli check
+```
+
+!!! warning "`tc` também é o `tc(8)` do iproute2"
+    Enquanto o ambiente que instalou o pacote estiver no `PATH`, `tc`
+    resolve para esta CLI. Para o controlador de tráfego do Linux, chame
+    pelo caminho absoluto (`/usr/sbin/tc`) ou use `tempest-cli` e deixe
+    o `tc` livre.
+
+## De onde vêm o ruff, o mypy e o pytest
+
+O `tempest-cli` **não** fixa versão de nenhum dos três: ele executa o que
+encontrar, nesta ordem:
+
+1. **o ambiente da execução** — o diretório do interpretador que está
+   rodando a CLI (onde o extra `[tools]` instala as três), depois
+   `$VIRTUAL_ENV`, depois o `.venv` mais próximo subindo a árvore;
+2. **o `PATH`** — pulando um *shim* de gerenciador de versão que não
+   despacha para lugar nenhum (veja abaixo);
+3. **`uv run --with <ferramenta> <ferramenta>`**, quando o `uv` está
+   disponível — o ambiente do projeto mais a ferramenta, sem exigir
+   ativação nem `uv sync` prévio.
+
+Se nada resolver, o comando sai com **127** e diz qual ferramenta faltou
+e como instalá-la, em vez de estourar um traceback.
+
+!!! info "Por que o `PATH` não vem primeiro"
+    Em máquina com pyenv/asdf, o diretório `shims` está no `PATH`
+    globalmente e tem um stub para toda ferramenta que qualquer versão
+    instalada já forneceu. Procurar `ruff` ali acha
+    `~/.pyenv/shims/ruff` mesmo quando o projeto não tem ruff nenhum — e
+    rodá-lo dá `pyenv: ruff: command not found`. Por isso o ambiente da
+    execução ganha do `PATH`, e um shim só é aceito depois de provar que
+    despacha (`<ferramenta> --version` saindo `0`).
+
+!!! tip "Por que não fixar as versões"
+    Uma versão de ruff fixada aqui viraria o teto de todo projeto que
+    instalasse este pacote — e atualizar o linter é decisão de quem
+    escreve o código, não de quem empacota o gate.
+
+Se você prefere instalar as três junto:
+
+```bash
+uv add --dev "tempest-cli[tools]"
+```
+
+## Verificando
+
+```bash
+tempest-cli --version
+tc --version          # o mesmo programa
+tempest-cli check --help
+```
+
+## Em CI
+
+Cada comando devolve o código de saída da ferramenta por baixo, então o
+job lê exatamente como leria o `ruff` direto:
+
+```yaml
+- name: Quality gate
+  run: uv run tempest-cli check
+```
+
+## Recap
+
+- `uv add --dev tempest-cli`, Python 3.11+, só o `typer` de dependência.
+- Dois executáveis: `tempest-cli` e o apelido `tc`.
+- As ferramentas vêm do ambiente da execução, do `PATH` (sem shim morto)
+  ou do `uv run --with`.
+- Ferramenta ausente = saída 127 com mensagem, não traceback.

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Framework-agnostic quality gate for Python projects: ruff + mypy + pytest behind one command, with a typing-strictness dial and a PR-description prompt generator."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -53,6 +53,10 @@ Documentation = "https://mauriciobenjamin700.github.io/tempest-cli/"
 
 [project.scripts]
 tempest-cli = "tempest_cli.main:main"
+# `tc` is the short alias for the same entry point. It shadows iproute2's
+# `tc(8)` while the environment providing it is on PATH — a traffic-control
+# call must then be made through its absolute path (/usr/sbin/tc).
+tc = "tempest_cli.main:main"
 
 [build-system]
 requires = ["hatchling"]

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/tempest_cli/__init__.py

@@ -14,6 +14,8 @@ tempest-cli check                 # lint + fmt-check + type + test
 tempest-cli fix                   # every ruff autofix, then format
 tempest-cli type -s strict        # override the configured strictness
 tempest-cli pr-prompt | claude -p
+
+tc check                          # `tc` is the short alias for the same CLI
 ```
 
 Everything is importable too, for a project that would rather wire the
@@ -47,7 +49,7 @@ from tempest_cli.pr_prompt import GitError as GitError
 from tempest_cli.pr_prompt import PromptLanguage as PromptLanguage
 from tempest_cli.pr_prompt import generate_pr_prompt as generate_pr_prompt
 
-__version__: str = "0.1.0"
+__version__: str = "0.2.0"
 """Installed package version."""
 
 __all__: list[str] = [

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/tempest_cli/lint.py

@@ -2,14 +2,19 @@
 
 from __future__ import annotations
 
+import os
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
 import typer
 
 from tempest_cli.config import TempestConfig
 
+SHIM_PROBE_TIMEOUT_SECONDS = 20.0
+"""Seconds allowed for the ``<tool> --version`` probe of a version-manager shim."""
+
 
 def _ruff_ann_args(config: TempestConfig | None) -> list[str]:
     """Build the ruff ``--extend-select`` args for ``config``'s level.
@@ -28,20 +33,138 @@ def _ruff_ann_args(config: TempestConfig | None) -> list[str]:
     return ["--extend-select", ",".join(codes)]
 
 
+def _environment_dirs() -> list[Path]:
+    """Return the executable directories searched ahead of ``PATH``.
+
+    ``PATH`` is a poor first answer on a machine running a version
+    manager: pyenv/asdf put their shim directory on it globally, so a
+    lookup finds ``~/.pyenv/shims/ruff`` even when the project's own
+    environment has no ruff at all. The environments below are the ones
+    that actually belong to the run, so they are consulted first:
+
+    1. the directory of the interpreter running this CLI — where the
+       ``[tools]`` extra installs ruff/mypy/pytest next to the
+       ``tempest-cli`` executable itself;
+    2. ``$VIRTUAL_ENV`` — the activated environment, which matters when
+       the CLI itself lives elsewhere (``uv tool install`` / pipx);
+    3. the nearest ``.venv`` walking up from the working directory — a
+       project environment that was never activated.
+
+    Returns:
+        list[Path]: Existing directories, in preference order, without
+        duplicates.
+    """
+    roots: list[Path] = [Path(sys.executable).parent]
+    virtual_env = os.environ.get("VIRTUAL_ENV")
+    if virtual_env:
+        roots.extend((Path(virtual_env) / "bin", Path(virtual_env) / "Scripts"))
+    try:
+        cwd = Path.cwd()
+    except OSError:
+        cwd = None
+    if cwd is not None:
+        for directory in (cwd, *cwd.parents):
+            candidate = directory / ".venv"
+            if candidate.is_dir():
+                roots.extend((candidate / "bin", candidate / "Scripts"))
+                break
+    seen: set[Path] = set()
+    ordered: list[Path] = []
+    for root in roots:
+        if root not in seen and root.is_dir():
+            seen.add(root)
+            ordered.append(root)
+    return ordered
+
+
+def _is_shim(path: Path) -> bool:
+    """Report whether ``path`` looks like a version-manager shim.
+
+    pyenv, asdf and rbenv all install their shims into a directory named
+    ``shims``. A shim is a stub that exists for every tool any installed
+    interpreter version ever provided, so its presence says nothing
+    about whether the command can actually run right now.
+
+    Args:
+        path (Path): The resolved executable path.
+
+    Returns:
+        bool: True when the executable sits in a ``shims`` directory.
+    """
+    return path.parent.name == "shims"
+
+
+def _shim_runs(path: Path) -> bool:
+    """Report whether a shim actually dispatches to a real executable.
+
+    Runs ``<path> --version`` and reads the exit code. A pyenv shim for
+    a tool missing from the selected version prints ``pyenv: ruff:
+    command not found`` and exits non-zero — running the gate through it
+    would fail with that message instead of falling back to a runner
+    that works.
+
+    Args:
+        path (Path): The shim to probe.
+
+    Returns:
+        bool: True when the probe exits ``0``. False on a non-zero exit,
+        a timeout, or an OS-level failure to spawn.
+    """
+    try:
+        completed = subprocess.run(
+            [str(path), "--version"],
+            capture_output=True,
+            timeout=SHIM_PROBE_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return completed.returncode == 0
+
+
+def _path_lookup(executable: str) -> str | None:
+    """Find ``executable`` on ``PATH``, rejecting a shim that goes nowhere.
+
+    Args:
+        executable (str): The command name to look up.
+
+    Returns:
+        str | None: The resolved path, or ``None`` when the command is
+        absent or resolves to a shim that does not dispatch.
+    """
+    found = shutil.which(executable)
+    if found is None:
+        return None
+    path = Path(found)
+    if _is_shim(path) and not _shim_runs(path):
+        return None
+    return found
+
+
 def resolve_tool(executable: str) -> list[str] | None:
     """Return an argv prefix invoking ``executable`` or ``None`` when absent.
 
     Public because callers outside the gate need the same lookup — the
     SDK's OpenAPI code generator formats what it emits with the project's
-    own ruff, and reimplementing the PATH/``uv run`` fallback there would
-    be a second answer to the same question.
+    own ruff, and reimplementing the environment/``uv run`` fallback
+    there would be a second answer to the same question.
 
     Preference order:
 
-    1. ``executable`` available on ``PATH`` directly (already activated venv,
-       global install, etc.).
-    2. ``uv run <executable>`` when ``uv`` is on the ``PATH`` (handles
-       project-local virtualenvs without requiring activation).
+    1. the environments that belong to this run (see
+       :func:`_environment_dirs`): the CLI's own interpreter directory,
+       ``$VIRTUAL_ENV``, then the nearest ``.venv``;
+    2. ``executable`` on ``PATH`` — skipped when it resolves to a
+       version-manager shim that does not dispatch anywhere;
+    3. ``uv run --with <executable> <executable>`` when ``uv`` is on the
+       ``PATH``: the project's own environment plus the tool, without
+       requiring activation or a prior ``uv sync``.
+
+    Step 3 carries ``--with`` on purpose. A plain ``uv run ruff`` falls
+    back to ``PATH`` when the project environment has no ruff — landing
+    right back on the dead shim this lookup just rejected. ``--with``
+    puts the tool in the run's own overlay, so the command is always the
+    one that runs. When the project pins a version, uv resolves the
+    overlay against the project's requirements, so the pin still wins.
 
     Args:
         executable (str): The command name (``ruff``/``mypy``/``pytest``).
@@ -50,12 +173,16 @@ def resolve_tool(executable: str) -> list[str] | None:
         list[str] | None: argv prefix to extend with extra arguments, or
         ``None`` when no runner could be found.
     """
-    direct = shutil.which(executable)
+    for directory in _environment_dirs():
+        local = shutil.which(executable, path=str(directory))
+        if local is not None:
+            return [local]
+    direct = _path_lookup(executable)
     if direct is not None:
         return [direct]
-    uv = shutil.which("uv")
+    uv = _path_lookup("uv")
     if uv is not None:
-        return [uv, "run", executable]
+        return [uv, "run", "--with", executable, executable]
     return None
 
 
@@ -73,8 +200,10 @@ def _execute(executable: str, args: list[str]) -> int:
     argv = resolve_tool(executable)
     if argv is None:
         typer.echo(
-            f"error: '{executable}' is not on PATH and 'uv' is unavailable. "
-            f"Install it (or activate the project venv) and retry.",
+            f"error: '{executable}' was not found in this project's environment, "
+            f"on PATH, and 'uv' is unavailable to run it. "
+            f"Install it with 'uv add --dev {executable}' — or the whole set "
+            f"with 'uv add --dev \"tempest-cli[tools]\"' — and retry.",
             err=True,
         )
         return 127

{tempest_cli-0.1.0 → tempest_cli-0.2.0}/tests/test_cli.py

@@ -82,6 +82,26 @@ def test_public_surface_is_importable() -> None:
         assert hasattr(tempest_cli, name), name
 
 
+def test_both_console_scripts_point_at_the_same_entry_point() -> None:
+    """`tc` is the short alias, so it must stay wired to `main`.
+
+    Read from the installed distribution rather than from
+    ``pyproject.toml``: what matters is the script a user actually got,
+    which is what the wheel declared at build time.
+    """
+    from importlib.metadata import entry_points
+
+    scripts = {
+        entry.name: entry.value
+        for entry in entry_points(group="console_scripts")
+        if entry.name in {"tempest-cli", "tc"}
+    }
+    assert scripts == {
+        "tempest-cli": "tempest_cli.main:main",
+        "tc": "tempest_cli.main:main",
+    }
+
+
 def test_importing_the_package_pulls_no_web_framework() -> None:
     """The whole point of the extraction: no FastAPI, no SQLAlchemy."""
     import subprocess