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

{lib_cli_exit_tools-1.3.1 → lib_cli_exit_tools-1.4.0}/AGENTS.md

@@ -13,6 +13,8 @@ Review the system prompt files in `/media/srv-main/softdev/*/projects/softwarest
 - python_structure_template.md
 - self_documenting.md
 - self_documenting_template.md
+- python_jupyter_notebooks.md
+- python_testing.md
 
 always apply those Rules :
 
@@ -41,18 +43,6 @@ when writing or refracturing Python scripts, apply those Rules :
 - `packaging/`: Conda, Homebrew, and Nix specs kept in sync via scripts.
 - `tests/`: placeholder suite skipping until logging features exist.
 
-
-## Build, Test, and Development Commands
-
-- `make help` — list all targets with one‑line docs.
-- `make test` — run ruff (lint + format check), pyright, pytest with coverage (enabled by default), and upload to Codecov (if configured via `.env`).
-  - Auto‑bootstrap: `make test` installs dev tools (`pip install -e .[dev]`) if linters/test deps are missing. Use `SKIP_BOOTSTRAP=1 make test` to disable.
-  - Coverage control: `COVERAGE=on|auto|off` (default `on` locally). Uses a unique `COVERAGE_FILE` each run to avoid DB locks.
-  - Before uploading to Codecov the harness creates an allow-empty commit (`test: auto commit before Codecov upload`) so the report attaches to a revision. Reset or amend if you do not want to keep it.
-- `make build` — build Python wheel/sdist and attempt Conda/Homebrew/Nix builds (auto‑installs missing tools when needed).
-- `make push` — runs the full `scripts/test.py` flow, prompts for/accepts a commit message (or `COMMIT_MESSAGE`), creates an allow-empty commit if needed, then pushes to the selected remote.
-- `make clean` — remove caches, coverage, and build artifacts (includes `dist/` and `build/`).
-
 ### Versioning & Releases
 
 - Single source of truth for the package version is `pyproject.toml` (`[project].version`).
@@ -84,13 +74,6 @@ when writing or refracturing Python scripts, apply those Rules :
 
 ## Coding Style & Naming Conventions
 
-## Testing Guidelines
-
-- Unit and integration-style tests live under `tests/`; keep them up to date when adding features.
-- Extend coverage for new CLI or library behaviour (the suite exercises CLI commands, package metadata, and automation scripts).
-- When adding functionality, replace or remove placeholders and ensure `make test` remains green.
-- write good doctests which clearly show how the function works and what are the intensions. Use it as an enhancement of the inline documentation
-
 ## Commit & Pull Request Guidelines
 
 ## Architecture Overview
@@ -119,13 +102,10 @@ when writing or refracturing Python scripts, apply those Rules :
 - run "make test" before any push to avoid lint/test breakage.
 - after push, monitor errors in the github actions and try to correct the errors
 
-## Jupyter Notebooks
-use at least nbformat >=4.5 
- - "nbformat": 4,
- - "nbformat_minor": 5
-
 ---
 
+# ONLY ON USER REQEST !!!! :
+
 # 📘 Documentation Review & Enhancement Prompt
 
 You are a **senior software developer specializing in code documentation and system design clarity**. Your task is to review, correct, and enhance all documentation (external and inline) across the codebase with the following principles and workflow.

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

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.4.0] - 2025-09-26
+
+- Reafracture, TestSuite
+
 ## [1.3.1] - 2025-09-26
 
 - patch colored traceback
@@ -51,6 +55,8 @@
 - Metadata lookup in `__init__conf__` resolved once and reused.
 - Coverage gate relaxed to 80% and removed `# pragma: no cover` comments.
 - Quickstart notebook defaults to install from GitHub; added cell IDs; last cell prints exit code example instead of exiting.
+- Repartitioned the exit tooling into `core`, `adapters`, and `application` packages with `lib_cli_exit_tools` now acting as a facade to preserve import paths.
+- `run_cli` accepts injectable `exception_handler` and `signal_installer` hooks; CLI rich-click configuration now runs during `main()` execution instead of at import time.
 
 ### Fixed
 - Pyright 3.10 compatibility in `__init__conf__` by typing to a minimal metadata protocol; resolved unknown `.get` errors.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 1.3.1
