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

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/.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/

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

@@ -4,6 +4,18 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [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.0}/Makefile

@@ -1,4 +1,4 @@
-# BMK MAKEFILE 3.13.2
+# BMK MAKEFILE 3.18.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.18.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 → lib_cli_exit_tools-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: lib_cli_exit_tools
-Version: 2.3.4
+Version: 2.4.0
 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
@@ -21,21 +21,21 @@ 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
+Requires-Dist: rich-click>=1.9.9
 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: 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.4; 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.411; 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.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.16.0; extra == 'dev'
+Requires-Dist: ruff>=0.16.10; extra == 'dev'
 Requires-Dist: textual>=8.2.8; extra == 'dev'
 Requires-Dist: twine>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -63,15 +63,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
 
@@ -101,11 +101,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 +126,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 +223,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 +244,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 +357,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 +427,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 +457,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 +470,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 → lib_cli_exit_tools-2.4.0}/README.md

@@ -21,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
 
@@ -59,11 +59,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 +84,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 +181,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 +202,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 +315,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 +385,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 +415,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 +428,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 → lib_cli_exit_tools-2.4.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "2.3.4"
+version = "2.4.0"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = ["rich-click>=1.9.8"]
+dependencies = ["rich-click>=1.9.9"]
 license = { text = "MIT" }
 authors = [{ name = "bitranox", email = "bitranox@gmail.com" }]
 keywords = ["cli", "exit", "signals", "errors", "click"]
