Add previewsmcp logs subcommand and promote Debugging section

[obj-p]

Summary

• New previewsmcp logs subcommand — prints the last N lines of ~/.previewsmcp/serve.log (default 100), or streams new lines with -f/--follow. Creates the log file if absent so it works before the daemon has ever started.
• Promoted ## Debugging to a top-level README section (previously a sub-subsection inside ### Daemon model), leading with the new subcommand and keeping tail -F as the raw-file fallback.
• Added previewsmcp logs -f to the "Enumeration and diagnostics" command list under ## Usage for discoverability.

Motivation

Users have no documented diagnostic path when run hangs during an iOS host build. The daemon stderr has always been redirected to ~/.previewsmcp/serve.log, and build-phase progress streams to the CLI's stderr via MCP log notifications, but none of it was surfaced in the README and there was no one-command shortcut.

Implementation notes

LogsCommand shells out to /usr/bin/tail rather than reimplementing log-follow in Swift. Process is used directly (not AsyncProcess, which buffers) with stdio wired to the CLI's own TTY handles so tail's output streams live.

Signal handling is the only non-trivial piece: after Process.run(), the parent installs DispatchSource.makeSignalSource for SIGINT/SIGTERM on a background queue (because waitUntilExit blocks main) and forwards them to the tail child. Two scenarios covered:

• Ctrl-C in a terminal — the tty delivers SIGINT to the foreground process group, so tail receives it on its own; the forward is a redundant, idempotent poke.
• kill -INT <parent-pid> from a supervisor/script — the signal arrives only at the parent; without forwarding, tail would be orphaned to launchd.

Flag defaults follow tail/kubectl logs/docker logs/journalctl convention: snapshot by default, explicit -f to stream.

Test plan

• swift build — clean build
• .build/debug/previewsmcp logs --help — expected flags present, discussion mentions the log path and $PREVIEWSMCP_SOCKET_DIR
• logs with seeded log + -n 5 — returns the last 5 lines, exit 0
• logs when log file is missing — creates the file, exits 0, empty stdout (no banner)
• logs --follow — streams an appended sentinel line within 10s and exits within 5s of SIGINT to the parent PID (covered by LogsCommandTests.followStreamsAndExitsOnSIGINT)
• PREVIEWSMCP_SOCKET_DIR redirect honored — verified implicitly via DaemonTestLock-scoped tests targeting an isolated dir
• swift test --filter CLIIntegrationTests — all 66 tests across 12 suites pass

Out of scope (follow-ups worth filing)

• --verbose / --debug flag threading through existing commands
• Live subprocess stdout/stderr streaming during build phases (the "hang with no output" gap — when xcodebuild or swiftc is the one stuck, nothing new lands in serve.log until the child exits)

🤖 Generated with Claude Code