lib-cli-exit-tools 2.3.4__tar.gz → 2.4.1__tar.gz

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.1}/.github/workflows/default_cicd_public.yml

@@ -124,9 +124,36 @@ jobs:
               print("No CI system dependencies configured for macOS.")
 
       - name: Install dev deps
-        shell: bash
+        shell: python
         run: |
-          uv pip install -e .[dev] --system
+          import os, subprocess, tempfile
+          from pathlib import Path
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import pip._vendor.tomli as tomllib
+
+          # Push and pull_request runs install exactly the tree uv.lock pins - versions
+          # plus file hashes, which uv verifies - so CI tests what the lock ships and no
+          # release published upstream since the last lock refresh can enter the build.
+          # The nightly schedule run resolves afresh instead (still inside the project's
+          # [tool.uv] exclude-newer cooldown, which uv honours here): it is the canary
+          # that reports upstream breakage before a lock refresh adopts it. A project
+          # without a uv.lock keeps the unlocked install.
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          # Asking uv for an extra the project does not declare is a hard error.
+          extra = ["--extra", "dev"] if "dev" in data.get("project", {}).get("optional-dependencies", {}) else []
+          target = ["--system"]  # setup-python's interpreter; the job runs no venv
+          locked = Path("uv.lock").is_file() and os.environ["GITHUB_EVENT_NAME"] != "schedule"
+          if locked:
+              req = Path(tempfile.mkdtemp()) / "locked-requirements.txt"
+              # --locked fails when pyproject.toml changed without a lock refresh.
+              subprocess.check_call(["uv", "export", "--locked", "--no-emit-project", *extra, "-o", str(req), "--quiet"])
+              subprocess.check_call(["uv", "pip", "install", *target, "-r", str(req)])
+              subprocess.check_call(["uv", "pip", "install", *target, "--no-deps", "-e", "."])
+          else:
+              subprocess.check_call(["uv", "pip", "install", *target, "-e", ".[dev]" if extra else "."])
 
       - name: Install CI system dependencies (Windows/choco)
         if: runner.os == 'Windows'
@@ -236,7 +263,7 @@ jobs:
         continue-on-error: true
         shell: python
         run: |
-          import subprocess, sys, tempfile
+          import os, subprocess, sys, tempfile
           import rtoml
           from pathlib import Path
 
@@ -263,9 +290,18 @@ jobs:
 
           tmp = Path(tempfile.mkdtemp())
           req = tmp / "compiled-requirements.txt"
-          subprocess.check_call(
-              ["uv", "pip", "compile", *selector, "pyproject.toml", "-o", str(req), "--quiet"]
-          )
+          # With a uv.lock the install step put exactly the locked tree on the
+          # runner, so audit that tree; the schedule canary and lock-less
+          # projects resolve pyproject.toml afresh, as their install did.
+          if Path("uv.lock").is_file() and os.environ["GITHUB_EVENT_NAME"] != "schedule":
+              subprocess.check_call(
+                  ["uv", "export", "--locked", "--no-emit-project", "--no-hashes", *selector,
+                   "-o", str(req), "--quiet"]
+              )
+          else:
+              subprocess.check_call(
+                  ["uv", "pip", "compile", *selector, "pyproject.toml", "-o", str(req), "--quiet"]
+              )
 
           # Drop direct URL references ("pkg @ git+https://...") before auditing.
           # pip-audit cannot audit those (they are not on PyPI) but, given a

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.1}/.gitignore

@@ -46,7 +46,8 @@ tmp_*
 # *.py[cod]: catches .pyc, .pyo, .pyd
 __pycache__/
 *.py[cod]
-*$py.class     # other compiled artifacts
+# other compiled artifacts
+*$py.class
 
 # pytest, coverage, MyPy, Hypothesis
 .pytest_cache/
@@ -72,12 +73,15 @@ coverage.xml
 # source/package builds
 build/
 dist/
-*.egg-info/    # metadata for pip installs
+# metadata for pip installs
+*.egg-info/
 *.egg
 *.whl
 pip-wheel-metadata/
-*.manifest     # PyInstaller metadata
-*.spec         # PyInstaller spec files
+# PyInstaller metadata
+*.manifest
+# PyInstaller spec files
+*.spec
 
 # Eggs, parts, wheels, sdist, etc.
 develop-eggs/
