fix: --version issues (#22)

[konard]

Summary

This PR fixes the --version issues reported in #22, specifically addressing the screen version detection bug on macOS.

Root Cause Analysis

The macOS bundled version of GNU Screen (4.00.03) has a known bug where screen --version returns a non-zero exit code even when successful. This bug was fixed in GNU Screen v4.8.0. Reference: GNU Screen v.4.8.0 Release Notes

The previous fix used execSync() with 2>&1, but execSync() throws an exception when the command returns non-zero exit code, so the output was never captured.

Fixes in This PR

1. Screen version detection on macOS - Use spawnSync instead of execSync to capture output regardless of exit code
2. --verbose flag support - Added $ --version --verbose for debugging version detection
3. Use -v flag for screen - More universally supported than --version

Previous Fixes (already in main via PR #23)

• Node.js version shown instead of Bun - Fixed by detecting runtime and using Bun.version
• macOS OS version incorrect - Fixed by using sw_vers -productVersion on darwin
• $ --version -- error - Fixed by allowing trailing -- with version flag

Changes

Code Changes

• src/bin/cli.js:
  • Added spawnSync import
  • Rewrote getToolVersion() to use spawnSync for exit-code-independent output capture
  • Added verbose parameter to printVersion() and getToolVersion()
  • Changed screen version flag from --version to -v

Test Changes

• test/version.test.js: Added 3 new tests for verbose mode

Documentation

• docs/case-studies/issue-22/analysis.md: Updated with root cause analysis and solution

Test Plan

• All 106 tests pass locally across 5 test files
• $ --version shows correct versions
• $ --version --verbose shows debugging info
• $ --version -- works correctly
• Screen detected correctly (on systems where it's installed)
• Lint and format checks pass

Verified Behavior

$ --version
start-command version: 0.7.1

OS: linux
OS Version: 6.8.0-90-generic
Bun Version: 1.3.3
Architecture: x64

Isolation tools:
  screen: Screen version 4.09.01 (GNU) 20-Aug-23
  tmux: tmux 3.4
  docker: not installed

$ --version --verbose
start-command version: 0.7.1

OS: linux
OS Version: 6.8.0-90-generic
Bun Version: 1.3.3
Architecture: x64

Isolation tools:
[verbose] Checking isolation tools...
[verbose] screen -v: exit=0, output="Screen version 4.09.01 (GNU) 20-Aug-23"
  screen: Screen version 4.09.01 (GNU) 20-Aug-23
[verbose] tmux -V: exit=0, output="tmux 3.4"
  tmux: tmux 3.4
[verbose] docker: not found in PATH
  docker: not installed

Fixes #22

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $6.007922 USD
• Calculated by Anthropic: $3.714445 USD
• Difference: $-2.293477 (-38.17%)
  📎 Log file uploaded as GitHub Gist (739KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

I see no actual code changes in this Pull Request, also we may need additional tests, logging in --verbose mode and so on. Or did we have ignored #22 (comment)? Please read all comments on the issue, do not ignore any requirements. Double check everything.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-23T19:36:26.825Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 AI Work Session Completed

Summary of Changes

This session addressed the remaining issue from #22 - screen version detection on macOS.

Root Cause Found

The macOS bundled version of GNU Screen (4.00.03) has a known bug where screen --version returns a non-zero exit code even when successful. This bug was fixed in GNU Screen v4.8.0 (see release notes).

The previous fix used execSync() with 2>&1, but since execSync() throws on non-zero exit codes, the output was never captured.

Solution Implemented

1. Use spawnSync instead of execSync - Captures output regardless of exit code
2. Added --verbose flag - Users can now debug version detection with $ --version --verbose
3. Changed screen flag to -v - More universally supported

Test Results

• ✅ All 106 tests pass (14 version tests, 5 CLI tests, 42 args-parser tests, 23 isolation tests, 22 substitution tests)
• ✅ Lint and format checks pass
• ✅ CI passes

Files Changed

• src/bin/cli.js - Fixed getToolVersion() function
• test/version.test.js - Added 3 new tests for verbose mode
• docs/case-studies/issue-22/analysis.md - Updated with root cause analysis

The PR is now ready for review.

---

AI work session completed at 2025-12-23T19:46:00Z

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $5.381888 USD
• Calculated by Anthropic: $3.395636 USD
• Difference: $-1.986252 (-36.91%)
  📎 Log file uploaded as GitHub Gist (657KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.