lib-cli-exit-tools 1.6.0__tar.gz → 2.1.0__tar.gz

lib_cli_exit_tools-2.1.0/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks (e.g., higher rate limits on dependency audits)
+GITHUB_TOKEN=

lib_cli_exit_tools-2.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    allow:
+      - dependency-type: "direct"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

lib_cli_exit_tools-2.1.0/.github/workflows/ci.yml

@@ -0,0 +1,162 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Test against Python 3.13 and the latest 3.x available on Actions runners
+        python: ["3.13", "3.x"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Install make on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install -y make
+          echo "C:\\ProgramData\\chocolatey\\bin" >> $env:GITHUB_PATH
+      - name: Upgrade pip
+        shell: bash
+        run: python -m pip install --upgrade pip
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          pip install -e .[dev]
+
+      - name: Install Windows Event Log prerequisites
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          pip install pywin32
+      - name: Run full test suite (lint, types, tests, coverage, codecov)
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+        run: make test
+      - name: Build wheel/sdist
+        shell: bash
+        run: python -m build
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          python -m venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: pipx install from wheel
+        run: |
+          python -m pip install pipx
+          pipx install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: uv tool install
+        run: |
+          uv tool install .
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install notebook runner deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          notebook = nbformat.read(nb_path, as_version=4)
+          client = NotebookClient(
+              notebook,
+              timeout=900,
+              kernel_name='python3',
+              allow_errors=False,
+          )
+          client.execute()
+
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          nbformat.write(notebook, out_path)
+          print(f"Executed notebook written to: {out_path}")
+          PY

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/.github/workflows/codeql.yml

@@ -23,18 +23,17 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4
         with:
           category: "/language:${{ matrix.language }}"
-

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Verify PyPI token is set
         run: |
           if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
@@ -22,7 +22,7 @@ jobs:
             echo "See: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions" 
             exit 1
           fi
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.13'
       - name: Build artifacts

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/AGENTS.md

@@ -45,14 +45,13 @@ when writing or refracturing Python scripts, apply those Rules :
 
 - `src/lib_cli_exit_tools/`: Python package.
 - `scripts/`: shared automation (build/test/release) reused from scaffold.
-- `packaging/`: Conda, Homebrew, and Nix specs kept in sync via scripts.
-- `tests/`: placeholder suite skipping until logging features exist.
+- `tests/`: behaviour/spec integration suite covering CLI, metadata, and automation workflows.
 
 ### Versioning & Releases
 
 - Single source of truth for the package version is `pyproject.toml` (`[project].version`).
-- Runtime code reads metadata via `importlib.metadata`; do not duplicate the version in code files.
-- On a version bump, update only `pyproject.toml` and the `CHANGELOG.md` entry; runtime code should continue to read the version via `importlib.metadata` (no separate `__init__conf__` file).
+- Automation rewrites `src/lib_cli_exit_tools/__init__conf__.py` from `pyproject.toml`, so runtime code imports generated constants instead of querying `importlib.metadata`.
+- After updating project metadata (version, summary, URLs, authors) run `make test` (or `python -m scripts.test`) to regenerate the metadata module before committing.
 - Tag releases `vX.Y.Z` and push tags; CI will build artifacts and publish when configured.
 
 ### Common Make Targets (Alphabetical)
@@ -60,7 +59,7 @@ when writing or refracturing Python scripts, apply those Rules :
 
 | Target            | One-line description                                                           |
 |-------------------|--------------------------------------------------------------------------------|
-| `build`           | Build wheel/sdist and attempt Conda/Brew/Nix builds (auto-installs tools).     |
+| `build`           | Build wheel/sdist; validates the Python artifacts locally.                      |
 | `bump`            | Bump version (VERSION=X.Y.Z or PART=major\|minor\|patch) and update changelog. |
 | `bump-major`      | Increment major version ((X+1).0.0).                                           |
 | `bump-minor`      | Increment minor version (X.Y.Z → X.(Y+1).0).                                   |
@@ -71,7 +70,7 @@ when writing or refracturing Python scripts, apply those Rules :
 | `install`         | Editable install.                                                              |
 | `menu`            | Interactive TUI menu (make menu).                                              |
 | `push`            | Commit changes once and push to GitHub (no CI monitoring).                     |
-| `release`         | Tag vX.Y.Z, push, sync packaging, run gh release if available.                 |
+| `release`         | Tag vX.Y.Z, push, and run the release helper (PyPI upload when configured).    |
 | `run`             | Run module entry (`python -m ... --help`).                                     |
 | `test`            | Lint, format, type-check, run tests with coverage, upload to Codecov.          |
 | `version-current` | Print current version from `pyproject.toml`.                                   |

lib_cli_exit_tools-2.1.0/AGENTS_README.md

@@ -0,0 +1,176 @@
+# AGENTS README — Using `lib_cli_exit_tools`
+
+This guide targets coding agents (Codex, Claude-CLI, etc.) that need to consume the
+`lib_cli_exit_tools` library while building or refactoring Python CLIs. It focuses
+on runtime usage rather than project maintenance.
+
+## 1. Install
+
+```bash
+pip install lib_cli_exit_tools
+```
+
+If you are operating inside a virtual environment, ensure the environment is
+active before installing so the console scripts (`lib_cli_exit_tools`,
+`cli-exit-tools`, `lib-cli-exit-tools`) land on PATH.
+
+## 2. Minimal Usage
+
+Wrap an existing Click command with the bundled orchestration so signals and
+exit codes work consistently:
+
+```python
+from __future__ import annotations
+
+import click
+from lib_cli_exit_tools import run_cli
+
+
+@click.command()
+def hello() -> None:
+    click.echo("Hello world")
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_cli(hello))
+```
+
+`run_cli` intercepts `SIGINT`, `SIGTERM`/`SIGBREAK`, and standard exceptions,
+translating them into predictable exit codes for shells and calling scripts.
+
+## 3. Temporary Overrides with `cli_session`
+
+Enable traceback output or other configuration for a single invocation:
+
+```python
+from collections.abc import Sequence
+from lib_cli_exit_tools import cli_session
+
+
+def run_command(argv: Sequence[str] | None = None, *, verbose: bool = False) -> int:
+    overrides = {"traceback": verbose}
+    with cli_session(overrides=overrides) as execute:
+        return execute(hello, argv=argv)
+```
+
+Outside the `with` block, global configuration reverts to its previous state,
+so you can safely toggle verbose diagnostics based on flags or environment.
+
+## 4. Global Configuration Surface
+
+The module-level `config` object exposes runtime switches. Mutate them once
+at process startup if you need persistent behaviour changes:
+
+```python
+from lib_cli_exit_tools import config
+
+config.traceback = True              # always render full tracebacks
+config.exit_code_style = "sysexits"  # use BSD sysexits mapping
+config.broken_pipe_exit_code = 0     # treat BrokenPipeError as success
+```
+
+For scoped overrides (tests, nested CLIs), prefer `config_overrides`:
+
+```python
+from lib_cli_exit_tools import config_overrides
+
+with config_overrides(traceback=True, traceback_force_color=True):
+    run_something()
+# state restored automatically
+```
+
+## 5. Direct Exit-Code Translation
+
+If you catch exceptions manually, reuse the resolver:
+
+```python
+from lib_cli_exit_tools import get_system_exit_code, print_exception_message
+
+try:
+    risky_operation()
+except Exception as exc:
+    print_exception_message()
+    raise SystemExit(get_system_exit_code(exc))
+```
+
+## 6. Custom Signal Handling
+
+You can supply your own `SignalSpec` list and installer when calling `run_cli`:
+
+```python
+import signal
+from contextlib import ExitStack
+
+from lib_cli_exit_tools import SignalSpec, default_signal_specs, run_cli
+
+CUSTOM_SIG = getattr(signal, "SIGUSR1", None)
+
+
+def custom_specs() -> list[SignalSpec]:
+    specs = default_signal_specs()
+    if CUSTOM_SIG is not None:
+        specs.append(
+            SignalSpec(
+                signum=CUSTOM_SIG,
+                exception=RuntimeError,
+                message="USR1 received",
+                exit_code=75,
+            )
+        )
+    return specs
+
+
+def install_specs(specs: list[SignalSpec] | None) -> callable[[], None]:
+    stack = ExitStack()
+    for spec in specs or []:
+        def _handler(signum: int, frame: object | None, *, spec: SignalSpec = spec) -> None:
+            raise spec.exception(spec.message)
+
+        try:
+            previous = signal.getsignal(spec.signum)
+            signal.signal(spec.signum, _handler)
+        except OSError:
+            continue
+        stack.callback(signal.signal, spec.signum, previous)
+    return stack.close
+
+
+exit_code = run_cli(
+    hello,
+    signal_specs=custom_specs(),
+    signal_installer=install_specs,
+)
+```
+
+The installer must return a zero-argument callable that restores prior handlers.
+`run_cli` invokes it automatically during teardown.
+
+## 7. Testing Your Integration
+
+When you wire the library into your project, add behaviour tests that mirror the
+bundled suite:
+
+```bash
+PYTHONPATH=src python -m pytest tests/test_my_cli.py
+```
+
+Focus on asserting exit codes and stderr text under failures or signals.
+
+## 8. Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Tracebacks not showing despite `--traceback` | Ensure you call `cli_session` or set `config.traceback = True` before running the command. |
+| SIGINT doesn’t produce exit code 130 | Verify the command is executed via `run_cli` and no other signal handlers override the one supplied by the library. |
+| Windows CTRL+BREAK ignored | Include `SignalSpec` for `SIGBREAK` or rely on `default_signal_specs()` which already accounts for it when available. |
+| “Unknown configuration fields” error | Check the keyword names passed into `config_overrides`; they must match the dataclass fields (`traceback`, `exit_code_style`, `broken_pipe_exit_code`, `traceback_force_color`). |
+
+## 9. Need a Quick Reference?
+
+- **run_cli**: Orchestrates Click commands with signal-aware exit handling.
+- **cli_session**: Context manager wrapping `run_cli` that applies temporary config overrides and returns a callable bound to the standard exception handler.
+- **config/reset_config**: Global defaults; call `reset_config()` in tests to avoid leakage.
+- **get_system_exit_code**: Standalone mapping from `BaseException` to numeric exit codes.
+- **SignalSpec + default_signal_specs**: Build or extend the signal handling roster for `run_cli`.
+
+Use these primitives to retrofit deterministic exit behaviour into any Click-based CLI your agent constructs.

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [2.1.0] - 2025-10-13
+
+### Changed
+- `scripts.build` now calls `sync_metadata_module()` before invoking `python -m build`, ensuring wheels and sdists ship freshly generated metadata.
+- Added an explicit CLI test covering the `--version` flag so console-script aliases stay aligned with generated constants.
+- Updated README, INSTALL instructions, and the Quickstart notebook to document `lib-cli-exit-tools` as the canonical console entry point alongside its aliases.
+
+## [2.0.0] - 2025-10-12
+
+### Changed
+- Modernised runtime and automation tooling to rely on native Python 3.13 APIs, including updated signal adapters and simplified exception rendering.
+- Raised development dependency floors (codecov-cli, import-linter, bandit, pip-audit, pyright, pytest, pytest-asyncio, ruff, textual) to the latest stable releases.
+- Refined documentation to reflect the current behaviour-focused test suite and active automation scripts.
+- Brought script modules and metadata fallbacks back into coverage reporting and removed ad-hoc sys.path manipulation from the automation launcher.
+- Adopted PEP 604 union typing throughout the CLI runner and facade helpers to underline the Python 3.13-only baseline and to keep function signatures declarative.
+- Updated packaging metadata to require `build>=1.3.0`, `pytest-cov>=7.0.0`, `twine>=6.2.0`, and `hatchling>=1.27.0`, matching the latest stable releases verified via `pip index`.
+- Restored real signal integration coverage and Hypothesis-backed exit-code property tests to guard regression-prone paths.
+
+### Removed
+- Retired Conda/Homebrew/Nix packaging automation and updated documentation to reflect the PyPI-only distribution path.
+- Dropped legacy ImportError-based script fallbacks now that automation entry points run as a proper package.
+
+### Documentation
+- Highlighted the Python 3.13 baseline, dependency refresh, and updated CI action set in the README.
+- Documented the revived signal integration suite and property-based tests in the system module reference.
+
+
 ## [1.6.0] - 2025-10-08
 
 ### Added

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/CONTRIBUTING.md

@@ -21,22 +21,11 @@ Thanks for helping improve lib_cli_exit_tools! This guide keeps changes small, s
 - Honour the documented system prompts: small functions, type hints throughout, and doctests that explain intent.
 - No sweeping refactors in unrelated modules; keep pull requests reviewable.
 
-## 4) Build & Packaging
-
-### Packaging Sync (Conda/Brew/Nix)
-
-- Sync is automatic on common workflows:
-  - `make test` and `make push` run a sync step that aligns packaging files under `packaging/` with `pyproject.toml`.
-  - `make bump` also updates packaging files when bumping the version.
-- What gets synced from `pyproject.toml`:
-  - Version and minimum Python (`requires-python`).
-  - Runtime dependencies (from `[project].dependencies`).
-    - Conda: rewrites `requirements: run` with `python >=X.Y` plus all deps (exact `==` pins kept; ranges copied as-is).
-    - Homebrew: ensures a `resource "<dep>"` for each dep; if pinned, uses that version; otherwise pins to the latest PyPI release, updating `url` + `sha256`.
-    - Nix: updates the package version, `pkgs.pythonXYZPackages`/`pkgs.pythonXYZ` to match the min Python, and `propagatedBuildInputs` to include all deps as `pypkgs.<name>`.
-- Network note: Homebrew resource updates fetch PyPI metadata; if offline, those updates may be skipped.
-- If packaging drifts, run: `python scripts/bump_version.py --sync-packaging`.
-- CI enforces consistency on tags via a `packaging-consistency` job.
+## 4) Build & Release
+
+- `make build` produces the wheel/sdist that CI later uploads to PyPI.
+- `make release` tags the repository and runs the release helper (publishes to PyPI when `PYPI_API_TOKEN` is configured).
+- Third-party packaging targets (Conda, Homebrew, Nix) are no longer maintained.
 
 ## 5) Tests & Style
 

{lib_cli_exit_tools-1.6.0 → lib_cli_exit_tools-2.1.0}/DEVELOPMENT.md

@@ -18,7 +18,7 @@ This guide aggregates everything maintainers need for building, testing, and rel
 | `bump-major`      | Bump major version ((X+1).0.0)                                                             |
 | `clean`           | Remove caches, build artifacts, and coverage                                               |
 | `push`            | Commit all changes once and push to GitHub (no CI monitoring)                              |
-| `build`           | Build wheel/sdist and attempt conda, brew, and nix builds (auto-installs tools if missing) |
+| `build`           | Build wheel/sdist artifacts for PyPI distribution                                         |
 | `menu`            | Interactive TUI to run targets and edit parameters (requires dev dep: textual)             |
 
 ### Target Parameters (env vars)
@@ -36,7 +36,7 @@ This guide aggregates everything maintainers need for building, testing, and rel
   - `TEST_VERBOSE=1` — echo each command executed by the test harness
   - Also respects `CODECOV_TOKEN` when needed for uploads
 - `run`
-  - No parameters via `make` (always shows `--help`). For custom args: `python scripts/run_cli.py -- <args>`.
+  - No parameters via `make` (always shows `--help`). For custom args: `python -m scripts.run_cli -- <args>`.
 - `version-current`
   - No parameters
 - `bump`
@@ -52,10 +52,10 @@ This guide aggregates everything maintainers need for building, testing, and rel
 - `push`
   - `REMOTE=<name>` (default: `origin`) — git remote to push to
 - `build`
-  - No parameters via `make`. Advanced: use the script directly, e.g. `python scripts/build.py --no-conda --no-nix`.
+  - No parameters via `make`. Advanced: call `python -m scripts.build` directly for custom flows.
 - `release`
   - `REMOTE=<name>` (default: `origin`) — git remote to push to
-  - Advanced (via script): `python scripts/release.py --retries 5 --retry-wait 3.0`
+  - Advanced (via script): `python -m scripts.release --retries 5 --retry-wait 3.0`
 
 ## Interactive Menu (Textual)
 
@@ -78,7 +78,7 @@ make menu
 
 - `test`: single entry point for local CI — runs ruff lint + format check, pyright, pytest (including doctests) with coverage (enabled by default), and uploads coverage to Codecov if configured (reads `.env`).
 - Auto‑bootstrap: `make test` will try to install dev tools (`pip install -e .[dev]`) if `ruff`/`pyright`/`pytest` are missing. Set `SKIP_BOOTSTRAP=1` to skip this behavior.
-- `build`: convenient builder — creates Python wheel/sdist, then attempts Conda, Homebrew, and Nix builds. It auto‑installs missing tools (Miniforge, Homebrew, Nix) when needed.
+- `build`: creates Python wheel/sdist artifacts that match what CI uploads to PyPI.
 - `install`/`dev`/`user-install`: common install flows for editable or per‑user installs.
 - `version-current`: prints current version from `pyproject.toml`.
 - `bump`: updates `pyproject.toml` version and inserts a new section in `CHANGELOG.md`. Use `VERSION=X.Y.Z make bump` or `make bump-minor`/`bump-major`/`bump-patch`.
@@ -92,8 +92,20 @@ make test                 # ruff + pyright + pytest + coverage (default ON)
 SKIP_BOOTSTRAP=1 make test  # skip auto-install of dev deps
 COVERAGE=off make test       # disable coverage locally
 COVERAGE=on make test        # force coverage and generate coverage.xml/codecov.xml
+make coverage               # python -m coverage run -m pytest -vv (no coverage CLI needed)
 ```
 
+The same helper can be run directly without Make:
+
+```bash
+python -m scripts coverage
+```
+
+The coverage helper sets `COVERAGE_NO_SQL=1` before launching pytest so the
+legacy file-backed coverage data store is used instead of SQLite. This sidesteps
+the "database is locked" failures that occur when multiple runs touch the same
+workspace.
+
 The pytest suite uses OS markers (`skipif` guards) to exercise POSIX-, Windows-,
 and platform-agnostic behaviours. Run `make test` on every platform you ship to
 keep the signal-handling guarantees honest.
@@ -104,38 +116,18 @@ keep the signal-handling guarantees honest.
 - For private repos, set `CODECOV_TOKEN` (see `.env.example`) or export it in your shell.
 - For public repos, a token is typically not required.
 
-## Packaging Sync (Conda/Brew/Nix)
-
-- `make test` and `make push` automatically align the packaging skeletons in `packaging/` with the current `pyproject.toml`:
-  - Conda: updates `{% set version = "X.Y.Z" %}` and both `python >=X.Y` constraints to match `requires-python`.
-  - Homebrew: updates the source URL tag to `vX.Y.Z` and sets `depends_on "python@X.Y"` to match `requires-python`.
-  - Nix: updates the package `version`, example `rev = "vX.Y.Z"`, and switches `pkgs.pythonXYZPackages` / `pkgs.pythonXYZ` to match the minimum Python version from `requires-python`.
-- Local `make test` runs skip the sync unless you export `ENFORCE_PACKAGING_SYNC=1` (CI enables it automatically).
-- To run just the sync without bumping versions: `python scripts/bump_version.py --sync-packaging`.
-- On release tags (`v*.*.*`), CI validates that packaging files are consistent with `pyproject.toml` and will fail if they drift.
-
 ## Versioning & Metadata
 
-- Single source of truth for package metadata is `pyproject.toml` (`[project]`).
-- The library reads its own installed metadata at runtime via `importlib.metadata` (see `src/lib_cli_exit_tools/__init__conf__.py`).
-- Do not duplicate the version in code; bump only `pyproject.toml` and update `CHANGELOG.md`.
-- Console script name is discovered from entry points; defaults to `lib_cli_exit_tools`.
-
-## Packaging Skeletons
-
-Starter files for package managers live under `packaging/`:
-
-- Conda: `packaging/conda/recipe/meta.yaml` (update version + sha256)
-- Homebrew: `packaging/brew/Formula/lib-cli-exit-tools.rb` (fill sha256 and vendored resources)
-- Nix: `packaging/nix/flake.nix` (use working tree or pin to GitHub rev with sha256)
-
-These are templates; fill placeholders (e.g., sha256) before publishing. Version and Python constraints are auto-synced from `pyproject.toml` by `make test`/`make push` and during version bumps.
+- `pyproject.toml` (`[project]`) remains the single source of truth for name, version, homepage, and authors.
+- `scripts._utils.sync_metadata_module()` rewrites `src/lib_cli_exit_tools/__init__conf__.py` so runtime code consumes generated constants instead of `importlib.metadata`.
+- After editing project metadata (name, version, description, URLs, authors), run `make test` or `python -m scripts.test` to regenerate the module before committing.
+- Console script name is still discovered from entry points; automation falls back to `lib_cli_exit_tools` when no explicit alias exists.
 
 ## CI & Publishing
 
 GitHub Actions workflows are included:
 
-- `.github/workflows/ci.yml` — lint/type/test, build wheel/sdist, verify pipx and uv installs, Nix and Conda builds (CI-only; no local install required).
+- `.github/workflows/ci.yml` — lint/type/test, build wheel/sdist, and verify pipx/uv installs.
 - `.github/workflows/release.yml` — on tags `v*.*.*`, builds artifacts and publishes to PyPI when `PYPI_API_TOKEN` secret is set.
 
 To publish a release:
@@ -144,4 +136,4 @@ To publish a release:
 3. Ensure `PYPI_API_TOKEN` secret is configured in the repo.
 4. Release workflow uploads wheel/sdist to PyPI.
 
-Conda/Homebrew/Nix: use files in `packaging/` to submit to their ecosystems. CI also attempts builds to validate recipes, but does not publish automatically.
+Third-party packaging targets (Conda, Homebrew, Nix) were removed; distribution now flows solely through PyPI.