+Version: 1.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
@@ -155,7 +155,7 @@ Mutable dataclass-like singleton holding process-wide settings. Configure it dur
 - `broken_pipe_exit_code` (`int`): Overrides the exit status for `BrokenPipeError` (default `141`).
 - `traceback_force_color` (`bool`): Forces Rich-coloured tracebacks even when stderr is not a TTY.
 
-### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True) -> int`
+### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True, exception_handler=None, signal_installer=None) -> int`
 Wrap a Click command or group so every invocation shares the same signal handling and exit-code policy. Returns the numeric exit code instead of exiting the process.
 
 Parameters:
@@ -164,6 +164,8 @@ Parameters:
 - `prog_name`: Override the program name shown in help/version output.
 - `signal_specs`: Iterable of `SignalSpec` objects to customise signal handling; defaults to `default_signal_specs()`.
 - `install_signals`: Set `False` when the host application already manages signal handlers.
+- `exception_handler`: Optional callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
+- `signal_installer`: Optional callable mirroring ``install_signal_handlers`` for embedding scenarios.
 
 ### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
 Translate exceptions raised by Click commands into deterministic exit codes, honouring configured signal mappings and traceback policy.
@@ -222,9 +224,9 @@ When `run_cli` executes your Click command it will:
 2. Optionally install handlers that raise the exceptions above.
 3. Execute the command with `standalone_mode=False`.
 4. Funnel any exception through `handle_cli_exception`.
-5. Restore prior signal handlers and flush streams before returning.
+5. Restore prior signal handlers and flush streams before returning (or rely on any injected replacements).
 
-This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools`.
+This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools` while still allowing custom hooks when needed.
 
 ### Advanced CLI wiring
 

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

@@ -124,7 +124,7 @@ Mutable dataclass-like singleton holding process-wide settings. Configure it dur
 - `broken_pipe_exit_code` (`int`): Overrides the exit status for `BrokenPipeError` (default `141`).
 - `traceback_force_color` (`bool`): Forces Rich-coloured tracebacks even when stderr is not a TTY.
 
-### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True) -> int`
+### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True, exception_handler=None, signal_installer=None) -> int`
 Wrap a Click command or group so every invocation shares the same signal handling and exit-code policy. Returns the numeric exit code instead of exiting the process.
 
 Parameters:
@@ -133,6 +133,8 @@ Parameters:
 - `prog_name`: Override the program name shown in help/version output.
 - `signal_specs`: Iterable of `SignalSpec` objects to customise signal handling; defaults to `default_signal_specs()`.
 - `install_signals`: Set `False` when the host application already manages signal handlers.
+- `exception_handler`: Optional callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
+- `signal_installer`: Optional callable mirroring ``install_signal_handlers`` for embedding scenarios.
 
 ### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
 Translate exceptions raised by Click commands into deterministic exit codes, honouring configured signal mappings and traceback policy.
@@ -191,9 +193,9 @@ When `run_cli` executes your Click command it will:
 2. Optionally install handlers that raise the exceptions above.
 3. Execute the command with `standalone_mode=False`.
 4. Funnel any exception through `handle_cli_exception`.
-5. Restore prior signal handlers and flush streams before returning.
+5. Restore prior signal handlers and flush streams before returning (or rely on any injected replacements).
 
-This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools`.
+This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools` while still allowing custom hooks when needed.
 
 ### Advanced CLI wiring
 

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

@@ -10,6 +10,10 @@ Complete
 **Related Files:**
 
 * `src/lib_cli_exit_tools/lib_cli_exit_tools.py`
+* `src/lib_cli_exit_tools/core/configuration.py`
+* `src/lib_cli_exit_tools/core/exit_codes.py`
+* `src/lib_cli_exit_tools/application/runner.py`
+* `src/lib_cli_exit_tools/adapters/signals.py`
 * `src/lib_cli_exit_tools/cli.py`
 * `src/lib_cli_exit_tools/__init__conf__.py`
 * `src/lib_cli_exit_tools/__init__.py`
@@ -42,8 +46,8 @@ Automations and downstream CLIs rely on `lib_cli_exit_tools` for deterministic e
 1. Console script (or `python -m lib_cli_exit_tools`) resolves to `lib_cli_exit_tools.cli.main`.  
 2. The Click group stores global flags and mutates `lib_cli_exit_tools.config`.  
 3. `run_cli` optionally installs signal handlers, executes the requested Click command, and funnels exceptions into `handle_cli_exception`.  
