feat: Phase 15 — distribution + cpal + CI hardening (11 tasks, 44 SP)

.cargo/mutants.toml

@@ -0,0 +1,20 @@
+# cargo-mutants configuration (BEE-1887).
+#
+# Whole-workspace mutation sweep, scheduled weekly via
+# `.github/workflows/mutants.yml`. Per-PR runs are out of scope — the sweep
+# is too slow (minutes per file × ~30 files) for the per-PR budget.
+
+# Skip the FFI bindings crate. Mutants there require the prebuilt
+# beeping-core static lib + the FFI test harness, which would re-download
+# the static lib on every mutant iteration (~10 MB × N mutants = hours).
+# Mutation testing of the FFI surface is its own follow-up if it ever
+# becomes valuable; the rest of the workspace is pure Rust and benefits
+# more from this sweep.
+exclude_globs = ["crates/core-bindings/**"]
+
+# Per-mutant timeout uses cargo-mutants' default (5× the baseline test
+# time), which is generous enough for the offline FFI round-trip
+# (~5s × 5 = 25s budget). We avoided `timeout_multiplier` here because
+# the slowest test runs only when a specific module is mutated; tying
+# the multiplier globally would inflate budgets for fast tests too.
+# Override on the CLI with `--timeout SECS` if a specific run needs it.

.github/workflows/ci.yml

@@ -2,7 +2,12 @@ name: 🧪 CI
 
 on:
   push:
-    branches: [develop, main]
+    # `milestone/*` branches accumulate commits during the milestone
+    # cycle (one branch per phase per global methodology). Running CI on
+    # them gives continuous feedback before the closure PR — without
+    # this, we only get a CI signal at PR time, which delays detection
+    # of cross-platform issues. BEE-150.
+    branches: [develop, main, "milestone/*"]
   pull_request:
     branches: [develop, main]
 
@@ -34,6 +39,8 @@ jobs:
       - name: 🦀 Setup Rust (from rust-toolchain.toml)
         run: rustup show
       - uses: Swatinem/rust-cache@v2
+      - name: 🔊 Install libasound2-dev (cpal alsa-sys backend, BEE-1885)
+        run: sudo apt-get update -qq && sudo apt-get install -y libasound2-dev
       - name: 🔍 cargo clippy
         run: cargo clippy --all-targets --all-features -- -D warnings
 
@@ -42,28 +49,70 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      # `rust-version: stable` avoids the action's default behaviour of
+      # installing a musl override toolchain matching `rust-toolchain.toml`,
+      # which fails for our pinned `1.88` channel — the action only ships
+      # `stable`/`nightly` aliases for the musl target. BEE-150.
       - uses: EmbarkStudios/cargo-deny-action@v2
         with:
           command: check
