start-command 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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
+
+- 9e24fb5: Add --version flag to display comprehensive version and system information. Users can now run `$ --version` or `$ -v` to see the version of start-command, system details, and versions of isolation tools (screen, tmux, docker).
+
 ## 0.6.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-18/README.md

@@ -0,0 +1,343 @@
+# Case Study: Issue #18 - Missing `--version` Option Support
+
+## Executive Summary
+
+This case study documents the investigation, root cause analysis, and resolution of Issue #18, which identified the absence of a `--version` flag in the start-command CLI tool. The issue prevented users from easily determining the version of the tool and its dependencies, which is crucial for debugging and troubleshooting.
+
+## Timeline of Events
+
+### 2025-12-23 12:53:10 UTC - Issue Created
+
+- **Reporter**: @konard
+- **Issue**: [#18 - We need to ensure `start-command --version` option is supported](https://github.com/link-foundation/start/issues/18)
+- **Labels**: bug, enhancement
+
+### Initial Discovery
+
+The user attempted to run `$ --version` expecting version information but instead received unexpected behavior:
+
+```bash
+$ --version
+[2025-12-23 12:51:15.314] Starting: --version
+
+zsh 5.9 (arm64-apple-darwin24.0)
+
+[2025-12-23 12:51:15.322] Finished
+Exit code: 0
+```
+
+The command was interpreted as trying to execute `--version` as a shell command, which fell through to the default shell (`zsh`) and displayed the shell's version instead of the start-command version.
+
+### 2025-12-23 15:59:11 UTC - Issue Updated
+
+The issue was updated with additional context and requirements.
+
+## Problem Analysis
+
+### Root Cause
+
+The `start-command` CLI tool (`src/bin/cli.js`) did not have a dedicated handler for the `--version` or `-v` flags. The argument parser treated any unknown flags as potential commands, leading to:
+
+1. **Unexpected behavior**: `$ --version` executed `--version` as a shell command
+2. **Poor user experience**: No standard way to check the tool version
+3. **Debugging challenges**: Users couldn't easily verify which version they were running
+4. **Missing dependency information**: No visibility into isolation tool versions (screen, tmux, docker)
+
+### Impact Assessment
+
+**Severity**: Medium
+
+- **User Experience**: Users had no standard way to check version information
+- **Debugging**: Troubleshooting was more difficult without version info
+- **Best Practices**: Missing a fundamental CLI feature expected by users
+
+**Affected Components**:
+
+- `src/bin/cli.js` - Main CLI entry point
+- Documentation/Help text
+- CI/CD testing coverage
+
+## Investigation Process
+
+### Analysis Steps
+
+1. **Code Review** (`src/bin/cli.js:48-60`):
+   - Examined argument parsing logic
+   - Identified that only empty arguments triggered usage display
+   - No special handling for `--version` flag
+
+2. **Argument Parser Review** (`src/lib/args-parser.js`):
+   - Confirmed that wrapper options didn't include `--version`
+   - Parser passed unknown flags to command execution
+
+3. **Test Coverage Review**:
+   - Found no existing tests for version display
+   - Identified gap in CLI behavior testing
+
+4. **User Expectation Analysis**:
+   - Standard CLI tools support `--version` and `-v`
+   - Users expect version information for debugging
+   - Version info should include dependencies
+
+## Solution Design
+
+### Requirements
+
+Based on the issue description, the solution needed to:
+
+1. Support both `--version` and `-v` flags
+2. Display start-command version from package.json
+3. Show OS and system information:
+   - OS platform
+   - OS release
+   - Node.js version
+   - Architecture
+4. Display versions of isolation tools:
+   - screen
+   - tmux
+   - docker
+5. Indicate when tools are not installed
+6. Include comprehensive CI tests
+
+### Implementation Strategy
+
+1. **Version Detection** (`src/bin/cli.js:51-55`):
+   - Check for `--version` or `-v` as sole argument
+   - Call dedicated `printVersion()` function
+   - Exit with code 0
+
+2. **Version Information Display** (`src/bin/cli.js:62-106`):
+   - Read version from `package.json`
+   - Use Node.js `os` module for system info
+   - Execute version commands for each tool
+   - Handle missing tools gracefully
+
+3. **Tool Version Helper** (`src/bin/cli.js:108-129`):
+   - Generic function to check tool versions
+   - Timeout protection (5 seconds)
+   - Error handling for missing tools
+   - Return first line of version output
+
+4. **Test Coverage** (`test/cli.test.js`):
+   - Test `--version` flag
+   - Test `-v` shorthand
+   - Verify correct package version
+   - Test basic CLI behavior
+   - Ensure usage text includes `--version`
+
+## Implementation Details
+
+### Code Changes
+
+#### 1. CLI Version Handler
+
+```javascript
+// Handle --version flag
+if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+  printVersion();
+  process.exit(0);
+}
+```
+
+#### 2. Version Display Function
+
+```javascript
+function printVersion() {
+  // Get package version
+  const packageJson = require('../../package.json');
+  const startCommandVersion = packageJson.version;
+
+  console.log(`start-command version: ${startCommandVersion}`);
+  console.log('');
+
+  // Get OS information
+  console.log(`OS: ${process.platform}`);
+  console.log(`OS Release: ${os.release()}`);
+  console.log(`Node Version: ${process.version}`);
+  console.log(`Architecture: ${process.arch}`);
+  console.log('');
+
+  // Check for installed isolation tools
+  console.log('Isolation tools:');
+
+  const screenVersion = getToolVersion('screen', '--version');
+  if (screenVersion) {
+    console.log(`  screen: ${screenVersion}`);
+  } else {
+    console.log('  screen: not installed');
+  }
+
+  // Similar for tmux and docker...
+}
+```
+
+#### 3. Tool Version Helper
+
+```javascript
+function getToolVersion(toolName, versionFlag) {
+  try {
+    const result = execSync(`${toolName} ${versionFlag}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+
+    const firstLine = result.split('\n')[0];
+    return firstLine;
+  } catch {
+    return null;
+  }
+}
+```
+
+#### 4. Updated Usage Text
+
+```javascript
+console.log('  --version, -v             Show version information');
+```
+
+### Test Implementation
+
+Created `test/cli.test.js` with comprehensive test coverage:
+
+- Version flag tests (both `--version` and `-v`)
+- Package version verification
+- Basic CLI behavior tests
+- Usage text verification
+
+## Verification and Testing
+
+### Test Results
+
+All tests passed successfully:
+
+```
+✓ CLI version flag
+  ✓ should display version with --version
+  ✓ should display version with -v
+  ✓ should show correct package version
+✓ CLI basic behavior
+  ✓ should show usage when no arguments provided
+  ✓ should show usage when no command provided after --
+```
+
+Total: 71 tests passed across all test suites.
+
+### Manual Testing
+
+```bash
+$ bun src/bin/cli.js --version
+start-command version: 0.6.0
+
+OS: linux
+OS Release: 6.8.0-90-generic
+Node Version: v24.3.0
+Architecture: x64
+
+Isolation tools:
+  screen: Screen version 4.09.01 (GNU) 20-Aug-23
+  tmux: tmux 3.4
+  docker: not installed
+```
+
+## Lessons Learned
+
+### What Went Well
+
+1. **Clear Requirements**: Issue description provided specific requirements
+2. **Comprehensive Solution**: Implementation exceeded basic requirements by including dependency versions
+3. **Good Test Coverage**: Tests ensure the feature won't regress
+4. **Defensive Programming**: Tool version detection handles missing tools gracefully
+
+### Areas for Improvement
+
+1. **Earlier Detection**: This fundamental feature should have been included from the start
+2. **Pre-commit Checklist**: Could have caught this during initial development
+3. **User Feedback**: Faster response to user needs
+
+### Best Practices Applied
+
+1. **Version Information Sources**: Used package.json as single source of truth
+2. **Error Handling**: Gracefully handle missing tools with timeout protection
+3. **User Experience**: Clear, well-formatted output
+4. **Testing**: Comprehensive test coverage for new feature
+5. **Documentation**: Updated usage text to include new flag
+
+## Recommendations
+
+### Immediate Actions
+
+1. ✅ Implement `--version` flag support
+2. ✅ Add comprehensive tests
+3. ✅ Update documentation/usage text
+4. ✅ Verify all existing tests pass
+
+### Future Enhancements
+
+1. **Version Comparison**: Add ability to check for updates
+2. **JSON Output**: Support `--version --json` for machine-readable output
+3. **Detailed Mode**: Add `--version --verbose` for more detailed information
+4. **Config Info**: Include configuration file locations and settings
+
+### Process Improvements
+
+1. **Feature Checklist**: Ensure standard CLI features are in initial release:
+   - `--help` / `-h`
+   - `--version` / `-v`
+   - `--verbose` / `-v` (if not conflicting)
+   - Exit codes documentation
+2. **User Testing**: Early beta testing to catch missing features
+3. **CLI Standards**: Follow established CLI conventions
+
+## Conclusion
+
+Issue #18 highlighted the importance of implementing standard CLI features that users expect. The solution not only added the missing `--version` flag but enhanced it to provide comprehensive diagnostic information including OS details and dependency versions.
+
+This case study demonstrates the value of:
+
+- Clear issue reporting with examples
+- Thorough root cause analysis
+- Comprehensive implementation
+- Strong test coverage
+- Documentation of the investigation process
+
+The implementation is now complete and ready for production use, providing users with essential version and diagnostic information for troubleshooting.
+
+## References
+
+- **Issue**: [#18 - We need to ensure `start-command --version` option is supported](https://github.com/link-foundation/start/issues/18)
+- **Pull Request**: [#21 - Implementation of --version flag](https://github.com/link-foundation/start/pull/21)
+- **Related Files**:
+  - `src/bin/cli.js` - Main implementation
+  - `test/cli.test.js` - Test coverage
+  - `package.json` - Version source
+
+## Appendix
+
+### A. Example Output
+
+```bash
+$ $ --version
+start-command version: 0.6.0
+
+OS: linux
+OS Release: 6.8.0-90-generic
+Node Version: v24.3.0
+Architecture: x64
+
+Isolation tools:
+  screen: Screen version 4.09.01 (GNU) 20-Aug-23
+  tmux: tmux 3.4
+  docker: not installed
+```
+
+### B. Test Coverage Summary
+
+- **Total Tests**: 71
+- **New Tests Added**: 5
+- **Pass Rate**: 100%
+- **Coverage Areas**:
+  - Version flag handling
+  - Package version accuracy
+  - CLI basic behavior
+  - Usage text verification

package/docs/case-studies/issue-18/issue-comments.json

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,7 @@
+{
+  "author": "konard",
+  "body": "```\nonard@MacBook-Pro-Konstantin ~ % --version  \nzsh: command not found: --version\nkonard@MacBook-Pro-Konstantin ~ % $ --version\n[2025-12-23 12:51:15.314] Starting: --version\n\nzsh 5.9 (arm64-apple-darwin24.0)\n\n[2025-12-23 12:51:15.322] Finished\nExit code: 0\nLog saved: /var/folders/cl/831lqjgd58v5mb_m74cfdfcw0000gn/T/start-command-1766494275314-ws2i7w.log\nkonard@MacBook-Pro-Konstantin ~ % $ --version --\nError: No command provided\nUsage: $ [options] [--] \u003ccommand\u003e [args...]\n       $ \u003ccommand\u003e [args...]\n\nOptions:\n  --isolated, -i \u003cenvironment\u003e      Run in isolated environment (screen, tmux, docker, zellij)\n  --attached, -a            Run in attached mode (foreground)\n  --detached, -d            Run in detached mode (background)\n  --session, -s \u003cname\u003e      Session name for isolation\n  --image \u003cimage\u003e           Docker image (required for docker isolation)\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, zellij, or docker\n\nAlias examples:\n  $ install lodash npm package           -\u003e npm install lodash\n  $ install 4.17.21 version of lodash npm package -\u003e npm install lodash@4.17.21\n  $ clone https://github.com/user/repo repository -\u003e git clone https://github.com/user/repo\n```\n\nThat should be the root source of debug information.\n\nIt should display version of start-command itself, version of OS, version of screen and docker and tmux (all if installed).\n\nAlso it should be added to CI tests, so never again we will have the problem.\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.",
+  "createdAt": "2025-12-23T12:53:10Z",
+  "title": "We need to ensure `start-command --version` option is supported",
+  "updatedAt": "2025-12-23T15:59:11Z"
+}

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.6.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

@@ -48,11 +48,114 @@ const config = {
 // Get all arguments passed after the command
 const args = process.argv.slice(2);
 
+// Handle --version flag
+// 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);
+}
+
 if (args.length === 0) {
   printUsage();
   process.exit(0);
 }
 
+/**
+ * Print version information
+ */
+function printVersion() {
+  // Get package version
+  const packageJson = require('../../package.json');
+  const startCommandVersion = packageJson.version;
+
+  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}`);
+
+  // 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('');
+
+  // Check for installed isolation tools
+  console.log('Isolation tools:');
+
+  // Check screen
+  const screenVersion = getToolVersion('screen', '--version');
+  if (screenVersion) {
+    console.log(`  screen: ${screenVersion}`);
+  } else {
+    console.log('  screen: not installed');
+  }
+
+  // Check tmux
+  const tmuxVersion = getToolVersion('tmux', '-V');
+  if (tmuxVersion) {
+    console.log(`  tmux: ${tmuxVersion}`);
+  } else {
+    console.log('  tmux: not installed');
+  }
+
+  // Check docker
+  const dockerVersion = getToolVersion('docker', '--version');
+  if (dockerVersion) {
+    console.log(`  docker: ${dockerVersion}`);
+  } else {
+    console.log('  docker: not installed');
+  }
+}
+
+/**
+ * Get version of an installed tool
+ * @param {string} toolName - Name of the tool
+ * @param {string} versionFlag - Flag to get version (e.g., '--version', '-V')
+ * @returns {string|null} Version string or null if not installed
+ */
+function getToolVersion(toolName, versionFlag) {
+  try {
+    // 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',
+      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;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Print usage information
  */
@@ -70,13 +173,14 @@ function printUsage() {
   console.log(
     '  --image <image>           Docker image (required for docker isolation)'
   );
+  console.log('  --version, -v             Show version information');
   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');
@@ -237,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`;
@@ -249,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`;
 
@@ -398,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
@@ -669,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`;
@@ -676,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