-4. `handle_cli_exception` maps signals and errors to exit codes using `default_signal_specs`, `_sysexits_mapping`, and `get_system_exit_code`.  
-5. `print_exception_message` and `_print_output` render diagnostics when tracebacks are suppressed.  
+4. `handle_cli_exception` maps signals and errors to exit codes using `default_signal_specs` and `get_system_exit_code`.  
+5. `print_exception_message` and `_print_output` (within `application.runner`) render diagnostics when tracebacks are suppressed.  
 6. Packaging metadata from `__init__conf__` feeds CLI help/version output so docs and runtime stay synchronized.
 
 **System Dependencies:** Standard library (`signal`, `subprocess`, `sys`, `importlib.metadata`) plus `click` and `rich-click` for CLI/TUI behavior.
@@ -53,80 +57,63 @@ Automations and downstream CLIs rely on `lib_cli_exit_tools` for deterministic e
 ## Core Components
 
 ### Module: lib_cli_exit_tools/lib_cli_exit_tools.py
-* **Purpose:** Centralize configuration, signal registration, and exception-to-exit-code translation so all CLIs share identical behavior.  
+* **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.
+
+### Module: lib_cli_exit_tools/core/configuration.py
+* **Purpose:** Own the mutable runtime configuration shared across CLI executions.
+* **Location:** `src/lib_cli_exit_tools/core/configuration.py`
 
 #### Dataclass: `_Config`
-* **Purpose:** Mutable singleton holding traceback, exit-code style, and broken-pipe overrides.  
-* **Fields:**
-  * `traceback` (bool) — emit full tracebacks when `True`.
-  * `exit_code_style` (`"errno" | "sysexits"`) — choose mapping strategy.
-  * `broken_pipe_exit_code` (int) — exit status for `BrokenPipeError`.  
-  * `traceback_force_color` (bool) — opt-in flag to force ANSI-coloured Rich tracebacks on non-TTY streams.  
-* **Notes:** Mutations apply process-wide; callers should restore defaults in tests.
+* **Role:** Captures traceback, exit-code style, broken-pipe handling, and Rich colouring toggles.
+* **Notes:** Mutations apply process-wide; tests must restore defaults to avoid leakage.
 
 #### Constant: `config`
-* **Purpose:** Shared `_Config` instance consulted by all helpers.  
-* **Interactions:** Mutated by CLI options and tests; read by `handle_cli_exception`, `get_system_exit_code`, and `print_exception_message`.
-
-#### Exception Hierarchy: `CliSignalError`, `SigIntInterrupt`, `SigTermInterrupt`, `SigBreakInterrupt`
-* **Purpose:** Represent signal-triggered interruptions so exit handlers can differentiate them from generic errors.  
-* **Notes:** Raised by generated signal handlers; mapped to exit codes 130 (SIGINT), 143 (SIGTERM), 149 (SIGBREAK).
+* **Role:** Singleton instance consumed by adapters and orchestration code.
+* **Interactions:** Mutated by the CLI (`--traceback`) and inspected by error handlers and exit-code mappers.
 
-#### Dataclass: `SignalSpec`
-* **Purpose:** Describe how to translate a signal into an exception, stderr message, and exit code.  
-* **Key Fields:** `signum`, `exception`, `message`, `exit_code`.  
-* **Usage:** Consumed by `install_signal_handlers`, `handle_cli_exception`.
+### Module: lib_cli_exit_tools/core/exit_codes.py
+* **Purpose:** Convert exceptions into deterministic OS exit statuses.
+* **Location:** `src/lib_cli_exit_tools/core/exit_codes.py`
 
-#### Protocol: `_Echo`
-* **Purpose:** Structural type for echo-like callables (defaulting to `click.echo`).  
-* **Usage:** Enables dependency injection/testing of output behavior.
+#### Function: `get_system_exit_code(exc: BaseException) -> int`
+* **Role:** Mirrors platform-specific errno/winerror semantics or BSD sysexits based on `config.exit_code_style`.
+* **Notes:** Handles `CalledProcessError`, `SystemExit`, and `BrokenPipeError` explicitly before falling back to errno tables.
 
-#### Function: `_default_echo(message: str, *, err: bool = True) -> None`
-* **Purpose:** Bridge to `click.echo` when no custom echo is provided.  
-* **Side Effects:** Writes text to stdout/stderr via Click.
+### Module: lib_cli_exit_tools/adapters/signals.py
+* **Purpose:** Translate operating-system signals into structured exceptions and reversible handlers.
+* **Location:** `src/lib_cli_exit_tools/adapters/signals.py`
 
