Rename programs: 9player -> 9ns, introspect -> 9proc, app -> web (9web)

Directories, binaries, build options (-D9ns, -D9proc), step names, module
name (9proc), thread and fs names, env var NINEPLAYER_MOUNT -> NINE_MOUNT,
docs and test scripts. Browser assets move to web/static.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

1 files changed, 84 insertions, 0 deletions

diff --git a/9proc/test/debug.sh b/9proc/test/debug.sh
new file mode 100755
index 0000000..1334dff
--- /dev/null
+++ b/9proc/test/debug.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# End-to-end test of the 9proc debug facilities through 9ns:
+# threads and stacks, address resolution, memory, exposed values, breakpoints, panics.
+# Usage: bash 9proc/test/debug.sh <9ns> <9proc-demo>   (zig build 9proc-debug-itest)
+set -u
+NS=$(realpath "${1:?path to 9ns}")
+PROC=$(realpath "${2:?path to 9proc-demo}")
+TMP=$(mktemp -d /tmp/9pdbg.XXXXXX)
+M=/mnt/9p
+FAILED=0; PASSED=0
+SRV=
+
+cleanup() { [ -n "$SRV" ] && kill "$SRV" 2>/dev/null; rm -rf "$TMP"; }
+trap cleanup EXIT
+if ! unshare -Urm true 2>/dev/null || [ ! -c /dev/fuse ]; then echo "SKIP: namespaces or /dev/fuse unavailable"; exit 0; fi
+
+pass() { PASSED=$((PASSED + 1)); echo "ok   - $1"; }
+fail() { FAILED=$((FAILED + 1)); echo "FAIL - $1"; shift; [ $# -gt 0 ] && printf '       %s\n' "$@"; }
+expect_eq() { if [ "$2" = "$3" ]; then pass "$1"; else fail "$1" "expected: $(printf %q "$2")" "actual:   $(printf %q "$3")"; fi; }
+expect_contains() { case "$3" in *"$2"*) pass "$1" ;; *) fail "$1" "missing: $(printf %q "$2")" "in: $(printf %q "$3")" ;; esac; }
+run_in() { timeout 60 "$NS" --unix "$SOCK" -- sh -c "$1" 2>"$TMP/stderr"; }
+
+SOCK=$TMP/dbg.sock
+"$PROC" --unix "$SOCK" >"$TMP/server.log" 2>&1 &
+SRV=$!
+for _ in $(seq 1 100); do [ -S "$SOCK" ] && break; sleep 0.05; done
+[ -S "$SOCK" ] || { echo "server did not start"; cat "$TMP/server.log"; exit 1; }
+
+echo "# threads"
+expect_eq "threads listed" "yes" "$(run_in "[ \$(ls $M/threads | wc -l) -ge 2 ] && echo yes")"
+WORKER=$(run_in "for t in $M/threads/*; do if grep -q '^worker' \$t/name 2>/dev/null; then basename \$t; fi; done | head -1")
+expect_eq "worker thread found by name" "yes" "$([ -n "$WORKER" ] && echo yes)"
+STACK=$(run_in "cat $M/threads/$WORKER/stack")
+expect_contains "worker stack names workerLoop" "workerLoop" "$STACK"
+expect_contains "worker stack has source locations" "demo/main.zig:" "$STACK"
+expect_contains "worker regs" "0x" "$(run_in "cat $M/threads/$WORKER/regs | head -3")"
+expect_eq "own (server) thread stack works" "yes" "$(run_in "for t in $M/threads/*; do cat \$t/stack >/dev/null 2>&1 || echo bad; done; echo yes")"
+
+echo "# addresses and memory"
+FRAME=$(printf '%s\n' "$STACK" | grep -oE '0x[0-9a-f]+' | head -1)
+expect_contains "addr resolves a stack frame to the demo source" "demo/main.zig" "$(run_in "cat $M/addr/${FRAME#0x}")"
+expect_contains "addr of garbage is an error, not a crash" "No such file" "$(run_in "cat $M/addr/zzz 2>&1")"
+expect_contains "mem/maps readable" "r-xp" "$(run_in "head -c 4000 $M/mem/maps")"
+STATE_ADDR=$(run_in "cat $M/vars/state/addr")
+expect_contains "hexdump of the exposed state" "  " "$(run_in "head -2 $M/hex/${STATE_ADDR#0x}")"
+expect_eq "raw bytes of the state match its size" "$(run_in "cat $M/vars/state/size")" "$(run_in "cat $M/mem/${STATE_ADDR#0x} | head -c \$(cat $M/vars/state/size) | wc -c")"
+expect_eq "reading unmapped memory is an error, not a crash" "no" "$(run_in "cat $M/mem/8 >/dev/null 2>&1 && echo yes || echo no")"
+
+echo "# exposed values"
+T1=$(run_in "cat $M/vars/state/f/ticks/value"); sleep 0.4; T2=$(run_in "cat $M/vars/state/f/ticks/value")
+expect_eq "ticks is numeric" "num" "$(printf '%s' "$T1" | grep -Eq '^[0-9]+$' && echo num)"
+expect_eq "ticks advance" "yes" "$([ "$T2" -gt "$T1" ] 2>/dev/null && echo yes)"
+expect_contains "rendered struct value" "ticks" "$(run_in "cat $M/vars/state/value")"
+expect_contains "type name" "State" "$(run_in "cat $M/vars/state/type")"
+T3=$(run_in "echo 5 > $M/vars/state/f/ticks/value && cat $M/vars/state/f/ticks/value")
+expect_eq "writing a scalar changes the live variable" "yes" "$([ "$T3" -lt "$T2" ] 2>/dev/null && echo yes)"
+
+echo "# breakpoints"
+expect_eq "no breakpoints initially" "" "$(run_in "ls $M/breakpoints")"
+run_in "echo trap > $M/runtime/ctl" >/dev/null; sleep 0.6
+PAUSED=$(run_in "ls $M/breakpoints | head -1")
+expect_eq "worker paused at @breakpoint()" "$WORKER" "$PAUSED"
+expect_contains "paused stack names workerLoop" "workerLoop" "$(run_in "cat $M/breakpoints/$WORKER/stack 2>&1")"
+P1=$(run_in "cat $M/vars/state/f/ticks/value"); sleep 0.4; P2=$(run_in "cat $M/vars/state/f/ticks/value")
+expect_eq "ticks frozen while paused" "$P1" "$P2"
+run_in "echo continue > $M/breakpoints/$WORKER/ctl" >/dev/null; sleep 0.4
+expect_eq "breakpoint list empty after continue" "" "$(run_in "ls $M/breakpoints")"
+P3=$(run_in "cat $M/vars/state/f/ticks/value")
+expect_eq "ticks advance after continue" "yes" "$([ "$P3" -gt "$P2" ] 2>/dev/null && echo yes)"
+
+echo "# panic"
+expect_eq "no panic recorded" "" "$(run_in "cat $M/panic/message")"
+run_in "echo panic > $M/runtime/ctl" >/dev/null; sleep 0.6
+expect_contains "panic message published" "demo panic" "$(run_in "cat $M/panic/message")"
+expect_contains "panic stack names the worker" "workerLoop" "$(run_in "cat $M/panic/stack")"
+expect_eq "server still alive while holding the panic" "yes" "$(kill -0 $SRV 2>/dev/null && echo yes)"
+run_in "echo continue > $M/panic/ctl" >/dev/null 2>&1
+for _ in $(seq 1 50); do kill -0 $SRV 2>/dev/null || break; sleep 0.1; done
+if kill -0 $SRV 2>/dev/null; then fail "server exits after panic continue"; else wait $SRV; RC=$?; SRV=; expect_eq "server exit status is non-zero after the panic" "yes" "$([ $RC -ne 0 ] && echo yes)"; fi
+expect_contains "default panic output reached stderr" "demo panic" "$(cat "$TMP/server.log")"
+
+echo
+echo "passed=$PASSED failed=$FAILED"
+[ "$FAILED" -eq 0 ]