lib-cli-exit-tools 2.2.3__tar.gz → 2.3.0__tar.gz

lib_cli_exit_tools-2.3.0/.claude/commands/tfbp.md

@@ -0,0 +1,84 @@
+Test, Fix, Bump, Push — full release pipeline.
+
+Execute the following steps sequentially. Do NOT skip steps. Stop and ask the user if any decision requires human judgement.
+
+---
+
+## Step 1 — Run Tests
+
+Run `make test` and capture the full output.
+
+## Step 2 — Fix All Errors
+
+If `make test` failed:
+- Analyze every error in the output (lint, type-check, unit tests, shellcheck, etc.).
+- Fix all errors in the source code.
+- Re-run `make test` to confirm all errors are resolved.
+- Repeat until `make test` passes with zero failures.
+
+If `make test` passed, proceed to the next step.
+
+## Step 3 — Determine Semver Bump Level
+
+Analyze all changes since the last released version:
+- Run `git log $(git describe --tags --abbrev=0)..HEAD --oneline` to list commits since the last tag.
+- Run `git diff $(git describe --tags --abbrev=0)..HEAD --stat` to see which files changed.
+- Apply semver rules:
+  - **major** — breaking API changes, removed public functions/classes, changed signatures
+  - **minor** — new features, new public API, new modules, backward-compatible additions
+  - **patch** — bug fixes, documentation, internal refactors, dependency updates, CI/CD changes
+- Present your reasoning and recommended bump level to the user for confirmation before proceeding.
+
+## Step 4 — Bump Version
+
+Run the appropriate command based on the confirmed semver level:
+- `make bump-patch` for patch
+- `make bump-minor` for minor
+- `make bump-major` for major
+
+## Step 5 — Update Changelog
+
+Update `CHANGELOG.md` with the important changes since the last version:
+- Group changes under the new version heading with the current date.
+- Categorize entries (Added, Changed, Fixed, Removed, etc.) following Keep a Changelog format.
+- Be concise but cover all user-visible and developer-visible changes.
+
+## Step 6 — Create Commit Message
+
+Compose a meaningful commit message that:
+- Summarizes the version bump and key changes.
+- References the new version number.
+- Follows conventional commit style if the project uses it.
+
+Present the commit message to the user for approval.
+
+## Step 7 — Push
+
+Run `make push <approved commit message>` to run tests, commit, and push to the remote.
+
+## Step 8 — Monitor GitHub CI
+
+After pushing:
+- Run `gh run list --limit 1` to find the latest workflow run.
+- Run `gh run watch <run-id>` to monitor it until completion.
+- If the run **succeeds**, proceed to Step 9.
+- If the run **fails**:
+  - Run `gh run view <run-id> --log-failed` to get failure details.
+  - Fix all errors in the source code.
+  - Go back to **Step 5** (update changelog if the fix is meaningful, re-commit, re-push).
+
+## Step 9 — Release
+
+Once GitHub CI is green:
+- Run `make release` to create the version tag and GitHub release.
+
+## Step 10 — Monitor Release CI
+
+After releasing:
+- Run `gh run list --limit 1` to find the release workflow run.
+- Run `gh run watch <run-id>` to monitor it until completion.
+- If the run **succeeds**, report the release URL and confirm completion.
+- If the run **fails**:
+  - Run `gh run view <run-id> --log-failed` to get failure details.
+  - Fix all errors in the source code.
+  - Go back to **Step 5** (update changelog, re-commit, re-push, re-release).

{lib_cli_exit_tools-2.2.3 → lib_cli_exit_tools-2.3.0}/.codacy/cli.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 
-
 set -e +o pipefail
 
 # Set up paths first
@@ -11,15 +10,15 @@ os_name=$(uname)
 arch=$(uname -m)
 
 case "$arch" in
-"x86_64")
-  arch="amd64"
-  ;;
-"x86")
-  arch="386"
-  ;;
-"aarch64"|"arm64")
-  arch="arm64"
-  ;;
+    "x86_64")
+        arch="amd64"
+        ;;
+    "x86")
+        arch="386"
+        ;;
+    "aarch64" | "arm64")
+        arch="arm64"
+        ;;
 esac
 
 if [ -z "$CODACY_CLI_V2_TMP_FOLDER" ]; then
@@ -34,10 +33,10 @@ fi
 
 version_file="$CODACY_CLI_V2_TMP_FOLDER/version.yaml"
 
