Summary

The current serve command works but has hidden reliability and security issues. This ticket upgrades it to a modern, safe, and predictable implementation while keeping the same CLI behavior, with one optional flag to open the browser.

CLI Contract

Quantum uses presence-based flags.

php quantum serve        -> starts server (no browser)
php quantum serve --open -> starts server and opens browser

What to change

• Use real port binding (stream_socket_server) instead of connection checks
• Avoid recursion; scan a limited range of ports
• Start the PHP server with proc_open() and PHP_BINARY
• Wait until the server is ready before opening a browser
• Add --open flag (disabled by default)
• Use correct OS-specific browser commands
• Handle Ctrl+C and terminate the child process cleanly
• Never build shell strings from user input

Acceptance criteria

• php quantum serve starts the server without opening a browser
• php quantum serve --open starts the server and opens the browser
• The server always binds to a free port or fails with a clear error
• Browser opens only after the server is listening
• Ctrl+C stops the PHP server
• Works on Windows, Linux, and macOS