Make install.sh sourceable; unit-test its helpers (#23)

install.sh's release-resolution had no automated coverage: e2e installs
a local .deb via CLAUDE_CODE_DEB, skipping the download/parse path.

- Extract release-JSON parsing into a pure asset_url() helper; move the
  install flow into main() behind a CLAUDE_CODE_INSTALL_LIB guard so the
  unit test can source the helpers without running it (curl | bash still
  runs main).
- Add test/install_test.sh: hermetic shUnit2 tests for the helpers (no
  network/apt), exercising the no-match guard under pipefail.
- Split test:fast into an aggregator over test:greatest (the C launcher)
  and test:shunit2; greatest defaults to -v.
- Keep the temp-.deb EXIT trap working under set -u: deb stays
  script-global, since a local would be out of scope when the trap fires.

Seam for verifying the download against the release asset digest (#18),
which reapplies as a sibling asset_digest() helper plus its cases.

Author: gtbuchanan

.github/workflows/ci.yml

@@ -35,8 +35,7 @@ jobs:
         with:
           persist-credentials: false
       - uses: gtbuchanan/tooling/.github/actions/mise-setup@main
-      # -v lists each test by name in the log (default is a compact summary).
-      - run: mise run test:fast -- -v
+      - run: mise run test:fast
 
   # Native arm64 runner (free for public repos) → the aarch64 container runs
   # without QEMU. Split into two jobs so a compile break and an install/behavior

AGENTS.md

@@ -56,7 +56,7 @@ publish the binary; the `.deb` contains no Anthropic bytes.
 
 | Path | Role |
 |---|---|
-| `install.sh` | Single install path. Downloads the latest release `.deb` (or installs a local one via `CLAUDE_CODE_DEB=<path>`), enables `glibc-repo`, `apt install`s it. |
+| `install.sh` | Single install path. Downloads the latest release `.deb` (or installs a local one via `CLAUDE_CODE_DEB=<path>`), enables `glibc-repo`, `apt install`s it. The install flow is in `main` behind a `CLAUDE_CODE_INSTALL_LIB` guard so the unit test can source its pure helpers without running it (and `curl \| bash` still runs `main`). |
 | `package/control` | Metadata. `Depends: bash, curl, jq, python3, glibc-runner, patchelf-glibc`. |
 | `package/postinst` | Settings merge (skip via `CLAUDE_CODE_SKIP_SETTINGS`) + native-path symlink (via `link-native.sh`) + fetch the binary. |
 | `package/postrm` | Removes the fetched binary and the native-path symlink on uninstall. |
@@ -68,9 +68,10 @@ publish the binary; the `.deb` contains no Anthropic bytes.
 | `src/claude-wrapper.c` | The C launcher (`-DBINARY=`/`-DTMPDIR_PATH=`/`-DUNAME_SHIM=` baked in at compile). `claude_wrapper_run()` takes its exec function as a parameter — a seam the unit tests fake. |
 | `src/uname-shim.c` | Freestanding `LD_PRELOAD` `uname()` interposer reporting kernel `5.10.0`, so Bun avoids the `epoll_pwait2` startup segfault (bun#32489). Built by `build-wrapper.sh`, shipped to `lib/claude-code-termux/uname-spoof.so`, preloaded by the launcher. |
 | `test/wrapper_test.c` | Unit tests for the launcher (greatest; recording exec stub). |
+| `test/install_test.sh` | Hermetic unit tests for `install.sh`'s pure helpers (shUnit2; no network/apt). |
 | `test/compat.h` | Test-only `setenv`/`unsetenv` shims for Windows libc; force-included into the test build, never shipped. |
 | `vendor/greatest.h` | Vendored single-header test framework (greatest 1.5.0, ISC; from silentbicycle/greatest). |
-| `vendor/shunit2` | Vendored single-file shell test framework (shUnit2 2.1.9pre, Apache-2.0; pinned to kward/shunit2 master @ `f39734a` — no tagged release since 2.1.8, and master carries the `egrep`→`grep -E` fix we'd otherwise patch). Drives `scripts/e2e.sh`. Carries one local patch (grep `PATCHED FOR TERMUX`; re-apply on bump): `#! /bin/sh` stub scripts → resolve `sh` via PATH (submitted upstream as kward/shunit2#189). |
+| `vendor/shunit2` | Vendored single-file shell test framework (shUnit2 2.1.9pre, Apache-2.0; pinned to kward/shunit2 master @ `f39734a` — no tagged release since 2.1.8, and master carries the `egrep`→`grep -E` fix we'd otherwise patch). Drives `scripts/e2e.sh` and `test/install_test.sh`. Carries one local patch (grep `PATCHED FOR TERMUX`; re-apply on bump): `#! /bin/sh` stub scripts → resolve `sh` via PATH (submitted upstream as kward/shunit2#189). |
 | `scripts/build-wrapper.sh` | Compile the wrapper + uname shim with Termux's clang. |
 | `scripts/build-deb.sh` | Stage + `dpkg-deb --build` → `artifacts/packages/`. |
 | `scripts/compile.sh` | Compile the wrapper + assemble the `.deb`, in a Termux env. |
@@ -94,11 +95,13 @@ hosts and the Linux CI runner.
 - `mise run hk:all` — run the hk hooks over all files (autofixes locally,
   checks in CI). `mise run hk:base [ref]` runs them over files changed from a
   base ref (default `origin/main`). Append `-- -S <step>` to target one step.
-- `mise run test:fast` — fast, host-native unit tests for the C launcher:
-  compiles `src/claude-wrapper.c` with mise's `zig` and runs it directly (no
-  Termux/Docker), in milliseconds. Append `-- -v` for per-test greatest output.
+- `mise run test:fast` — the fast, host-native unit suites (no Termux/Docker,
+  milliseconds); an aggregator over two focused tasks you can also run alone:
+  - `mise run test:greatest` — the C launcher: compiles `src/claude-wrapper.c`
+    with mise's `zig` and runs it directly (defaults to `-v`, per-test names).
+  - `mise run test:shunit2` — `install.sh`'s pure helpers, via shUnit2.
 - `mise run check` — the fast local gate: the hk hooks (`hk:all`) plus
-  the launcher unit tests (`test:fast`). No Docker.
+  the unit suites (`test:fast`). No Docker.
 - `mise run compile [version]` — compile the launcher + assemble the `.deb`
   (→ `artifacts/packages/`), env-aware: `scripts/compile.sh` natively on a Termux
   device, else `scripts/docker-run.sh` (the container) on a dev host.
@@ -133,10 +136,11 @@ The version is passed in by the caller; `build-deb.sh`, `compile.sh`, and
 
 ## Testing locally
 
-Two layers. The launcher's logic (env shaping + the exec handoff) has fast
-**unit tests** that run anywhere via `mise run test:fast` — no Termux, no
-Docker (see Dev environment). The end-to-end behaviors (real binary, dispatch,
-install) need the container, split across two tasks:
+Two layers. Fast **unit tests** for the launcher's logic (env shaping + the exec
+handoff) and for `install.sh`'s pure helpers run anywhere via `mise run
+test:fast` — no Termux, no Docker (see Dev environment). The end-to-end
+behaviors (real binary, dispatch, install) need the container, split across two
+tasks:
 
 `mise run compile` produces the `.deb`, then `mise run test:e2e` installs it via
 `install.sh` and asserts the real fixes: `argv[0]=rg`/`bfs` dispatch to the
@@ -171,8 +175,9 @@ vars **inline** in the `bash -c` string instead.
   the shared `tooling/.github/workflows/pre-commit.yml` reusable (PR-only — the
   reusable diffs against the PR base, so it's skipped on push/schedule
   `workflow_call` invocations); a `unit` job that runs `mise run test:fast`
-  (the launcher unit tests build + run natively via `zig` — no container, fast,
-  arch-independent); plus the `compile` and `e2e` jobs. `compile` runs `mise run
+  (the launcher tests build + run natively via `zig`, the `install.sh` tests via
+  shUnit2 — no container, fast, arch-independent); plus the `compile` and `e2e`
+  jobs. `compile` runs `mise run
   compile` and uploads the `.deb` as an artifact; `e2e` (`needs: compile`)
   downloads it and runs `mise run test:e2e` — so a compile break and an
   install/behavior break surface as distinct job failures. Both go through the

CONTRIBUTING.md

@@ -38,8 +38,9 @@ the generated `hk:*` tasks in `mise.tasks.toml`:
 - `mise run hk:all` — run the hk hooks over all files (autofixes locally, checks
   in CI). `mise run hk:base [ref]` runs them over files changed from a base ref
   (default `origin/main`). Append `-- -S <step>` to target one step.
-- `mise run check` — the fast local gate: the hk hooks plus the C launcher
-  unit tests (`test:fast`). No Docker.
+- `mise run check` — the fast local gate: the hk hooks plus the host-native
+  unit suites (`test:fast` → the C launcher via greatest + `install.sh`'s
+  helpers via shUnit2). No Docker.
 - `mise run compile [version]` — compile the launcher and assemble the `.deb`
   (→ `artifacts/packages/`). `version` is optional; empty derives the local
   CalVer (`scripts/version.sh`, run number `0`).

install.sh

@@ -19,8 +19,6 @@
 # Anthropic's Commercial Terms of Service:
 #   https://www.anthropic.com/legal/commercial-terms
 #
-set -euo pipefail
-
 REPO="gtbuchanan/claude-code-termux"
 API="https://api.github.com/repos/$REPO/releases/latest"
 
@@ -30,39 +28,62 @@ die() {
   exit 1
 }
 
-command -v curl >/dev/null 2>&1 || die "missing 'curl' — pkg install curl"
-command -v apt-get >/dev/null 2>&1 || die "apt-get not found — this installer is for Termux."
-
-deb="${CLAUDE_CODE_DEB:-}"
-if [ -n "$deb" ]; then
-  [ -f "$deb" ] || die "CLAUDE_CODE_DEB not found: $deb"
-  log "Installing local package $deb"
-else
-  log "Resolving the latest release of $REPO…"
-  url=$(curl -fsSL "$API" |
-    grep -oE '"browser_download_url"[[:space:]]*:[[:space:]]*"[^"]*_aarch64\.deb"' |
+# Extract the aarch64 .deb's browser_download_url from GitHub release JSON ($1).
+# grep/sed, not jq: jq is only pulled in later as a package dependency. `|| true`
+# keeps a no-match grep from tripping main's pipefail; main handles the empty.
+asset_url() {
+  printf '%s' "$1" |
+    { grep -oE '"browser_download_url"[[:space:]]*:[[:space:]]*"[^"]*_aarch64\.deb"' || true; } |
     head -1 |
-    sed -E 's/.*"(https[^"]+)"$/\1/')
-  [ -n "$url" ] || die "no aarch64 .deb asset found in the latest release."
+    sed -E 's/.*"(https[^"]+)"$/\1/'
+}
+
+main() {
+  set -euo pipefail
 
-  deb=$(mktemp --suffix=.deb)
-  trap 'rm -f "$deb"' EXIT
-  log "Downloading $url"
-  curl -fsSL "$url" -o "$deb"
-fi
+  command -v curl >/dev/null 2>&1 || die "missing 'curl' — pkg install curl"
+  command -v apt-get >/dev/null 2>&1 || die "apt-get not found — this installer is for Termux."
 
-# glibc-runner and patchelf-glibc live in the glibc-packages repo, which the
-# `glibc-repo` package enables. It must be added (and the index refreshed)
-# BEFORE installing the package — apt resolves the whole dependency graph up
-# front, so a repo added mid-transaction wouldn't be consulted.
-log "Enabling the glibc package repo…"
-apt-get update -y || true
-apt-get install -y glibc-repo
-apt-get update -y
+  # Not `local`: the EXIT trap below fires after main() returns and reads $deb,
+  # which a local would put out of scope (unbound under set -u).
+  deb="${CLAUDE_CODE_DEB:-}"
+  if [ -n "$deb" ]; then
+    [ -f "$deb" ] || die "CLAUDE_CODE_DEB not found: $deb"
+    log "Installing local package $deb"
+  else
+    log "Resolving the latest release of $REPO…"
+    local api url
+    api=$(curl -fsSL "$API") ||
+      die "could not reach the GitHub API (network down or rate limited)."
+    url=$(asset_url "$api")
+    [ -n "$url" ] || die "no aarch64 .deb asset found in the latest release."
 
-# apt reads the package's Depends and pulls glibc-runner, patchelf-glibc, jq,
-# and python3 automatically (dpkg -i would not).
-log "Installing (apt resolves dependencies)…"
-apt-get install -y "$deb"
+    deb=$(mktemp --suffix=.deb)
+    trap 'rm -f -- "$deb"' EXIT
+    log "Downloading $url"
+    curl -fsSL "$url" -o "$deb"
+  fi
+
+  # glibc-runner and patchelf-glibc live in the glibc-packages repo, which the
+  # `glibc-repo` package enables. It must be added (and the index refreshed)
+  # BEFORE installing the package — apt resolves the whole dependency graph up
+  # front, so a repo added mid-transaction wouldn't be consulted.
+  log "Enabling the glibc package repo…"
+  apt-get update -y || true
+  apt-get install -y glibc-repo
+  apt-get update -y
+
+  # apt reads the package's Depends and pulls glibc-runner, patchelf-glibc, jq,
+  # and python3 automatically (dpkg -i would not).
+  log "Installing (apt resolves dependencies)…"
+  apt-get install -y "$deb"
+
+  log "Done. Run 'claude' to start."
+}
 
-log "Done. Run 'claude' to start."
+# Run the installer, unless this file is being sourced by the unit test for its
+# helper functions (which sets CLAUDE_CODE_INSTALL_LIB). A piped `curl … | bash`
+# leaves the var unset — and since BASH_SOURCE is empty in that case the usual
+# "${BASH_SOURCE[0]}" = "$0" guard would wrongly skip the install — so the
+# normal one-liner still runs main.
+[ -n "${CLAUDE_CODE_INSTALL_LIB:-}" ] || main "$@"

mise-tasks/test/fast

@@ -1,42 +1,3 @@
 #!/usr/bin/env bash
-#MISE description="Unit-test the C launcher natively (fast; no Docker)"
-# Keep Git Bash / MSYS from rewriting the leading-slash sentinel paths
-# (BINARY/TMPDIR_PATH/UNAME_SHIM below) into Windows paths on the way to zig
-# (no-op elsewhere).
-#MISE env={ MSYS_NO_PATHCONV = "1" }
-#
-# Compiles src/claude-wrapper.c with zig and runs it directly — no Termux, no
-# Docker, milliseconds. The wrapper is pure POSIX env-shaping plus an injected
-# exec handoff (the seam in claude-wrapper.c), so a native build exercises the
-# real logic.
-#
-#   mise run test:fast [-- greatest args, e.g. -v]
-#
-set -euo pipefail
-
-# Sentinel literals baked into the build so the test can assert the exact
-# path/tmpdir the wrapper bakes in. They need not exist on disk: exec is faked.
-BINARY=/claude-code-termux-test/claude
-TMPDIR_PATH=/claude-code-termux-test/tmp
-UNAME_SHIM=/claude-code-termux-test/uname-spoof.so
-
-out="$MISE_PROJECT_ROOT/artifacts/build"
-mkdir -p "$out"
-
-bin="$out/wrapper_test"
-case "${OSTYPE:-}" in msys* | cygwin* | win*) bin="$bin.exe" ;; esac
-
-# Flags mirror build-wrapper.sh (notably no -std: the default gnu mode exposes
-# POSIX setenv/unsetenv on Linux/macOS, where compat.h is a no-op).
-# -DCLAUDE_WRAPPER_NO_MAIN drops the wrapper's main() (greatest supplies one);
-# -include compat.h shims setenv/unsetenv on Windows.
-zig cc -O2 -Wall -Wextra -Werror \
-  -DBINARY="\"$BINARY\"" -DTMPDIR_PATH="\"$TMPDIR_PATH\"" \
-  -DUNAME_SHIM="\"$UNAME_SHIM\"" \
-  -DCLAUDE_WRAPPER_NO_MAIN \
-  -include "$MISE_PROJECT_ROOT/test/compat.h" \
-  -I "$MISE_PROJECT_ROOT/vendor" \
-  -o "$bin" \
-  "$MISE_PROJECT_ROOT/src/claude-wrapper.c" "$MISE_PROJECT_ROOT/test/wrapper_test.c"
-
-"$bin" "$@"
+#MISE description="Run the fast host-native unit suites (greatest + shUnit2; no Docker)"
+#MISE depends=["test:greatest", "test:shunit2"]

mise-tasks/test/greatest

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#MISE description="Unit-test the C launcher with greatest natively (fast; no Docker)"
+# Keep Git Bash / MSYS from rewriting the leading-slash sentinel paths
+# (BINARY/TMPDIR_PATH/UNAME_SHIM below) into Windows paths on the way to zig
+# (no-op elsewhere).
+#MISE env={ MSYS_NO_PATHCONV = "1" }
+#
+# Compiles src/claude-wrapper.c with zig and runs it directly — no Termux, no
+# Docker, milliseconds. The wrapper is pure POSIX env-shaping plus an injected
+# exec handoff (the seam in claude-wrapper.c), so a native build exercises the
+# real logic.
+#
+#   mise run test:greatest [-- greatest args]   # defaults to -v (per-test names)
+#
+set -euo pipefail
+
+# Sentinel literals baked into the build so the test can assert the exact
+# path/tmpdir the wrapper bakes in. They need not exist on disk: exec is faked.
+BINARY=/claude-code-termux-test/claude
+TMPDIR_PATH=/claude-code-termux-test/tmp
+UNAME_SHIM=/claude-code-termux-test/uname-spoof.so
+
+out="$MISE_PROJECT_ROOT/artifacts/build"
+mkdir -p "$out"
+
+bin="$out/wrapper_test"
+case "${OSTYPE:-}" in msys* | cygwin* | win*) bin="$bin.exe" ;; esac
+
+# Flags mirror build-wrapper.sh (notably no -std: the default gnu mode exposes
+# POSIX setenv/unsetenv on Linux/macOS, where compat.h is a no-op).
+# -DCLAUDE_WRAPPER_NO_MAIN drops the wrapper's main() (greatest supplies one);
+# -include compat.h shims setenv/unsetenv on Windows.
+zig cc -O2 -Wall -Wextra -Werror \
+  -DBINARY="\"$BINARY\"" -DTMPDIR_PATH="\"$TMPDIR_PATH\"" \
+  -DUNAME_SHIM="\"$UNAME_SHIM\"" \
+  -DCLAUDE_WRAPPER_NO_MAIN \
+  -include "$MISE_PROJECT_ROOT/test/compat.h" \
+  -I "$MISE_PROJECT_ROOT/vendor" \
+  -o "$bin" \
+  "$MISE_PROJECT_ROOT/src/claude-wrapper.c" "$MISE_PROJECT_ROOT/test/wrapper_test.c"
+
+# Default to -v (greatest lists each test by name; its bare default is a compact
+# dot summary). Explicit args override — e.g. a `-t <name>` filter.
+"$bin" "${@:--v}"

mise-tasks/test/shunit2

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+#MISE description="Unit-test install.sh's pure helpers with shUnit2 (fast; no Docker)"
+#
+# Sources install.sh under its lib guard and drives its pure helpers via
+# shUnit2 — no network, no apt, no Termux. See test/install_test.sh.
+#
+#   mise run test:shunit2 [-- shUnit2 args, e.g. a test_* name filter]
+set -euo pipefail
+
+exec bash "$MISE_PROJECT_ROOT/test/install_test.sh" "$@"

test/install_test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# Hermetic unit tests for install.sh's pure helpers. Sources install.sh with
+# CLAUDE_CODE_INSTALL_LIB set so its main() does NOT run (no network, no apt),
+# then drives the helpers directly. Runs anywhere via `mise run test:shunit2`
+# — no Termux, no Docker, milliseconds.
+#
+# Built on the vendored shUnit2 (vendor/shunit2): each behavior is a `test_*`
+# function; shUnit2 discovers them and prints the run summary. Like e2e.sh, this
+# deliberately does NOT `set -e` (errexit fights the framework) — and sourcing
+# install.sh under the lib guard skips its `set -euo pipefail` (that lives in
+# main()), so the test shell stays errexit-free.
+
+# Resolve install.sh and vendor/shunit2 against the repo root regardless of cwd.
+cd "$(dirname "$0")/.." || exit 1
+
+# Source the installer for its functions only; the guard keeps main() — and its
+# strict mode — from running.
+# shellcheck source=/dev/null
+CLAUDE_CODE_INSTALL_LIB=1 . ./install.sh
+
+# A release-JSON shape mirroring GitHub's, with a decoy asset before the aarch64
+# .deb so the selector has to discriminate rather than grab the first URL.
+release_json() {
+  cat <<'EOF'
+{
+  "assets": [
+    {
+      "name": "SHA256SUMS",
+      "browser_download_url": "https://github.com/gtbuchanan/claude-code-termux/releases/download/v2026.6.19/SHA256SUMS"
+    },
+    {
+      "name": "claude-code-termux_2026.6.19_aarch64.deb",
+      "browser_download_url": "https://github.com/gtbuchanan/claude-code-termux/releases/download/v2026.6.19/claude-code-termux_2026.6.19_aarch64.deb"
+    }
+  ]
+}
+EOF
+}
+
+test_asset_url_extracts_aarch64_deb() {
+  assertEquals 'picks the aarch64 .deb download URL over a decoy asset' \
+    'https://github.com/gtbuchanan/claude-code-termux/releases/download/v2026.6.19/claude-code-termux_2026.6.19_aarch64.deb' \
+    "$(asset_url "$(release_json)")"
+}
+
+# Run asset_url under pipefail — as main() does — and assert it yields no output
+# AND still exits 0. This is what proves the `|| true` guard: without it, the
+# no-match grep's non-zero status would trip pipefail and abort the install.
+assert_no_match_under_pipefail() { # $1 = message, $2 = release JSON
+  local out rc
+  out="$(
+    set -o pipefail
+    asset_url "$2"
+  )"
+  rc=$?
+  assertEquals "$1" '' "$out"
+  assertEquals "$1 (exits 0 under pipefail)" 0 "$rc"
+}
+
+test_asset_url_empty_when_no_aarch64_deb() {
+  assert_no_match_under_pipefail 'empty when the release has no aarch64 .deb asset' \
+    '{"assets":[{"browser_download_url":"https://example.com/x.txt"}]}'
+}
+
+test_asset_url_empty_on_non_json() {
+  assert_no_match_under_pipefail 'empty on a non-JSON blob' 'this is not json'
+}
+
+# shUnit2 hands control here: it discovers the test_* functions above and prints
+# the summary.
+# shellcheck source=/dev/null
+. ./vendor/shunit2