lib-cli-exit-tools 1.4.0__tar.gz → 1.5.0__tar.gz

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.5.0] - 2025-09-26
+
+- Refracture
+
 ## [1.4.0] - 2025-09-26
 
 - Reafracture, TestSuite

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 1.4.0
+Version: 1.5.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
@@ -18,15 +18,15 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: rich-click>=1.9.1
 Provides-Extra: dev
-Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: build>=1.3; extra == 'dev'
 Requires-Dist: codecov>=2.1.13; extra == 'dev'
 Requires-Dist: pyright>=1.1; extra == 'dev'
-Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest>=8.2; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Requires-Dist: textual>=0.50; extra == 'dev'
-Requires-Dist: tomli>=2.0; extra == 'dev'
-Requires-Dist: twine>=5.1; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0; extra == 'dev'
+Requires-Dist: pytest>=8.4; extra == 'dev'
+Requires-Dist: ruff>=0.13; extra == 'dev'
+Requires-Dist: textual>=6.1.0; extra == 'dev'
+Requires-Dist: tomli>=2.2.1; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # lib_cli_exit_tools
@@ -65,6 +65,7 @@ Console script:
 lib_cli_exit_tools --help
 cli-exit-tools --help  # alias
 lib_cli_exit_tools info
+lib_cli_exit_tools fail  # intentionally trigger RuntimeError to test error paths
 ```
 
 ### Embed in your own CLI
@@ -189,6 +190,9 @@ Parameters:
 - `length_limit`: Maximum characters for summary output.
 - `stream`: Target text stream; defaults to `sys.stderr`.
 
+### `i_should_fail()`
+Deterministically raise `RuntimeError('i should fail')` to exercise error-handling paths. Useful for smoke-testing exit-code translation, CLI traceback toggles, and log formatting without inventing ad-hoc failing commands.
+
 ### `flush_streams() -> None`
 Best-effort flush of `sys.stdout` and `sys.stderr`, ensuring buffered output is written before exit.
 

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/README.md

@@ -34,6 +34,7 @@ Console script:
 lib_cli_exit_tools --help
 cli-exit-tools --help  # alias
 lib_cli_exit_tools info
+lib_cli_exit_tools fail  # intentionally trigger RuntimeError to test error paths
 ```
 
 ### Embed in your own CLI
@@ -158,6 +159,9 @@ Parameters:
 - `length_limit`: Maximum characters for summary output.
 - `stream`: Target text stream; defaults to `sys.stderr`.
 
+### `i_should_fail()`
+Deterministically raise `RuntimeError('i should fail')` to exercise error-handling paths. Useful for smoke-testing exit-code translation, CLI traceback toggles, and log formatting without inventing ad-hoc failing commands.
+
 ### `flush_streams() -> None`
 Best-effort flush of `sys.stdout` and `sys.stderr`, ensuring buffered output is written before exit.
 

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/docs/system-design/module_reference.md

@@ -59,7 +59,7 @@ Automations and downstream CLIs rely on `lib_cli_exit_tools` for deterministic e
 ### Module: lib_cli_exit_tools/lib_cli_exit_tools.py
 * **Purpose:** Provide a façade that re-exports configuration, signal helpers, and orchestration utilities so existing imports stay valid after the refactor.
 * **Location:** `src/lib_cli_exit_tools/lib_cli_exit_tools.py`
-* **Notes:** Contains no implementation logic; it simply aggregates symbols from the layered modules to minimise breaking changes.
+* **Notes:** Aggregates symbols from the layered modules to minimise breaking changes and exposes `i_should_fail()` as a deterministic failure helper for exercising error-handling paths.
 
 ### Module: lib_cli_exit_tools/core/configuration.py
 * **Purpose:** Own the mutable runtime configuration shared across CLI executions.
@@ -131,6 +131,10 @@ Automations and downstream CLIs rely on `lib_cli_exit_tools` for deterministic e
 #### Function: `cli_info() -> None`
 * **Purpose:** Emit project metadata by delegating to `__init__conf__.print_info()`.
 