-#### Function: `default_signal_specs() -> list[SignalSpec]`
-* **Purpose:** Produce platform-aware default signal specs.  
-* **Behavior:** Always includes SIGINT; adds SIGTERM/SIGBREAK when available.
+#### Exceptions: `CliSignalError`, `SigIntInterrupt`, `SigTermInterrupt`, `SigBreakInterrupt`
+* **Role:** Represent distinct signal pathways so exit handling can map them to stable codes (130/143/149).
 
-#### Function: `_make_raise_handler(exc_type) -> Callable`
-* **Purpose:** Wrap an exception type into a signal-compatible `(signum, frame)` handler that raises the type immediately.  
-* **Usage:** Internal helper for `install_signal_handlers`.
-
-#### Function: `install_signal_handlers(specs | None) -> Callable[[], None]`
-* **Purpose:** Register handlers for provided signal specs and return a restoration callback.  
-* **Considerations:** Handlers are process-wide; callers must invoke the returned function to restore prior state.
-
-#### Function: `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
-* **Purpose:** Convert exceptions into deterministic exit codes, honoring configured signal mappings and traceback settings.  
-* **Behavior:** Detects signal exceptions, `BrokenPipeError`, `click.ClickException`, and `SystemExit`; otherwise defers to `print_exception_message` and `get_system_exit_code`.
-
-#### Function: `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True) -> int`
-* **Purpose:** Execute a Click command under shared signal/error handling, flushing streams before returning.  
-* **Behavior:** Optionally installs handlers, invokes `cli.main(...)`, funnels exceptions to `handle_cli_exception`, and restores handlers.
+#### Dataclass: `SignalSpec`
+* **Role:** Describe signal metadata (signum, exception, message, exit code) used by installers and handlers.
 
-#### Function: `get_system_exit_code(exc) -> int`
-* **Purpose:** Map exceptions to platform-appropriate exit codes using errno, Windows `winerror`, or sysexits semantics.  
-* **Behavior:** Supports subprocess return codes, `SystemExit`, `KeyboardInterrupt`, `BrokenPipeError`, and default fallbacks.
+#### Function: `default_signal_specs(extra: Iterable[SignalSpec] | None = None) -> list[SignalSpec]`
+* **Role:** Provide platform-aware defaults (always SIGINT; conditional SIGTERM/SIGBREAK) with optional extension points.
 
-#### Function: `_sysexits_mapping(exc) -> int`
-* **Purpose:** Provide BSD `sysexits` codes when `config.exit_code_style == "sysexits"`.
+#### Function: `install_signal_handlers(specs: Sequence[SignalSpec] | None = None) -> Callable[[], None]`
+* **Role:** Register handlers that raise the specified exceptions and return a restoration callback for clean-up.
 
-#### Function: `_build_console(stream=None) -> rich.console.Console`
-* **Purpose:** Construct a Rich console aligned with current rich-click styling for consistent error/help rendering.  
-* **Usage:** Employed by `print_exception_message`.
+### Module: lib_cli_exit_tools/application/runner.py
+* **Purpose:** Orchestrate Click command execution with shared signal wiring, exception translation, and Rich-based diagnostics.
+* **Location:** `src/lib_cli_exit_tools/application/runner.py`
 
-#### Function: `print_exception_message(trace_back=config.traceback, length_limit=500, stream=None) -> None`
-* **Purpose:** Emit the active exception message (and optional Rich traceback) with truncation safeguards.  
-* **Behavior:** Flushes streams, surfaces captured subprocess output, renders highlighted tracebacks when enabled.
+#### Protocol: `_Echo`
+* **Role:** Structural type enabling dependency injection for stderr writers in tests.
 
-#### Function: `_print_output(exc_info, attr, stream=None) -> None`
-* **Purpose:** Print `stdout`/`stderr` captured on exceptions such as `subprocess.CalledProcessError`.
+#### Utilities: `flush_streams`, `_build_console`, `_print_output`, `print_exception_message`
+* **Role:** Manage stream flushing and Rich rendering when tracebacks are suppressed or forced.
 
