CLI for SidePulse
Python
#!/usr/bin/env bash
set -u -o pipefail
usage() {
cat <<'USAGE'
Usage: scripts/macos-sd-diagnostics.sh [options]
Collect macOS host-side diagnostics for the built-in SD reader/card path.
Options:
--last DURATION Log window passed to `log show --last` (default: 30m).
Examples: 10m, 2h, 1d.
--start DATE Start time for `log show --start`.
Example: "2026-06-25 00:40:00".
--end DATE End time for `log show --end`.
Use with --start. If omitted, log show uses "now".
--out PATH Output report path.
--cmd-timeout SEC Timeout for storage/registry commands (default: 20).
--log-timeout SEC Timeout for each `log show` query (default: 180).
-h, --help Show this help.
Examples:
scripts/macos-sd-diagnostics.sh --last 2h
scripts/macos-sd-diagnostics.sh --start "2026-06-25 00:40:00" --end "2026-06-25 00:50:00"
USAGE
}
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
stamp="$(date '+%Y%m%d-%H%M%S')"
last_window="${SD_DIAG_LAST:-30m}"
start_time=""
end_time=""
out_path="$repo_root/temp_data/macos-sd-diagnostics-$stamp.txt"
cmd_timeout="${SD_DIAG_CMD_TIMEOUT:-20}"
log_timeout="${SD_DIAG_LOG_TIMEOUT:-180}"
while [[ $# -gt 0 ]]; do
case "$1" in
--last)
[[ $# -ge 2 ]] || { echo "--last requires a duration" >&2; exit 2; }
last_window="$2"
shift 2
;;
--start)
[[ $# -ge 2 ]] || { echo "--start requires a date" >&2; exit 2; }
start_time="$2"
shift 2
;;
--end)
[[ $# -ge 2 ]] || { echo "--end requires a date" >&2; exit 2; }
end_time="$2"
shift 2
;;
--out)
[[ $# -ge 2 ]] || { echo "--out requires a path" >&2; exit 2; }
out_path="$2"
shift 2
;;
--cmd-timeout)
[[ $# -ge 2 ]] || { echo "--cmd-timeout requires seconds" >&2; exit 2; }
cmd_timeout="$2"
shift 2
;;
--log-timeout)
[[ $# -ge 2 ]] || { echo "--log-timeout requires seconds" >&2; exit 2; }
log_timeout="$2"
shift 2
;;
-h|--help)
usage
exit 0
;;
*)
echo "Unknown option: $1" >&2
usage >&2
exit 2
;;
esac
done
mkdir -p "$(dirname "$out_path")"
section() {
printf '\n\n===== %s =====\n\n' "$1"
}
run() {
printf '$'
printf ' %q' "$@"
printf '\n'
"$@"
local status=$?
if [[ $status -ne 0 ]]; then
printf '[exit status %d]\n' "$status"
fi
}
run_shell() {
printf '$ %s\n' "$*"
/bin/bash -lc "$*"
local status=$?
if [[ $status -ne 0 ]]; then
printf '[exit status %d]\n' "$status"
fi
}
run_timeout() {
local timeout_seconds="$1"
shift
printf '$ timeout %ss' "$timeout_seconds"
printf ' %q' "$@"
printf '\n'
perl -e '
use strict;
use warnings;
my $timeout = shift @ARGV;
my $pid = fork();
die "fork: $!\n" unless defined $pid;
if ($pid == 0) {
setpgrp(0, 0);
exec @ARGV or die "exec @ARGV: $!\n";
}
local $SIG{ALRM} = sub {
kill "TERM", -$pid;
select undef, undef, undef, 1;
kill "KILL", -$pid;
print STDERR "\n[timeout after ${timeout}s]\n";
exit 124;
};
alarm $timeout;
waitpid($pid, 0);
my $status = $?;
alarm 0;
if ($status == -1) {
exit 127;
} elsif ($status & 127) {
exit 128 + ($status & 127);
} else {
exit($status >> 8);
}
' "$timeout_seconds" "$@"
local status=$?
if [[ $status -ne 0 ]]; then
printf '[exit status %d]\n' "$status"
fi
}
run_timeout_shell() {
local timeout_seconds="$1"
shift
run_timeout "$timeout_seconds" /bin/bash -lc "$*"
}
log_window_args=()
if [[ -n "$start_time" ]]; then
log_window_args=(--start "$start_time")
if [[ -n "$end_time" ]]; then
log_window_args+=(--end "$end_time")
fi
else
log_window_args=(--last "$last_window")
fi
kernel_predicate='process == "kernel" && (eventMessage CONTAINS[c] "AppleSDXC" || eventMessage CONTAINS[c] "Port-SD" || eventMessage CONTAINS[c] "SDXC" || eventMessage CONTAINS[c] "SD Card" || eventMessage CONTAINS[c] "IOBlockStorage" || eventMessage CONTAINS[c] "IOMedia")'
disk_predicate='(process == "diskarbitrationd" || process == "diskmanagementd" || process == "kernel") && (eventMessage CONTAINS[c] "disk" || eventMessage CONTAINS[c] "SidePulse" || eventMessage CONTAINS[c] "Side" || eventMessage CONTAINS[c] "FAT" || eventMessage CONTAINS[c] "MS-DOS" || eventMessage CONTAINS[c] "IOMedia" || eventMessage CONTAINS[c] "eject" || eventMessage CONTAINS[c] "mount")'
system_eject_predicate='process == "diskarbitrationd" && (eventMessage CONTAINS[c] "kind = disk eject" || eventMessage CONTAINS[c] "ejected disk" || eventMessage CONTAINS[c] "SidePulse Pro Eject Prevention" || eventMessage CONTAINS[c] "sd_eject_guard" || eventMessage CONTAINS[c] "sdejectguard")'
guard_label="io.sidepulse.sdejectguard"
guard_display_name="SidePulse Pro Eject Prevention"
guard_user_data_root="${XDG_DATA_HOME:-$HOME/.local/share}"
guard_user_state_root="${XDG_STATE_HOME:-$HOME/.local/state}"
guard_user_plist="$HOME/Library/LaunchAgents/$guard_label.plist"
guard_user_binary="$guard_user_data_root/sidepulse/sd-eject-guard/$guard_display_name"
guard_user_stdout="$guard_user_state_root/sidepulse/agent-monitor/sd-eject-guard.out.log"
guard_user_stderr="$guard_user_state_root/sidepulse/agent-monitor/sd-eject-guard.err.log"
guard_system_plist="/Library/LaunchDaemons/$guard_label.plist"
guard_system_binary="/Library/Application Support/SidePulse/sd-eject-guard/$guard_display_name"
guard_system_stdout="/Library/Logs/SidePulse/sd-eject-guard.out.log"
guard_system_stderr="/Library/Logs/SidePulse/sd-eject-guard.err.log"
show_path_status() {
local target
for target in "$@"; do
if [[ -e "$target" ]]; then
run /usr/bin/stat -f '%N | mode=%Sp | owner=%Su:%Sg | size=%z | modified=%Sm | created=%SB' \
-t '%Y-%m-%d %H:%M:%S %z' "$target"
else
printf 'Missing: %s\n' "$target"
fi
done
}
show_log_tail() {
local target="$1"
if [[ -e "$target" ]]; then
run /usr/bin/tail -n 100 "$target"
else
printf 'Missing: %s\n' "$target"
fi
}
{
section "Run Metadata"
printf 'Generated: %s\n' "$(date '+%Y-%m-%d %H:%M:%S %z')"
printf 'Host: %s\n' "$(hostname)"
printf 'Working directory: %s\n' "$(pwd)"
printf 'Repository root: %s\n' "$repo_root"
printf 'Output path: %s\n' "$out_path"
printf 'Command timeout: %ss\n' "$cmd_timeout"
printf 'Log timeout: %ss\n' "$log_timeout"
if [[ -n "$start_time" ]]; then
printf 'Log window: start=%s end=%s\n' "$start_time" "${end_time:-now}"
else
printf 'Log window: last=%s\n' "$last_window"
fi
section "System"
run date
run sw_vers
run uname -a
run uptime
section "Card Reader Summary"
run_timeout "$cmd_timeout" system_profiler SPCardReaderDataType
run_timeout "$cmd_timeout" system_profiler -json SPCardReaderDataType
section "Disk State"
run_timeout "$cmd_timeout" diskutil list
run_timeout "$cmd_timeout" diskutil info -all
run_timeout "$cmd_timeout" mount
run_timeout "$cmd_timeout" df -h
run_timeout_shell "$cmd_timeout" 'ls -la /Volumes'
section "AppleSDXC IORegistry Path"
run_timeout "$cmd_timeout" ioreg -p IOService -w0 -t -r -c AppleSDXC
section "AppleSDXC IORegistry Properties"
run_timeout "$cmd_timeout" ioreg -p IOService -l -w0 -r -c AppleSDXC
section "AppleSDXC Quick Filter"
run_timeout_shell "$cmd_timeout" 'ioreg -p IOService -l -w0 -r -c AppleSDXC | grep -E "AppleSDXC|Port-SD|Card Present|ConnectionActive|TransportsActive|Authorization|Block Count|Ejected|IOMedia|BSD Name|Errors|Operations|Product Name|Manufacture|Serial|Card Type|Specification|Bus Width|Speed Mode|Clock|TRM|HashStatus|DriverStatus" || true'
section "IOPort Plane SD View"
run_timeout_shell "$cmd_timeout" 'for name in "Port-SD Card@1" "SD"; do echo "--- $name ---"; ioreg -p IOPort -l -w0 -r -n "$name"; done'
section "IOMedia Filter"
run_timeout_shell "$cmd_timeout" 'ioreg -p IOService -l -w0 -r -c IOMedia | grep -E "IOMedia|BSD Name|Content|Whole|Writable|Removable|Size|Leaf|Preferred Block Size|SidePulse|Side|PulseDot|FAT|MS-DOS|Secure Digital" || true'
section "Power Assertions"
run_timeout "$cmd_timeout" pmset -g assertions
section "SidePulse Eject Prevention State"
printf 'The launchctl checks show whether the guard is running at report collection time.\n'
printf 'The process start time helps determine whether it was alive during an earlier eject event.\n\n'
run_timeout "$cmd_timeout" launchctl print "gui/$(id -u)/$guard_label"
run_timeout "$cmd_timeout" launchctl print "system/$guard_label"
run_timeout_shell "$cmd_timeout" '/bin/ps -axo user=,pid=,ppid=,lstart=,etime=,state=,command= | /usr/bin/grep -E "[S]idePulse Pro Eject Prevention|[s]d_eject_guard" || true'
section "SidePulse Eject Prevention Files"
show_path_status \
"$guard_user_plist" \
"$guard_user_binary" \
"$guard_user_stdout" \
"$guard_user_stderr" \
"$guard_system_plist" \
"$guard_system_binary" \
"$guard_system_stdout" \
"$guard_system_stderr"
section "SidePulse Eject Prevention Logs"
printf '%s\n' "--- User stdout: $guard_user_stdout ---"
show_log_tail "$guard_user_stdout"
printf '%s\n' "--- User stderr: $guard_user_stderr ---"
show_log_tail "$guard_user_stderr"
printf '%s\n' "--- System stdout: $guard_system_stdout ---"
show_log_tail "$guard_system_stdout"
printf '%s\n' "--- System stderr: $guard_system_stderr ---"
show_log_tail "$guard_system_stderr"
section "Kernel SD Logs"
run_timeout "$log_timeout" log show --style syslog --info --debug "${log_window_args[@]}" --predicate "$kernel_predicate"
section "Focused System Eject And Guard Logs"
printf '%s\n' 'Interpretation:'
printf '%s\n' '- "loginwindow ... queued solicitation ... kind = disk eject" means macOS initiated the eject.'
printf '%s\n' '- "kind = disk eject approval ... dissented" means a registered client prevented it.'
printf '%s\n' '- "ejected disk ... success" means the eject completed and was not prevented.'
printf '%s\n\n' '- A SidePulse callback/response plus "prevented eject" in the guard stdout confirms the project guard handled it.'
run_timeout "$log_timeout" log show --style syslog --info --debug "${log_window_args[@]}" --predicate "$system_eject_predicate"
section "Disk Arbitration And Mount Logs"
run_timeout "$log_timeout" log show --style syslog --info --debug "${log_window_args[@]}" --predicate "$disk_predicate"
} >"$out_path" 2>&1
printf 'Wrote diagnostics to %s\n' "$out_path"