+#### Function: `cli_fail() -> None`
+* **Purpose:** Invoke `lib_cli_exit_tools.i_should_fail()` so operators can validate error-path handling from the packaged CLI without crafting bespoke failing commands.
+* **Notes:** Surfaces the stable `RuntimeError('i should fail')` message, making it safe for scripted assertions and support playbooks.
+
 #### Function: `main(argv=None) -> int`
 * **Purpose:** Compose the CLI invocation by delegating to `lib_cli_exit_tools.run_cli`, returning exit codes instead of exiting directly.
 

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/notebooks/Quickstart.ipynb

@@ -191,6 +191,78 @@
     "except Exception:\n",
     "    lib_cli_exit_tools.print_exception_message(trace_back=True)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d56cb190",
+   "metadata": {},
+   "source": [
+    "## 7) Registered Command Fail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b2eb015b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6c546140",
+   "metadata": {},
+   "source": [
+    "## 8) Registered Command Fail with Traceback"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "db445316",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools --traceback fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24c157fa",
+   "metadata": {},
+   "source": [
+    "## 9)  Script Command Fail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "81a4fa19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!{sys.executable} -m lib_cli_exit_tools fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab2685a2",
+   "metadata": {},
+   "source": [
+    "## 10) Script Command Fail with Traceback"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ea02859a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!{sys.executable} -m lib_cli_exit_tools --traceback fail"
+   ]
   }
  ],
  "metadata": {
@@ -206,4 +278,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

lib_cli_exit_tools-1.5.0/notebooks/Quickstart.ipynb.Backup

@@ -0,0 +1,281 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
+   "metadata": {},
+   "source": [
+    "# lib_cli_exit_tools Quickstart\n",
+    "\n",
+    "Use this notebook to install the package, explore the CLI, and observe how rich-formatted tracebacks behave when you enable debugging output.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "acae54e37e7d407bbb7b55eff062a284",
+   "metadata": {},
+   "source": [
+    "## 1) Install latest from GitHub (default)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# update pip and setuptools\n",
+    "import sys\n",
+    "\n",
+    "!{sys.executable} -m pip install --upgrade pip\n",
+    "!{sys.executable} -m pip install --upgrade setuptools\n",
+    "\n",
+    "# install lib_cli_exit_tools from GitHub (default)\n",
+    "!{sys.executable} -m pip install --upgrade git+https://github.com/bitranox/lib_cli_exit_tools.git"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
+   "metadata": {},
+   "source": [
+    "## Or: Install from PyPI (alternative)\n",
+    "Uncomment and run the cell below if you prefer the PyPI release.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "72eea5119410473aa328ad9291626812",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !{sys.executable} -m pip install --upgrade lib_cli_exit_tools\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8edb47106e1a46a883d545849b8ab81b",
+   "metadata": {},
+   "source": [
+    "## 2) CLI: version and help\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools --version\n",
+    "!lib_cli_exit_tools --help\n",
+    "!lib_cli_exit_tools info"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
+   "metadata": {},
+   "source": [
+    "## 3) Demo command for failure handling\n",
+    "The helper below builds a tiny Click command that purposely raises an error so you can compare short messages with rich tracebacks.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7623eae2785240b9bd12b16a66d81610",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import click\n",
+    "from lib_cli_exit_tools.lib_cli_exit_tools import config, run_cli\n",
+    "\n",
+    "\n",
+    "@click.command()\n",
+    "def quickstart_fail() -> None:\n",
+    "    \"\"\"Raise a demo error to exercise lib_cli_exit_tools.\"\"\"\n",
+    "    raise RuntimeError(\"demo failure from Quickstart\")\n",
+    "\n",
+    "\n",
+    "def run_quickstart_demo(traceback_enabled: bool) -> int:\n",
+    "    \"\"\"Execute the demo command with the desired traceback mode.\n",
+    "\n",
+    "    The helper keeps tests deterministic by disabling signal handlers\n",
+    "    in notebook contexts and resets global flags after execution.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    original_flag = config.traceback\n",
+    "    config.traceback = traceback_enabled\n",
+    "    try:\n",
+    "        return run_cli(quickstart_fail, argv=[], install_signals=False)\n",
+    "    finally:\n",
+    "        config.traceback = original_flag"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7cdc8c89c7104fffa095e18ddfef8986",
+   "metadata": {},
+   "source": [
+    "## 4) CLI failure with short message (default)\n",
+    "Tracebacks are suppressed by default; the CLI emits a concise summary and returns a deterministic exit code.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b118ea5561624da68c537baed56e602f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exit_code = run_quickstart_demo(False)\n",
+    "print(f\"Exit code: {exit_code}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "938c804e27f84196a10c8828c723f798",
+   "metadata": {},
+   "source": [
+    "## 5) CLI failure with rich traceback\n",
+    "Enable tracebacks to surface a full Rich-formatted stack trace for debugging.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "504fb2a444614c0babb325280ed9130a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import lib_cli_exit_tools\n",
+    "\n",
+    "try:\n",
+    "    run_quickstart_demo(True)\n",
+    "except RuntimeError:\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "59bbdb311c014d738909a11f9e486628",
+   "metadata": {},
+   "source": [
+    "## 6) Library usage: exit codes and traceback formatting\n",
+    "Use the functional API to translate exceptions into exit codes and to opt in to rich tracebacks programmatically.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b43b363d81ae4b689946ece5c682cd59",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import lib_cli_exit_tools\n",
+    "\n",
+    "# Short message (default)\n",
+    "try:\n",
+    "    raise FileNotFoundError(\"missing.txt\")\n",
+    "except Exception as exc:\n",
+    "    exit_code = lib_cli_exit_tools.get_system_exit_code(exc)\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=False)\n",
+    "    print(f\"Exit code would be: {exit_code}\")\n",
+    "\n",
+    "# Rich traceback\n",
+    "try:\n",
+    "    raise ValueError(\"boom\")\n",
+    "except Exception:\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d56cb190",
+   "metadata": {},
+   "source": [
+    "## 7) Registered Command Fail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b2eb015b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6c546140",
+   "metadata": {},
+   "source": [
+    "## 8) Registered Command Fail with Traceback"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "db445316",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools --traceback fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24c157fa",
+   "metadata": {},
+   "source": [
+    "## 9)  Script Command Fail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "81a4fa19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!{sys.executable} -m lib_cli_exit_tools fail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab2685a2",
+   "metadata": {},
+   "source": [
+    "## 10) Script Command Fail with Traceback"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ea02859a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!{sys.executable} -m lib_cli_exit_tools --traceback fail"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/packaging/brew/Formula/lib-cli-exit-tools.rb

@@ -3,7 +3,7 @@ class LibCliExitTools < Formula
 
   desc "CLI exit handling helpers: clean signals, exit codes, and error printing"
   homepage "https://github.com/bitranox/lib_cli_exit_tools"
-  url "https://github.com/bitranox/lib_cli_exit_tools/archive/refs/tags/v1.4.0.tar.gz"
+  url "https://github.com/bitranox/lib_cli_exit_tools/archive/refs/tags/v1.5.0.tar.gz"
 k3cc316e7d0b09dd79e617cb3e91b14ee414b7e6695b108a326d9d3ccd08dd9"
   license "MIT"
 

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/packaging/conda/recipe/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "lib_cli_exit_tools" %}
-{% set version = "1.4.0" %}
+{% set version = "1.5.0" %}
 
 package:
   name: {{ name|lower }}

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/packaging/nix/flake.nix

@@ -44,7 +44,7 @@
       {
         packages.default = pypkgs.buildPythonPackage {
           pname = "lib_cli_exit_tools";
-          version = "1.4.0";
+          version = "1.5.0";
           pyproject = true;
           src = ../..;
           nativeBuildInputs = [ hatchlingVendor ];

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "1.4.0"
+version = "1.5.0"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,15 +24,15 @@ Issues = "https://github.com/bitranox/lib_cli_exit_tools/issues"
 
 [project.optional-dependencies]
 dev = [
-  "pytest>=8.2",
-  "pytest-cov>=5.0",
-  "ruff>=0.5",
+  "pytest>=8.4",
+  "pytest-cov>=7.0",
+  "ruff>=0.13",
   "pyright>=1.1",
-  "build>=1.2",
-  "twine>=5.1",
+  "build>=1.3",
+  "twine>=6.2",
   "codecov>=2.1.13",
-  "textual>=0.50",
-  "tomli>=2.0",
+  "textual>=6.1.0",
+  "tomli>=2.2.1",
 ]
 
 [project.scripts]

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/src/lib_cli_exit_tools/__init__.py

@@ -25,6 +25,7 @@ from .lib_cli_exit_tools import (
     handle_cli_exception,
     install_signal_handlers,
     print_exception_message,
+    i_should_fail,
     run_cli,
 )
 
@@ -42,5 +43,6 @@ __all__ = [
     "default_signal_specs",
     "install_signal_handlers",
     "handle_cli_exception",
+    "i_should_fail",
     "run_cli",
 ]

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/src/lib_cli_exit_tools/application/runner.py

@@ -240,8 +240,8 @@ def handle_cli_exception(
     Returns:
         Integer exit code suitable for :func:`sys.exit`.
     Side Effects:
-        May write to stderr, invoke :func:`print_exception_message`, or re-raise
-        the original exception when tracebacks are enabled.
+        May write to stderr, invoke :func:`print_exception_message`, and render
+        rich tracebacks when requested.
     """
 
     specs = list(default_signal_specs() if signal_specs is None else signal_specs)
@@ -265,7 +265,8 @@ def handle_cli_exception(
         return 1
 
     if config.traceback:
-        raise exc
+        print_exception_message(trace_back=True)
+        return get_system_exit_code(exc)
 
     print_exception_message()
     return get_system_exit_code(exc)

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/src/lib_cli_exit_tools/cli.py

@@ -6,6 +6,7 @@ Purpose:
 Contents:
     * :func:`cli` group exposing shared options.
     * :func:`cli_info` subcommand reporting distribution metadata.
+    * :func:`cli_fail` subcommand triggering a deterministic failure for testing error paths.
     * :func:`main` entry point used by console scripts and ``python -m``.
 System Integration:
     The CLI mutates :data:`lib_cli_exit_tools.config` based on the ``--traceback``
@@ -125,6 +126,30 @@ def cli_info() -> None:
     __init__conf__.print_info()
 
 
+@cli.command("fail", context_settings=CLICK_CONTEXT_SETTINGS)
+def cli_fail() -> None:
+    """Intentionally raise a failure to validate error handling.
+
+    Why:
+        Exercise the error-reporting path so engineers can confirm exit-code
+        translation and optional traceback behaviour without crafting custom
+        failing commands.
+    Side Effects:
+        Delegates to :func:`lib_cli_exit_tools.i_should_fail`, which raises
+        ``RuntimeError`` for the caller to handle.
+    Examples:
+        >>> from click.testing import CliRunner
+        >>> runner = CliRunner()
+        >>> result = runner.invoke(cli, ["fail"])
+        >>> result.exit_code != 0
+        True
+        >>> "i should fail" in result.output or "i should fail" in result.stderr
+        True
+    """
+
+    lib_cli_exit_tools.i_should_fail()
+
+
 def main(argv: Optional[Sequence[str]] = None) -> int:
     """Run the CLI with :func:`lib_cli_exit_tools.run_cli` wiring.
 

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/src/lib_cli_exit_tools/lib_cli_exit_tools.py

@@ -9,6 +9,7 @@ Contents:
     * ``get_system_exit_code`` from :mod:`lib_cli_exit_tools.core.exit_codes`.
     * ``handle_cli_exception`` and ``run_cli`` from
       :mod:`lib_cli_exit_tools.application.runner`.
+    * :func:`i_should_fail` defined here for intentionally exercising error paths.
     * Signal helpers from :mod:`lib_cli_exit_tools.adapters.signals`.
 System Integration:
     The CLI adapter (:mod:`lib_cli_exit_tools.cli`) and external consumers
@@ -49,5 +50,26 @@ __all__ = [
     "default_signal_specs",
     "install_signal_handlers",
     "handle_cli_exception",
+    "i_should_fail",
     "run_cli",
 ]
+
+
+def i_should_fail() -> None:
+    """Raise :class:`RuntimeError` to exercise error-handling flows.
+
+    Why:
+        Provide a deterministic failure path so engineers can verify traceback
+        toggles, exit-code translation, and structured error reporting during
+        manual or automated testing.
+    Raises:
+        RuntimeError: Always raised with a stable message for assertion-friendly
+            diagnostics.
+    Examples:
+        >>> i_should_fail()
+        Traceback (most recent call last):
+        ...
+        RuntimeError: i should fail
+    """
+
+    raise RuntimeError("i should fail")

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/tests/application/test_runner.py

@@ -78,11 +78,25 @@ def test_handle_cli_exception_generic_delegates(monkeypatch: pytest.MonkeyPatch)
     assert calls == {"printed": True, "exc": err}
 
 
-def test_handle_cli_exception_respects_traceback(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Traceback mode re-raises instead of swallowing the exception."""
+def test_handle_cli_exception_prints_rich_traceback(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Traceback mode renders rich tracebacks and returns exit codes."""
+    calls: dict[str, object] = {}
+
+    def _fake_print(*_args, **kwargs) -> None:
+        calls["called"] = True
+        calls["trace_back"] = kwargs.get("trace_back")
+
+    def _fake_exit(exc: BaseException) -> int:
+        calls["exc"] = exc
+        return 17
+
+    monkeypatch.setattr("lib_cli_exit_tools.application.runner.print_exception_message", _fake_print)
+    monkeypatch.setattr("lib_cli_exit_tools.application.runner.get_system_exit_code", _fake_exit)
+
     config.traceback = True
-    with pytest.raises(RuntimeError):
-        handle_cli_exception(RuntimeError("boom"))
+    err = RuntimeError("boom")
+    assert handle_cli_exception(err) == 17
+    assert calls == {"called": True, "trace_back": True, "exc": err}
 
 
 def test_print_exception_message_outputs_summary() -> None:

{lib_cli_exit_tools-1.4.0 → lib_cli_exit_tools-1.5.0}/tests/cli/test_cli_entrypoints.py

@@ -19,10 +19,16 @@ from _pytest.capture import CaptureFixture
 
 import pytest
 
-from lib_cli_exit_tools import run_cli
+from lib_cli_exit_tools import run_cli, i_should_fail
 from lib_cli_exit_tools.cli import cli as root_cli, main
 
 
+def test_i_should_fail_helper_raises_runtime_error() -> None:
+    """The public helper always raises RuntimeError with a stable message."""
+    with pytest.raises(RuntimeError, match="^i should fail$"):
+        i_should_fail()
+
+
 def test_cli_info_command_outputs_metadata(capsys: CaptureFixture[str]) -> None:
     """The info subcommand surfaces package metadata without stderr output."""
     exit_code = main(["info"])
@@ -32,6 +38,15 @@ def test_cli_info_command_outputs_metadata(capsys: CaptureFixture[str]) -> None:
     assert err == ""
 
 
+def test_cli_fail_command_emits_runtime_error(capsys: CaptureFixture[str]) -> None:
+    """The fail subcommand intentionally raises RuntimeError for error-path tests."""
+    exit_code = main(["fail"])
+    out, err = capsys.readouterr()
+    assert exit_code == 1
+    assert out == ""
+    assert "RuntimeError: i should fail" in err
+
+
 def test_cli_unknown_option_returns_usage_error(capsys: CaptureFixture[str]) -> None:
     """Unknown options trigger Click usage errors with exit code 2."""
     exit_code = main(["--does-not-exist"])