retch-cli 0.17.3

name: Packaging Verification

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
    paths:
      - '**/*.rs'
      - '**/Cargo.toml'
      - 'Cargo.lock'
      - 'flake.nix'
      - 'flake.lock'
      - 'packaging/**'
      # The recipes that RENDER packaging/aur (aur-bump / aur-srcinfo / aur-check) live in
      # the Justfile, so a change there can alter the AUR tooling without touching anything
      # under packaging/ — which is exactly how #203 shipped with every workflow's paths
      # filter skipping it, CI green having never looked at the change. This job cannot run
      # those recipes (no podman, no `just` in the container), so what the entry buys is
      # artifact-level coverage: the committed PKGBUILD/.SRCINFO pair is re-verified against
      # the real tarball, rebuilt with makepkg, and its packaged man page inspected.
      - 'Justfile'
      # The three packaging guards themselves. Same hole as the Justfile one above, one
      # directory over: `scripts/brew_check.py` and its siblings decide whether a drifted
      # packaging file can reach a commit, and until this entry a PR touching only a guard
      # matched no filter and got no packaging verification at all.
      - 'scripts/*_check.py'
      # .copr/Makefile is what GENERATES the SRPM, and until v0.9.10 no PR-triggered
      # workflow watched it: copr.yml watches '.copr/**' but only on push to main, so a PR
      # touching only that file got no packaging verification whatsoever. That is not
      # hypothetical — it is how the v0.9.9 bug (`rpmdev-setuptree` assuming %{_topdir},
      # which mock moves) reached main and failed on COPR instead of in CI. Same hole as
      # the Justfile one above, one directory over.
      - '.copr/**'
      - '.github/workflows/packaging.yml'
  workflow_dispatch:

permissions:
  contents: read

jobs:
  nixpkgs:
    runs-on: ubuntu-latest
    if: false  # disabled: nixpkgs PR declined due to lack of popularity
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install Nix
        uses: cachix/install-nix-action@v31
        with:
          nix_path: nixpkgs=channel:nixos-unstable

      - name: Build Nixpkgs Derivation
        run: nix-build packaging/nixpkgs/test.nix

      - name: Build Nix Flake
        run: nix build .#default

  aur:
    runs-on: ubuntu-latest
    container: archlinux:latest
    steps:
      - name: Install system dependencies
        run: |
          # mandown is deliberately NOT installed: the PKGBUILD no longer regenerates the man
          # page (it installs the committed docs/retch.1), so mandown is not in makedepends
          # either. Pre-installing it here would mask a future build() that calls it without
          # declaring it — `makepkg -s` installs what makedepends asks for, and nothing else.
          # `cargo` is still pre-installed, so that one makedepend remains masked.
          pacman -Syu --noconfirm git base-devel cargo curl sudo

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      # Runs BEFORE the build step, which rewrites source= and sha256sums= to build from local
      # sources. Without this, the declared checksum is never checked by anything: a stale or
      # wrong sha256 in the reference PKGBUILD would sail through CI and only fail for someone
      # actually installing from the AUR.
      - name: Verify declared source checksum
        shell: bash
        run: |
          set -euo pipefail
          cd packaging/aur
          # A PKGBUILD is a bash script of assignments; sourcing defines the functions without
          # running them.
          # shellcheck disable=SC1091
          source ./PKGBUILD
          url_field="${source[0]#*::}"
          declared="${sha256sums[0]}"
          echo "pkgver:   $pkgver"
          echo "url:      $url_field"
          echo "declared: $declared"

          if [ "$declared" = "SKIP" ]; then
            echo "::error::sha256sums is SKIP in the committed PKGBUILD; it must carry a real checksum"
            exit 1
          fi

          # The reference copy tracks the last RELEASED version, so its tag normally exists. On
          # a branch that has bumped it ahead of the last release it will not yet — that is a
          # legitimate state, not a failure, so skip rather than go red.
          if ! curl -fsSL --retry 3 -o upstream.tar.gz "$url_field"; then
            echo "::notice::tag not published yet ($url_field) — checksum not verifiable at this commit"
            exit 0
          fi

          actual=$(sha256sum upstream.tar.gz | cut -d' ' -f1)
          echo "actual:   $actual"
          if [ "$actual" != "$declared" ]; then
            echo "::error::sha256 mismatch for $url_field — declared $declared, actual $actual"
            exit 1
          fi
          echo "checksum OK"
          rm -f upstream.tar.gz

      - name: Build AUR PKGBUILD
        run: |
          # Create builduser
          useradd -m builduser
          echo "builduser ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
          
          cd packaging/aur
          
          # Package local source to avoid downloading tag that doesn't exist yet
          tar --exclude=packaging/aur/cargo-home --exclude=target --exclude=.git -czf /tmp/retch.tar.gz -C ../.. .
          mv /tmp/retch.tar.gz retch.tar.gz
          
          # Patch PKGBUILD for local build
          sed -i 's|source=.*|source=("retch.tar.gz")|' PKGBUILD
          sed -i 's|sha256sums=.*|sha256sums=("SKIP")|' PKGBUILD
          sed -i 's|"$pkgname-\$pkgver"|"$srcdir"|g' PKGBUILD
          
          chown -R builduser:builduser .
          
          # Run makepkg (unsetting any runner-inherited cargo linker configs)
          sudo -u builduser env -u CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER makepkg -s --noconfirm

      # Regression test for two real defects that shipped in this PKGBUILD for months, both
      # silent — the package built fine and the installed page was wrong:
      #   1. `\$DATE` / `\$pkgver` are LITERAL inside a bash double-quoted string, so the .TH
      #      footer read `$DATE` / `retch $pkgver` instead of the date and version.
      #   2. the `s/\\fB\\fB/\\fB/g` font-strip never matched on any platform (GNU sed reads
      #      `\\f` as a form feed), so it was dead code pretending to clean the output.
      # Both are fixed by installing the committed docs/retch.1 rather than regenerating it.
      # Nothing else inspects the packaged man page, so without this the defects could return.
      - name: Verify packaged man page
        shell: bash
        run: |
          set -euo pipefail
          cd packaging/aur

          # NOTE: every inspection below reads a materialised FILE, never `producer | grep -q`.
          # Under `set -o pipefail` that idiom is a check that fails for the wrong reason:
          # `grep -q` (and `head -1`, and `grep -m1`) exit on the first match, the producer
          # takes SIGPIPE and exits 141, and pipefail turns the whole pipeline nonzero — so the
          # check reports "not found" precisely WHEN IT MATCHES. The first version of this step
          # did exactly that and failed CI while the package was perfectly correct.
          pkg=$(find . -maxdepth 1 -name 'retch-*.pkg.tar.*' ! -name '*-debug-*' -print -quit)
          if [ -z "$pkg" ]; then
            echo "::error::no built package found in packaging/aur"
            ls -1
            exit 1
          fi
          echo "inspecting $pkg"

          bsdtar -tf "$pkg" > pkg-listing.txt

          # makepkg's `zipman` option is ON by default, so the packaged page is
          # `retch.1.gz`, not `retch.1` — match either, and any other compressor a
          # makepkg.conf might select, rather than assuming one name.
          man_entry=$(grep -m1 -E '^usr/share/man/man1/retch\.1(\.gz|\.zst|\.xz|\.bz2)?$' pkg-listing.txt || true)
          if [ -z "$man_entry" ]; then
            echo "::error::package contains no usr/share/man/man1/retch.1"
            echo "--- what it did install under usr/share:"
            grep -E '^usr/share' pkg-listing.txt || echo "(nothing)"
            exit 1
          fi
          echo "man page entry: $man_entry"

          bsdtar -xOf "$pkg" "$man_entry" > packaged-man.raw
          case "$man_entry" in
            *.gz)  gzip -dc  < packaged-man.raw > packaged-retch.1 ;;
            *.zst) zstd -dc  < packaged-man.raw > packaged-retch.1 ;;
            *.xz)  xz -dc    < packaged-man.raw > packaged-retch.1 ;;
            *.bz2) bzip2 -dc < packaged-man.raw > packaged-retch.1 ;;
            *)     cp packaged-man.raw packaged-retch.1 ;;
          esac

          th=$(grep -m1 '^\.TH' packaged-retch.1)
          echo "TH line: $th"

          # Defect 1: an unexpanded shell variable in the footer.
          case "$th" in
            *'$'*)
              echo "::error::.TH line contains a literal \$ — unexpanded variable in the footer"
              exit 1
              ;;
          esac

          # The footer must name the program and a real date. Deliberately NOT asserted against
          # $pkgver: this job builds from the local tree, whose committed page carries the
          # in-development version while pkgver tracks the last release. Coupling them here
          # would fail for a reason that has nothing to do with the packaging.
          case "$th" in
            *'"retch '[0-9]*) : ;;
            *)
              echo "::error::.TH line does not carry a 'retch <version>' footer"
              exit 1
              ;;
          esac

          # Defect 2: doubled font escapes the dead sed claimed to strip.
          if grep -q '\\fB\\fB\|\\fP\\fP' packaged-retch.1; then
            echo "::error::packaged man page contains doubled font escapes (\\fB\\fB / \\fP\\fP)"
            exit 1
          fi

          rm -f pkg-listing.txt packaged-retch.1 packaged-man.raw
          echo "packaged man page OK"

  copr:
    runs-on: ubuntu-latest
    container: fedora:latest
    steps:
      # Installed BEFORE checkout: fedora:latest ships no git, and without it
      # actions/checkout silently falls back to a REST tarball download. Same ordering and
      # the same reason as the aur job above.
      - name: Install system dependencies
        run: dnf -y install git make rpm-build rpmdevtools

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      # Offline consistency, the same half `just check` runs. CI invokes cargo directly and
      # never `just` (see NOTES.md), so the checker has to be called explicitly here or the
      # guard only ever runs on the machine of whoever remembered to type `just check`.
      - name: Verify the spec has not drifted
        run: python3 scripts/copr_check.py

      # This is the artifact-level half, and it is deliberately the SRPM step rather than a
      # full `rpmbuild -ba`: COPR itself does the full build on every packaging commit, so
      # duplicating a ~6-minute compile here would buy a second copy of a signal we already
      # get. What COPR does NOT give us is a signal *before* merge, which is the gap this
      # closes.
      - name: Build the SRPM exactly as COPR does
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p /tmp/srpm-plain
          make -f .copr/Makefile srpm outdir=/tmp/srpm-plain
          ls -1 /tmp/srpm-plain

      # THE REGRESSION TEST, and the run with the actual diagnostic value.
      #
      # COPR does not run .copr/Makefile in a plain container: it runs it inside MOCK, which
      # sets HOME=/builddir and redefines rpm's %{_topdir} to /builddir/build. v0.9.8 claimed
      # its Makefile was "verified by running exactly what COPR runs" — true of the COMMAND,
      # false of the ENVIRONMENT, and the environment was the half that mattered. The build
      # died on COPR in 60 seconds with
      #   cp: cannot create regular file '/builddir/rpmbuild/SPECS/': No such file or directory
      #
      # BOTH conditions are required to reproduce it. Setting %{_topdir} alone does NOT fail
      # on the pre-fix Makefile (rpmdev-setuptree simply creates the tree wherever _topdir
      # points); it is the combination with HOME=/builddir that separates the two paths. This
      # step was written by reconstructing the pre-fix Makefile from a606bbe and confirming it
      # FAILS here with that exact message, then confirming the current one passes — a check
      # nobody has watched fail is not yet a check.
      #
      # Both runs are kept, and neither is redundant: the plain run catches a Makefile that
      # hardcodes /builddir/build (which would work on COPR and break every dev box), and the
      # mock run catches one that assumes the default. NOTES.md's v0.9.9 entry names exactly
      # that pair as the reason not to hardcode.
      - name: Build the SRPM under mock's environment
        shell: bash
        run: |
          set -euo pipefail
          rm -rf .copr-sources
          mkdir -p /builddir /tmp/srpm-mock
          echo "%_topdir /builddir/build" > /builddir/.rpmmacros
          export HOME=/builddir
          echo "HOME=$HOME  _topdir=$(rpmbuild --eval '%{_topdir}')"
          make -f .copr/Makefile srpm outdir=/tmp/srpm-mock
          ls -1 /tmp/srpm-mock

      # The SRPM's name encodes the version rpm actually resolved, so this closes the loop
      # between the text copr_check.py reads and the artifact the build produced.
      - name: Verify the SRPM matches the version the spec pins
        shell: bash
        run: |
          set -euo pipefail
          version=$(sed -n 's/^Version:[[:space:]]*//p' packaging/copr/retch.spec | head -1)
          # find -print -quit, never `ls | head`: under pipefail a producer killed by SIGPIPE
          # makes the pipeline fail, so that idiom reports "not found" precisely when it
          # matched. The aur job's man-page step went red on a correct package for exactly
          # this reason; see NOTES.md.
          srpm=$(find /tmp/srpm-mock -maxdepth 1 -name '*.src.rpm' -print -quit)
          if [ -z "$srpm" ]; then
            echo "::error::no .src.rpm was produced"
            ls -la /tmp/srpm-mock || true
            exit 1
          fi
          echo "spec Version: $version"
          echo "built:        $(basename "$srpm")"
          case "$(basename "$srpm")" in
            retch-"$version"-*.src.rpm) ;;
            *)
              echo "::error::SRPM name does not carry the spec's Version ($version)"
              exit 1
              ;;
          esac
          echo "SRPM matches the pinned version"

  # The macOS half of packaging verification. The other two packaging targets are verified
  # on Linux runners; a Homebrew formula can only be exercised where Homebrew runs.
  #
  # WHAT THIS BUYS OVER `just brew-check`
  # --------------------------------------
  # brew-check is the cheap, offline half wired into `just check`: it proves the formula's
  # fields agree with the PKGBUILD, the COPR spec and Cargo.toml. It cannot prove the
  # formula BUILDS, that the man page lands, or that completions generate — and an
  # unbuildable formula fails only on a user's machine. This job is that expensive half,
  # the same division of labour the `aur` job has against `aur_check.py`.
  brew:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v7.0.1

      # Offline consistency first: if the fields are wrong there is no point spending
      # several minutes on a build that pins the wrong tarball.
      - name: Formula consistency (offline)
        run: python3 scripts/brew_check.py --self-test && python3 scripts/brew_check.py

      - name: Ruby syntax
        run: ruby -c packaging/homebrew/retch.rb

      # The declared sha256 is verified against the tarball that will actually be
      # downloaded, BEFORE the build patches anything — the same check the `aur` job makes,
      # and for the same reason: a formula can name the right version and carry a wrong
      # hash, which fails only for the person installing it.
      #
      # When the pinned tag is not published yet (a branch that has bumped past the last
      # release) this emits a notice and passes, rather than going red for a legitimate
      # state.
      - name: Verify declared sha256 against the real tarball
        run: |
          set -euo pipefail
          VER=$(sed -n 's|.*/refs/tags/v\([0-9.]*\)\.tar\.gz.*|\1|p' packaging/homebrew/retch.rb | head -1)
          DECLARED=$(sed -n 's/^  sha256 "\(.*\)"/\1/p' packaging/homebrew/retch.rb)
          URL="https://github.com/l1a/retch/archive/refs/tags/v${VER}.tar.gz"
          echo "formula pins v$VER, sha256 $DECLARED"
          if ! curl -sfIL -o /dev/null "$URL"; then
            echo "::notice::v$VER is not published yet — skipping the checksum comparison"
            exit 0
          fi
          curl -sfL -o /tmp/src.tar.gz "$URL"
          ACTUAL=$(shasum -a 256 /tmp/src.tar.gz | cut -d' ' -f1)
          echo "actual sha256 $ACTUAL"
          [ "$ACTUAL" = "$DECLARED" ] || { echo "::error::checksum mismatch for v$VER"; exit 1; }

      # The formula has to be installed THROUGH A TAP, not from a path.
      #
      # `brew install ./packaging/homebrew/retch.rb` is the obvious thing to write and
      # modern Homebrew rejects it outright: "Homebrew requires formulae to be in a tap".
      # So this creates a throwaway local tap and installs from there.
      #
      # **THIS IS NOT QUITE THE PATH A USER TAKES, and the difference matters.** Homebrew
      # 6.0 added a trust gate for third-party taps: `brew tap l1a/retch` refuses to load
      # the formula until `brew trust l1a/retch` has been run, and the error it gives is
      # actively misleading ("Cannot tap l1a/retch: invalid syntax in tap!" for a formula
      # whose syntax is fine). A tap created locally with `tap-new` bypasses that gate, so
      # **this job cannot and does not prove the trust step is unnecessary** — it proves
      # the formula builds, installs and works. The trust requirement is a documentation
      # problem, handled in README.md and the wiki.
      #
      # A local tap is still the right thing to test here: it exercises THIS PR's formula,
      # where tapping the published l1a/retch would test whatever is already released.
      #
      # `--no-git` because the tap is discarded with the runner; there is nothing to commit.
      - name: Stage the formula in a local tap
        run: |
          set -euo pipefail
          brew tap-new --no-git local/test
          cp packaging/homebrew/retch.rb "$(brew --repository local/test)/Formula/retch.rb"
          echo "staged at $(brew --repository local/test)/Formula/retch.rb"

      # The real test. --build-from-source because there is no bottle, and there is
      # deliberately no bottle (see the formula's own comment block).
      - name: Install from source
        run: brew install --build-from-source local/test/retch

      # `brew test` runs the formula's own `test do` block: the binary runs, reports the
      # version the formula claims, can actually probe the machine, and the man page is
      # installed with a real version footer rather than a `$DATE` placeholder.
      - name: Run the formula's test block
        run: brew test local/test/retch

      # Style and correctness lint. Deliberately AFTER the install and test steps so the
      # log distinguishes "the formula does not work" from "the formula is untidy" — an
      # audit-rule change upstream can redden this for a formula that still installs
      # perfectly, and that should not look like a build failure.
      #
      # `--strict` is what flagged the redundant `shells:` argument this step was added
      # for. Note `brew audit` is also what broke the development machine's Homebrew when
      # its output was piped through `head`: the truncation SIGPIPE-killed a native gem
      # build mid-install. Nothing here pipes it.
      - name: Audit the formula
        run: brew audit --formula --strict local/test/retch

      # Assert the payload directly as well, rather than trusting the test block alone —
      # the `aur` job inspects its packaged man page for the same reason.
      - name: Inspect the installed payload
        run: |
          set -euo pipefail
          PREFIX=$(brew --prefix local/test/retch)
          echo "prefix: $PREFIX"
          test -x "$PREFIX/bin/retch"
          "$PREFIX/bin/retch" --version
          # The man page must exist and must NOT carry the literal-$ footer defect the AUR
          # package shipped for months.
          MAN=$(find "$PREFIX/share/man/man1" -name 'retch.1*' -print -quit)
          [ -n "$MAN" ] || { echo "::error::no man page installed"; exit 1; }
          case "$MAN" in *.gz) gunzip -c "$MAN" > /tmp/retch.1 ;; *) cp "$MAN" /tmp/retch.1 ;; esac
          head -1 /tmp/retch.1
          grep -q '^\.TH' /tmp/retch.1 || { echo "::error::man page has no .TH line"; exit 1; }
          if grep -m1 '^\.TH' /tmp/retch.1 | grep -q '\$'; then
            echo "::error::man page .TH contains a literal \$ — the v0.7.0 footer defect"; exit 1
          fi
          # Completions for all three shells the formula generates.
          #
          # NOTE THE BASH PATH. Homebrew's `bash_completion` is `etc/bash_completion.d`,
          # NOT the freedesktop `share/bash-completion/completions` that the AUR and COPR
          # packages install into. Asserting the freedesktop path reports the completion
          # missing on a package that installs it perfectly well — which is what the first
          # version of this step did.
          MISSING=0
          for f in "$PREFIX/etc/bash_completion.d/retch" \
                   "$PREFIX/share/zsh/site-functions/_retch" \
                   "$PREFIX/share/fish/vendor_completions.d/retch.fish"; do
            if [ -s "$f" ]; then
              echo "  ok  $f ($(wc -c < "$f" | tr -d ' ') bytes)"
            else
              echo "::error::missing or empty completion: $f"
              MISSING=1
            fi
          done
          # Print what IS there before failing. An assertion about a built artefact that
          # does not say what it actually saw costs a whole round trip to diagnose — the
          # lesson from the `aur` job's zipman failure (v0.7.0).
          if [ "$MISSING" -ne 0 ]; then
            echo "--- everything actually installed under the prefix ---"
            find "$PREFIX" -type f | sed "s|^$PREFIX/||" | sort
            exit 1
          fi
          echo "payload verified: binary, man page, three completion files"