start-command 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # start-command
 
+## 0.7.1
+
+### Patch Changes
+
+- d5a7c66: Fix all --version detection issues
+  - Fix screen version detection by capturing stderr
+  - Show Bun version instead of Node.js version when running with Bun
+  - Show macOS ProductVersion instead of kernel version
+  - Fix argument parsing to handle `$ --version --` same as `$ --version`
+  - Update all scripts and examples to use Bun instead of Node.js
+  - Add comprehensive tests for --version flag
+
 ## 0.7.0
 
 ### Minor Changes

package/REQUIREMENTS.md

@@ -76,7 +76,7 @@ The `$` command is a CLI tool that wraps any shell command and provides automati
   - Command that was executed
   - Exit code
   - Link to uploaded log
-  - System information (OS, Node version)
+  - System information (OS, Bun/Node.js version)
   - Timestamp
 - Print the created issue URL to console
 
@@ -209,7 +209,8 @@ Repository not detected - automatic issue creation skipped
 
 ### Required
 
-- Node.js >= 14.0.0
+- **Bun >= 1.0.0** (primary runtime)
+- Alternatively: Node.js >= 20.0.0 (for compatibility)
 - `child_process` (built-in)
 - `os` (built-in)
 - `fs` (built-in)

package/docs/case-studies/issue-22/analysis.md

