fix(alpine): build R with cairo, png, jpeg and tiff graphics devices

The Alpine builder images install R-dev but never the graphics headers.
R's configure treats those as optional and does not fail when they are
absent, so the build succeeds and ships an R whose capabilities() reports
cairo, png, jpeg and tiff as FALSE. Installing the runtime libraries on
the target system afterwards cannot bring compiled-out devices back.

Note that --with-x=no was not the cause. R's bitmap and pangocairo checks
run independently of R_X11, and libpng was in fact found. capabilities("png")
needs a device backend, and with X11 off and cairo absent there was none,
which is why all four read FALSE. X11 stays off: these are headless images
and cairo covers png()/jpeg()/tiff()/svg().

- Install pkgconf, cairo-dev, pango-dev, fontconfig-dev, freetype-dev,
  libpng-dev, jpeg-dev, tiff-dev and zlib-dev in every Alpine builder image.
- Pass --with-cairo, --with-libpng, --with-jpeglib and --with-libtiff
  explicitly so the intent is visible next to --with-x=no.
- Assert REQUIRED_CAPABILITIES after make install, so a build that loses a
  device fails instead of being packaged and uploaded. Opt-in per Dockerfile,
  leaving the other platforms untouched.
- Add a FORCE_REBUILD escape hatch to the dedup step. Artifact filenames
  carry only the R version, so the HEAD probe would otherwise keep skipping
  every Alpine version and serving the stale broken binaries.
- Record the three gotchas in CLAUDE.md.

Verified by compiling R 4.5.1 in the patched alpine-322 image: jpeg, png,
tiff and cairo are TRUE, default bitmapType is cairo, and all four devices
render. The guard was exercised in both directions against that build.

builder/Dockerfile.alpine-320

@@ -5,6 +5,13 @@ ENV OS_IDENTIFIER alpine-320
 RUN set -x \
   && apk add -q R-dev curl ca-certificates bash g++ tzdata openjdk17 texmf-dist texlive-full tar sed patch tcl tk tk-dev xvfb libdeflate libdeflate-dev
 
+# Graphics devices. R's configure only enables the cairo/png/jpeg/tiff devices
+# when the corresponding headers are present at compile time, and pkgconf must
+# exist for the pangocairo check to run at all. Without these, capabilities()
+# reports cairo/png/jpeg/tiff as FALSE, and installing the runtime libraries
+# afterwards cannot bring the compiled-out devices back.
+RUN apk add -q pkgconf cairo-dev pango-dev fontconfig-dev freetype-dev libpng-dev jpeg-dev tiff-dev zlib-dev
+
 # Install s5cmd for S3 uploads (much faster than AWS CLI)
 RUN ARCH=$(uname -m); if [ "$ARCH" = "x86_64" ]; then S5CMD_ARCH="64bit"; else S5CMD_ARCH="arm64"; fi && \
     curl -sL "https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-${S5CMD_ARCH}.tar.gz" | tar xz -C /usr/local/bin s5cmd
@@ -18,7 +25,12 @@ RUN chmod 0777 /opt
 # Override the default pager used by R
 ENV PAGER /usr/bin/pager
 
-ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-blas --with-lapack"
+# X11 stays off: these are headless images, and the cairo/bitmap devices are
+# detected independently of X11, so png()/svg() still work via cairo.
+ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-cairo --with-libpng --with-jpeglib --with-libtiff --with-blas --with-lapack"
+
+# Fail the build if a graphics device silently drops out again.
+ENV REQUIRED_CAPABILITIES "cairo,png,jpeg,tiff"
 
 COPY package.alpine-320 /package.sh
 COPY build.sh .

builder/Dockerfile.alpine-321

@@ -5,6 +5,13 @@ ENV OS_IDENTIFIER alpine-321
 RUN set -x \
   && apk add -q R-dev curl ca-certificates bash g++ tzdata openjdk17 texmf-dist texlive-full tar sed patch tcl tk tk-dev xvfb libdeflate libdeflate-dev
 
+# Graphics devices. R's configure only enables the cairo/png/jpeg/tiff devices
+# when the corresponding headers are present at compile time, and pkgconf must
+# exist for the pangocairo check to run at all. Without these, capabilities()
+# reports cairo/png/jpeg/tiff as FALSE, and installing the runtime libraries
+# afterwards cannot bring the compiled-out devices back.
+RUN apk add -q pkgconf cairo-dev pango-dev fontconfig-dev freetype-dev libpng-dev jpeg-dev tiff-dev zlib-dev
+
 # Install s5cmd for S3 uploads (much faster than AWS CLI)
 RUN ARCH=$(uname -m); if [ "$ARCH" = "x86_64" ]; then S5CMD_ARCH="64bit"; else S5CMD_ARCH="arm64"; fi && \
     curl -sL "https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-${S5CMD_ARCH}.tar.gz" | tar xz -C /usr/local/bin s5cmd