@@ -177,7 +181,6 @@ result
 # Optional lockfiles (for alternative managers)
 poetry.lock
 pdm.lock
-uv.lock
 /.github_bak/
 prompts.md
 CLAUDE.md

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.1}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [2.4.1] 2026-10-12 22:22:57
+
+### Added
+- Python 3.15 is a supported version: declared in the classifiers, so CI and `make test-all` run it.
+- `uv.lock` is committed, and `[tool.uv] exclude-newer` sets a cooldown that keeps releases younger
+  than it out of the lock. CI installs exactly the locked tree on push and pull request; the nightly
+  scheduled run still resolves afresh to catch upstream breakage early.
+
+### Changed
+- The install section explains why installing with uv protects against supply-chain attacks and why
+  a plain `pip install` from PyPI does not.
+- `rtoml` floor raised to 0.14.0 (dev extra), the first release with Python 3.15 wheels.
+
+## [2.4.0] 2026-10-05 20:48:53
+
+### Fixed
+- `cli_session()` now resolves exit codes the way `run_cli()`'s default handler does. Its handler went straight to a traceback summary plus `get_system_exit_code()`, skipping the resolver chain, so under a session a Click usage error (bad flag, unknown command) exited `1` and printed `NoSuchOption: ...` instead of exiting `2` with Click's usage message, a `ClickException` with its own `exit_code` lost it, and the `signal_specs` passed to the session runner were ignored. The session's `summary_limit`/`verbose_limit` still apply to an exception nothing else claims. CLIs built on `cli_session` now report a usage error as `2`, like Click and like `run_cli`.
+
+### Added
+- `SessionRunner`, a `Protocol` typing the callable `cli_session()` yields. The previous annotation was a union whose first member took only the command, so a type checker rejected `run(cmd, argv=[...])` and callers had to `cast` the session.
+
+### Changed
+- `README.md` is ASCII-only, and its `cli_session` section says how the session's handler resolves exit codes.
+- Raised the dev tool floors.
+
 ## [2.3.4] 2026-07-29 15:20:59
 
 ### Fixed

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.1}/Makefile

@@ -1,4 +1,4 @@
-# BMK MAKEFILE 3.13.2
+# BMK MAKEFILE 3.21.0
 # do not alter this file - it might be overwritten on new versions of BMK
 # if You want to alter it, remove the first line # BMK MAKEFILE 1.0 - then it is a custom makefile and will not be overwritten
 # bmk Makefile - thin wrapper using `uv tool upgrade` for persistent bmk
@@ -186,16 +186,50 @@ endif
 # BMK_MIN floors the FALLBACK install. The upgrade path does not consult it: uv re-resolves
 # the requirement recorded at install time, which is itself a `bmk>=...`, so it always lands
 # on the newest release and clears the floor anyway.
-BMK_MIN := 3.13.2
+BMK_MIN := 3.21.0
 
 # Absent env, missing check, or damaged env - all three mean "do not upgrade, rebuild".
 # `test -x` keeps a fresh machine quiet: there is no interpreter to run yet.
 BMK_INTACT := $(if $(BMK_PY),test -x "$(BMK_PY)" && "$(BMK_PY)" -m bmk_selfcheck,false)
 