-
 get_version_from_yaml() {
     if [ -f "$version_file" ]; then
-        local version=$(grep -o 'version: *"[^"]*"' "$version_file" | cut -d'"' -f2)
+        local version
+        version=$(grep -o 'version: *"[^"]*"' "$version_file" | cut -d'"' -f2)
         if [ -n "$version" ]; then
             echo "$version"
             return 0
@@ -49,20 +48,24 @@ get_version_from_yaml() {
 get_latest_version() {
     local response
     if [ -n "$GH_TOKEN" ]; then
-        response=$(curl -Lq --header "Authorization: Bearer $GH_TOKEN" "https://api.github.com/repos/codacy/codacy-cli-v2/releases/latest" 2>/dev/null)
+        response=$(curl -Lq \
+            --header "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/codacy/codacy-cli-v2/releases/latest" 2>/dev/null)
     else
-        response=$(curl -Lq "https://api.github.com/repos/codacy/codacy-cli-v2/releases/latest" 2>/dev/null)
+        response=$(curl -Lq \
+            "https://api.github.com/repos/codacy/codacy-cli-v2/releases/latest" 2>/dev/null)
     fi
 
     handle_rate_limit "$response"
-    local version=$(echo "$response" | grep -m 1 tag_name | cut -d'"' -f4)
+    local version
+    version=$(echo "$response" | grep -m 1 tag_name | cut -d'"' -f4)
     echo "$version"
 }
 
 handle_rate_limit() {
     local response="$1"
     if echo "$response" | grep -q "API rate limit exceeded"; then
-          fatal "Error: GitHub API rate limit exceeded. Please try again later"
+        fatal "Error: GitHub API rate limit exceeded. Please try again later"
     fi
 }
 
@@ -70,9 +73,9 @@ download_file() {
     local url="$1"
 
     echo "Downloading from URL: ${url}"
-    if command -v curl > /dev/null 2>&1; then
+    if command -v curl >/dev/null 2>&1; then
         curl -# -LS "$url" -O
-    elif command -v wget > /dev/null 2>&1; then
+    elif command -v wget >/dev/null 2>&1; then
         wget "$url"
     else
         fatal "Error: Could not find curl or wget, please install one."
@@ -83,7 +86,7 @@ download() {
     local url="$1"
     local output_folder="$2"
 
-    ( cd "$output_folder" && download_file "$url" )
+    (cd "$output_folder" && download_file "$url")
 }
 
 download_cli() {
@@ -95,7 +98,7 @@ download_cli() {
     local version="$3"
 
     if [ ! -f "$bin_path" ]; then
-        echo "📥 Downloading CLI version $version..."
+        echo "Downloading CLI version $version..."
 
         remote_file="codacy-cli-v2_${version}_${suffix}_${arch}.tar.gz"
         url="https://github.com/codacy/codacy-cli-v2/releases/download/${version}/${remote_file}"
@@ -107,16 +110,16 @@ download_cli() {
 
 # Warn if CODACY_CLI_V2_VERSION is set and update is requested
 if [ -n "$CODACY_CLI_V2_VERSION" ] && [ "$1" = "update" ]; then
-    echo "⚠️  Warning: Performing update with forced version $CODACY_CLI_V2_VERSION"
+    echo "Warning: Performing update with forced version $CODACY_CLI_V2_VERSION"
     echo "    Unset CODACY_CLI_V2_VERSION to use the latest version"
 fi
 
 # Ensure version.yaml exists and is up to date
 if [ ! -f "$version_file" ] || [ "$1" = "update" ]; then
-    echo "ℹ️  Fetching latest version..."
+    echo "Fetching latest version..."
     version=$(get_latest_version)
     mkdir -p "$CODACY_CLI_V2_TMP_FOLDER"
-    echo "version: \"$version\"" > "$version_file"
+    echo "version: \"$version\"" >"$version_file"
 fi
 
 # Set the version to use
@@ -126,7 +129,6 @@ else
     version=$(get_version_from_yaml)
 fi
 
-
 # Set up version-specific paths
 bin_folder="${CODACY_CLI_V2_TMP_FOLDER}/${version}"
 
@@ -146,4 +148,4 @@ if [ "$#" -eq 1 ] && [ "$1" = "download" ]; then
     echo "Codacy cli v2 download succeeded"
 else
     eval "$run_command $*"
-fi
+fi

lib_cli_exit_tools-2.3.0/.data_arch_violations.json

@@ -0,0 +1,38 @@
+{
+  "pass": 1,
+  "total_violations": 0,
+  "files": {
+    "src/lib_cli_exit_tools/core/configuration.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/core/exit_codes.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/application/runner.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/__init__.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/__init__conf__.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/cli.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/lib_cli_exit_tools.py": {
+      "violations": [],
+      "status": "clean"
+    },
+    "src/lib_cli_exit_tools/adapters/signals.py": {
+      "violations": [],
+      "status": "clean"
+    }
+  }
+}

lib_cli_exit_tools-2.3.0/.github/actions/extract-metadata/action.yml

@@ -0,0 +1,92 @@
+name: Extract project metadata
+description: >-
+  Parse pyproject.toml and expose project metadata as step outputs.
+  Requires Python to be available in the runner environment.
+  Auto-installs rtoml if not already present.
+
+outputs:
+  PACKAGE_MODULE:
+    description: Python-importable module name (underscored)
+    value: ${{ steps.meta.outputs.PACKAGE_MODULE }}
+  PROJECT_NAME:
+    description: Project name from pyproject.toml
+    value: ${{ steps.meta.outputs.PROJECT_NAME }}
+  CLI_BIN:
+    description: CLI entry-point binary name
+    value: ${{ steps.meta.outputs.CLI_BIN }}
+  SRC_PATH:
+    description: Source directory path (e.g. "src")
+    value: ${{ steps.meta.outputs.SRC_PATH }}
+  COV_FAIL_UNDER:
+    description: Minimum coverage percentage from tool.coverage.report.fail_under
+    value: ${{ steps.meta.outputs.COV_FAIL_UNDER }}
+  COV_REPORT_FILE:
+    description: Coverage report filename (e.g. "coverage.xml")
+    value: ${{ steps.meta.outputs.COV_REPORT_FILE }}
+  PYTEST_VERBOSITY:
+    description: Pytest verbosity flag (e.g. "-vv")
+    value: ${{ steps.meta.outputs.PYTEST_VERBOSITY }}
+  BANDIT_SKIP_FLAG:
+    description: Bandit skip flag string (e.g. "-s B101,B601") or empty
+    value: ${{ steps.meta.outputs.BANDIT_SKIP_FLAG }}
+
+runs:
+  using: composite
+  steps:
+    - name: Extract project metadata from pyproject.toml
+      id: meta
+      shell: python
+      run: |
+        import os, subprocess, sys
+        try:
+            import rtoml
+        except ModuleNotFoundError:
+            subprocess.check_call([sys.executable, "-m", "pip", "install", "rtoml", "-q"])
+            import rtoml
+
+        from pathlib import Path
+        data = rtoml.load(Path('pyproject.toml'))
+
+        # --- [project] section ---
+        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
+
+        # --- [tool.scripts.test] section ---
+        scripts_test = data.get('tool', {}).get('scripts', {}).get('test', {})
+        src_path = scripts_test.get('src-path', 'src')
+        pytest_verbosity = scripts_test.get('pytest-verbosity', '-vv')
+        cov_report_file = scripts_test.get('coverage-report-file', 'coverage.xml')
+
+        # --- [tool.coverage.report] section ---
+        cov_fail_under = (
+            data.get('tool', {}).get('coverage', {}).get('report', {}).get('fail_under', 90)
+        )
+
+        # --- [tool.bandit] section ---
+        bandit_skips = data.get('tool', {}).get('bandit', {}).get('skips', [])
+        bandit_skip_flag = f"-s {','.join(bandit_skips)}" if bandit_skips else ""
+
+        # Write to GITHUB_OUTPUT for composite action outputs
+        with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as out:
+            out.write(f"PROJECT_NAME={project}\n")
+            out.write(f"PACKAGE_MODULE={module}\n")
+            out.write(f"CLI_BIN={cli_bin}\n")
+            out.write(f"SRC_PATH={src_path}\n")
+            out.write(f"PYTEST_VERBOSITY={pytest_verbosity}\n")
+            out.write(f"COV_REPORT_FILE={cov_report_file}\n")
+            out.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
+            out.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")
+
+        # Also write to GITHUB_ENV so subsequent steps can use ${{ env.VAR }}
+        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")
+            env.write(f"SRC_PATH={src_path}\n")
+            env.write(f"PYTEST_VERBOSITY={pytest_verbosity}\n")
+            env.write(f"COV_REPORT_FILE={cov_report_file}\n")
+            env.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
+            env.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")

lib_cli_exit_tools-2.3.0/.github/workflows/default_cicd_public.yml

@@ -0,0 +1,283 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Run daily at 3:17 AM UTC (off-peak hours, odd minute to avoid congestion)
+    - cron: '17 3 * * *'
+
+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 all supported Python versions (3.10+)
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      PYTHONIOENCODING: "utf-8"
+      UV_LINK_MODE: "copy"
+      UV_BREAK_SYSTEM_PACKAGES: "1"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install bash 4+ on macOS
+        if: runner.os == 'macOS'
+        run: |
+          brew install bash
+          echo "$(brew --prefix)/bin" >> "$GITHUB_PATH"
+
+      - name: Extract project metadata
+        id: metadata
+        uses: ./.github/actions/extract-metadata
+
+      - name: Install journald prerequisites
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-systemd
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          uv pip install -e .[dev] --system
+
+      - name: Install Windows Event Log prerequisites
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv pip install pywin32 --system
+
+      - name: Restore ruff cache
+        id: ruff-cache
+        uses: actions/cache/restore@v5
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+          restore-keys: |
+            ruff-${{ runner.os }}-py${{ matrix.python }}-
+            ruff-${{ runner.os }}-
+
+      - name: Run ruff (lint + format)
+        id: ruff
+        continue-on-error: true
+        shell: bash
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run pyright (type check)
+        id: pyright
+        continue-on-error: true
+        shell: bash
+        run: pyright
+
+      - name: Run pytest (tests + coverage)
+        id: pytest
+        continue-on-error: true
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+          # Write coverage SQLite database to local disk — network mounts
+          # and stale journal files cause "database is locked" errors.
+          COVERAGE_FILE: "${{ runner.temp }}/.coverage"
+        run: >-
+          pytest -m "not local_only"
+          --cov=${{ env.SRC_PATH }}/${{ env.PACKAGE_MODULE }}
+          --cov-report=term-missing
+          --cov-report=xml:${{ env.COV_REPORT_FILE }}
+          --cov-fail-under=${{ env.COV_FAIL_UNDER }}
+          ${{ env.PYTEST_VERBOSITY }}
+
+      - name: Upload coverage to Codecov
+        if: >-
+          always()
+          && steps.pytest.outcome == 'success'
+          && matrix.os == 'ubuntu-latest'
+          && matrix.python == '3.13'
+        uses: codecov/codecov-action@v5
+        with:
+          files: ${{ env.COV_REPORT_FILE }}
+          fail_ci_if_error: false
+
+      - name: Run import-linter (architecture)
+        id: importlinter
+        continue-on-error: true
+        shell: bash
+        run: lint-imports
+
+      - name: Run bandit (security scan)
+        id: bandit
+        continue-on-error: true
+        shell: bash
+        run: bandit -q -r ${{ env.SRC_PATH }}/${{ env.PACKAGE_MODULE }} ${{ env.BANDIT_SKIP_FLAG }}
+
+      - name: Run pip-audit (vulnerability scan)
+        id: pipaudit
+        continue-on-error: true
+        shell: python
+        run: |
+          import subprocess, sys
+          import rtoml
+          from pathlib import Path
+          data = rtoml.load(Path("pyproject.toml"))
+          vulns = data.get("tool", {}).get("pip-audit", {}).get("ignore-vulns", [])
+          cmd = ["pip-audit", "--skip-editable"]
+          for v in vulns:
+              cmd.extend(["--ignore-vuln", v])
+          sys.exit(subprocess.call(cmd))
+
+      - name: Check all steps passed
+        shell: bash
+        run: |
+          if [[ "${{ steps.ruff.outcome }}" != "success" ]]; then
+            echo "::error::Ruff check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pyright.outcome }}" != "success" ]]; then
+            echo "::error::Pyright check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pytest.outcome }}" != "success" ]]; then
+            echo "::error::Pytest failed"
+            exit 1
+          fi
+          if [[ "${{ steps.importlinter.outcome }}" != "success" ]]; then
+            echo "::error::Import-linter check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.bandit.outcome }}" != "success" ]]; then
+            echo "::error::Bandit security scan failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pipaudit.outcome }}" != "success" ]]; then
+            echo "::error::pip-audit vulnerability scan failed"
+            exit 1
+          fi
+          echo "All checks passed!"
+
+      - name: Build wheel/sdist
+        shell: bash
+        run: uv build
+
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          uv venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          uv pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+      - name: Prune uv cache
+        continue-on-error: true
+        shell: bash
+        run: uv cache prune --ci
+
+      - name: Save ruff cache
+        if: always() && steps.ruff-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Extract project metadata
+        id: metadata
+        uses: ./.github/actions/extract-metadata
+
+      - name: Build wheel
+        run: uv build
+      - name: pipx install from wheel
+        run: |
+          uv pip install --system pipx
+          pipx ensurepath
+          export PATH="$HOME/.local/bin:$PATH"
+          pipx install dist/*.whl
+          "$CLI_BIN" --version
+
+      - name: uv tool install
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          uv tool install --force .
+          "$CLI_BIN" --version
+
+      - name: Prune uv cache
+        continue-on-error: true
+        run: uv cache prune --ci
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.14)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install notebook runner deps
+        run: |
+          uv pip install --system 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