@@ -18,7 +25,12 @@ RUN chmod 0777 /opt
 # Override the default pager used by R
 ENV PAGER /usr/bin/pager
 
-ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-blas --with-lapack"
+# X11 stays off: these are headless images, and the cairo/bitmap devices are
+# detected independently of X11, so png()/svg() still work via cairo.
+ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-cairo --with-libpng --with-jpeglib --with-libtiff --with-blas --with-lapack"
+
+# Fail the build if a graphics device silently drops out again.
+ENV REQUIRED_CAPABILITIES "cairo,png,jpeg,tiff"
 
 COPY package.alpine-321 /package.sh
 COPY build.sh .

builder/Dockerfile.alpine-322

@@ -5,6 +5,13 @@ ENV OS_IDENTIFIER alpine-322
 RUN set -x \
   && apk add -q R-dev curl ca-certificates bash g++ tzdata openjdk17 texmf-dist texlive-full tar sed patch tcl tk tk-dev xvfb libdeflate libdeflate-dev
 
+# Graphics devices. R's configure only enables the cairo/png/jpeg/tiff devices
+# when the corresponding headers are present at compile time, and pkgconf must
+# exist for the pangocairo check to run at all. Without these, capabilities()
+# reports cairo/png/jpeg/tiff as FALSE, and installing the runtime libraries
+# afterwards cannot bring the compiled-out devices back.
+RUN apk add -q pkgconf cairo-dev pango-dev fontconfig-dev freetype-dev libpng-dev jpeg-dev tiff-dev zlib-dev
+
 # Install s5cmd for S3 uploads (much faster than AWS CLI)
 RUN ARCH=$(uname -m); if [ "$ARCH" = "x86_64" ]; then S5CMD_ARCH="64bit"; else S5CMD_ARCH="arm64"; fi && \
     curl -sL "https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-${S5CMD_ARCH}.tar.gz" | tar xz -C /usr/local/bin s5cmd
@@ -18,7 +25,12 @@ RUN chmod 0777 /opt
 # Override the default pager used by R
 ENV PAGER /usr/bin/pager
 
-ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-blas --with-lapack"
+# X11 stays off: these are headless images, and the cairo/bitmap devices are
+# detected independently of X11, so png()/svg() still work via cairo.
+ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-cairo --with-libpng --with-jpeglib --with-libtiff --with-blas --with-lapack"
+
+# Fail the build if a graphics device silently drops out again.
+ENV REQUIRED_CAPABILITIES "cairo,png,jpeg,tiff"
 
 COPY package.alpine-322 /package.sh
 COPY build.sh .

builder/Dockerfile.alpine-323

@@ -5,6 +5,13 @@ ENV OS_IDENTIFIER alpine-323
 RUN set -x \
   && apk add -q R-dev curl ca-certificates bash g++ tzdata openjdk17 texmf-dist texlive-full tar sed patch tcl tk tk-dev xvfb libdeflate libdeflate-dev
 
+# Graphics devices. R's configure only enables the cairo/png/jpeg/tiff devices
+# when the corresponding headers are present at compile time, and pkgconf must
+# exist for the pangocairo check to run at all. Without these, capabilities()
+# reports cairo/png/jpeg/tiff as FALSE, and installing the runtime libraries
+# afterwards cannot bring the compiled-out devices back.
+RUN apk add -q pkgconf cairo-dev pango-dev fontconfig-dev freetype-dev libpng-dev jpeg-dev tiff-dev zlib-dev
+
 # Install s5cmd for S3 uploads (much faster than AWS CLI)
 RUN ARCH=$(uname -m); if [ "$ARCH" = "x86_64" ]; then S5CMD_ARCH="64bit"; else S5CMD_ARCH="arm64"; fi && \
     curl -sL "https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-${S5CMD_ARCH}.tar.gz" | tar xz -C /usr/local/bin s5cmd
@@ -18,7 +25,12 @@ RUN chmod 0777 /opt
 # Override the default pager used by R
 ENV PAGER /usr/bin/pager
 
-ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-blas --with-lapack"
+# X11 stays off: these are headless images, and the cairo/bitmap devices are
+# detected independently of X11, so png()/svg() still work via cairo.
+ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-cairo --with-libpng --with-jpeglib --with-libtiff --with-blas --with-lapack"
+
+# Fail the build if a graphics device silently drops out again.
+ENV REQUIRED_CAPABILITIES "cairo,png,jpeg,tiff"
 
 COPY package.alpine-322 /package.sh
 COPY build.sh .