+          rust-version: stable
 
   test:
     name: 🧪 test (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
+    # BEE-1897 re-enabled `windows-latest` — fmt 11 is now pinned via the
+    # vcpkg baseline checkout in the Windows-only setup step below.
+    #
+    # Windows test is `continue-on-error: true` because beeping-core's
+    # Windows static lib has a runtime FFI crash (STATUS_ACCESS_VIOLATION
+    # `0xC0000005`) on every test that invokes `beeping decode <wav>` —
+    # tracked in BEE-2222 (BEE-1897 follow-up). Build, snapshot tests,
+    # and the encode-only path on Windows DO work; the segfault is
+    # specific to the FFI decode call. Removing this flag is part of
+    # BEE-2222's DoD.
+    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
+        include:
+          - os: windows-latest
+            experimental: true
     steps:
       - uses: actions/checkout@v4
       - name: 🦀 Setup Rust (from rust-toolchain.toml)
         run: rustup show
       - uses: Swatinem/rust-cache@v2
+      - name: 🔊 Install libasound2-dev (cpal alsa-sys backend, BEE-1885 follow-up)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -qq && sudo apt-get install -y libasound2-dev
+      - name: 🪟 Install fmt 11.2 via vcpkg classic mode at pinned baseline (Windows MSVC only)
+        # Pin the runner's vcpkg to the baseline commit that has fmt 11.2.0
+        # (last commit before vcpkg's fmt 12 update on 2025-09-22). beeping-core's
+        # Windows static lib references fmt::v11 symbols externally because
+        # spdlog's bundled fmt was elided at packaging time; without this
+        # pin the runner installs fmt 12 and the linker can't resolve them.
+        # BEE-1897.
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          cd $env:VCPKG_INSTALLATION_ROOT
+          git fetch
+          git checkout 6b3172d1a7be062b3d0278369aac9a0258cefc65
+          .\bootstrap-vcpkg.bat -disableMetrics
+          .\vcpkg.exe install spdlog:x64-windows-static fmt:x64-windows-static
+          cd $env:GITHUB_WORKSPACE
+          echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
+          echo "RUSTFLAGS=-C target-feature=+crt-static" | Out-File -FilePath $env:GITHUB_ENV -Append
       - name: 🧪 cargo test
         run: cargo test --all-targets --all-features
 
   build:
     name: 📦 release build (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
+    # BEE-1897 re-enabled `windows-latest` — see test job for the vcpkg
+    # baseline rationale.
     strategy:
       fail-fast: false
       matrix:
@@ -73,41 +122,177 @@ jobs:
       - name: 🦀 Setup Rust (from rust-toolchain.toml)
         run: rustup show
       - uses: Swatinem/rust-cache@v2
+      - name: 🔊 Install libasound2-dev (cpal alsa-sys backend, BEE-1885 follow-up)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -qq && sudo apt-get install -y libasound2-dev
+      - name: 🪟 Install fmt 11.2 via vcpkg classic mode at pinned baseline (Windows MSVC only)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          cd $env:VCPKG_INSTALLATION_ROOT
+          git fetch
+          git checkout 6b3172d1a7be062b3d0278369aac9a0258cefc65
+          .\bootstrap-vcpkg.bat -disableMetrics
+          .\vcpkg.exe install spdlog:x64-windows-static fmt:x64-windows-static
+          cd $env:GITHUB_WORKSPACE
+          echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
+          echo "RUSTFLAGS=-C target-feature=+crt-static" | Out-File -FilePath $env:GITHUB_ENV -Append
       - name: 📦 cargo build --release
         run: cargo build --release --all-features
 
+  completions-smoke:
+    name: 🐚 completions smoke
+    # BEE-152: snapshot tests pin the *content* of each completion script,
+    # but text-snapshotting can miss subtle syntax errors that real shells
+    # would catch. This job loads each completion under its native shell
+    # and asserts no syntax errors — the cheapest end-to-end "did
+    # clap_complete actually generate something the shell will accept?"
+    # check.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 🦀 Setup Rust (from rust-toolchain.toml)
+        run: rustup show
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: completions-smoke
+      - name: 🔊 + 🐚 Install libasound2-dev (cpal alsa-sys, BEE-1885) + zsh + fish
+        # libasound2-dev is required by cpal's alsa-sys backend on Linux;
+        # zsh + fish aren't on ubuntu-latest by default. Bundling both
+        # apt-get installs into one update + one install call.
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y libasound2-dev zsh fish
+      - name: 🔨 cargo build
+        run: cargo build --bin beeping
+      - name: 📜 Generate man page + completions
+        run: |
+          ./target/debug/beeping __generate-man-page    --out-dir /tmp/man
+          ./target/debug/beeping __generate-completions --shell bash       --out-dir /tmp/completions
+          ./target/debug/beeping __generate-completions --shell zsh        --out-dir /tmp/completions
+          ./target/debug/beeping __generate-completions --shell fish       --out-dir /tmp/completions
+          ./target/debug/beeping __generate-completions --shell power-shell --out-dir /tmp/completions
+          ls -la /tmp/man /tmp/completions
+      - name: 🐚 bash -n
+        run: bash -n /tmp/completions/beeping.bash
+      - name: 🐚 zsh -n
+        run: zsh -n /tmp/completions/_beeping
+      - name: 🐚 fish syntax check
+        # `fish --no-execute FILE` parses the script without executing it
+        # and exits 1 only on real syntax errors — the right gate for a
+        # smoke check (BEE-152 follow-up).
+        #
+        # The original BEE-152 command (`fish_indent --check`) was wrong:
+        # `--check` returns 1 whenever the input would be reformatted by
+        # `fish_indent`, which always happens on `clap_complete`'s output
+        # because clap_complete uses a different (also-valid) style. That
+        # made the gate fire on a stylistic mismatch, not a real syntax
+        # problem.
+        run: fish --no-execute /tmp/completions/beeping.fish
+      - name: 📜 mandoc lint (best-effort)
+        # mandoc may flag spec violations clap_mangen produces (clap_mangen
+        # is decent but not perfect). We capture warnings as a job
+        # annotation but do not fail the build — that pin would couple
+        # us too tightly to mandoc's evolving heuristics.
+        run: |
+          sudo apt-get install -qq mandoc
+          mandoc -Tlint /tmp/man/beeping.1 || echo "::warning::mandoc reported issues — review the output"
+
+  external-smoke:
+    name: 🔍 external/ scaffolding smoke
+    # BEE-151: cheap structural checks for the Homebrew tap formula
+    # (`external/tap/`) and the Scoop manifest (`external/scoop-bucket/`)
+    # before they get transplanted to `beeping-io/tap` and
+    # `beeping-io/scoop-bucket`. We do NOT run `brew audit` or
+    # `scoop checkver` here — those need their respective CLIs and
+    # network access. The full audit lives in BEE-1786 (post-release
+    # smoke matrix).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 💎 ruby -c on Homebrew formula
+        run: ruby -c external/tap/Formula/beeping-cli.rb
+      - name: 🐍 JSON parse on Scoop manifest
+        run: python3 -c "import json; json.load(open('external/scoop-bucket/bucket/beeping-cli.json'))"
+
+  publish-dryrun:
+    name: 📦 cargo publish --dry-run
+    # BEE-151: smoke gate that the publishable crates can be packaged
+    # for crates.io. `bindings` + `lib` have no internal deps, so they
+    # dry-run cleanly with full build verification.
+    #
+    # The binary crate (`beeping-cli`) is intentionally NOT included
+    # here: cargo refuses to package any crate whose deps are not
+    # resolvable from the registry, even with `--no-verify`. Since
+    # `beeping-cli` depends on `beeping-cli-bindings` + `beeping-cli-lib`
+    # which only land on crates.io after `release.yml`'s first
+    # `publish-crates` run, a CI-side dry-run for `beeping-cli` would
+    # always fail until that first release. Build + behaviour of the
+    # binary are already covered by the `test`, `clippy`, and `build`
+    # jobs above. The first real publish from a tag is the canonical
+    # end-to-end gate for the binary's packaging.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 🦀 Setup Rust (from rust-toolchain.toml)
+        run: rustup show
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: publish-dryrun
+      - name: 📦 dry-run beeping-cli-bindings
+        run: cargo publish -p beeping-cli-bindings --dry-run
+      - name: 📦 dry-run beeping-cli-lib
+        run: cargo publish -p beeping-cli-lib --dry-run
+
   coverage:
-    name: 📊 coverage (tarpaulin)
+    name: 📊 coverage (cargo-llvm-cov)
     runs-on: ubuntu-latest
+    # BEE-1897 swapped tarpaulin → cargo-llvm-cov. tarpaulin's
+    # `cargo-platform v0.3.3` transitive dep requires rustc 1.91 vs our
+    # pinned 1.88, which made `cargo install` fail at the install step.
+    # cargo-llvm-cov is a thin wrapper around rustc's stable
+    # `-C instrument-coverage`, has a much smaller dep tree, and installs
+    # cleanly on the runner under our MSRV. The 70 % floor is preserved.
+    # No more `continue-on-error: true` — coverage now blocks on real
+    # regressions. Codecov upload still no-ops without `CODECOV_TOKEN`
+    # (BEE-1888 founder action).
     steps:
       - uses: actions/checkout@v4
       - name: 🦀 Setup Rust (from rust-toolchain.toml)
         run: rustup show
       - uses: Swatinem/rust-cache@v2
-      - name: 📦 install cargo-tarpaulin
-        run: cargo install cargo-tarpaulin --locked
-      - name: 📊 cargo tarpaulin → lcov
-        # `--ignore-tests` stops the report from double-counting test code
-        # itself. `--timeout 300` covers the slowest E2E (offline FFI
-        # round-trip is the bottleneck at ~5 s). `--fail-under 70` is the
-        # initial floor (BEE-149); the BEE-149 spec target is 80 %, but
-        # we set the gate at 70 % until the first real CI run measures
-        # the baseline. Bumping to 80 % is queued in pending-007 alongside
-        # the Codecov account setup.
+      - name: 🔊 Install libasound2-dev (cpal alsa-sys backend, BEE-1885 follow-up)
+        run: sudo apt-get update -qq && sudo apt-get install -y libasound2-dev
+      - name: 📦 install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+      - name: 📊 cargo llvm-cov → lcov
+        # `--workspace` covers all crates; `--all-targets` includes
+        # integration tests; `--lcov` produces the format Codecov ingests.
+        # `--fail-under-lines 70` is the BEE-149 bootstrap floor,
+        # restored when BEE-1885 + BEE-1884 added cpal-driven `audio.rs`
+        # (~370 lines of cpal IO paths that can't be unit-tested without
+        # real audio hardware; the pure `pump_samples` + `downmix_to_mono`
+        # kernels ARE covered by 14 tests, but the real-stream code
+        # diluted the workspace % from 82 to ~75 on macOS / ~73 on Linux
+        # CI runners which also `cfg_attr`-ignore the FFI-flaky tests).
+        # Bumping back toward the BEE-149 spec target of 80 % requires
+        # either mock-testing cpal paths (extract trait + dependency
+        # injection) or closing BEE-2222 so the Linux FFI ignores can be
+        # removed — both are queued as follow-ups.
+        # mkdir is required because cargo-llvm-cov doesn't auto-create
+        # the parent directory of `--output-path`.
         run: |
-          cargo tarpaulin \
+          mkdir -p target/llvm-cov
+          cargo llvm-cov \
             --workspace \
             --all-targets \
-            --engine llvm \
-            --timeout 300 \
-            --ignore-tests \
-            --out lcov \
-            --output-dir target/tarpaulin \
-            --fail-under 70
+            --lcov \
+            --output-path target/llvm-cov/lcov.info \
+            --fail-under-lines 70
       - name: 📈 Upload to Codecov
         uses: codecov/codecov-action@v4
         with:
-          files: target/tarpaulin/lcov.info
+          files: target/llvm-cov/lcov.info
           fail_ci_if_error: false # Codecov outage shouldn't block CI
           flags: rust
         env: