start-command 0.7.1 → 0.7.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # start-command
 
+## 0.7.4
+
+### Patch Changes
+
+- d058c43: fix: Screen isolation output not captured for quoted commands
+
+  This fixes issue #25 where commands with quoted strings (e.g., echo "hello") would not show their output when using screen isolation. The fix uses spawnSync with array arguments instead of execSync with a constructed string to avoid shell quoting issues.
+
+## 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

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

@@ -210,7 +210,6 @@ Repository not detected - automatic issue creation skipped
 ### Required
 
 - **Bun >= 1.0.0** (primary runtime)
-- Alternatively: Node.js >= 20.0.0 (for compatibility)
 - `child_process` (built-in)
 - `os` (built-in)
 - `fs` (built-in)

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

@@ -330,3 +330,218 @@ if ((args.length === 1 && hasVersionFlag) || isOnlyVersionWithSeparator) {
 - ✅ 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-25/README.md

@@ -0,0 +1,225 @@
+# Case Study: Issue #25 - Screen Isolation Output Missing
+
+## Issue Summary
+
+**Issue URL:** https://github.com/link-foundation/start/issues/25
+**Date Reported:** 2025-12-23
+**Reporter:** @konard
+**Status:** Resolved
+
+### Problem Statement
+
+When running commands with screen isolation in attached mode (without `-d`/`--detached`), the command output is not displayed. Specifically:
+
+```bash
+$ --isolated screen --verbose -- echo "hello"
+```
+
+Shows `[screen is terminating]` but no "hello" output, even though the command executes successfully with exit code 0.
+
+### Environment
+
+- **Platform:** macOS 15.7.2
+- **Package:** start-command@0.7.2
+- **Screen version:** macOS bundled 4.00.03 (FAU) 23-Oct-06
+- **Bun Version:** 1.2.20
+- **Architecture:** arm64
+
+## Timeline of Events
+
+1. User installs start-command: `bun install -g start-command`
+2. Direct command execution works: `$ echo "hello"` shows "hello"
+3. Docker isolation works: `$ --isolated docker --image alpine -- echo "hello"` shows "hello"
+4. **Screen isolation fails**: `$ --isolated screen -- echo "hello"` shows only `[screen is terminating]`
+
+## Observed Behavior
+
+### Expected
+
+```
+$ --isolated screen --verbose -- echo "hello"
+[2025-12-23 20:56:28.265] Starting: echo hello
+
+[Isolation] Environment: screen, Mode: attached
+
+hello
+
+Screen session "screen-1766523388276-4oecji" exited with code 0
+
+[2025-12-23 20:56:28.362] Finished
+Exit code: 0
+```
+
+### Actual (Before Fix)
+
+```
+$ --isolated screen --verbose -- echo "hello"
+[2025-12-23 20:56:28.265] Starting: echo hello
+
+[Isolation] Environment: screen, Mode: attached
+
+[screen is terminating]
+
+Screen session "screen-1766523388276-4oecji" exited with code 0
+
+[2025-12-23 20:56:28.362] Finished
+Exit code: 0
+```
+
+**Notice:** No "hello" output in the screen isolation case, though exit code is 0.
+
+## Root Cause Analysis
+
+### PRIMARY ROOT CAUSE: Shell Quoting Issues with execSync
+
+The issue was in the `runScreenWithLogCapture` function in `src/lib/isolation.js`.
+
+**The Problematic Code:**
+
+```javascript
+execSync(`screen ${screenArgs.map((a) => `"${a}"`).join(' ')}`, {
+  stdio: 'inherit',
+});
+```
+
+This code constructs a shell command string by wrapping each argument in double quotes. However, when the command being executed already contains double quotes (like `echo "hello"`), the nested quoting breaks the shell parsing.
+
+**Example of Broken Command:**
+
+For the command `echo "hello"`:
+
+1. `effectiveCommand` becomes: `(echo "hello") 2>&1 | tee "/tmp/...log"`
+2. `screenArgs` is: `['-dmS', 'session-name', '/bin/sh', '-c', '(echo "hello") 2>&1 | tee "/tmp/...log"']`
+3. After wrapping with `"${a}"`:
+   ```
+   screen "-dmS" "session-name" "/bin/sh" "-c" "(echo "hello") 2>&1 | tee "/tmp/...log""
+   ```
+4. **Problem**: The nested double quotes cause shell parsing errors - the shell sees `hello` as a separate token!
+
+**Why Simple Commands Worked:**
+
+Commands without quotes (like `echo hello` without the quotes) worked because there was no quoting conflict.
+
+### Experimental Evidence
+
+We created `experiments/test-screen-tee-debug.js` to test different approaches:
+
+| Test   | Command                                         | Result                           |
+| ------ | ----------------------------------------------- | -------------------------------- |
+| Test 3 | `echo "hello"` (simple)                         | SUCCESS                          |
+| Test 4 | `echo "hello from attached mode"` (with spaces) | **FAILED** - No log file created |
+| Test 5 | Same with escaped quotes                        | SUCCESS                          |
+| Test 6 | Using `spawnSync` with array                    | **SUCCESS**                      |
+
+The experiments clearly showed that:
+
+1. Commands with spaces in quoted strings fail with `execSync` + string construction
+2. Using `spawnSync` with an array of arguments works correctly
+
+### Why spawnSync Works
+
+Node.js/Bun's `spawnSync` with array arguments:
+
+- Passes arguments directly to the process without shell interpretation
+- Each array element becomes a separate argv entry
+- No shell quoting issues - the quotes in the command are preserved as-is
+
+## The Solution
+
+### Code Changes in `src/lib/isolation.js`
+
+1. **Added `spawnSync` import:**
+
+```javascript
+const { execSync, spawn, spawnSync } = require('child_process');
+```
+
+2. **Replaced `execSync` with `spawnSync` in two locations:**
+
+**Location 1: `runScreenWithLogCapture` function (attached mode with log capture)**
+
+```javascript
+// Before (broken):
+execSync(`screen ${screenArgs.map((a) => `"${a}"`).join(' ')}`, {
+  stdio: 'inherit',
+});
+
+// After (fixed):
+const result = spawnSync('screen', screenArgs, {
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  throw result.error;
+}
+```
+
+**Location 2: `runInScreen` function (detached mode)**
+
+```javascript
+// Same pattern - replaced execSync with spawnSync
+```
+
+## Testing Strategy
+
+### New Regression Tests Added
+
+Two new tests were added to `test/isolation.test.js`:
+
+1. **Test: should capture output from commands with quoted strings (issue #25)**
+   - Tests: `echo "hello"`
+   - Verifies the exact scenario from issue #25
+
+2. **Test: should capture output from commands with complex quoted strings**
+   - Tests: `echo "hello from attached mode"`
+   - Verifies commands with spaces inside quotes work
+
+### Test Results
+
+All 25 isolation tests pass:
+
+```
+bun test test/isolation.test.js
+
+  Captured quoted output: "hello"
+  Captured complex quote output: "hello from attached mode"
+
+ 25 pass
+ 0 fail
+```
+
+## Key Learnings
+
+1. **String construction for shell commands is fragile**: When building shell command strings, nested quoting can cause silent failures.
+
+2. **Prefer array-based process spawning**: `spawnSync`/`spawn` with arrays are more robust than `execSync` with constructed strings.
+
+3. **Test with varied input**: Simple commands may work while complex ones fail - test with real-world examples including quotes and spaces.
+
+4. **Debug systematically**: Creating experiments (`test-screen-tee-debug.js`) helped isolate the exact failure mode.
+
+## Connection to Previous Issues
+
+This issue is related to Issue #15 (Screen Isolation Not Working As Expected) which addressed a different root cause:
+
+- Issue #15: macOS Screen version incompatibility (lacking `-Logfile` option)
+- Issue #25: Shell quoting issues in the tee fallback approach (used for older screen versions)
+
+Both issues together ensure screen isolation works on:
+
+- Modern screen (>= 4.5.1) with native `-Logfile` support
+- Older screen (< 4.5.1, like macOS bundled 4.0.3) with tee fallback
+
+## Files Modified
+
+1. `src/lib/isolation.js` - Core fix: use `spawnSync` instead of `execSync`
+2. `test/isolation.test.js` - Added 2 regression tests for issue #25
+3. `experiments/test-screen-tee-fallback.js` - Experiment script (new)
+4. `experiments/test-screen-tee-debug.js` - Debug experiment script (new)
+
+## References
+
+- [Node.js child_process.spawnSync](https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options)
+- [GNU Screen Manual](https://www.gnu.org/software/screen/manual/screen.html)
+- [Issue #15 Case Study](../issue-15/README.md)
+- [Issue #22 Case Study](../issue-22/analysis.md)

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

@@ -0,0 +1,21 @@
+{
+  "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.2 with binaries:\n - $\n\n1 package installed [2.34s]\nkonard@MacBook-Pro-Konstantin ~ % $ --version                 \nstart-command version: 0.7.2\n\nOS: darwin\nOS Version: 15.7.2\nBun Version: 1.2.20\nArchitecture: arm64\n\nIsolation tools:\n  screen: Screen version 4.00.03 (FAU) 23-Oct-06\n  tmux: not installed\n  docker: Docker version 28.5.1, build e180ab8\nkonard@MacBook-Pro-Konstantin ~ % $ --version --              \nstart-command version: 0.7.2\n\nOS: darwin\nOS Version: 15.7.2\nBun Version: 1.2.20\nArchitecture: arm64\n\nIsolation tools:\n  screen: Screen version 4.00.03 (FAU) 23-Oct-06\n  tmux: not installed\n  docker: Docker version 28.5.1, build e180ab8\nkonard@MacBook-Pro-Konstantin ~ % $ --isolated screen --verbose -- echo \"hello\"\n[2025-12-23 20:56:28.265] Starting: echo hello\n\n[Isolation] Environment: screen, Mode: attached\n\n[screen is terminating]\n\nScreen session \"screen-1766523388276-4oecji\" exited with code 0\n\n[2025-12-23 20:56:28.362] Finished\nExit code: 0\nLog saved: /var/folders/cl/831lqjgd58v5mb_m74cfdfcw0000gn/T/start-command-screen-1766523388265-j5puqf.log\nkonard@MacBook-Pro-Konstantin ~ % $ echo \"hello\"                               \n[2025-12-23 20:56:37.680] Starting: echo hello\n\nhello\n\n[2025-12-23 20:56:37.688] Finished\nExit code: 0\nLog saved: /var/folders/cl/831lqjgd58v5mb_m74cfdfcw0000gn/T/start-command-1766523397680-fb62fx.log\nkonard@MacBook-Pro-Konstantin ~ % $ --isolated docker --image alpine -- echo \"hello\"\n[2025-12-23 20:56:45.619] Starting: echo hello\n\n[Isolation] Environment: docker, Mode: attached\n[Isolation] Image: alpine\n\nhello\n\nDocker container \"docker-1766523405627-qgv7h1\" exited with code 0\n\n[2025-12-23 20:56:47.091] Finished\nExit code: 0\nLog saved: /var/folders/cl/831lqjgd58v5mb_m74cfdfcw0000gn/T/start-command-docker-1766523405619-8izdfr.log\nkonard@MacBook-Pro-Konstantin ~ % \n```\n\nMake sure we have test on macOS that does specifically reproduces this exact error. After that it must be fixed. And that test will guarantee we will never get regression again.\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-23T20:57:23Z",
+  "labels": [
+    {
+      "id": "LA_kwDOP85RQM8AAAACMMqWww",
+      "name": "bug",
+      "description": "Something isn't working",
+      "color": "d73a4a"
+    }
+  ],
+  "number": 25,
+  "state": "OPEN",
+  "title": "We don't get `Hello` output from `$ --isolated screen --verbose -- echo \"hello\"` command"
+}