builder/Dockerfile.alpine-324

@@ -5,6 +5,13 @@ ENV OS_IDENTIFIER alpine-324
 RUN set -x \
   && apk add -q R-dev curl ca-certificates bash g++ tzdata openjdk17 texmf-dist texlive-full tar sed patch tcl tk tk-dev xvfb libdeflate libdeflate-dev
 
+# Graphics devices. R's configure only enables the cairo/png/jpeg/tiff devices
+# when the corresponding headers are present at compile time, and pkgconf must
+# exist for the pangocairo check to run at all. Without these, capabilities()
+# reports cairo/png/jpeg/tiff as FALSE, and installing the runtime libraries
+# afterwards cannot bring the compiled-out devices back.
+RUN apk add -q pkgconf cairo-dev pango-dev fontconfig-dev freetype-dev libpng-dev jpeg-dev tiff-dev zlib-dev
+
 # Install s5cmd for S3 uploads (much faster than AWS CLI)
 RUN ARCH=$(uname -m); if [ "$ARCH" = "x86_64" ]; then S5CMD_ARCH="64bit"; else S5CMD_ARCH="arm64"; fi && \
     curl -sL "https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-${S5CMD_ARCH}.tar.gz" | tar xz -C /usr/local/bin s5cmd
@@ -18,7 +25,12 @@ RUN chmod 0777 /opt
 # Override the default pager used by R
 ENV PAGER /usr/bin/pager
 
-ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-blas --with-lapack"
+# X11 stays off: these are headless images, and the cairo/bitmap devices are
+# detected independently of X11, so png()/svg() still work via cairo.
+ENV CONFIGURE_OPTIONS "--enable-R-shlib --with-tcltk --enable-memory-profiling --with-x=no --with-cairo --with-libpng --with-jpeglib --with-libtiff --with-blas --with-lapack"
+
+# Fail the build if a graphics device silently drops out again.
+ENV REQUIRED_CAPABILITIES "cairo,png,jpeg,tiff"
 
 COPY package.alpine-324 /package.sh
 COPY build.sh .

builder/build.sh

@@ -209,6 +209,47 @@ local({
 EOF
 }
 
+# verify_capabilities()
+# Guard against a graphics device being silently compiled out. R's configure
+# only enables the cairo/png/jpeg/tiff devices when the matching headers were
+# present at compile time, and it does not fail when they are missing, so a
+# missing -dev package produces a working R that simply cannot draw. Once that
+# tarball is published, installing the runtime libraries on the target system
+# cannot bring the devices back; the build has to be redone.
+#
+# Dockerfiles opt in by setting REQUIRED_CAPABILITIES to a comma-separated list
+# of capabilities() names, e.g. "cairo,png,jpeg,tiff".
+verify_capabilities() {
+  if [ -z "${REQUIRED_CAPABILITIES}" ]; then
+    return 0
+  fi
+
+  echo "Verifying required R capabilities: ${REQUIRED_CAPABILITIES}"
+
+  # The full capabilities() table goes to stderr so it shows up in the build
+  # log; stdout carries only the space-separated list of missing entries.
+  local missing
+  missing=$("${R_INSTALL_PATH}/bin/Rscript" --vanilla -e '
+    required <- trimws(strsplit(Sys.getenv("REQUIRED_CAPABILITIES"), ",")[[1]])
+    required <- required[nzchar(required)]
+    caps <- capabilities()
+    writeLines(capture.output(print(caps)), con = stderr())
+    ok <- (required %in% names(caps)) & (unname(caps[required]) %in% TRUE)
+    cat(paste(required[!ok], collapse = " "), "\n", sep = "")
+  ') || {
+    echo "ERROR: could not query capabilities() from the freshly built R" >&2
+    return 1
+  }
+
+  if [ -n "${missing}" ]; then
+    echo "ERROR: R ${R_VERSION} for ${OS_IDENTIFIER} is missing required capabilities: ${missing}" >&2
+    echo "ERROR: install the matching -dev packages in builder/Dockerfile.${OS_IDENTIFIER} and rebuild." >&2
+    return 1
+  fi
+
+  echo "All required capabilities are present."
+}
+
 # check for packager script
 ## If it exists this build is ready for packaging with nFPM, so run the script
 ## else do nothing
@@ -236,6 +277,7 @@ set_up_environment
 fetch_r_source $R_VERSION
 patch_r $R_VERSION
 compile_r $R_VERSION
+verify_capabilities
 package_r $R_VERSION
 archive_r
 upload_r $R_VERSION