@@ -40,7 +40,7 @@ Issues = "https://github.com/bitranox/lib_cli_exit_tools/issues"
 dev = [
   # 1.5.1 was yanked upstream (unintended breaking changes), so 1.5.0 is the newest usable
   # release; a >=1.5.1 floor has ZERO candidates and makes this extra unresolvable.
-  "build>=1.5.0",
+  "build>=1.6.1",
   # codecov-cli is disabled, not dropped: it requires click<8.3.0, which drags click back to
   # 8.2.1 - the version with CVE-2026-7246 (command injection in click.edit(), fixed in 8.3.3).
   # Nothing else here caps click, so with this line active the audit gate goes red on every
@@ -49,17 +49,17 @@ dev = [
   # Re-enable once codecov-cli relaxes its click<8.3.0 pin.
   # "codecov-cli>=11.2.8",
   # Transitive CVE pins
-  "click>=8.4.2",                # CVE-2026-7246
-  "coverage[toml]>=7.15.2",
-  "hypothesis>=6.163.0",
-  "import-linter>=2.13",
+  "click>=8.5.0",                # CVE-2026-7246
+  "coverage[toml]>=7.16.2",
+  "hypothesis>=6.168.4",
+  "import-linter>=2.15",
   "bandit>=1.9.4",
   "pip-audit>=2.10.1",
-  "pyright[nodejs]>=1.1.411",
+  "pyright[nodejs]>=1.1.414",
   "pytest>=9.1.1",
   "pytest-asyncio>=1.4.0",
   "pytest-cov>=7.1.0",
-  "ruff>=0.16.0",
+  "ruff>=0.16.10",
   "textual>=8.2.8",
   "rtoml>=0.13.0",
   "twine>=7.0.0"
@@ -72,7 +72,7 @@ cli-exit-tools = "lib_cli_exit_tools.cli:main"
 lib-cli-exit-tools = "lib_cli_exit_tools.cli:main"
 
 [build-system]
-requires = ["hatchling>=1.31.0"]
+requires = ["hatchling>=1.32.4"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/src/lib_cli_exit_tools/__init__conf__.py

@@ -26,7 +26,7 @@ name = "lib_cli_exit_tools"
 #: Human-readable summary shown in CLI help output.
 title = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "2.3.4"
+version = "2.4.0"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/lib_cli_exit_tools"
 #: Author attribution surfaced in CLI output.

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/src/lib_cli_exit_tools/application/runner.py

@@ -67,6 +67,7 @@ class ClickCommand(Protocol):
 
 __all__ = [
     "SessionOverrides",
+    "SessionRunner",
     "cli_session",
     "flush_streams",
     "handle_cli_exception",
@@ -75,6 +76,22 @@ __all__ = [
 ]
 
 
+class SessionRunner(Protocol):
+    """The callable :func:`cli_session` yields: :func:`run_cli` with the session's handler."""
+
+    def __call__(  # pragma: no cover - structural typing
+        self,
+        command: ClickCommand,
+        *,
+        argv: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        signal_specs: Sequence[SignalSpec] | None = None,
+        install_signals: bool = True,
+        exception_handler: Callable[[BaseException], int] | None = None,
+        signal_installer: Callable[[Sequence[SignalSpec] | None], Callable[[], None]] | None = None,
+    ) -> int: ...
+
+
 class _Echo(Protocol):
     """Protocol describing the echo interface expected by error handlers."""
 
@@ -360,7 +377,7 @@ def handle_cli_exception(
 
     specs = _resolve_signal_specs(signal_specs)
     echo_fn = _choose_echo(echo)
-    return _resolve_exit_code(exc, specs, echo_fn)
+    return _resolve_exit_code(exc, specs, echo_fn, fallback=_render_and_translate)
 
 
 def _choose_echo(echo: _Echo | None) -> _Echo:
@@ -372,13 +389,20 @@ def _resolve_exit_code(
     exc: BaseException,
     specs: Sequence[SignalSpec],
     echo: _Echo,
+    *,
+    fallback: Callable[[BaseException], int],
 ) -> int:
-    """Walk the resolver chain until a numeric exit code emerges."""
+    """Walk the resolver chain; hand an exception none of them claims to ``fallback``.
+
+    Signals, broken pipes, Click exceptions and ``SystemExit`` carry their own
+    exit code and message, so only an otherwise unhandled exception reaches
+    ``fallback``, which renders it and maps it to a code.
+    """
     for resolver in _exception_resolvers(specs, echo):
         code = resolver(exc)
         if code is not None:
             return code
-    return _render_and_translate(exc)
+    return fallback(exc)
 
 
 def _exception_resolvers(
@@ -466,15 +490,7 @@ def cli_session(
     verbose_limit: int = 10_000,
     overrides: SessionOverrides | None = None,
     restore: bool = True,
-) -> Generator[
-    Callable[
-        [
-            ClickCommand,
-        ],
-        int,
-    ]
-    | Callable[..., int]
-]:
+) -> Generator[SessionRunner]:
     """Provide a managed execution context around :func:`run_cli`.
 
     Why
@@ -509,7 +525,7 @@ def cli_session(
 
     Yields
     ------
-    Callable
+    SessionRunner
         Function that accepts a Click command and forwards optional ``run_cli``
         keyword arguments, returning the resulting exit code.
     """
@@ -518,7 +534,6 @@ def cli_session(
     manager = _session_config_manager(applied, restore=restore)
 
     with manager:
-        handler = _session_exception_handler(summary_limit, verbose_limit)
 
         def _run(
             command: ClickCommand,
@@ -530,7 +545,11 @@ def cli_session(
             exception_handler: Callable[[BaseException], int] | None = None,
             signal_installer: Callable[[Sequence[SignalSpec] | None], Callable[[], None]] | None = None,
         ) -> int:
-            chosen_handler = exception_handler or handler
+            chosen_handler = exception_handler or _session_exception_handler(
+                summary_limit=summary_limit,
+                verbose_limit=verbose_limit,
+                signal_specs=signal_specs,
+            )
             return run_cli(
                 command,
                 argv=argv,
@@ -587,15 +606,30 @@ def _apply_overrides_without_restore(applied: SessionOverrides) -> Generator[Non
     yield
 
 
-def _session_exception_handler(summary_limit: int, verbose_limit: int) -> Callable[[BaseException], int]:
-    """Build the exception handler used inside :func:`cli_session`."""
+def _session_exception_handler(
+    *,
+    summary_limit: int,
+    verbose_limit: int,
+    signal_specs: Sequence[SignalSpec] | None,
+) -> Callable[[BaseException], int]:
+    """Build the exception handler used inside :func:`cli_session`.
 
-    def _handler(exc: BaseException) -> int:
+    It runs the same resolver chain as :func:`handle_cli_exception`, so a Click
+    usage error exits with Click's own code and message under a session too;
+    the session's character budgets apply only to the exception nothing else
+    claims.
+    """
+    specs = _resolve_signal_specs(signal_specs)
+
+    def _render_with_session_limits(exc: BaseException) -> int:
         active = bool(config.traceback)
         limit = verbose_limit if active else summary_limit
         print_exception_message(trace_back=active, length_limit=limit)
         return get_system_exit_code(exc)
 
+    def _handler(exc: BaseException) -> int:
+        return _resolve_exit_code(exc, specs, _default_echo, fallback=_render_with_session_limits)
+
     return _handler
 
 

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/src/lib_cli_exit_tools/cli/styling.py

@@ -15,10 +15,10 @@ System Integration:
 
 from __future__ import annotations
 
+import sys
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, TypedDict
 
-import rich_click as click
 from rich_click import rich_click as rich_config
 
 if TYPE_CHECKING:
@@ -104,9 +104,10 @@ def _temporary_rich_click_configuration() -> Generator[None]:  # pyright: ignore
     """Apply plain-output safeguards and restore rich-click globals afterwards."""
 
     snapshot = _snapshot_rich_click_options()
-    stdout_stream = click.get_text_stream("stdout")
-    stderr_stream = click.get_text_stream("stderr")
-    if _needs_plain_output(stdout_stream) and _needs_plain_output(stderr_stream):
+    # sys.stdout/sys.stderr, not click's resolution of them: rich renders through
+    # its own Console on these streams, and click 8.5.0 deprecated get_text_stream
+    # (removed in 9.0) with no supported replacement.
+    if _needs_plain_output(sys.stdout) and _needs_plain_output(sys.stderr):
         _prefer_ascii_layout()
     try:
         yield

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/tests/test_application_runner.py

@@ -417,6 +417,90 @@ def test_session_config_manager_with_no_overrides_returns_null_context() -> None
         pass  # Should not raise
 
 
+class _ExitThree(click.ClickException):
+    """A Click exception that chooses its own exit code."""
+
+    exit_code = 3
+
+
+class _HangupError(Exception):
+    """A caller-defined signal exception for signal-spec tests."""
+
+
+@click.command("ok")
+def _ok_command() -> None:
+    """Succeed."""
+
+
+@click.command("chosen")
+def _chosen_command() -> None:
+    """Fail with a Click exception that sets exit_code 3."""
+    raise _ExitThree("chosen failure")
+
+
+@click.command("boom")
+def _boom_command() -> None:
+    """Fail with an ordinary exception."""
+    raise RuntimeError("boom")
+
+
+@click.command("hangup")
+def _hangup_command() -> None:
+    """Raise the caller-defined signal exception."""
+    raise _HangupError
+
+
+def _session_probe_cli() -> click.Group:
+    """Build a real Click group whose commands cover every exit-code path."""
+    return click.Group("probe", commands=[_ok_command, _chosen_command, _boom_command, _hangup_command])
+
+
+@pytest.mark.os_agnostic
+def test_a_usage_error_under_cli_session_exits_two_with_clicks_usage_message(reset_config: None, capsys: pytest.CaptureFixture[str]) -> None:
+    with runner.cli_session() as execute:
+        code = execute(_session_probe_cli(), argv=["--bad-flag"], install_signals=False)
+
+    err = capsys.readouterr().err
+    assert code == 2
+    assert "Usage:" in err
+    assert "No such option" in err
+
+
+@pytest.mark.os_agnostic
+@pytest.mark.parametrize(
+    "argv",
+    [["ok"], ["--bad-flag"], ["no-such-command"], ["ok", "--bad-flag"], ["chosen"], ["boom"]],
+    ids=["success", "bad-flag", "unknown-command", "bad-subcommand-flag", "click-chosen-code", "plain-exception"],
+)
+def test_cli_session_exits_with_the_code_run_cli_gives(reset_config: None, argv: list[str]) -> None:
+    expected = runner.run_cli(_session_probe_cli(), argv=argv, install_signals=False)
+
+    with runner.cli_session() as execute:
+        code = execute(_session_probe_cli(), argv=argv, install_signals=False)
+
+    assert code == expected
+
+
+@pytest.mark.os_agnostic
+def test_cli_session_honours_the_signal_specs_its_caller_passes(reset_config: None, capsys: pytest.CaptureFixture[str]) -> None:
+    specs = [SignalSpec(signum=0, exception=_HangupError, message="hung up", exit_code=129)]
+
+    with runner.cli_session() as execute:
+        code = execute(_session_probe_cli(), argv=["hangup"], signal_specs=specs, install_signals=False)
+
+    assert code == 129
+    assert "hung up" in capsys.readouterr().err
+
+
+@pytest.mark.os_agnostic
+def test_cli_session_still_truncates_an_unhandled_exception_at_its_summary_limit(reset_config: None, capsys: pytest.CaptureFixture[str]) -> None:
+    with runner.cli_session(summary_limit=5) as execute:
+        code = execute(_session_probe_cli(), argv=["boom"], install_signals=False)
+
+    assert code != 0
+    assert "[TRUNCATED at 5 characters]" in capsys.readouterr().err
+
+
 # =============================================================================
 # Run CLI
 # =============================================================================

{lib_cli_exit_tools-2.3.4 → lib_cli_exit_tools-2.4.0}/tests/test_cli.py

@@ -10,10 +10,10 @@ Each test verifies exactly one CLI behavior:
 
 from __future__ import annotations
 
+import sys
 from typing import TYPE_CHECKING, Any
 
 import pytest
-import rich_click as click
 from rich_click import rich_click as rich_config
 
 import lib_cli_exit_tools
@@ -260,10 +260,8 @@ def test_ascii_streams_disable_force_terminal(monkeypatch: pytest.MonkeyPatch) -
 
     original = _snapshot_rich_click_options()
 
-    def _get_dummy_stream(name: str) -> DummyStream:
-        return DummyStream()
-
-    monkeypatch.setattr(click, "get_text_stream", _get_dummy_stream)
+    monkeypatch.setattr(sys, "stdout", DummyStream())
+    monkeypatch.setattr(sys, "stderr", DummyStream())
 
     with _temporary_rich_click_configuration():
         assert rich_config.FORCE_TERMINAL is False
@@ -282,10 +280,8 @@ def test_ascii_streams_disable_color_system(monkeypatch: pytest.MonkeyPatch) ->
 
     original = _snapshot_rich_click_options()
 
-    def _get_dummy_stream(name: str) -> DummyStream:
-        return DummyStream()
-
-    monkeypatch.setattr(click, "get_text_stream", _get_dummy_stream)
+    monkeypatch.setattr(sys, "stdout", DummyStream())
+    monkeypatch.setattr(sys, "stderr", DummyStream())
 
     with _temporary_rich_click_configuration():
         assert rich_config.COLOR_SYSTEM is None
@@ -304,10 +300,8 @@ def test_utf8_tty_streams_preserve_color_system(monkeypatch: pytest.MonkeyPatch)
 
     original = _snapshot_rich_click_options()
 
-    def _get_fancy_stream(name: str) -> FancyStream:
-        return FancyStream()
-
-    monkeypatch.setattr(click, "get_text_stream", _get_fancy_stream)
+    monkeypatch.setattr(sys, "stdout", FancyStream())
+    monkeypatch.setattr(sys, "stderr", FancyStream())
 
     with _temporary_rich_click_configuration():
         assert original.get("COLOR_SYSTEM") == rich_config.COLOR_SYSTEM