-#### Function: `flush_streams() -> None`
-* **Purpose:** Best-effort flush of `sys.stdout` / `sys.stderr` to avoid buffered output loss during termination.
+#### Function: `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
+* **Role:** Map exceptions to exit codes, emit signal messages, honour `config.traceback`, and delegate to `get_system_exit_code` when needed.
+* **Notes:** Raises the original exception when traceback mode is enabled; otherwise trims output and prints captured subprocess streams.
 
+#### Function: `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True, exception_handler=None, signal_installer=None) -> int`
+* **Role:** Install signal handlers (unless disabled), execute the passed Click command, and funnel exceptions through an injectable handler before flushing streams.
+* **Notes:** New `exception_handler` and `signal_installer` hooks support advanced embedding and unit testing scenarios.
 ### Module: lib_cli_exit_tools/cli.py
 * **Purpose:** Provide the Click command group and subcommands that surface the exit tooling.  
 * **Location:** `src/lib_cli_exit_tools/cli.py`
@@ -187,6 +174,10 @@ Automations and downstream CLIs rely on `lib_cli_exit_tools` for deterministic e
 * `install_signal_handlers` returns a restoration callback; callers must execute it (preferably in `finally`) to restore original handlers.  
 * SIGTERM and SIGBREAK specs are conditionally added based on platform capabilities.
 
+**Extensibility:**
+
+* `run_cli` exposes `exception_handler` and `signal_installer` hooks so embedders and unit tests can replace the default wiring without patching globals.
+
 ---
 
 ## Testing Approach