+# The env this recipe mutates is shared by EVERY repo on the machine, so the mutation has to
+# wait for the bmk processes running out of it. Every bmk started from that env holds a
+# SHARED lock on <uv tool dir>/.bmk-tool.lock for its whole lifetime; these wrappers take
+# the same lock EXCLUSIVE for the length of the upgrade. Without it, a make here deleted the
+# site-packages out from under a bmk minutes into a test suite in an UNRELATED repo, and it
+# surfaced as an ImportError inside bmk's OWN dependencies that cleared on a re-run - so it
+# read as a flake rather than as the environment vanishing mid-gate.
+#
+# `bmk_toollock` is a second stdlib-only TOP-LEVEL module bmk ships, run on the tool env's
+# own interpreter. That is not circular: a uv tool env's bin/python is a SYMLINK to a base
+# interpreter OUTSIDE the tool dir, so the stdlib the guard runs on is not part of the tree
+# uv is about to replace, and the guard is read and compiled before uv is ever spawned.
+#
+# NOT uv's own <uv tool dir>/.lock, which uv does honour: `uv tool upgrade` and `uv tool
+# list` block on it too (measured), and the upgrade runs before every target - so a
+# gate-lifetime shared lock there would make every make on the machine, and every unrelated
+# `uv tool install`, wait for the longest-running gate.
+#
+# $(wildcard) rather than a shell test: on a machine with no tool env yet these expand to
+# NOTHING and the install runs bare, which is exactly what a first install needs.
+#
+# The bounded wait is load-bearing in both directions. An unbounded one would serialise
+# every repo's make behind the longest gate on the machine. A SKIPPED upgrade costs nothing
+# (the next make picks it up), so the upgrade skips. The REPAIR may not skip: proceeding
+# would leave a damaged env in place, so it fails and drops through to the retry.
+#
+# The LAST attempt is deliberately NEVER guarded, and a test pins that. The guard lives
+# inside the env being repaired, so on the path where that env is absent or broken the guard
+# may be broken too; an unguarded last resort is what stops a defective guard from making
+# `make` unrunnable in every repo at once. If bmk_toollock ever falls out of the wheel, every
+# make everywhere drops to a full reinstall - there is a packaging test for exactly that.
+BMK_LOCK := $(if $(wildcard $(BMK_PY)),"$(BMK_PY)" -m bmk_toollock --exclusive --timeout 10 --on-timeout skip --,)
+BMK_LOCK_REPAIR := $(if $(wildcard $(BMK_PY)),"$(BMK_PY)" -m bmk_toollock --exclusive --timeout 60 --on-timeout fail --,)
+
 .PHONY: _ensure_bmk
 _ensure_bmk:
-	@$(BMK_INTACT) && uv tool upgrade bmk \
-	  || uv tool install --reinstall --force "bmk>=$(BMK_MIN)" \
+	@$(BMK_INTACT) && $(BMK_LOCK) uv tool upgrade bmk \
+	  || $(BMK_LOCK_REPAIR) uv tool install --reinstall --force "bmk>=$(BMK_MIN)" \
 	  || uv tool install --reinstall --force "bmk>=$(BMK_MIN)"
 
 # ──────────────────────────────────────────────────────────────

lib_cli_exit_tools-2.3.4/README.md → lib_cli_exit_tools-2.4.1/PKG-INFO

@@ -1,3 +1,46 @@
+Metadata-Version: 2.5
+Name: lib_cli_exit_tools
+Version: 2.4.1
+Summary: CLI exit handling helpers: clean signals, exit codes, and error printing
+Project-URL: Homepage, https://github.com/bitranox/lib_cli_exit_tools
+Project-URL: Repository, https://github.com/bitranox/lib_cli_exit_tools.git
+Project-URL: Issues, https://github.com/bitranox/lib_cli_exit_tools/issues
+Author-email: bitranox <bitranox@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,click,errors,exit,signals
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rich-click>=1.9.9
+Provides-Extra: dev
+Requires-Dist: bandit>=1.9.4; extra == 'dev'
+Requires-Dist: build>=1.6.1; extra == 'dev'
+Requires-Dist: click>=8.5.0; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.16.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.168.5; extra == 'dev'
+Requires-Dist: import-linter>=2.15; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.1; extra == 'dev'
+Requires-Dist: pyright[nodejs]>=1.1.414; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: rtoml>=0.14.0; extra == 'dev'
+Requires-Dist: ruff>=0.17.0; extra == 'dev'
+Requires-Dist: textual>=8.2.8; extra == 'dev'
+Requires-Dist: twine>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # lib_cli_exit_tools
 
 <!-- Badges -->
@@ -21,15 +64,15 @@ Small helpers for robust CLI exit handling:
 
 Building CLI applications that behave correctly in shell pipelines, CI/CD systems, and across platforms is surprisingly tricky. This library solves five common pain points:
 
-1. **Correct Exit Codes** — Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` — matching shell conventions without manual bookkeeping.
+1. **Correct Exit Codes** - Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` - matching shell conventions without manual bookkeeping.
 
-2. **Portable Signal Handling** — SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
+2. **Portable Signal Handling** - SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
 
-3. **Clean Error Output** — Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging — no code changes required.
+3. **Clean Error Output** - Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging - no code changes required.
 
-4. **Pipeline-Friendly** — `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
+4. **Pipeline-Friendly** - `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
 
