first pass at linux+macos+wsl support

.gitignore

@@ -55,3 +55,6 @@ downloads/
 
 # Rust build artifacts
 target/
+
+# the local build cache folder
+**/.cache/

docs/bash.md

@@ -97,6 +97,8 @@ WORKER_COUNT="${WORKER_COUNT:-1}"
 DEBUG="${DEBUG:-false}"
 ```
 
+Note: The test framework uses `get_cpu_count()` from `lib/lib-host-os.sh` for cross-platform CPU detection (macOS uses `sysctl`, Linux/WSL uses `nproc`).
+
 **snake_case** for:
 - Local variables
 - Function parameters
@@ -132,7 +134,7 @@ Use parameter expansion for defaults:
 IMAGES_YAML="${IMAGES_YAML:-./images.yaml}"
 
 # Command substitution default
-WORKER_COUNT="${WORKER_COUNT:-$(nproc 2>/dev/null || echo 4)}"
+WORKER_COUNT="${WORKER_COUNT:-$(get_cpu_count)}"
 
 # Empty string default (variable may not be set)
 TEST_IGNORE="${TEST_IGNORE:-}"
@@ -918,7 +920,7 @@ done
 
 **Pattern**:
 ```bash
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 run_test() {
   local index="${1}"
@@ -976,7 +978,7 @@ seq 0 $((TEST_COUNT - 1)) | xargs -P "${WORKER_COUNT}" -I {} bash -c 'run_test {
 **Alternative pattern** using bash job control:
 
 ```bash
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 for ((i=0; i<TEST_COUNT; i++)); do
   # Run in background
@@ -1034,7 +1036,7 @@ wait  # Wait for all background jobs
 **2. Resource Limits**:
 ```bash
 # Respect system resources
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 # Or limit explicitly
 WORKER_COUNT=4

docs/overall-flow.md

@@ -178,8 +178,8 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 
 4. Set test-specific defaults:
    - **Perf**: `ITERATIONS=10`, `UPLOAD_BYTES=1GB`, `DOWNLOAD_BYTES=1GB`
-   - **Transport**: `WORKER_COUNT=$(nproc)`
-   - **Hole-Punch**: `WORKER_COUNT=$(nproc)`
+   - **Transport**: `WORKER_COUNT=$(get_cpu_count)` (from lib-host-os.sh)
+   - **Hole-Punch**: `WORKER_COUNT=$(get_cpu_count)` (from lib-host-os.sh)
 
 **Code Location**:
 - `perf/run.sh:88-207`
@@ -674,6 +674,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 
    b. **Parallel** (transport, hole-punch with WORKER_COUNT>1):
    ```bash
+   WORKER_COUNT=$(get_cpu_count)  # From lib-host-os.sh
    for ((i=0; i<TEST_COUNT; i++)); do
      bash "${SCRIPT_DIR}/run-single-test.sh" "$i" "tests" "$RESULTS_FILE" &
 
@@ -1061,7 +1062,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 ### Transport Tests
 
 **Unique Characteristics**:
-- Parallel execution (WORKER_COUNT=$(nproc))
+- Parallel execution (WORKER_COUNT=$(get_cpu_count))
 - Browser implementations (dialOnly)
 - GitHub sources with patches
 - Simple pass/fail (no measurements)
@@ -1074,7 +1075,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 ### Hole-Punch Tests
 
 **Unique Characteristics**:
-- Parallel execution (WORKER_COUNT=$(nproc))
+- Parallel execution (WORKER_COUNT=$(get_cpu_count))
 - 5-container topology per test
 - Unique subnets per test (NAT simulation)
 - DCUtR protocol measurements
@@ -1131,7 +1132,7 @@ These stop the entire run:
 
 ### Parallel Execution
 
-- **Transport/Hole-Punch**: WORKER_COUNT=$(nproc) for fast execution
+- **Transport/Hole-Punch**: WORKER_COUNT=$(get_cpu_count) for fast execution (from lib-host-os.sh)
 - **Perf**: WORKER_COUNT=1 for accurate measurements
 
 ### Network Isolation

hole-punch/README.md

@@ -110,7 +110,17 @@ Check dependencies:
 ./run.sh --check-deps
 ```
 
-Required: bash 4.0+, docker 20.10+, yq 4.0+, wget, unzip
+**Required dependencies**:
+- bash 4.0+
+- docker 20.10+ (with daemon running)
+- yq 4.0+
+- git 2.0+
+- docker compose (plugin or standalone)
+- Standard UNIX utilities (see [lib/check-dependencies.sh](../lib/check-dependencies.sh) for complete list)
+
+**Optional dependencies** (for advanced features):
+- gnuplot 5.0+ (for performance charts)
+- pandoc (for HTML report generation)
 
 ### Basic Usage
 
@@ -134,7 +144,7 @@ Required: bash 4.0+, docker 20.10+, yq 4.0+, wget, unzip
 ### Parallel Execution
 
 Hole-punch tests run in **parallel** (like transport tests):
-- Default workers: `$(nproc)` (number of CPU cores)
+- Default workers: `$(get_cpu_count)` from lib-host-os.sh (cross-platform CPU detection)
 - Override with `--workers N`
 - Tests execute concurrently for faster completion
 - Each test creates isolated Docker networks to avoid collisions

hole-punch/images/linux/run.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Linux NAT Router Configuration Script
 # Configures iptables-based NAT between LAN and WAN networks
 

hole-punch/images/rust/v0.56/run-peer.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e
 
 # Set route to relay subnet

hole-punch/images/rust/v0.56/run-relay.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e
 
 # Set route to dialer subnet

hole-punch/lib/generate-dashboard.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Generate results.md dashboard from results.yaml
 
 set -euo pipefail

hole-punch/lib/generate-tests.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Generate test matrix from images.yaml with filtering
 # Outputs test-matrix.yaml with content-addressed caching
 # Permutations: dialer × listener × transport × secureChannel × muxer × relay × dialer_router × listener_router
@@ -12,6 +12,7 @@ trap 'echo "ERROR in generate-tests.sh at line $LINENO: Command exited with stat
 # Source common libraries
 source "${SCRIPT_LIB_DIR}/lib-filter-engine.sh"
 source "${SCRIPT_LIB_DIR}/lib-generate-tests.sh"
+source "${SCRIPT_LIB_DIR}/lib-host-os.sh"
 source "${SCRIPT_LIB_DIR}/lib-image-building.sh"
 source "${SCRIPT_LIB_DIR}/lib-image-naming.sh"
 source "${SCRIPT_LIB_DIR}/lib-output-formatting.sh"
@@ -422,8 +423,8 @@ echo ""
 main_tests=()
 ignored_main_tests=()
 
-# Determine worker count (from environment, defaults to nproc)
-WORKER_COUNT="${WORKER_COUNT:-$(nproc 2>/dev/null || echo 4)}"
+# Determine worker count (from environment, defaults to hardware cpu count)
+WORKER_COUNT="${WORKER_COUNT:-$(get_cpu_count)}"
 
 # Worker function to generate tests for a chunk of dialers
 # Args: worker_id dialer_id1 dialer_id2 ...

hole-punch/lib/run-single-test.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run a single hole punch test using docker compose
 
 set -euo pipefail

hole-punch/run.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 # run in strict failure mode
 set -euo pipefail
@@ -65,7 +65,7 @@ else
 fi
 
 # Append actual command-line args (these override inputs.yaml)
-CMD_LINE_ARGS=("${YAML_ARGS[@]}" "$@")
+CMD_LINE_ARGS=(${YAML_ARGS[@]+"${YAML_ARGS[@]}"} "$@")
 
 # Set positional parameters to merged args
 set -- "${CMD_LINE_ARGS[@]}"
@@ -204,10 +204,10 @@ Examples:
 
 Dependencies:
   Required: bash 4.0+, docker 20.10+ (or podman), docker-compose, yq 4.0+
-            wget, zip, unzip, tar, gzip, bc, sha256sum, cut, timeout, flock
+            wget, zip, unzip, bc, sha256sum, cut, timeout, flock
             Text utilities: awk, sed, grep, sort, head, tail, wc, tr, paste, cat
             File utilities: mkdir, cp, mv, rm, chmod, find, xargs, basename, dirname, mktemp
-            System utilities: date, sleep, nproc, uname, hostname, ps
+            System utilities: date, sleep, uname, hostname, ps
   Optional: gnuplot (box plots), git (submodule-based builds)
   Run with --check-deps to verify installation.
 
@@ -546,6 +546,18 @@ yq eval '.tests[].relay.id' "${TEST_PASS_DIR}/test-matrix.yaml" 2>/dev/null | so
 sort -u "${REQUIRED_IMAGES}" -o "${REQUIRED_IMAGES}"
 IMAGE_COUNT=$(wc -l < "${REQUIRED_IMAGES}")
 
+# Exit early if no tests were selected
+if [ "${TOTAL_TESTS}" -eq 0 ]; then
+  println
+  print_error "No tests selected with current filters"
+  indent
+  print_message "All tests were filtered out by your selection criteria."
+  print_message "Adjust your --test-select or --test-ignore settings to select tests."
+  unindent
+  println
+  exit 0
+fi
+
 # Prompt for confirmation unless auto-approved
 indent
 if [ "${AUTO_YES}" != true ]; then
@@ -696,7 +708,7 @@ FAILED=${FAILED:-0}
 cat > "${TEST_PASS_DIR}/results.yaml" <<EOF
 metadata:
   testPass: ${TEST_PASS_NAME}
-  startedAt: $(date -d @"${TEST_START_TIME}" -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -r "${TEST_START_TIME}" -u +%Y-%m-%dT%H:%M:%SZ)
+  startedAt: $(format_timestamp "${TEST_START_TIME}")
   completedAt: $(date -u +%Y-%m-%dT%H:%M:%SZ)
   duration: ${TEST_DURATION}s
   platform: $(uname -m)

hole-punch/test-filtering.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test script to debug relay/router filtering
 
 set -euo pipefail

hole-punch/test-pattern-loading.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test how patterns are loaded from CLI arguments
 
 set -euo pipefail

lib/README.md

@@ -110,11 +110,28 @@ local:
 ```
 
 **Checks**:
-- bash 4.0+
-- docker 20.10+
-- yq 4.0+
-- wget, unzip, zip
-- docker compose (detects `docker compose` or `docker-compose`)
+
+The test framework requires the following dependencies, verified by `check-dependencies.sh`:
+
+#### Versioned Tools (minimum versions required)
+- **bash** 4.0+
+- **docker** 20.10+
+- **yq** 4.0+
+- **git** 2.0+
+
+#### Required UNIX Utilities
+Standard utilities checked by the framework:
+- **File operations**: patch, wget, zip, unzip, tar, gzip, cat, mkdir, cp, mv, rm, chmod, find, basename, dirname, mktemp
+- **Text processing**: cut, awk, sed, grep, sort, head, tail, wc, tr, paste
+- **System utilities**: bc, sha256sum, timeout, flock, xargs, date, sleep, uname, hostname, ps
+
+#### Docker Services
+- Docker daemon (must be running)
+- docker compose (either `docker compose` v2 plugin or legacy `docker-compose` command)
+
+#### Optional Tools
+- **gnuplot** 5.0+ (for performance visualization in perf tests)
+- **pandoc** (for HTML report generation)
 
 **Output**:
 - Exports `DOCKER_COMPOSE_CMD` to environment and `/tmp/docker-compose-cmd.txt`
@@ -192,7 +209,7 @@ Initializes standard variables with consistent defaults:
 - `TEST_RUN_DIR=$CACHE_DIR/test-run` - Test run artifacts
 - `TEST_IGNORE=""` - Test ignore filter
 - `TRANSPORT_IGNORE=""`, `SECURE_IGNORE=""`, `MUXER_IGNORE=""` - Dimension filters
-- `WORKER_COUNT=$(nproc)` - Parallel workers
+- `WORKER_COUNT=$(get_cpu_count)` - Parallel workers (from lib-host-os.sh)
 - `DEBUG=false` - Debug mode
 - `CHECK_DEPS=false`, `LIST_IMAGES=false`, `LIST_TESTS=false` - Flags
 - `CREATE_SNAPSHOT=false`, `AUTO_YES=false` - Flags
@@ -855,7 +872,7 @@ The library supports three distinct test suites with different execution models:
   - Baseline comparisons (iperf, HTTPS, QUIC-Go)
 
 ### Transport Tests (Parallel)
-- **Worker Count**: `$(nproc)` (parallel execution for speed)
+- **Worker Count**: `$(get_cpu_count)` (parallel execution for speed, from lib-host-os.sh)
 - **Network**: Single `transport-network` with dynamic IPs
 - **Sections**: `implementations` only
 - **Special Features**:
@@ -864,7 +881,7 @@ The library supports three distinct test suites with different execution models:
   - 40+ implementation variations including browsers
 
 ### Hole-Punch Tests (Parallel)
-- **Worker Count**: `$(nproc)` (parallel execution for speed)
+- **Worker Count**: `$(get_cpu_count)` (parallel execution for speed, from lib-host-os.sh)
 - **Network**: Isolated networks per test (WAN + 2 LANs)
   - WAN: 10.x.x.64/27
   - Dialer LAN: 10.x.x.96/27
@@ -913,7 +930,7 @@ trap handle_shutdown INT
 WORKER_COUNT=1  # Perf must run 1 test at a time
 
 # transport/run.sh, hole-punch/run.sh - Parallel execution
-WORKER_COUNT=$(nproc)  # Use all CPU cores
+WORKER_COUNT=$(get_cpu_count)  # Use all CPU cores (from lib-host-os.sh)
 ```
 
 ### Pattern 2: Build Docker Images
@@ -1040,19 +1057,36 @@ fi
 
 ## Dependencies
 
-### Required System Tools
-- bash 4.0+
-- docker 20.10+
-- yq 4.0+
-- wget
-- unzip, zip
-- git (for GitHub submodules)
-
-### Required Docker
-- Docker daemon running
-- docker compose (v2 plugin or legacy command)
+The test framework requires the following dependencies, verified by `check-dependencies.sh`:
+
+### Versioned Tools (minimum versions required)
+- **bash** 4.0+
+- **docker** 20.10+
+- **yq** 4.0+
+- **git** 2.0+
+
+### Required UNIX Utilities
+Standard utilities checked by the framework:
+- **File operations**: patch, wget, zip, unzip, tar, gzip, cat, mkdir, cp, mv, rm, chmod, find, basename, dirname, mktemp
+- **Text processing**: cut, awk, sed, grep, sort, head, tail, wc, tr, paste
+- **System utilities**: bc, sha256sum, timeout, flock, xargs, date, sleep, uname, hostname, ps
+
+### Docker Services
+- Docker daemon (must be running)
+- docker compose (either `docker compose` v2 plugin or legacy `docker-compose` command)
 - Sufficient disk space for images and caches
 
+### Optional Tools
+- **gnuplot** 5.0+ (for performance visualization in perf tests)
+- **pandoc** (for HTML report generation)
+
+**Verify all dependencies**:
+```bash
+./lib/check-dependencies.sh
+```
+
+The script provides helpful error messages and platform-specific installation instructions for macOS (Homebrew), Linux, and WSL.
+
 ### Environment Variables
 - `CACHE_DIR` - Cache root (default: `/srv/cache`)
 - `TEST_RUN_DIR` - Test run artifacts (default: `$CACHE_DIR/test-run`)

lib/build-single-image.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Thin executor: Builds a single Docker image based on YAML parameters
 # Used by all test suites (transport, perf, hole-punch)