{lib_cli_exit_tools-1.3.1 → lib_cli_exit_tools-1.4.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.3.1.tar.gz"
+  url "https://github.com/bitranox/lib_cli_exit_tools/archive/refs/tags/v1.4.0.tar.gz"
 k3cc316e7d0b09dd79e617cb3e91b14ee414b7e6695b108a326d9d3ccd08dd9"
   license "MIT"
 

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

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

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "1.3.1"
+version = "1.4.0"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"

lib_cli_exit_tools-1.4.0/src/lib_cli_exit_tools/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Adapter layer for lib_cli_exit_tools.
+
+Purpose:
+    Provide integration points with concrete frameworks (Click, Rich, signal
+    handlers) while delegating policy decisions to the core module.
+Contents:
+    Modules added here will contain Click helpers, signal installers, and other
+    I/O-centric code paths.
+System Integration:
+    Imported by the application layer to wire concrete behaviour without
+    violating dependency rules.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

lib_cli_exit_tools-1.4.0/src/lib_cli_exit_tools/adapters/signals.py

@@ -0,0 +1,177 @@
+"""Signal handling adapters for lib_cli_exit_tools.
+
+Purpose:
+    Translate operating-system signals into structured Python exceptions and
+    provide installation helpers that keep process-wide handlers reversible.
+Contents:
+    * :class:`CliSignalError` hierarchy capturing supported interrupts.
+    * :class:`SignalSpec` dataclass describing signal→exception mappings.
+    * :func:`default_signal_specs` building platform-aware defaults.
+    * :func:`install_signal_handlers` installing reversible handlers.
+System Integration:
+    The application runner leverages these helpers to provide consistent exit
+    codes across console entry points while allowing tests to inject fakes.
+"""
+
+from __future__ import annotations
+
+import signal
+from dataclasses import dataclass
+from types import FrameType
+from typing import Callable, Iterable, List, Sequence
+
+__all__ = [
+    "CliSignalError",
+    "SigIntInterrupt",
+    "SigTermInterrupt",
+    "SigBreakInterrupt",
+    "SignalSpec",
+    "default_signal_specs",
+    "install_signal_handlers",
+]
+
+
+class CliSignalError(RuntimeError):
+    """Base class for translating OS signals into structured CLI errors.
+
+    Why:
+        Provide a dedicated hierarchy so exit handlers can recognise signal-driven
+        interruptions and map them to deterministic exit codes.
+    Usage:
+        Raised automatically by handlers created via :func:`install_signal_handlers`.
+    """
+
+
+class SigIntInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGINT`` (Ctrl+C)."""
+
+
+class SigTermInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGTERM`` (termination request)."""
+
+
+class SigBreakInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGBREAK`` on Windows consoles."""
+
+
+@dataclass(slots=True)
+class SignalSpec:
+    """Describe how to translate a low-level signal into CLI-facing behaviour.
+
+    Fields:
+        signum: Numeric identifier registered with :mod:`signal`.
+        exception: Exception type raised by the generated handler.
+        message: User-facing text echoed to stderr when the signal fires.
+        exit_code: Numeric code returned to the operating system.
+    """
+
+    signum: int
+    exception: type[BaseException]
+    message: str
+    exit_code: int
+
+
+_Handler = Callable[[int, FrameType | None], None]
+
+
+def default_signal_specs(extra: Iterable[SignalSpec] | None = None) -> List[SignalSpec]:
+    """Build the default list of signal specifications for the host platform.
+
+    Why:
+        Ensure every CLI managed by this project responds consistently to Ctrl+C
+        and termination signals without duplicating configuration.
+    Parameters:
+        extra: Optional iterable of additional :class:`SignalSpec` records that
+            extend the standard platform-aware set.
+    Returns:
+        Fresh list of :class:`SignalSpec` entries ready for
+        :func:`install_signal_handlers` or :func:`handle_cli_exception`.
+    """
+
+    specs: List[SignalSpec] = [
+        SignalSpec(
+            signum=signal.SIGINT,
+            exception=SigIntInterrupt,
+            message="Aborted (SIGINT).",
+            exit_code=130,
+        )
+    ]
+
+    if hasattr(signal, "SIGTERM"):
+        specs.append(
+            SignalSpec(
+                signum=getattr(signal, "SIGTERM"),
+                exception=SigTermInterrupt,
+                message="Terminated (SIGTERM/SIGBREAK).",
+                exit_code=143,
+            )
+        )
+    if hasattr(signal, "SIGBREAK"):
+        specs.append(
+            SignalSpec(
+                signum=getattr(signal, "SIGBREAK"),
+                exception=SigBreakInterrupt,
+                message="Terminated (SIGBREAK).",
+                exit_code=149,
+            )
+        )
+
+    if extra is not None:
+        specs.extend(extra)
+
+    return specs
+
+
+def _make_raise_handler(exc_type: type[BaseException]) -> _Handler:
+    """Wrap ``exc_type`` in a signal-compatible callable.
+
+    Why:
+        ``signal.signal`` expects handlers with a ``(signum, frame)`` signature.
+        The returned closure ignores those arguments and raises ``exc_type``
+        immediately so higher layers see a structured exception.
+    Parameters:
+        exc_type: Exception subclass to raise when the signal fires.
+    Returns:
+        Callable compatible with ``signal.signal`` registration.
+    """
+
+    def _handler(signo: int, frame: FrameType | None) -> None:  # pragma: no cover - just raises
+        raise exc_type()
+
+    return _handler
+
+
+def install_signal_handlers(specs: Sequence[SignalSpec] | None = None) -> Callable[[], None]:
+    """Install signal handlers that re-raise as structured exceptions.
+
+    Why:
+        Centralise signal wiring so CLI entry points can opt in with a single
+        call and reliably restore previous handlers afterwards.
+    Parameters:
+        specs: Iterable of :class:`SignalSpec` entries. When omitted the
+            platform-aware defaults from :func:`default_signal_specs` are used.
+    Returns:
+        Callable that restores the prior handlers. Invoke it in ``finally`` to
+        avoid leaking process-wide state into callers or tests.
+    """
+
+    active_specs = list(default_signal_specs() if specs is None else specs)
+    previous: List[tuple[int, object]] = []
+
+    for spec in active_specs:
+        handler = _make_raise_handler(spec.exception)
+        try:
+            current = signal.getsignal(spec.signum)
+            signal.signal(spec.signum, handler)
+            previous.append((spec.signum, current))
+        except (AttributeError, OSError, RuntimeError):  # pragma: no cover - platform differences
+            continue
+
+    def restore() -> None:
+        for signum, prior in previous:
+            try:
+                signal.signal(signum, prior)  # type: ignore[arg-type]
+            except Exception:  # pragma: no cover - restore best-effort
+                pass
+
+    return restore

lib_cli_exit_tools-1.4.0/src/lib_cli_exit_tools/application/__init__.py

@@ -0,0 +1,16 @@
+"""Application orchestration for lib_cli_exit_tools.
+
+Purpose:
+    Coordinate core exit-code logic with adapter implementations (Click,
+    signal handlers) while exposing a small surface for CLI entry points.
+Contents:
+    The `runner` module will host the refactored `run_cli` orchestration and any
+    supporting protocols.
+System Integration:
+    Imports only from `lib_cli_exit_tools.core` and adapter packages, keeping the
+    dependency direction consistent with Clean Architecture guidelines.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []