retch-cli 0.17.6

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 publish packaging/aur (aur-publish / 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 PKGBUILD is rendered for the last released tag
      # and its checksum re-derived from the real tarball, then built 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'
      # The renderer is a stronger instance of the same thing: it does not merely decide
      # whether a packaging file may be committed, it WRITES the files that get published to
      # the AUR, COPR and the Homebrew tap. `scripts/*_check.py` does not match it.
      - 'scripts/render_packaging.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.
          # `python` is needed by scripts/render_packaging.py; base-devel does not include it.
          pacman -Syu --noconfirm git base-devel cargo curl sudo python

      # fetch-depth: 0 because the render step below needs the last RELEASED tag, and the
      # default shallow checkout carries no tags at all.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
        with:
          fetch-depth: 0

      # WHAT THIS REPLACED, AND WHY IT IS STRONGER.
      #
      # This step used to source the committed PKGBUILD and compare its declared sha256
      # against the real tarball. There is no declared sha256 any more: the PKGBUILD is a
      # template, and `scripts/render_packaging.py` supplies the version and checksum at
      # publish time. So instead of checking a committed constant, this performs the publish
      # render for the last released tag and checks THAT -- the same computation
      # `just aur-publish` will do, against the same tarball an AUR user downloads.
      #
      # A wrong committed checksum used to be invisible until someone installed from the AUR.
      # Now a renderer that produces a wrong one fails here, which is the same protection
      # aimed at the thing that can actually be wrong.
      - name: Render the PKGBUILD for the last released tag and verify its checksum
        shell: bash
        run: |
          set -euo pipefail
          git config --global --add safe.directory "$PWD"
          TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
          if [ -z "$TAG" ]; then
            echo "::notice::no tags in this checkout — nothing to render against"
            exit 0
          fi
          V="${TAG#v}"
          URL="https://github.com/l1a/retch/archive/refs/tags/${TAG}.tar.gz"
          echo "last released tag: $TAG"
          if ! curl -fsSL --retry 3 -o /tmp/upstream.tar.gz "$URL"; then
            echo "::notice::$URL is not fetchable — checksum not verifiable at this commit"
            exit 0
          fi
          SHA=$(sha256sum /tmp/upstream.tar.gz | cut -d' ' -f1)
          echo "computed sha256: $SHA"

          python3 scripts/render_packaging.py --target aur --version "$V" --sha256 "$SHA" \
            --out /tmp/PKGBUILD.rendered

          # Read the rendered file back rather than trusting the renderer's exit code: the
          # failure being guarded against is a substitution that silently did not happen,
          # which is exactly what an exit code cannot show (v0.6.13).
          # shellcheck disable=SC1091
          ( cd /tmp && source ./PKGBUILD.rendered
            echo "rendered pkgver:    $pkgver"
            echo "rendered sha256sums: ${sha256sums[0]}"
            [ "$pkgver" = "$V" ] || { echo "::error::rendered pkgver is $pkgver, expected $V"; exit 1; }
            [ "${sha256sums[0]}" = "$SHA" ] || { echo "::error::rendered sha256 does not match the tarball"; exit 1; }
            case "${source[0]}" in
              *"refs/tags/v${V}.tar.gz") ;;
              *) echo "::error::rendered source does not point at refs/tags/v$V"; exit 1 ;;
            esac )
          echo "render verified against the real $TAG tarball"
          rm -f /tmp/upstream.tar.gz

      - name: Build AUR PKGBUILD
        run: |
          set -euo pipefail
          # Create builduser
          useradd -m builduser
          echo "builduser ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers

          # The committed PKGBUILD is a template and makepkg refuses `@` in pkgver, so the
          # local build renders one first. The version is Cargo.toml's (this checkout's), and
          # the checksum is irrelevant because the next step replaces source= with a local
          # tarball -- hence a real-looking but arbitrary digest here, never SKIP in a
          # published file.
          cd packaging/aur
          V=$(python3 ../../scripts/render_packaging.py --print-version)
          python3 ../../scripts/render_packaging.py --target aur --version "$V" \
            --sha256 "$(printf 'local-build-only%s' "$V" | sha256sum | cut -d' ' -f1)" \
            --out PKGBUILD

          # 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-build
          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 version .copr/Makefile rendered and the artifact the build produced.
      #
      # The version comes from Cargo.toml, not from the spec: the spec is a template whose
      # `Version:` is `@VERSION@`, and reading that would compare the artifact against a
      # sentinel. This is also the assertion that proves the render actually happened -- an
      # unrendered spec produces `retch-@VERSION@-1.src.rpm`, which fails here by name.
      - name: Verify the SRPM matches the version the render used
        shell: bash
        run: |
          set -euo pipefail
          version=$(python3 scripts/render_packaging.py --print-version)
          # 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 "Cargo.toml version: $version"
          echo "built:              $(basename "$srpm")"
          case "$(basename "$srpm")" in
            retch-"$version"-*.src.rpm) ;;
            *)
              echo "::error::SRPM name does not carry Cargo.toml's version ($version)"
              exit 1
              ;;
          esac
          echo "SRPM matches the rendered 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 is
  # still a template that records no version and no checksum. It cannot prove the RENDERED
  # 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: it
  # renders for the last released tag and then installs what it rendered, which is the same
  # division of labour the `aur` job has against `aur_check.py`.
  brew:
    runs-on: macos-latest
    steps:
      # fetch-depth: 0 because the render step needs the last RELEASED tag, and the default
      # shallow checkout carries no tags.
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0

      # Offline consistency first: if the template has stopped being one there is no point
      # spending several minutes on a build.
      - name: Formula template is valid (offline)
        run: python3 scripts/brew_check.py --self-test && python3 scripts/brew_check.py

      # THE RENDER IS WHAT IS TESTED FROM HERE ON.
      #
      # The formula in the repo is a template whose `url` and `sha256` are sentinels, so it
      # cannot be installed as it stands. This renders it exactly as `just brew-publish`
      # will -- for the last released tag, with the checksum computed from the tarball a
      # user's `brew install` downloads -- and every later step operates on that output.
      #
      # Rendering for the last RELEASED tag rather than for Cargo.toml's version is
      # deliberate and is also what this job did before: the formula pinned the last
      # release, so the install step has always built released source. Rendering for an
      # in-development version would point at a tag that does not exist.
      - name: Render the formula for the last released tag
        run: |
          set -euo pipefail
          TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
          if [ -z "$TAG" ]; then
            echo "::error::no tags in this checkout — cannot render a formula to install"
            exit 1
          fi
          VER="${TAG#v}"
          URL="https://github.com/l1a/retch/archive/refs/tags/${TAG}.tar.gz"
          echo "last released tag: $TAG"
          curl -sfL -o /tmp/src.tar.gz "$URL" || { echo "::error::cannot fetch $URL"; exit 1; }
          SHA=$(shasum -a 256 /tmp/src.tar.gz | cut -d' ' -f1)
          echo "computed sha256: $SHA"
          python3 scripts/render_packaging.py --target brew --version "$VER" --sha256 "$SHA" \
            --out /tmp/retch.rb
          # Read the output back: a substitution that silently did not happen is the failure
          # an exit code cannot show (v0.6.13).
          grep -q "refs/tags/v${VER}.tar.gz" /tmp/retch.rb \
            || { echo "::error::rendered formula does not point at $TAG"; exit 1; }
          grep -q "sha256 \"${SHA}\"" /tmp/retch.rb \
            || { echo "::error::rendered formula does not carry the computed sha256"; exit 1; }
          echo "RENDERED_VER=$VER" >> "$GITHUB_ENV"
          echo "render verified against the real $TAG tarball"

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

      # 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 /tmp/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"