From 0c575bf34d7d496144ee8b5eeca70d3ff2a52b14 Mon Sep 17 00:00:00 2001 From: ruihan Date: Fri, 30 Oct 2026 04:57:47 -0300 Subject: [PATCH] fix(doctor): expose read-only build and Wi-Fi diagnostics --- README.md | 19 ++++++++++-- examples/build-standalone.sh | 1 + lib/doctor.sh | 51 ++++++++++++++++++++++++++------ tests/test_doctor.bats | 56 ++++++++++++++++++++++++++++++++++++ unleash | 4 ++- unleash-standalone.sh | 55 +++++++++++++++++++++++++++++------ 6 files changed, 165 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 420f732..2b6457e 100644 --- a/README.md +++ b/README.md @@ -447,8 +447,19 @@ You need a user password or the FileVault recovery key. If neither is available, ### "Not a macOS Data volume" Unleash checks for `/private/var/db/dslocal/nodes/Default` on the mounted volume. If it's missing, you mounted the wrong disk. Run `diskutil list` to find the correct one. -### macOS 27 (or future version) -Unleash should work on any macOS version that uses the same MDM enrollment mechanism. If a new macOS changes the enrollment daemons or DEP markers, open an issue. +### macOS 27 and later + +macOS 27 has no recorded passing hardware validation in this project yet. +Compatibility is tracked in [#22](https://github.com/mateussiqueira/unleash/issues/22). +For a compatibility or Wi-Fi report, collect the build and interface state: + +```bash +./unleash doctor --network +``` + +This reads the macOS build, Wi-Fi interface, power, and link status. Include +the script commit, hardware model, and external SSD/hub connection when +reporting an external-volume problem. It does not certify compatibility. ### Monitor won't start Check if it's already running (`monitor-status`). Check permissions — it needs root. Check logs at `/var/log/unleash-monitor.log`. @@ -456,7 +467,9 @@ Check if it's already running (`monitor-status`). Check permissions — it needs ## FAQ **What macOS versions are supported?** -12.x (Monterey) through 15.x (Sequoia), 26.x (Tahoe), and 27.x. Tested on Intel T2, M1, M2, M3, M4, M5. +The existing targets are macOS 12–15 and 26. Validation depends on the command, +OS build, and hardware; macOS 27 remains unverified. Shell regression tests +do not replace testing Recovery, FileVault, and networking on the target Mac. **Do I need to disable SIP?** No. All writes target the Data volume. diff --git a/examples/build-standalone.sh b/examples/build-standalone.sh index f11ce8e..3fd4500 100755 --- a/examples/build-standalone.sh +++ b/examples/build-standalone.sh @@ -9,6 +9,7 @@ cat > "$OUT" << HEADER #!/bin/bash set -euo pipefail VERSION="$VERSION" +STANDALONE_BUILD=true SCRIPT_DIR="\$(cd "\$(dirname "\$0")" && pwd)" SCRIPT_PATH="\$SCRIPT_DIR/\$(basename "\$0")" HEADER diff --git a/lib/doctor.sh b/lib/doctor.sh index d8e9b3d..b754245 100644 --- a/lib/doctor.sh +++ b/lib/doctor.sh @@ -1,22 +1,59 @@ +_network_diagnostics() { + header "Network Diagnostics" + local version=unavailable build=unavailable + if command -v sw_vers &>/dev/null; then + version=$(sw_vers -productVersion 2>/dev/null) || version=unavailable + build=$(sw_vers -buildVersion 2>/dev/null) || build=unavailable + fi + printf 'macOS: %s (build %s)\n' "$version" "$build" + case "$version" in 27.*) warn "macOS 27 hardware compatibility remains unverified (issue #22)." ;; esac + local interface + interface=$(networksetup -listallhardwareports 2>/dev/null | awk ' + /Hardware Port:/ { wifi=($0 ~ /: (Wi-Fi|AirPort)$/); next } + wifi && /^[[:space:]]*Device:/ { print $2; exit } + ' || true) + if [ -z "$interface" ]; then + info "No Wi-Fi hardware port reported." + return 0 + fi + local power status + power=$(networksetup -getairportpower "$interface" 2>/dev/null || true) + case "$power" in *': On') power=on ;; *': Off') power=off ;; *) power=unavailable ;; esac + status=$(ifconfig "$interface" 2>/dev/null | awk '/^[[:space:]]*status:/ {print $2; exit}' || true) + printf 'Wi-Fi interface: %s\nWi-Fi power: %s\nLink status: %s\n' "$interface" "$power" "${status:-unavailable}" +} + run_doctor() { + if [ "${1:-}" = --network ]; then _network_diagnostics; return; fi header "Unleash Doctor — Pre-Flight Check" local errors=0 warnings=0 begin "Script location" - if [ -n "$SCRIPT_DIR" ] && [ -d "$SCRIPT_DIR" ]; then - end_ok; echo " $SCRIPT_DIR" + local script_dir="${SCRIPT_DIR:-}" + if [ -n "$script_dir" ] && [ -d "$script_dir" ]; then + end_ok; echo " $script_dir" else end_fail; errors=$((errors + 1)) fi begin "Library files" local missing=0 - for _lib in colors detect validate dscl suppress backup status heal firewall harden whitelist check monitor history; do - [ -f "$LIB_DIR/$_lib.sh" ] || missing=$((missing + 1)) - done + if [ "${STANDALONE_BUILD:-false}" = true ]; then + local core + for core in log resolve_data_volume validate_username create_admin_user suppress_enrollment backup_state deep_status _launchd_script_path heal_suppress install_pf_mdm_block harden_live_os install_selective_block run_preformat_check monitor_mdm show_history; do + declare -F "$core" >/dev/null || missing=$((missing + 1)) + done + else + local lib_dir="${LIB_DIR:-}" + for _lib in colors detect validate dscl suppress backup status launchd heal firewall harden whitelist check monitor history; do + [ -n "$lib_dir" ] && [ -f "$lib_dir/$_lib.sh" ] || missing=$((missing + 1)) + done + fi if [ "$missing" -eq 0 ]; then - end_ok; echo " 13/13 modules loaded" + end_ok + if [ "${STANDALONE_BUILD:-false}" = true ]; then echo " Embedded core modules loaded"; + else echo " Core library files available"; fi else end_fail; echo " $missing module(s) missing"; errors=$((errors + 1)) fi @@ -38,8 +75,6 @@ run_doctor() { fi begin "Disk space (Data volume)" - local mount_pt - mount_pt=$(df / 2>/dev/null | awk 'NR>1 {print $NF; exit}') local avail avail=$(df / 2>/dev/null | awk 'NR>1 {print $4; exit}') if [ -n "$avail" ] && [ "$avail" -gt 1048576 ]; then diff --git a/tests/test_doctor.bats b/tests/test_doctor.bats index 7a87243..cb389f7 100644 --- a/tests/test_doctor.bats +++ b/tests/test_doctor.bats @@ -18,3 +18,59 @@ setup() { LIB_DIR="$old_dir" echo "$output" | grep -qi "missing\|error" } + +@test "network doctor reports build power and link using only read commands" { + local entrypoint + for entrypoint in unleash unleash-standalone.sh; do + local script="$BATS_TEST_DIRNAME/../$entrypoint" + local definitions="$BATS_TEST_TMPDIR/$entrypoint.functions" + local calls="$BATS_TEST_TMPDIR/$entrypoint.calls" + sed '/^main "\$@"$/d' "$script" > "$definitions" + run "${UNLEASH_TEST_SHELL:-bash}" -u -c ' + source "$1" + calls="$2" + load_config() { :; } + sw_vers() { + echo "sw_vers $*" >> "$calls" + case "$1" in -productVersion) echo 27.0 ;; -buildVersion) echo TESTBUILD ;; *) return 97 ;; esac + } + networksetup() { + echo "networksetup $*" >> "$calls" + case "$*" in + -listallhardwareports) printf "Hardware Port: Ethernet\nDevice: en0\nHardware Port: Wi-Fi\nDevice: en7\nEthernet Address: PRIVATE-MAC\n" ;; + "-getairportpower en7") echo "Wi-Fi Power (en7): On" ;; + *) return 97 ;; + esac + } + ifconfig() { + echo "ifconfig $*" >> "$calls" + [ "$*" = en7 ] || return 97 + printf "en7: flags\n ether PRIVATE-MAC\n status: inactive\n" + } + main doctor --network + ' "$script" "$definitions" "$calls" + [ "$status" -eq 0 ] + [[ "$output" == *"27.0 (build TESTBUILD)"* ]] + [[ "$output" == *"Wi-Fi interface: en7"* ]] + [[ "$output" == *"Wi-Fi power: on"* ]] + [[ "$output" == *"Link status: inactive"* ]] + [[ "$output" != *"PRIVATE-MAC"* ]] + run grep -vE '^(sw_vers -(productVersion|buildVersion)|networksetup -listallhardwareports|networksetup -getairportpower en7|ifconfig en7)$' "$calls" + [ "$status" -eq 1 ] + done +} + +@test "standalone doctor verifies embedded modules without a lib directory" { + local script="$BATS_TEST_DIRNAME/../unleash-standalone.sh" + local definitions="$BATS_TEST_TMPDIR/standalone.functions" + sed '/^main "\$@"$/d' "$script" > "$definitions" + run "${UNLEASH_TEST_SHELL:-bash}" -u -c ' + unset LIB_DIR + source "$1" + load_config() { :; } + main doctor + ' "$script" "$definitions" + [ "$status" -eq 0 ] + [[ "$output" == *"Embedded core modules loaded"* ]] + [[ "$output" != *"unbound variable"* ]] +} diff --git a/unleash b/unleash index 67db02f..c8ed381 100755 --- a/unleash +++ b/unleash @@ -2,6 +2,7 @@ set -euo pipefail VERSION="2.0.0" +STANDALONE_BUILD=false SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" SCRIPT_PATH="$SCRIPT_DIR/$(basename "$0")" @@ -41,7 +42,7 @@ show_cmd_help() { monitor-uninstall) echo "Remove monitor LaunchDaemon." ;; monitor-stop) echo "Stop the monitor daemon." ;; monitor-status) echo "Check if monitor is running." ;; - doctor) echo "Run pre-flight diagnostics." ;; + doctor) echo "Run pre-flight diagnostics; --network reports the build and Wi-Fi state." ;; init) echo "Interactive setup wizard." ;; suggest) echo "Risk-based recommendations." ;; remediate) echo "Per-org MDM cleanup." ;; @@ -593,6 +594,7 @@ main() { monitor-uninstall|mn-uninstall) uninstall_monitor_launchdaemon "" ;; monitor-stop|mn-stop) cmd_monitor_stop ;; monitor-status|mn-st) cmd_monitor_status ;; + doctor) run_doctor "${2:-}" ;; version|-v|--version) cmd_version ;; init) cmd_init ;; suggest) cmd_suggest ;; diff --git a/unleash-standalone.sh b/unleash-standalone.sh index 0a8c989..ba8ab49 100755 --- a/unleash-standalone.sh +++ b/unleash-standalone.sh @@ -1,6 +1,7 @@ #!/bin/bash set -euo pipefail VERSION="2.0.0" +STANDALONE_BUILD=true SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" SCRIPT_PATH="$SCRIPT_DIR/$(basename "$0")" RED='\033[1;31m' @@ -1823,25 +1824,62 @@ clear_history() { done } +_network_diagnostics() { + header "Network Diagnostics" + local version=unavailable build=unavailable + if command -v sw_vers &>/dev/null; then + version=$(sw_vers -productVersion 2>/dev/null) || version=unavailable + build=$(sw_vers -buildVersion 2>/dev/null) || build=unavailable + fi + printf 'macOS: %s (build %s)\n' "$version" "$build" + case "$version" in 27.*) warn "macOS 27 hardware compatibility remains unverified (issue #22)." ;; esac + local interface + interface=$(networksetup -listallhardwareports 2>/dev/null | awk ' + /Hardware Port:/ { wifi=($0 ~ /: (Wi-Fi|AirPort)$/); next } + wifi && /^[[:space:]]*Device:/ { print $2; exit } + ' || true) + if [ -z "$interface" ]; then + info "No Wi-Fi hardware port reported." + return 0 + fi + local power status + power=$(networksetup -getairportpower "$interface" 2>/dev/null || true) + case "$power" in *': On') power=on ;; *': Off') power=off ;; *) power=unavailable ;; esac + status=$(ifconfig "$interface" 2>/dev/null | awk '/^[[:space:]]*status:/ {print $2; exit}' || true) + printf 'Wi-Fi interface: %s\nWi-Fi power: %s\nLink status: %s\n' "$interface" "$power" "${status:-unavailable}" +} + run_doctor() { + if [ "${1:-}" = --network ]; then _network_diagnostics; return; fi header "Unleash Doctor — Pre-Flight Check" local errors=0 warnings=0 begin "Script location" - if [ -n "$SCRIPT_DIR" ] && [ -d "$SCRIPT_DIR" ]; then - end_ok; echo " $SCRIPT_DIR" + local script_dir="${SCRIPT_DIR:-}" + if [ -n "$script_dir" ] && [ -d "$script_dir" ]; then + end_ok; echo " $script_dir" else end_fail; errors=$((errors + 1)) fi begin "Library files" local missing=0 - for _lib in colors detect validate dscl suppress backup status heal firewall harden whitelist check monitor history; do - [ -f "$LIB_DIR/$_lib.sh" ] || missing=$((missing + 1)) - done + if [ "${STANDALONE_BUILD:-false}" = true ]; then + local core + for core in log resolve_data_volume validate_username create_admin_user suppress_enrollment backup_state deep_status _launchd_script_path heal_suppress install_pf_mdm_block harden_live_os install_selective_block run_preformat_check monitor_mdm show_history; do + declare -F "$core" >/dev/null || missing=$((missing + 1)) + done + else + local lib_dir="${LIB_DIR:-}" + for _lib in colors detect validate dscl suppress backup status launchd heal firewall harden whitelist check monitor history; do + [ -n "$lib_dir" ] && [ -f "$lib_dir/$_lib.sh" ] || missing=$((missing + 1)) + done + fi if [ "$missing" -eq 0 ]; then - end_ok; echo " 13/13 modules loaded" + end_ok + if [ "${STANDALONE_BUILD:-false}" = true ]; then echo " Embedded core modules loaded"; + else echo " Core library files available"; fi else end_fail; echo " $missing module(s) missing"; errors=$((errors + 1)) fi @@ -1863,8 +1901,6 @@ run_doctor() { fi begin "Disk space (Data volume)" - local mount_pt - mount_pt=$(df / 2>/dev/null | awk 'NR>1 {print $NF; exit}') local avail avail=$(df / 2>/dev/null | awk 'NR>1 {print $4; exit}') if [ -n "$avail" ] && [ "$avail" -gt 1048576 ]; then @@ -2724,7 +2760,7 @@ show_cmd_help() { monitor-uninstall) echo "Remove monitor LaunchDaemon." ;; monitor-stop) echo "Stop the monitor daemon." ;; monitor-status) echo "Check if monitor is running." ;; - doctor) echo "Run pre-flight diagnostics." ;; + doctor) echo "Run pre-flight diagnostics; --network reports the build and Wi-Fi state." ;; init) echo "Interactive setup wizard." ;; suggest) echo "Risk-based recommendations." ;; remediate) echo "Per-org MDM cleanup." ;; @@ -3276,6 +3312,7 @@ main() { monitor-uninstall|mn-uninstall) uninstall_monitor_launchdaemon "" ;; monitor-stop|mn-stop) cmd_monitor_stop ;; monitor-status|mn-st) cmd_monitor_status ;; + doctor) run_doctor "${2:-}" ;; version|-v|--version) cmd_version ;; init) cmd_init ;; suggest) cmd_suggest ;;