@@ -0,0 +1,114 @@
+#!/usr/bin/env bun
+/**
+ * Unit tests for the CLI
+ * Tests version flag and basic CLI behavior
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Path to the CLI script
+const CLI_PATH = path.join(__dirname, '../src/bin/cli.js');
+
+// Helper to run CLI
+function runCLI(args = []) {
+  return spawnSync('bun', [CLI_PATH, ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      START_DISABLE_AUTO_ISSUE: '1',
+      START_DISABLE_LOG_UPLOAD: '1',
+    },
+  });
+}
+
+describe('CLI version flag', () => {
+  it('should display version with --version', () => {
+    const result = runCLI(['--version']);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+
+    // Check for key elements in version output
+    assert.ok(
+      result.stdout.includes('start-command version:'),
+      'Should display start-command version'
+    );
+    assert.ok(result.stdout.includes('OS:'), 'Should display OS');
+    assert.ok(
+      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(
+      hasBunVersion || hasNodeVersion,
+      'Should display Bun Version or Node.js Version'
+    );
+    assert.ok(
+      result.stdout.includes('Architecture:'),
+      'Should display Architecture'
+    );
+    assert.ok(
+      result.stdout.includes('Isolation tools:'),
+      'Should display Isolation tools section'
+    );
+    assert.ok(
+      result.stdout.includes('screen:'),
+      'Should check for screen installation'
+    );
+    assert.ok(
+      result.stdout.includes('tmux:'),
+      'Should check for tmux installation'
+    );
+    assert.ok(
+      result.stdout.includes('docker:'),
+      'Should check for docker installation'
+    );
+  });
+
+  it('should display version with -v', () => {
+    const result = runCLI(['-v']);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(
+      result.stdout.includes('start-command version:'),
+      'Should display start-command version'
+    );
+  });
+
+  it('should show correct package version', () => {
+    const result = runCLI(['--version']);
+    const packageJson = JSON.parse(
+      fs.readFileSync(path.join(__dirname, '../package.json'), 'utf8')
+    );
+
+    assert.ok(
+      result.stdout.includes(`start-command version: ${packageJson.version}`),
+      `Should display version ${packageJson.version}`
+    );
+  });
+});
+
+describe('CLI basic behavior', () => {
+  it('should show usage when no arguments provided', () => {
+    const result = runCLI([]);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(result.stdout.includes('Usage:'), 'Should display usage');
+    assert.ok(
+      result.stdout.includes('--version'),
+      'Usage should mention --version flag'
+    );
+  });
+
+  it('should show usage when no command provided after --', () => {
+    const result = runCLI(['--']);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(result.stdout.includes('Usage:'), 'Should display usage');
+  });
+});

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');
+    });
+  });
+});