-5. **Zero Boilerplate** — Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
+5. **Zero Boilerplate** - Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
 
 ## Install
 
@@ -41,6 +84,36 @@ pip install lib_cli_exit_tools
 
 See [INSTALL.md](INSTALL.md) for editable installs, pipx/uv usage, and troubleshooting tips.
 
+### Why we recommend uv: supply-chain protection
+
+This repository commits a `uv.lock`. It pins every package the project needs, transitive
+dependencies included, to an exact version and to the hashes of that version's files. The
+`exclude-newer` setting under `[tool.uv]` in `pyproject.toml` adds a cooldown: uv leaves any
+release younger than that out of the lock. CI installs from the lock, so a hijacked release that
+gets pulled again within the cooldown never reaches our builds, and a file whose hash does not
+match is refused.
+
+That protection stays in this repository. The installable package declares only lower bounds
+(`>=`) for its dependencies, so a plain `pip install` takes the newest release of every transitive
+dependency at the moment you run it. If one of them was hijacked an hour earlier, you get the
+hijacked version. `pipx install` and `uv tool install` without options do the same.
+
+To install the command line tool with a cooldown of your own (uv then skips any release younger
+than 7 days, transitive ones included), or to run the exact tree our CI tests:
+
+```bash
+uv tool install --exclude-newer "7 days" lib_cli_exit_tools
+git clone https://github.com/bitranox/lib_cli_exit_tools.git && cd lib_cli_exit_tools && uv sync --locked && uv run lib_cli_exit_tools --help
+```
+
+If you depend on lib_cli_exit_tools in your own project, give that project the same cooldown (7 days here, as
+an example) and commit the `uv.lock` that `uv add lib_cli_exit_tools` writes:
+
+```toml
+[tool.uv]
+exclude-newer = "7 days"
+```
+
 ## Usage
 
 Console script (all commands map to ``lib_cli_exit_tools.cli:main``):
