Auto-install pinned Zig toolchain in setup + devcontainer (#33)

The Zig FFI bridge is half of the ABI-FFI standard, but nothing installed
Zig: .tool-versions only lists it (commented), setup.sh stops at `just`,
and the devcontainer's `postCreateCommand: just deps` referenced a `deps`
recipe that did not exist. Unlike the other toolchain pieces, Zig is not
distributed via GitHub releases, so it must come from ziglang.org.

Add scripts/install-zig.sh: an idempotent, fail-soft installer for the
pinned Zig 0.14.0 (arch/OS-aware, uses the system CA store the agent proxy
populates, never --insecure). If ziglang.org is not on the session's egress
allowlist the download 403s and the script exits 0 with an actionable
message, so it never blocks setup or a session.

Wire it in via the two paths the project already uses: a "Step 1b" in
setup.sh (where the template exposes that step), and a new `deps` Justfile
recipe backing the devcontainer postCreateCommand. Once ziglang.org is
allowlisted, future setups and dev containers install Zig automatically.


Claude-Session: https://claude.ai/code/session_019xMKB3T4Vo5FYC7Czx3JSH

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

Justfile

@@ -128,3 +128,9 @@ crg-badge:
       D) color="orange" ;; E) color="red" ;; F) color="critical" ;; \
       *) color="lightgrey" ;; esac; \
     echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)"
+
+# Install dev dependencies (invoked by the devcontainer postCreateCommand).
+# Installs the pinned Zig FFI toolchain, then warms the Cargo cache.
+deps:
+    ./scripts/install-zig.sh
+    cargo fetch

scripts/install-zig.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# install-zig.sh — install the pinned Zig toolchain (the Zig FFI bridge half of
+# the ABI-FFI standard). Idempotent and fail-soft: it never aborts the caller.
+#
+# Egress note: Zig is NOT distributed via GitHub releases, so it is fetched from
+# ziglang.org. Inside a Claude Code session, outbound HTTPS goes through the
+# policy-enforcing agent proxy; github.com is allowlisted by default but
+# ziglang.org must be added explicitly, or this download returns 403. We use the
+# system CA store the proxy already populated — never pass --insecure.
+set -eu
+
+ZIG_VERSION="${ZIG_VERSION:-0.14.0}"
+PREFIX="${ZIG_PREFIX:-/usr/local}"
+
+# Already at the pinned version? Done.
+if command -v zig >/dev/null 2>&1 && [ "$(zig version 2>/dev/null)" = "$ZIG_VERSION" ]; then
+  echo "install-zig: zig $ZIG_VERSION already installed"
+  exit 0
+fi
+
+# Map host arch/OS to Zig's release naming.
+case "$(uname -m)" in
+  x86_64|amd64)   zarch="x86_64" ;;
+  aarch64|arm64)  zarch="aarch64" ;;
+  *) echo "install-zig: unsupported arch $(uname -m); install Zig $ZIG_VERSION manually" >&2; exit 0 ;;
+esac
+case "$(uname -s)" in
+  Linux)   zos="linux" ;;
+  Darwin)  zos="macos" ;;
+  *) echo "install-zig: unsupported OS $(uname -s); install Zig $ZIG_VERSION manually" >&2; exit 0 ;;
+esac
+
+tarball="zig-${zos}-${zarch}-${ZIG_VERSION}.tar.xz"
+url="https://ziglang.org/download/${ZIG_VERSION}/${tarball}"
+dest="${PREFIX}/lib/zig-${ZIG_VERSION}"
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+echo "install-zig: fetching $url"
+if ! curl -fsSL --retry 2 -o "$tmp/$tarball" "$url"; then
+  echo "install-zig: download failed (HTTP error or blocked host)." >&2
+  echo "install-zig: if this is a Claude Code session, add 'ziglang.org' to the" >&2
+  echo "             egress allowlist — github.com is allowed but ziglang.org is not." >&2
+  exit 0   # fail-soft: a missing Zig must not block setup or session start
+fi
+
+mkdir -p "$dest" "${PREFIX}/bin"
+tar -xJf "$tmp/$tarball" -C "$dest" --strip-components=1
+ln -sf "$dest/zig" "${PREFIX}/bin/zig"
+
+if command -v zig >/dev/null 2>&1 && [ "$(zig version 2>/dev/null)" = "$ZIG_VERSION" ]; then
+  echo "install-zig: installed zig $(zig version)"
+else
+  echo "install-zig: installed to ${PREFIX}/bin/zig — ensure ${PREFIX}/bin is on PATH" >&2
+fi

setup.sh

@@ -194,6 +194,15 @@ main() {
     printf "%sStep 1: Install task runner%s\n" "$BOLD" "$RESET"
     install_just || { fail "Cannot proceed without just"; exit 1; }
     printf "\n"
+    # Step 1b: Install the pinned Zig toolchain (the Zig FFI bridge half of the
+    # ABI-FFI standard). Best-effort — see scripts/install-zig.sh.
+    printf "%sStep 1b: Install Zig toolchain%s\n" "$BOLD" "$RESET"
+    if [ -x ./scripts/install-zig.sh ]; then
+        ./scripts/install-zig.sh || warn "Zig install skipped (see scripts/install-zig.sh)"
+    else
+        warn "scripts/install-zig.sh not found — skipping Zig install"
+    fi
+    printf "\n"
 
     # Step 2: Check if we're in the repo directory
     if [ ! -f "Justfile" ] && [ ! -f "justfile" ]; then