@@ -0,0 +1,332 @@
+# Case Study: Issue #22 - Version Detection Issues
+
+## Issue Overview
+
+**Issue ID:** #22
+**Title:** --version issues
+**Reported By:** konard
+**Created:** 2025-12-23T17:55:53Z
+**Status:** Open
+
+## Problem Summary
+
+The `$ --version` command exhibited multiple issues when run on macOS:
+
+1. **Screen version not detected** - Despite screen being installed, it showed "not installed"
+2. **Wrong runtime displayed** - Showed Node.js version instead of Bun version
+3. **Incorrect OS version format** - Showed OS Release (kernel version) instead of macOS version
+4. **Argument parsing issue** - `$ --version --` resulted in "No command provided" error
+
+## Timeline of Events
+
+### User Environment
+
+- **System:** macOS 15.7.2 (ProductVersion)
+- **Kernel:** 24.6.0 (OS Release)
+- **Bun Version:** 1.2.20
+- **Node.js Emulation:** v24.3.0 (provided by Bun)
+- **Architecture:** arm64
+- **Package:** start-command@0.7.0
+
+### Observed Behavior
+
+#### Command 1: `$ --version --`
+
+```
+Error: No command provided
+Usage: $ [options] [--] <command> [args...]
+```
+
+**Expected:** Should display version information (same as `$ --version`)
+**Actual:** Treated `--` as command separator and found no command after it
+
+#### Command 2: `$ --version`
+
+```
+start-command version: 0.7.0
+
+OS: darwin
+OS Release: 24.6.0
+Node Version: v24.3.0
+Architecture: arm64
+
+Isolation tools:
+  screen: not installed
+  tmux: not installed
+  docker: Docker version 28.5.1, build e180ab8
+```
+
+**Issues Identified:**
+
+1. Screen shown as "not installed" despite being present
+2. "Node Version: v24.3.0" when using Bun
+3. "OS Release: 24.6.0" (kernel) instead of "15.7.2" (macOS version)
+
+#### Verification Commands
+
+```bash
+screen -v
+# Output: Screen version 4.00.03 (FAU) 23-Oct-06
+
+sw_vers
+# Output:
+# ProductName:		macOS
+# ProductVersion:	15.7.2
+# BuildVersion:		24G325
+```
+
+## Root Cause Analysis
+
+### Issue 1: Screen Version Not Detected
+
+**Location:** `src/bin/cli.js:84`
+
+**Root Cause:**
+
+- Screen outputs version to stderr, not stdout
+- Current implementation uses `execSync()` with default stdio configuration
+- On some systems/versions, screen sends output to stderr
+
+**Code Analysis:**
+
+```javascript
+const screenVersion = getToolVersion('screen', '--version');
+
+function getToolVersion(toolName, versionFlag) {
+  try {
+    const result = execSync(`${toolName} ${versionFlag}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'], // stderr is piped but not captured
+      timeout: 5000,
+    }).trim();
+    // ...
+```
+
+The `execSync()` call captures stdout but the function doesn't merge stderr into the result. On macOS, screen may output to stderr.
+
+### Issue 2: Node.js Version Instead of Bun Version
+
+**Location:** `src/bin/cli.js:76`
+
+**Root Cause:**
+
+- Code uses `process.version` which returns Node.js compatibility version in Bun
+- Bun emulates Node.js v24.3.0 for compatibility
+- Should use `process.versions.bun` or `Bun.version` instead
+
+**Code Analysis:**
+
+```javascript
+console.log(`Node Version: ${process.version}`);
+```
+
+**Research Findings:**
+
+- `process.version` in Bun → Returns emulated Node.js version (v24.3.0)
+- `process.versions.bun` → Returns actual Bun version (1.2.20)
+- `Bun.version` → Bun-specific API for version
+
+**Sources:**
+
+- [Bun — Detect the Version at Runtime](https://futurestud.io/tutorials/bun-detect-the-version-at-runtime)
+- [Get the current Bun version - Bun](https://bun.com/docs/guides/util/version)
+
+### Issue 3: Incorrect macOS Version Format
+
+**Location:** `src/bin/cli.js:75`
+
+**Root Cause:**
+
+- Code uses `os.release()` which returns kernel version (24.6.0)
+- Should use `sw_vers -productVersion` for user-facing macOS version (15.7.2)
+
+**Code Analysis:**
+
+```javascript
+console.log(`OS Release: ${os.release()}`);
+```
+
+**Kernel vs Product Version:**
+
+- `os.release()` → 24.6.0 (Darwin kernel version)
+- `sw_vers -productVersion` → 15.7.2 (macOS product version)
+
+**Research Findings:**
+The macOS `sw_vers` command provides user-facing version information:
+
+- `sw_vers -productVersion` returns the macOS version (e.g., "15.7.2", "26.0")
+- This is what users recognize as their macOS version
+
+**Sources:**
+
+- [sw_vers Man Page - macOS - SS64.com](https://ss64.com/mac/sw_vers.html)
+- [Check macOS Latest Version · For Tahoe · 2025](https://mac.install.guide/macos/check-version)
+
+### Issue 4: Argument Parsing for `--version --`
+
+**Location:** `src/bin/cli.js:52-55`
+
+**Root Cause:**
+
+- Version check happens before argument parsing
+- Only checks for exact match: `args.length === 1 && (args[0] === '--version' || args[0] === '-v')`
+- When `--version --` is passed, args = `['--version', '--']`, length is 2, fails the check
+- Falls through to argument parser which treats `--` as separator
+
+**Code Analysis:**
+
+```javascript
+if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+  printVersion();
+  process.exit(0);
+}
+```
+
+**Expected Behavior:**
+
+- `$ --version` → Show version ✓
+- `$ --version --` → Show version (should ignore trailing `--`)
+- `$ --` → "No command provided" error ✓
+- `$` → Show usage ✓
+
+## Proposed Solutions
+
+### Solution 1: Fix Screen Detection
+
+Capture both stdout and stderr when detecting tool versions:
+
+```javascript
+function getToolVersion(toolName, versionFlag) {
+  try {
+    const result = execSync(`${toolName} ${versionFlag} 2>&1`, {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+    const firstLine = result.split('\n')[0];
+    return firstLine;
+  } catch {
+    return null;
+  }
+}
+```
+
+### Solution 2: Use Bun Version
+
+Detect runtime and show appropriate version:
+
+```javascript
+// Detect if running in Bun
+const runtime = typeof Bun !== 'undefined' ? 'Bun' : 'Node.js';
+const runtimeVersion =
+  typeof Bun !== 'undefined' ? Bun.version : process.version;
+
+console.log(`${runtime} Version: ${runtimeVersion}`);
+```
+
+### Solution 3: Fix macOS Version Detection
+
+Use `sw_vers -productVersion` on macOS:
+
+```javascript
+function getOSVersion() {
+  if (process.platform === 'darwin') {
+    try {
+      return execSync('sw_vers -productVersion', { encoding: 'utf8' }).trim();
+    } catch {
+      return os.release();
+    }
+  }
+  return os.release();
+}
+
+console.log(`OS: ${process.platform}`);
+console.log(`OS Version: ${getOSVersion()}`);
+```
+
+### Solution 4: Fix Argument Parsing
+
+Check for `--version` flag regardless of other arguments:
+
+```javascript
+// Check if --version is present (ignore trailing --)
+const hasVersionFlag = args.includes('--version') || args.includes('-v');
+const isOnlyVersionWithSeparator =
+  args.length === 2 &&
+  (args[0] === '--version' || args[0] === '-v') &&
+  args[1] === '--';
+
+if ((args.length === 1 && hasVersionFlag) || isOnlyVersionWithSeparator) {
+  printVersion();
+  process.exit(0);
+}
+```
+
+## Implementation Plan
+
+1. **Fix argument parsing** - Handle `--version --` case
+2. **Fix screen detection** - Capture stderr in version detection
+3. **Replace Node with Bun** - Detect runtime and show correct version
+4. **Fix OS version** - Use `sw_vers` on macOS
+5. **Update REQUIREMENTS.md** - Remove npm references, emphasize Bun-first
+6. **Add comprehensive tests** - Cover all version scenarios
+7. **Ensure CI runs tests** - Validate quality
+
+## Testing Strategy
+
+### Test Cases Required
+
+1. **Argument Parsing Tests:**
+   - `$ --version` → Shows version
+   - `$ -v` → Shows version
+   - `$ --version --` → Shows version
+   - `$ --` → Error: No command provided
+   - `$` → Shows usage
+
+2. **Screen Detection Tests:**
+   - When screen installed → Shows version
+   - When screen not installed → Shows "not installed"
+
+3. **Runtime Detection Tests:**
+   - Running with Bun → Shows "Bun Version: X.X.X"
+   - Running with Node → Shows "Node.js Version: vX.X.X"
+
+4. **OS Version Tests:**
+   - On macOS → Shows ProductVersion (15.7.2 format)
+   - On Linux → Shows kernel version
+   - On Windows → Shows kernel version
+
+## Documentation Updates
+
+### REQUIREMENTS.md Changes Needed
+
+1. Replace all "npm install" references with "bun install"
+2. Update "Node.js >= 14.0.0" to "Bun >= 1.0.0"
+3. Update system information to show "Bun Version" instead of "Node Version"
+4. Emphasize Bun-first approach
+
+## Additional Notes
+
+- The project uses `#!/usr/bin/env bun` shebang correctly
+- Package scripts still use `node --test` which should be changed to `bun test`
+- All references to npm in documentation should be updated to bun
+- Consider removing npm-specific features if they don't work with bun
+
+## Files to Modify
+
+1. `src/bin/cli.js` - Fix all version detection issues
+2. `src/lib/args-parser.js` - No changes needed (issue is in cli.js)
+3. `REQUIREMENTS.md` - Update to Bun-first approach
+4. `package.json` - Update test script to use bun
+5. `test/cli.test.js` - Add version detection tests
+6. New: `test/version.test.js` - Comprehensive version tests
+
+## Success Criteria
+
+- ✅ `$ --version --` works same as `$ --version`
+- ✅ Screen version detected correctly when installed
+- ✅ Shows "Bun Version" instead of "Node Version"
+- ✅ macOS shows ProductVersion not kernel version
+- ✅ All tests pass locally
+- ✅ CI tests pass
+- ✅ REQUIREMENTS.md updated
+- ✅ No npm references in documentation

package/docs/case-studies/issue-22/issue-data.json

@@ -0,0 +1,12 @@
+{
+  "author": {
+    "id": "MDQ6VXNlcjE0MzE5MDQ=",
+    "is_bot": false,
+    "login": "konard",
+    "name": "Konstantin Diachenko"
+  },
+  "body": "```\nkonard@MacBook-Pro-Konstantin ~ % bun install -g start-command                      \nbun add v1.2.20 (6ad208bc)\n\ninstalled start-command@0.7.0 with binaries:\n - $\n\n1 package installed [2.40s]\nkonard@MacBook-Pro-Konstantin ~ % $ --version --              \nError: No command provided\nUsage: $ [options] [--] <command> [args...]\n       $ <command> [args...]\n\nOptions:\n  --isolated, -i <environment>      Run in isolated environment (screen, tmux, docker)\n  --attached, -a            Run in attached mode (foreground)\n  --detached, -d            Run in detached mode (background)\n  --session, -s <name>      Session name for isolation\n  --image <image>           Docker image (required for docker isolation)\n  --version, -v             Show version information\n\nExamples:\n  $ echo \"Hello World\"\n  $ npm test\n  $ --isolated tmux -- npm start\n  $ -i screen -d npm start\n  $ --isolated docker --image node:20 -- npm install\n\nFeatures:\n  - Logs all output to temporary directory\n  - Displays timestamps and exit codes\n  - Auto-reports failures for NPM packages (when gh is available)\n  - Natural language command aliases (via substitutions.lino)\n  - Process isolation via screen, tmux, or docker\n\nAlias examples:\n  $ install lodash npm package           -> npm install lodash\n  $ install 4.17.21 version of lodash npm package -> npm install lodash@4.17.21\n  $ clone https://github.com/user/repo repository -> git clone https://github.com/user/repo\nkonard@MacBook-Pro-Konstantin ~ % $ --version                 \nstart-command version: 0.7.0\n\nOS: darwin\nOS Release: 24.6.0\nNode Version: v24.3.0\nArchitecture: arm64\n\nIsolation tools:\n  screen: not installed\n  tmux: not installed\n  docker: Docker version 28.5.1, build e180ab8\nkonard@MacBook-Pro-Konstantin ~ % screen -v\nScreen version 4.00.03 (FAU) 23-Oct-06\nkonard@MacBook-Pro-Konstantin ~ % docker -v\nDocker version 28.5.1, build e180ab8\nkonard@MacBook-Pro-Konstantin ~ % sw_vers\nProductName:\t\tmacOS\nProductVersion:\t\t15.7.2\nBuildVersion:\t\t24G325\nkonard@MacBook-Pro-Konstantin ~ % \n```\n\nThe problems are:\n\n- `screen` tool version was not detected.\n- We use Bun, not Node.js (double check that, and also remove suggestions to install it using npm in the docs. Our tool should be Bun first and Bun only. For all scripts and shebangs we should use bun, not node. So in `--version` there should be bun version, not `node.js` version.\n- OS version detection was wrong.\n- `$ --version --` should work the same as `$ --version`, only `$ --` or `$` should result in `No command provided`.\n\nMake sure we have tests for all these (and these tests should be executed in CI, so we guarantee the quality). Also [REQUIREMENTS.md](https://github.com/link-foundation/start/blob/main/REQUIREMENTS.md) should be updated as needed.\n\nPlease download all logs and data related about the issue to this repository, make sure we compile that data to `./docs/case-studies/issue-{id}` folder, and use it to do deep case study analysis (also make sure to search online for additional facts and data), in which we will reconstruct timeline/sequence of events, find root causes of the problem, and propose possible solutions.",
+  "comments": [],
+  "createdAt": "2025-12-23T17:55:53Z",
+  "title": "--version issues"
+}

package/experiments/test-screen-attached.js

@@ -1,7 +1,7 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * Experiment to test different approaches for running screen in attached mode
- * from Node.js without a TTY
+ * from Bun without a TTY
  */
 
 const { spawn, spawnSync, execSync } = require('child_process');

package/experiments/test-screen-logfile.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * Experiment to test screen's logfile capture functionality
  * to understand the root cause of issue #15

package/experiments/test-screen-modes.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * Experiment to test different screen invocation modes
  * This helps understand how screen behaves in different contexts

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "start-command",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "index.js",
   "bin": {
     "$": "./src/bin/cli.js"
   },
   "scripts": {
-    "test": "node --test test/",
+    "test": "bun test test/",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "check:file-size": "node scripts/check-file-size.mjs",
-    "check": "npm run lint && npm run format:check && npm run check:file-size",
+    "check:file-size": "bun scripts/check-file-size.mjs",
+    "check": "bun run lint && bun run format:check && bun run check:file-size",
     "prepare": "husky || true",
     "changeset": "changeset",
-    "changeset:version": "node scripts/changeset-version.mjs",
+    "changeset:version": "bun scripts/changeset-version.mjs",
     "changeset:publish": "changeset publish",
     "changeset:status": "changeset status --since=origin/main"
   },

package/src/bin/cli.js

@@ -49,7 +49,14 @@ const config = {
 const args = process.argv.slice(2);
 
 // Handle --version flag
-if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+// Support: $ --version, $ -v, $ --version --
+// The trailing -- should be ignored for version check
+const hasVersionFlag =
+  args.length >= 1 && (args[0] === '--version' || args[0] === '-v');
+const isVersionOnly =
+  args.length === 1 || (args.length === 2 && args[1] === '--');
+
+if (hasVersionFlag && isVersionOnly) {
   printVersion();
   process.exit(0);
 }
@@ -70,10 +77,30 @@ function printVersion() {
   console.log(`start-command version: ${startCommandVersion}`);
   console.log('');
 
+  // Get runtime information (Bun or Node.js)
+  const runtime = typeof Bun !== 'undefined' ? 'Bun' : 'Node.js';
+  const runtimeVersion =
+    typeof Bun !== 'undefined' ? Bun.version : process.version;
+
   // Get OS information
   console.log(`OS: ${process.platform}`);
-  console.log(`OS Release: ${os.release()}`);
-  console.log(`Node Version: ${process.version}`);
+
+  // Get OS version (use sw_vers on macOS for user-friendly version)
+  let osVersion = os.release();
+  if (process.platform === 'darwin') {
+    try {
+      osVersion = execSync('sw_vers -productVersion', {
+        encoding: 'utf8',
+        timeout: 5000,
+      }).trim();
+    } catch {
+      // Fallback to kernel version if sw_vers fails
+      osVersion = os.release();
+    }
+  }
+
+  console.log(`OS Version: ${osVersion}`);
+  console.log(`${runtime} Version: ${runtimeVersion}`);
   console.log(`Architecture: ${process.arch}`);
   console.log('');
 
@@ -113,9 +140,10 @@ function printVersion() {
  */
 function getToolVersion(toolName, versionFlag) {
   try {
-    const result = execSync(`${toolName} ${versionFlag}`, {
+    // Redirect stderr to stdout (2>&1) to capture version info from stderr
+    // Some tools like screen output version to stderr instead of stdout
+    const result = execSync(`${toolName} ${versionFlag} 2>&1`, {
       encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 5000,
     }).trim();
 
@@ -149,10 +177,10 @@ function printUsage() {
   console.log('');
   console.log('Examples:');
   console.log('  $ echo "Hello World"');
-  console.log('  $ npm test');
-  console.log('  $ --isolated tmux -- npm start');
-  console.log('  $ -i screen -d npm start');
-  console.log('  $ --isolated docker --image node:20 -- npm install');
+  console.log('  $ bun test');
+  console.log('  $ --isolated tmux -- bun start');
+  console.log('  $ -i screen -d bun start');
+  console.log('  $ --isolated docker --image oven/bun:latest -- bun install');
   console.log('');
   console.log('Features:');
   console.log('  - Logs all output to temporary directory');
@@ -313,6 +341,11 @@ function runDirect(cmd) {
   let logContent = '';
   const startTime = getTimestamp();
 
+  // Get runtime information
+  const runtime = typeof Bun !== 'undefined' ? 'Bun' : 'Node.js';
+  const runtimeVersion =
+    typeof Bun !== 'undefined' ? Bun.version : process.version;
+
   // Log header
   logContent += `=== Start Command Log ===\n`;
   logContent += `Timestamp: ${startTime}\n`;
@@ -325,7 +358,7 @@ function runDirect(cmd) {
   }
   logContent += `Shell: ${shell}\n`;
   logContent += `Platform: ${process.platform}\n`;
-  logContent += `Node Version: ${process.version}\n`;
+  logContent += `${runtime} Version: ${runtimeVersion}\n`;
   logContent += `Working Directory: ${process.cwd()}\n`;
   logContent += `${'='.repeat(50)}\n\n`;
 
@@ -474,7 +507,7 @@ function handleFailure(cmdName, fullCommand, exitCode, logPath) {
     }
   } else {
     console.log('gh-upload-log not installed - log upload skipped');
-    console.log('Install with: npm install -g gh-upload-log');
+    console.log('Install with: bun install -g gh-upload-log');
   }
 
   // Check if we can create issues in this repository
@@ -745,6 +778,11 @@ function createIssue(repoInfo, fullCommand, exitCode, logUrl) {
   try {
     const title = `Command failed with exit code ${exitCode}: ${fullCommand.substring(0, 50)}${fullCommand.length > 50 ? '...' : ''}`;
 
+    // Get runtime information
+    const runtime = typeof Bun !== 'undefined' ? 'Bun' : 'Node.js';
+    const runtimeVersion =
+      typeof Bun !== 'undefined' ? Bun.version : process.version;
+
     let body = `## Command Execution Failure Report\n\n`;
     body += `**Command:** \`${fullCommand}\`\n\n`;
     body += `**Exit Code:** ${exitCode}\n\n`;
@@ -752,7 +790,7 @@ function createIssue(repoInfo, fullCommand, exitCode, logUrl) {
     body += `### System Information\n\n`;
     body += `- **Platform:** ${process.platform}\n`;
     body += `- **OS Release:** ${os.release()}\n`;
-    body += `- **Node Version:** ${process.version}\n`;
+    body += `- **${runtime} Version:** ${runtimeVersion}\n`;
     body += `- **Architecture:** ${process.arch}\n\n`;
 
     if (logUrl) {

package/test/cli.test.js

@@ -38,12 +38,15 @@ describe('CLI version flag', () => {
     );
     assert.ok(result.stdout.includes('OS:'), 'Should display OS');
     assert.ok(
-      result.stdout.includes('OS Release:'),
-      'Should display OS Release'
+      result.stdout.includes('OS Version:'),
+      'Should display OS Version'
     );
+    // Check for either Bun or Node.js version depending on runtime
+    const hasBunVersion = result.stdout.includes('Bun Version:');
+    const hasNodeVersion = result.stdout.includes('Node.js Version:');
     assert.ok(
-      result.stdout.includes('Node Version:'),
-      'Should display Node Version'
+      hasBunVersion || hasNodeVersion,
+      'Should display Bun Version or Node.js Version'
     );
     assert.ok(
       result.stdout.includes('Architecture:'),

package/test/version.test.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+/**
+ * Tests for --version flag behavior
+ * Tests for issue #22: --version issues
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+// Path to the CLI
+const cliPath = path.resolve(__dirname, '../src/bin/cli.js');
+
+/**
+ * Helper to run the CLI command
+ */
+function runCli(args) {
+  try {
+    // Use '--' separator to ensure args are passed to the script, not consumed by bun
+    // This is important for testing edge cases like passing '--' as an argument
+    const result = spawnSync('bun', [cliPath, '--', ...args], {
+      encoding: 'utf8',
+      timeout: 5000,
+      env: {
+        ...process.env,
+        START_DISABLE_AUTO_ISSUE: '1',
+        START_DISABLE_LOG_UPLOAD: '1',
+      },
+    });
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.status,
+      error: result.error,
+    };
+  } catch (error) {
+    return {
+      stdout: '',
+      stderr: error.message,
+      exitCode: 1,
+      error,
+    };
+  }
+}
+
+describe('Version Flag Tests', () => {
+  describe('Basic version flag', () => {
+    it('should show version with --version', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /start-command version:/,
+        'Should show start-command version'
+      );
+    });
+
+    it('should show version with -v', () => {
+      const result = runCli(['-v']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /start-command version:/,
+        'Should show start-command version'
+      );
+    });
+
+    it('should show version with --version -- (trailing separator)', () => {
+      const result = runCli(['--version', '--']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /start-command version:/,
+        'Should show start-command version with trailing --'
+      );
+      assert.doesNotMatch(
+        result.stderr,
+        /No command provided/,
+        'Should not show "No command provided" error'
+      );
+    });
+  });
+
+  describe('Runtime detection', () => {
+    it('should show Bun version when running with Bun', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+
+      // When running with Bun, should show "Bun Version"
+      if (typeof Bun !== 'undefined') {
+        assert.match(
+          result.stdout,
+          /Bun Version:/,
+          'Should show "Bun Version:" when running with Bun'
+        );
+        assert.doesNotMatch(
+          result.stdout,
+          /Node\.js Version:/,
+          'Should not show "Node.js Version:" when running with Bun'
+        );
+      } else {
+        // When running with Node.js, should show "Node.js Version"
+        assert.match(
+          result.stdout,
+          /Node\.js Version:/,
+          'Should show "Node.js Version:" when running with Node.js'
+        );
+      }
+    });
+  });
+
+  describe('OS version detection', () => {
+    it('should show OS information', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(result.stdout, /OS:/, 'Should show OS');
+      assert.match(result.stdout, /OS Version:/, 'Should show OS Version');
+    });
+
+    it('should show macOS ProductVersion on darwin', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+
+      if (process.platform === 'darwin') {
+        // Get the actual macOS version using sw_vers
+        const macOSVersion = execSync('sw_vers -productVersion', {
+          encoding: 'utf8',
+        }).trim();
+
+        // Version output should contain the ProductVersion, not the kernel version
+        assert.match(
+          result.stdout,
+          new RegExp(`OS Version: ${macOSVersion.replace('.', '\\.')}`),
+          `Should show macOS ProductVersion (${macOSVersion}), not kernel version`
+        );
+
+        // Should NOT show kernel version (which starts with 2x on modern macOS)
+        const kernelVersion = os.release();
+        if (kernelVersion.startsWith('2')) {
+          assert.doesNotMatch(
+            result.stdout,
+            new RegExp(`OS Version: ${kernelVersion.replace('.', '\\.')}`),
+            `Should not show kernel version (${kernelVersion})`
+          );
+        }
+      }
+    });
+  });
+
+  describe('Tool version detection', () => {
+    it('should detect screen version if installed', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+
+      // Check if screen is actually installed
+      try {
+        const screenVersion = execSync('screen --version 2>&1', {
+          encoding: 'utf8',
+          timeout: 5000,
+        });
+
+        if (screenVersion) {
+          // If screen is installed, it should not show "not installed"
+          assert.doesNotMatch(
+            result.stdout,
+            /screen: not installed/,
+            'Should not show "screen: not installed" when screen is available'
+          );
+          assert.match(
+            result.stdout,
+            /screen:/,
+            'Should show screen version info'
+          );
+        }
+      } catch {
+        // Screen is not installed, should show "not installed"
+        assert.match(
+          result.stdout,
+          /screen: not installed/,
+          'Should show "screen: not installed" when screen is unavailable'
+        );
+      }
+    });
+
+    it('should detect tmux version if installed', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+
+      // Check if tmux is actually installed
+      try {
+        const tmuxVersion = execSync('tmux -V 2>&1', {
+          encoding: 'utf8',
+          timeout: 5000,
+        });
+
+        if (tmuxVersion) {
+          // If tmux is installed, it should not show "not installed"
+          assert.doesNotMatch(
+            result.stdout,
+            /tmux: not installed/,
+            'Should not show "tmux: not installed" when tmux is available'
+          );
+        }
+      } catch {
+        // tmux is not installed, should show "not installed"
+        assert.match(
+          result.stdout,
+          /tmux: not installed/,
+          'Should show "tmux: not installed" when tmux is unavailable'
+        );
+      }
+    });
+
+    it('should detect docker version if installed', () => {
+      const result = runCli(['--version']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+
+      // Check if docker is actually installed
+      try {
+        const dockerVersion = execSync('docker --version 2>&1', {
+          encoding: 'utf8',
+          timeout: 5000,
+        });
+
+        if (dockerVersion) {
+          // If docker is installed, it should not show "not installed"
+          assert.doesNotMatch(
+            result.stdout,
+            /docker: not installed/,
+            'Should not show "docker: not installed" when docker is available'
+          );
+        }
+      } catch {
+        // docker is not installed, should show "not installed"
+        assert.match(
+          result.stdout,
+          /docker: not installed/,
+          'Should show "docker: not installed" when docker is unavailable'
+        );
+      }
+    });
+  });
+
+  describe('Error cases', () => {
+    it('should error with "No command provided" for $ --', () => {
+      const result = runCli(['--']);
+      assert.strictEqual(result.exitCode, 1, 'Exit code should be 1');
+      const output = result.stdout + result.stderr;
+      assert.match(
+        output,
+        /No command provided/,
+        'Should show "No command provided" error for --'
+      );
+    });
+
+    it('should error with "No command provided" for no args', () => {
+      const result = runCli([]);
+      assert.strictEqual(result.exitCode, 0, 'Should show usage and exit 0');
+      assert.match(result.stdout, /Usage:/, 'Should show usage message');
+    });
+  });
+});