@@ -59,11 +132,11 @@ The library installs three equivalent console scripts: `lib-cli-exit-tools` (pri
 
 ### Global Options
 
-| Option | Default | Description |
-|--------|---------|-------------|
+| Option                           | Default | Description                          |
+|----------------------------------|---------|--------------------------------------|
 | `--traceback` / `--no-traceback` | `False` | Show full Python traceback on errors |
-| `--version` | — | Show program version and exit |
-| `-h`, `--help` | — | Show help message and exit |
+| `--version`                      | -       | Show program version and exit        |
+| `-h`, `--help`                   | -       | Show help message and exit           |
 
 ### Commands
 
@@ -84,7 +157,7 @@ lib-cli-exit-tools --traceback fail  # show full traceback
 
 ### Examples
 
-The snippets below move from a minimal “hello world” through a production-ready
+The snippets below move from a minimal "hello world" through a production-ready
 CLI that demonstrates configuration hooks and structured error handling.
 
 #### 1. Minimal command (copy-paste ready)
@@ -181,7 +254,7 @@ def info(settings: Settings) -> None:
 @cli.command()
 @click.pass_obj
 def fail(settings: Settings) -> None:
-    click.echo("About to fail…")
+    click.echo("About to fail...")
     raise RuntimeError("intentional failure for diagnostics")
 
 
@@ -202,7 +275,7 @@ if __name__ == "__main__":
 
 This version parses `--traceback` early (before Click sees it), then wires
 configuration overrides, custom signal specs, and multiple commands into a
-single composition point—mirroring how a production CLI can layer policy logic
+single composition point - mirroring how a production CLI can layer policy logic
 around Click while still delegating exit-code translation to `lib_cli_exit_tools`.
 
 #### 4. Custom signal handlers
@@ -315,20 +388,20 @@ All configuration lives on the module-level `lib_cli_exit_tools.config` object.
 from lib_cli_exit_tools import config
 
 config.traceback = True  # emit full tracebacks instead of short messages
-config.exit_code_style = "sysexits"  # emit BSD-style exit codes (EX_USAGE, EX_NOINPUT, …)
+config.exit_code_style = "sysexits"  # emit BSD-style exit codes (EX_USAGE, EX_NOINPUT, ...)
 config.broken_pipe_exit_code = 0  # treat BrokenPipeError as a benign truncation
 ```
 
 Field reference:
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `traceback` | `bool` | `False` | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`. |
-| `exit_code_style` | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
-| `broken_pipe_exit_code` | `int` | `141` | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success. |
-| `traceback_force_color` | `bool` | `False` | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs. |
+| Field                   | Type                      | Default   | Description                                                                                                                                      |
+|-------------------------|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `traceback`             | `bool`                    | `False`   | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`.      |
+| `exit_code_style`       | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
+| `broken_pipe_exit_code` | `int`                     | `141`     | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success.                                  |
+| `traceback_force_color` | `bool`                    | `False`   | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs.                                                   |
 
-Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
+Remember that `config` is module-level - if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
 
 ```python
 from lib_cli_exit_tools import config_overrides, config
@@ -385,13 +458,13 @@ python -m scripts.test --coverage=off --verbose
 The suite includes OS-aware cases (POSIX, Windows-specific signal handling), so
 run it on each target platform you support to keep coverage consistent.
 
-If your environment reports “cannot execute” when running `pytest`, the auto-generated entry-point script likely points at a removed interpreter. Reinstall the dev extras or invoke tests with `python -m pytest` (for example, `python -m pytest tests/`).
+If your environment reports "cannot execute" when running `pytest`, the auto-generated entry-point script likely points at a removed interpreter. Reinstall the dev extras or invoke tests with `python -m pytest` (for example, `python -m pytest tests/`).
 
 When coverage uploads are skipped (no Codecov token), `make test` still writes `coverage.xml` and `codecov.xml` to the project root so you can inspect results locally or feed them into other tooling.
 
 ## Public API Reference
 
-The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import …`.
+The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import ...`.
 
 ### `config`
 Mutable dataclass-like singleton holding process-wide settings. Configure it during CLI startup.
@@ -415,8 +488,12 @@ Parameters:
 
 ### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None, restore=True)`
 Context manager that snapshots `lib_cli_exit_tools.config`, optionally
-applies temporary overrides, and yields a callable compatible with
-`run_cli`.
+applies temporary overrides, and yields a `SessionRunner`: a callable with
+`run_cli`'s signature. Its exception handler resolves exit codes exactly like
+`handle_cli_exception` - signals, broken pipes, Click exceptions and `SystemExit`
+keep their own code and message, so a usage error exits `2` with Click's usage
+text - and applies `summary_limit`/`verbose_limit` only to an exception none of
+those claims.
 
 Parameters:
 - `summary_limit` (`int`, default `500`): Character budget when tracebacks are disabled.
@@ -424,7 +501,7 @@ Parameters:
 - `overrides` (`Mapping[str, object] | None`, default `None`): Mapping of configuration field/value pairs applied during the session. When `traceback` is supplied and `traceback_force_color` is omitted, colour output is automatically forced.
 - `restore` (`bool`, default `True`): When `True`, configuration state is restored after the session. Set to `False` to leave overrides in place once the context exits.
 
-Use it to restore configuration automatically—even when the wrapped command
+Use it to restore configuration automatically - even when the wrapped command
 raises:
 
 ```python

lib_cli_exit_tools-2.3.4/PKG-INFO → lib_cli_exit_tools-2.4.1/README.md

@@ -1,45 +1,3 @@
-Metadata-Version: 2.4
-Name: lib_cli_exit_tools
-Version: 2.3.4
-Summary: CLI exit handling helpers: clean signals, exit codes, and error printing
-Project-URL: Homepage, https://github.com/bitranox/lib_cli_exit_tools
-Project-URL: Repository, https://github.com/bitranox/lib_cli_exit_tools.git
-Project-URL: Issues, https://github.com/bitranox/lib_cli_exit_tools/issues
-Author-email: bitranox <bitranox@gmail.com>
-License: MIT
-License-File: LICENSE
-Keywords: cli,click,errors,exit,signals
-Classifier: Environment :: Console
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: rich-click>=1.9.8
-Provides-Extra: dev
-Requires-Dist: bandit>=1.9.4; extra == 'dev'
-Requires-Dist: build>=1.5.0; extra == 'dev'
-Requires-Dist: click>=8.4.2; extra == 'dev'
-Requires-Dist: coverage[toml]>=7.15.2; extra == 'dev'
-Requires-Dist: hypothesis>=6.163.0; extra == 'dev'
-Requires-Dist: import-linter>=2.13; extra == 'dev'
-Requires-Dist: pip-audit>=2.10.1; extra == 'dev'
-Requires-Dist: pyright[nodejs]>=1.1.411; extra == 'dev'
-Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
-Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
-Requires-Dist: pytest>=9.1.1; extra == 'dev'
-Requires-Dist: rtoml>=0.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.16.0; extra == 'dev'
-Requires-Dist: textual>=8.2.8; extra == 'dev'
-Requires-Dist: twine>=7.0.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # lib_cli_exit_tools
 
 <!-- Badges -->
@@ -63,15 +21,15 @@ Small helpers for robust CLI exit handling:
 
 Building CLI applications that behave correctly in shell pipelines, CI/CD systems, and across platforms is surprisingly tricky. This library solves five common pain points:
 
-1. **Correct Exit Codes** — Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` — matching shell conventions without manual bookkeeping.
+1. **Correct Exit Codes** - Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` - matching shell conventions without manual bookkeeping.
 
-2. **Portable Signal Handling** — SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
+2. **Portable Signal Handling** - SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
 
-3. **Clean Error Output** — Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging — no code changes required.
+3. **Clean Error Output** - Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging - no code changes required.
 
-4. **Pipeline-Friendly** — `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
+4. **Pipeline-Friendly** - `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
 
-5. **Zero Boilerplate** — Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
+5. **Zero Boilerplate** - Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
 
 ## Install
 
@@ -83,6 +41,36 @@ pip install lib_cli_exit_tools
 
 See [INSTALL.md](INSTALL.md) for editable installs, pipx/uv usage, and troubleshooting tips.
 
+### Why we recommend uv: supply-chain protection
+
+This repository commits a `uv.lock`. It pins every package the project needs, transitive
+dependencies included, to an exact version and to the hashes of that version's files. The
+`exclude-newer` setting under `[tool.uv]` in `pyproject.toml` adds a cooldown: uv leaves any
+release younger than that out of the lock. CI installs from the lock, so a hijacked release that
+gets pulled again within the cooldown never reaches our builds, and a file whose hash does not
+match is refused.
+
+That protection stays in this repository. The installable package declares only lower bounds
+(`>=`) for its dependencies, so a plain `pip install` takes the newest release of every transitive
+dependency at the moment you run it. If one of them was hijacked an hour earlier, you get the
+hijacked version. `pipx install` and `uv tool install` without options do the same.
+
+To install the command line tool with a cooldown of your own (uv then skips any release younger
+than 7 days, transitive ones included), or to run the exact tree our CI tests:
+
+```bash
+uv tool install --exclude-newer "7 days" lib_cli_exit_tools
+git clone https://github.com/bitranox/lib_cli_exit_tools.git && cd lib_cli_exit_tools && uv sync --locked && uv run lib_cli_exit_tools --help
+```
+
+If you depend on lib_cli_exit_tools in your own project, give that project the same cooldown (7 days here, as
+an example) and commit the `uv.lock` that `uv add lib_cli_exit_tools` writes:
+
+```toml
+[tool.uv]
+exclude-newer = "7 days"
+```
+
 ## Usage
 
 Console script (all commands map to ``lib_cli_exit_tools.cli:main``):
@@ -101,11 +89,11 @@ The library installs three equivalent console scripts: `lib-cli-exit-tools` (pri
 
 ### Global Options
 
-| Option | Default | Description |
-|--------|---------|-------------|
+| Option                           | Default | Description                          |
+|----------------------------------|---------|--------------------------------------|
 | `--traceback` / `--no-traceback` | `False` | Show full Python traceback on errors |
-| `--version` | — | Show program version and exit |
-| `-h`, `--help` | — | Show help message and exit |
+| `--version`                      | -       | Show program version and exit        |
+| `-h`, `--help`                   | -       | Show help message and exit           |
 
 ### Commands
 
@@ -126,7 +114,7 @@ lib-cli-exit-tools --traceback fail  # show full traceback
 
 ### Examples
 
-The snippets below move from a minimal “hello world” through a production-ready
+The snippets below move from a minimal "hello world" through a production-ready
 CLI that demonstrates configuration hooks and structured error handling.
 
 #### 1. Minimal command (copy-paste ready)
@@ -223,7 +211,7 @@ def info(settings: Settings) -> None:
 @cli.command()
 @click.pass_obj
 def fail(settings: Settings) -> None:
-    click.echo("About to fail…")
+    click.echo("About to fail...")
     raise RuntimeError("intentional failure for diagnostics")
 
 
@@ -244,7 +232,7 @@ if __name__ == "__main__":
 
 This version parses `--traceback` early (before Click sees it), then wires
 configuration overrides, custom signal specs, and multiple commands into a
-single composition point—mirroring how a production CLI can layer policy logic
+single composition point - mirroring how a production CLI can layer policy logic
 around Click while still delegating exit-code translation to `lib_cli_exit_tools`.
 
 #### 4. Custom signal handlers
@@ -357,20 +345,20 @@ All configuration lives on the module-level `lib_cli_exit_tools.config` object.
 from lib_cli_exit_tools import config
 
 config.traceback = True  # emit full tracebacks instead of short messages
-config.exit_code_style = "sysexits"  # emit BSD-style exit codes (EX_USAGE, EX_NOINPUT, …)
+config.exit_code_style = "sysexits"  # emit BSD-style exit codes (EX_USAGE, EX_NOINPUT, ...)
 config.broken_pipe_exit_code = 0  # treat BrokenPipeError as a benign truncation
 ```
 
 Field reference:
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `traceback` | `bool` | `False` | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`. |
-| `exit_code_style` | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
-| `broken_pipe_exit_code` | `int` | `141` | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success. |
-| `traceback_force_color` | `bool` | `False` | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs. |
+| Field                   | Type                      | Default   | Description                                                                                                                                      |
+|-------------------------|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `traceback`             | `bool`                    | `False`   | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`.      |
+| `exit_code_style`       | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
+| `broken_pipe_exit_code` | `int`                     | `141`     | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success.                                  |
+| `traceback_force_color` | `bool`                    | `False`   | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs.                                                   |
 
-Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
+Remember that `config` is module-level - if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
 
 ```python
 from lib_cli_exit_tools import config_overrides, config
@@ -427,13 +415,13 @@ python -m scripts.test --coverage=off --verbose
 The suite includes OS-aware cases (POSIX, Windows-specific signal handling), so
 run it on each target platform you support to keep coverage consistent.
 
-If your environment reports “cannot execute” when running `pytest`, the auto-generated entry-point script likely points at a removed interpreter. Reinstall the dev extras or invoke tests with `python -m pytest` (for example, `python -m pytest tests/`).
+If your environment reports "cannot execute" when running `pytest`, the auto-generated entry-point script likely points at a removed interpreter. Reinstall the dev extras or invoke tests with `python -m pytest` (for example, `python -m pytest tests/`).
 
 When coverage uploads are skipped (no Codecov token), `make test` still writes `coverage.xml` and `codecov.xml` to the project root so you can inspect results locally or feed them into other tooling.
 
 ## Public API Reference
 
-The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import …`.
+The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import ...`.
 
 ### `config`
 Mutable dataclass-like singleton holding process-wide settings. Configure it during CLI startup.
@@ -457,8 +445,12 @@ Parameters:
 
 ### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None, restore=True)`
 Context manager that snapshots `lib_cli_exit_tools.config`, optionally
-applies temporary overrides, and yields a callable compatible with
-`run_cli`.
+applies temporary overrides, and yields a `SessionRunner`: a callable with
+`run_cli`'s signature. Its exception handler resolves exit codes exactly like
+`handle_cli_exception` - signals, broken pipes, Click exceptions and `SystemExit`
+keep their own code and message, so a usage error exits `2` with Click's usage
+text - and applies `summary_limit`/`verbose_limit` only to an exception none of
+those claims.
 
 Parameters:
 - `summary_limit` (`int`, default `500`): Character budget when tracebacks are disabled.
@@ -466,7 +458,7 @@ Parameters:
 - `overrides` (`Mapping[str, object] | None`, default `None`): Mapping of configuration field/value pairs applied during the session. When `traceback` is supplied and `traceback_force_color` is omitted, colour output is automatically forced.
 - `restore` (`bool`, default `True`): When `True`, configuration state is restored after the session. Set to `False` to leave overrides in place once the context exits.
 
-Use it to restore configuration automatically—even when the wrapped command
+Use it to restore configuration automatically - even when the wrapped command
 raises:
 
 ```python