start-command 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # start-command
 
+## 0.7.2
+
+### Patch Changes
+
+- fa0fb23: docs: Update documentation to Bun-first approach
+  - Remove npm installation option from README.md
+  - Update examples to use bun commands instead of npm
+  - Change package.json engines from node to bun
+  - Update REQUIREMENTS.md to remove Node.js alternative
+
+## 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/README.md

@@ -4,18 +4,12 @@ Gamification of coding - execute any command with automatic logging and ability
 
 ## Installation
 
-We recommend using [Bun](https://bun.sh) for the best performance:
+Install using [Bun](https://bun.sh):
 
 ```bash
 bun install -g start-command
 ```
 
-Or using npm:
-
-```bash
-npm install -g start-command
-```
-
 ## Usage
 
 The `$` command acts as a wrapper for any shell command:
@@ -123,16 +117,16 @@ Run commands in isolated environments using terminal multiplexers or containers:
 
 ```bash
 # Run in tmux (attached by default)
-$ --isolated tmux -- npm start
+$ --isolated tmux -- bun start
 
 # Run in screen detached
-$ --isolated screen --detached -- npm start
+$ --isolated screen --detached -- bun start
 
 # Run in docker container
-$ --isolated docker --image node:20 -- npm install
+$ --isolated docker --image oven/bun:latest -- bun install
 
 # Short form with custom session name
-$ -i tmux -s my-session -d npm start
+$ -i tmux -s my-session -d bun start
 ```
 
 #### Supported Backends
@@ -169,7 +163,7 @@ The tool works in any environment:
 
 ### Required
 
-- Node.js >= 14.0.0
+- [Bun](https://bun.sh) >= 1.0.0
 
 ### Optional (for full auto-reporting)
 
@@ -183,7 +177,7 @@ To set up auto-reporting:
 gh auth login
 
 # Install log uploader
-npm install -g gh-upload-log
+bun install -g gh-upload-log
 ```
 
 ## How It Works
@@ -214,10 +208,10 @@ Example:
 
 ```bash
 # Run without auto-issue creation
-START_DISABLE_AUTO_ISSUE=1 $ npm test
+START_DISABLE_AUTO_ISSUE=1 $ bun test
 
 # Use custom log directory
-START_LOG_DIR=./logs $ npm test
+START_LOG_DIR=./logs $ bun test
 
 # Disable substitutions (use raw command)
 START_DISABLE_SUBSTITUTIONS=1 $ install lodash npm package
@@ -237,10 +231,10 @@ Log files are saved as `start-command-{timestamp}-{random}.log` and contain:
 ```
 === Start Command Log ===
 Timestamp: 2024-01-15 10:30:45.123
-Command: npm test
+Command: bun test
 Shell: /bin/bash
 Platform: linux
-Node Version: v18.17.0
+Bun Version: 1.2.0
 Working Directory: /home/user/project
 ==================================================
 

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,7 @@ Repository not detected - automatic issue creation skipped
 
 ### Required
 
-- Node.js >= 14.0.0
+- **Bun >= 1.0.0** (primary runtime)
 - `child_process` (built-in)
 - `os` (built-in)
 - `fs` (built-in)

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

@@ -0,0 +1,547 @@
+# 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
+
+## Implementation Status
+
+**Status:** 🔄 In Progress (Second Iteration)
+
+### First Iteration (PR #23 - Merged to Main)
+
+The initial fixes were merged to `main` branch via PR #23, addressing:
+
+- Version flag handling with trailing `--`
+- Runtime detection (Bun vs Node.js)
+- macOS version detection using `sw_vers`
+- Basic screen detection using `2>&1`
+
+### Second Iteration (This PR) - The Screen Detection Bug
+
+After v0.7.1 was released, users on macOS still reported:
+
+```
+screen: not installed
+```
+
+Even though screen was installed:
+
+```bash
+$ screen -v
+Screen version 4.00.03 (FAU) 23-Oct-06
+```
+
+#### Deep Root Cause Analysis
+
+**The Problem:** The macOS bundled version of GNU Screen (4.00.03) returns a **non-zero exit code** when running `screen --version` or `screen -v`, even though it successfully outputs the version information.
+
+**Discovery Process:**
+
+1. Searched for known issues with GNU Screen version flag
+2. Found reference to [GNU Screen v.4.8.0 release notes](https://savannah.gnu.org/forum/forum.php?forum_id=9665)
+3. The release notes mention: "Make screen exit code be 0 when checking --version"
+
+**Root Cause Confirmed:**
+This was a **known bug in GNU Screen prior to version 4.8.0** where the `--version` flag would exit with a non-zero status code.
+
+- macOS bundled version: 4.00.03 (affected by bug)
+- Bug fix version: 4.8.0+
+- Linux typically has newer versions via package managers
+
+**Why Previous Fix Didn't Work:**
+
+The previous fix used `execSync()` with `2>&1` to capture stderr:
+
+```javascript
+const result = execSync(`${toolName} ${versionFlag} 2>&1`, {
+  encoding: 'utf8',
+  timeout: 5000,
+}).trim();
+```
+
+**Problem:** `execSync()` throws an exception when the command returns non-zero exit code, so even though the output was captured correctly, the `catch` block returned `null`.
+
+#### The Solution
+
+Use `spawnSync()` instead of `execSync()` to capture output **regardless of exit code**:
+
+```javascript
+function getToolVersion(toolName, versionFlag, verbose = false) {
+  const isWindows = process.platform === 'win32';
+  const whichCmd = isWindows ? 'where' : 'which';
+
+  // First, check if the tool exists in PATH
+  try {
+    execSync(`${whichCmd} ${toolName}`, {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    // Tool not found in PATH
+    return null;
+  }
+
+  // Tool exists, try to get version using spawnSync
+  // This captures output regardless of exit code
+  const result = spawnSync(toolName, [versionFlag], {
+    encoding: 'utf8',
+    timeout: 5000,
+    shell: false,
+  });
+
+  // Combine stdout and stderr
+  const output = ((result.stdout || '') + (result.stderr || '')).trim();
+
+  if (!output) {
+    return null;
+  }
+
+  return output.split('\n')[0];
+}
+```
+
+#### Additional Improvements
+
+1. **`--verbose` flag support** - Users can now debug version detection:
+
+   ```bash
+   $ --version --verbose
+   ```
+
+   This shows detailed debugging information about tool detection.
+
+2. **`-v` flag for screen** - Changed from `--version` to `-v` which is more universally supported.
+
+3. **Comprehensive test coverage** - Added 14 tests for version detection scenarios.
+
+### Changes Made (Second Iteration)
+
+#### src/bin/cli.js
+
+1. **Added `spawnSync` import:**
+
+   ```javascript
+   const { spawn, execSync, spawnSync } = require('child_process');
+   ```
+
+2. **Enhanced version flag handling with verbose support:**
+
+   ```javascript
+   const hasVerboseWithVersion =
+     hasVersionFlag &&
+     args.some((arg) => arg === '--verbose' || arg === '--debug');
+
+   if (hasVersionFlag && isVersionOnly) {
+     printVersion(hasVerboseWithVersion || config.verbose);
+     process.exit(0);
+   }
+   ```
+
+3. **Fixed getToolVersion to use spawnSync:**
+   - First checks if tool exists using `which`/`where`
+   - Uses `spawnSync` to capture output regardless of exit code
+   - Combines stdout and stderr
+   - Supports verbose mode for debugging
+
+4. **Updated printVersion to accept verbose parameter:**
+   - Shows `[verbose]` messages when debugging
+   - Logs tool detection details
+
+#### test/version.test.js
+
+Added 3 new tests for verbose mode:
+
+- `--version --verbose`
+- `--version --debug`
+- `START_VERBOSE=1` environment variable
+
+### Test Results
+
+All 84 tests passing across 4 test files:
+
+- `test/version.test.js`: 14 tests
+- `test/cli.test.js`: Passing
+- `test/args-parser.test.js`: Passing
+- `test/isolation.test.js`: Passing
+- `test/substitution.test.js`: 22 tests
+
+### Verified Behavior
+
+```bash
+$ --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
+```
+
+```bash
+$ --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
+```
+
+## Key Learnings
+
+1. **Exit codes matter**: Some tools return non-zero exit codes even for successful operations. Always consider using `spawnSync` when you need to capture output regardless of exit status.
+
+2. **macOS bundled tools are often outdated**: The macOS bundled version of screen (4.00.03 from 2006) has known bugs fixed in newer versions.
+
+3. **Testing on multiple platforms is crucial**: The bug only manifested on macOS with the bundled screen, not on Linux with modern screen versions.
+
+4. **Verbose mode is invaluable for debugging**: Adding `--verbose` support allows users to self-diagnose issues.
+
+## References
+
+- [GNU Screen v.4.8.0 Release Notes](https://savannah.gnu.org/forum/forum.php?forum_id=9665) - Documents the exit code fix
+- [screen Man Page - macOS](https://ss64.com/mac/screen.html) - macOS screen documentation
+- [Node.js spawnSync](https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options) - Alternative to execSync that doesn't throw on non-zero exit

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.2",
   "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"
   },
@@ -30,7 +30,7 @@
   "author": "",
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "bun": ">=1.0.0"
   },
   "repository": {
     "type": "git",

package/src/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-const { spawn, execSync } = require('child_process');
+const { spawn, execSync, spawnSync } = require('child_process');
 const process = require('process');
 const os = require('os');
 const fs = require('fs');
@@ -49,8 +49,28 @@ const config = {
 const args = process.argv.slice(2);
 
 // Handle --version flag
-if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
-  printVersion();
+// Support: $ --version, $ -v, $ --version --
+// The trailing -- should be ignored for version check
+// Also support --verbose flag for debugging: $ --version --verbose
+const hasVersionFlag =
+  args.length >= 1 && (args[0] === '--version' || args[0] === '-v');
+
+// Check for --verbose flag in version context
+const hasVerboseWithVersion =
+  hasVersionFlag &&
+  args.some((arg) => arg === '--verbose' || arg === '--debug');
+
+// Determine if this is a version-only call
+// Allow: --version, -v, --version --, --version --verbose, etc.
+const versionRelatedArgs = ['--version', '-v', '--', '--verbose', '--debug'];
+const isVersionOnly =
+  hasVersionFlag &&
+  args.every(
+    (arg) => versionRelatedArgs.includes(arg) || arg === args[0] // Allow the version flag itself
+  );
+
+if (hasVersionFlag && isVersionOnly) {
+  printVersion(hasVerboseWithVersion || config.verbose);
   process.exit(0);
 }
 
@@ -61,8 +81,9 @@ if (args.length === 0) {
 
 /**
  * Print version information
+ * @param {boolean} verbose - Whether to show verbose debugging info
  */
-function printVersion() {
+function printVersion(verbose = false) {
   // Get package version
   const packageJson = require('../../package.json');
   const startCommandVersion = packageJson.version;
@@ -70,18 +91,50 @@ 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();
+      if (verbose) {
+        console.log(`[verbose] macOS version from sw_vers: ${osVersion}`);
+      }
+    } catch {
+      // Fallback to kernel version if sw_vers fails
+      osVersion = os.release();
+      if (verbose) {
+        console.log(
+          `[verbose] sw_vers failed, using kernel version: ${osVersion}`
+        );
+      }
+    }
+  }
+
+  console.log(`OS Version: ${osVersion}`);
+  console.log(`${runtime} Version: ${runtimeVersion}`);
   console.log(`Architecture: ${process.arch}`);
   console.log('');
 
   // Check for installed isolation tools
   console.log('Isolation tools:');
 
-  // Check screen
-  const screenVersion = getToolVersion('screen', '--version');
+  if (verbose) {
+    console.log('[verbose] Checking isolation tools...');
+  }
+
+  // Check screen (use -v flag for compatibility with older versions)
+  const screenVersion = getToolVersion('screen', '-v', verbose);
   if (screenVersion) {
     console.log(`  screen: ${screenVersion}`);
   } else {
@@ -89,7 +142,7 @@ function printVersion() {
   }
 
   // Check tmux
-  const tmuxVersion = getToolVersion('tmux', '-V');
+  const tmuxVersion = getToolVersion('tmux', '-V', verbose);
   if (tmuxVersion) {
     console.log(`  tmux: ${tmuxVersion}`);
   } else {
@@ -97,7 +150,7 @@ function printVersion() {
   }
 
   // Check docker
-  const dockerVersion = getToolVersion('docker', '--version');
+  const dockerVersion = getToolVersion('docker', '--version', verbose);
   if (dockerVersion) {
     console.log(`  docker: ${dockerVersion}`);
   } else {
@@ -109,23 +162,53 @@ function printVersion() {
  * Get version of an installed tool
  * @param {string} toolName - Name of the tool
  * @param {string} versionFlag - Flag to get version (e.g., '--version', '-V')
+ * @param {boolean} verbose - Whether to log verbose information
  * @returns {string|null} Version string or null if not installed
  */
-function getToolVersion(toolName, versionFlag) {
+function getToolVersion(toolName, versionFlag, verbose = false) {
+  const isWindows = process.platform === 'win32';
+  const whichCmd = isWindows ? 'where' : 'which';
+
+  // First, check if the tool exists in PATH
   try {
-    const result = execSync(`${toolName} ${versionFlag}`, {
+    execSync(`${whichCmd} ${toolName}`, {
       encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 5000,
-    }).trim();
-
-    // Extract version number from output
-    // Most tools output version in various formats, so we'll return the first line
-    const firstLine = result.split('\n')[0];
-    return firstLine;
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
   } catch {
+    // Tool not found in PATH
+    if (verbose) {
+      console.log(`[verbose] ${toolName}: not found in PATH`);
+    }
+    return null;
+  }
+
+  // Tool exists, try to get version using spawnSync
+  // This captures output regardless of exit code (some tools like older screen
+  // versions return non-zero exit code even when showing version successfully)
+  const result = spawnSync(toolName, [versionFlag], {
+    encoding: 'utf8',
+    timeout: 5000,
+    shell: false,
+  });
+
+  // Combine stdout and stderr (some tools output version to stderr)
+  const output = ((result.stdout || '') + (result.stderr || '')).trim();
+
+  if (verbose) {
+    console.log(
+      `[verbose] ${toolName} ${versionFlag}: exit=${result.status}, output="${output.substring(0, 100)}"`
+    );
+  }
+
+  if (!output) {
     return null;
   }
+
+  // Return the first line of output
+  const firstLine = output.split('\n')[0];
+  return firstLine || null;
 }
 
 /**
@@ -149,10 +232,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 +396,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 +413,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 +562,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 +833,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 +845,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,310 @@
+#!/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('Verbose mode', () => {
+    it('should show verbose output with --version --verbose', () => {
+      const result = runCli(['--version', '--verbose']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /start-command version:/,
+        'Should show start-command version'
+      );
+      assert.match(
+        result.stdout,
+        /\[verbose\]/,
+        'Should show verbose output markers'
+      );
+    });
+
+    it('should show verbose output with --version --debug', () => {
+      const result = runCli(['--version', '--debug']);
+      assert.strictEqual(result.exitCode, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /\[verbose\]/,
+        'Should show verbose output with --debug flag'
+      );
+    });
+
+    it('should show verbose output with START_VERBOSE=1', () => {
+      const result = spawnSync('bun', [cliPath, '--version'], {
+        encoding: 'utf8',
+        timeout: 5000,
+        env: {
+          ...process.env,
+          START_VERBOSE: '1',
+          START_DISABLE_AUTO_ISSUE: '1',
+          START_DISABLE_LOG_UPLOAD: '1',
+        },
+      });
+      assert.strictEqual(result.status, 0, 'Exit code should be 0');
+      assert.match(
+        result.stdout,
+        /\[verbose\]/,
+        'Should show verbose output with START_VERBOSE=1'
+      );
+    });
+  });
+
+  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');
+    });
+  });
+});