Phase 3: Runtime Inspection API (JSON transport + stubs)

[pronskiy]

Phase 3: Runtime Inspection API

Branch: phase3-inspection-api (based on phase2-observer-migration)
Status: 3.1 done, 3.2-3.5 TODO

What this PR adds

Phase 3.1: JSON Transport Layer ✅ (62a1348)

New src/inspect/ subsystem — a TCP/Unix socket server that speaks JSON lines, independent of the existing DBGp debugger.

New files:

File	Lines	Purpose
src/inspect/inspect_transport.c	728	TCP server: bind, listen, accept, read, dispatch. Non-blocking I/O, poll-based, up to 16 clients
src/inspect/inspect_transport.h	45	Public API: init/check/process/send/broadcast/shutdown
src/inspect/inspect_commands.c	229	Command dispatch + stub handlers for all inspection commands
src/inspect/inspect_commands.h	49	Command handler declarations

Modified files:

File	Changes	Purpose
xdebug.c	+58	Wire transport into MINIT/RINIT/RSHUTDOWN/MSHUTDOWN lifecycle
src/lib/lib.h	+5	New INI setting declarations
config.m4	+4	Compile src/inspect/ directory

INI settings:

xdebug.inspect = off          ; off | on | auto | trigger
xdebug.inspect_port = 9007    ; TCP port for JSON API
xdebug.inspect_socket =       ; Unix socket path (alternative to TCP)

Working:

# Start PHP with inspect enabled
php -dzend_extension=modules/xdebug.so -dxdebug.inspect=on -r "sleep(3);" &
sleep 1

# Status command works
echo '{"id":1,"cmd":"status"}' | nc -q1 localhost 9007
# → {"id":1,"ok":true,"extension":"Xdebug","version":"3.6.0-dev","php_version":"8.6.0-dev",...}

# Stub commands return proper errors
echo '{"id":2,"cmd":"inspect","file":"test.php","line":1}' | nc -q1 localhost 9007
# → {"id":2,"ok":false,"error":"command 'inspect' not yet implemented"}

Architecture:

• Server model (bind+listen), unlike DBGp which connects out to IDE
• JSON lines framing (one JSON object per newline)
• Shares socket macros with existing com.h but is fully independent
• Uses ext/json (php_json_encode/php_json_decode_ex) for JSON handling
• Tick function for processing messages during PHP execution

TODO (remaining Phase 3 tasks)

• 3.2 inspect command (2 days) — Observation breakpoints: capture variable/expression at file:line without pausing
• 3.3 snapshot command (3 days) — Full context capture on exception/error with stack + locals
• 3.4 watch + trace (2 days) — Variable change streaming + filtered function call flow
• 3.5 CLI tool (1 day) — php-inspect CLI client

Testing

• Extension builds clean: make -j$(nproc) ✅
• Extension loads: php -dzend_extension=modules/xdebug.so -r "echo ok;" ✅
• INI settings in phpinfo ✅
• TCP server accepts connections and dispatches commands ✅
• Existing DBGp functionality unaffected ✅