start-command 0.24.2 → 0.24.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # start-command
 
+## 0.24.3
+
+### Patch Changes
+
+- c75983e: fix: hint users when a bare shell exits immediately due to startup file errors
+
+  When running `$ --isolated docker --image <image> -- bash` and the shell exits
+  with code 1 within 3 seconds, `start-command` now prints a helpful hint:
+
+  ```
+  Hint: The shell exited immediately — its startup file (.bashrc/.zshrc) may have errors.
+  Try skipping startup files: bash --norc
+  ```
+
+  This covers the post-fix regression from issue #84 where `konard/sandbox`
+  images with broken `.bashrc` files cause bash to exit immediately when run
+  directly. The hint also appears in the log file for later diagnosis.
+
+  The `bash --norc` (and `zsh --no-rcs`) workaround bypasses startup file
+  sourcing and is recognized as a bare shell invocation, so it is passed
+  directly to docker without any `-c` wrapping.
+
 ## 0.24.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/lib/isolation.js

@@ -162,7 +162,7 @@ function detectShellInEnvironment(
           return result.stdout.trim();
         }
       } catch {
-        // Continue to next shell
+        // ignore; try next shell
       }
     }
 
@@ -233,9 +233,7 @@ function wrapCommandWithUser(command, user) {
   if (!user) {
     return command;
   }
-  // Use sudo -u to run command as specified user
-  // -E preserves environment variables
-  // -n ensures non-interactive (fails if password required)
+  // sudo -n: non-interactive (fails if password required); -u: run as user
   return `sudo -n -u ${user} sh -c '${command.replace(/'/g, "'\\''")}'`;
 }
 
@@ -292,10 +290,7 @@ function runScreenWithLogCapture(command, sessionName, shellInfo, user = null) {
         }
       }
 
-      // Use spawnSync with array arguments to avoid shell quoting issues
-      // This is critical for commands containing quotes (e.g., echo "hello")
-      // Using execSync with a constructed string would break on nested quotes
-      // See issue #25 for details
+      // Use spawnSync with array args (not execSync string) to avoid quoting issues (issue #25)
       const result = spawnSync('screen', screenArgs, {
         stdio: 'inherit',
       });
@@ -433,14 +428,10 @@ function runInScreen(command, options = {}) {
 
     if (options.detached) {
       // Detached mode: screen -dmS <session> <shell> -c '<command>'
-      // By default (keepAlive=false), the session will exit after command completes
-      // With keepAlive=true, we start a shell that runs the command but stays alive
-
       if (options.keepAlive) {
         // With keep-alive: run command, then keep shell open
         effectiveCommand = `${effectiveCommand}; exec ${shell}`;
       }
-      // Without keep-alive: command runs and session exits naturally when done
 
       const screenArgs = isInteractiveShellCommand(command)
         ? ['-dmS', sessionName, ...command.trim().split(/\s+/)]
@@ -451,9 +442,7 @@ function runInScreen(command, options = {}) {
         console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
       }
 
-      // Use spawnSync with array arguments to avoid shell quoting issues
-      // This is critical for commands containing quotes (e.g., echo "hello")
-      // See issue #25 for details
+      // Use spawnSync with array args (not execSync string) to avoid quoting issues (issue #25)
       const result = spawnSync('screen', screenArgs, {
         stdio: 'inherit',
       });
@@ -476,15 +465,8 @@ function runInScreen(command, options = {}) {
         message,
       });
     } else {
-      // Attached mode: always use detached mode with log capture
-      // This ensures output is captured and displayed correctly, even for quick commands
-      // that would otherwise have their output lost in a rapidly-terminating screen session.
-      // Direct screen invocation (screen -S session shell -c command) loses output because:
-      // 1. Screen creates a virtual terminal for the session
-      // 2. Command output goes to that virtual terminal
-      // 3. When the command exits quickly, screen shows "[screen is terminating]"
-      // 4. The virtual terminal is destroyed and output is lost
-      // See issue #25 for details: https://github.com/link-foundation/start/issues/25
+      // Attached mode: use detached mode with log capture for reliable output
+      // (direct attached screen loses output for quick commands; see issue #25)
       if (DEBUG) {
         console.log(
           `[DEBUG] Using detached mode with log capture for reliable output`
@@ -533,14 +515,10 @@ function runInTmux(command, options = {}) {
   try {
     if (options.detached) {
       // Detached mode: tmux new-session -d -s <session> '<command>'
-      // By default (keepAlive=false), the session will exit after command completes
-      // With keepAlive=true, we keep the shell alive after the command
-
       if (options.keepAlive) {
         // With keep-alive: run command, then keep shell open
         effectiveCommand = `${effectiveCommand}; exec ${shell}`;
       }
-      // Without keep-alive: command runs and session exits naturally when done
 
       if (DEBUG) {
         console.log(
@@ -724,8 +702,14 @@ function runInSsh(command, options = {}) {
   }
 }
 
-// Import docker image utilities from docker-utils
-const { dockerImageExists, dockerPullImage } = require('./docker-utils');
+// Import docker utilities from docker-utils
+const {
+  dockerImageExists,
+  dockerPullImage,
+  isDockerAvailable,
+  getDefaultDockerImage,
+  canRunLinuxDockerImages,
+} = require('./docker-utils');
 
 /**
  * Run command in Docker container
@@ -743,6 +727,15 @@ function runInDocker(command, options = {}) {
     });
   }
 
+  if (!isDockerAvailable()) {
+    return Promise.resolve({
+      success: false,
+      containerName: null,
+      message:
+        'Docker is installed but not running. Please start Docker Desktop or the Docker daemon, then try again.',
+    });
+  }
+
   if (!options.image) {
     return Promise.resolve({
       success: false,
@@ -772,7 +765,6 @@ function runInDocker(command, options = {}) {
     : detectShellInEnvironment('docker', options, options.shell);
   const shellInteractiveFlag = getShellInteractiveFlag(shellToUse);
 
-  // Print the user command (this appears after any virtual commands like docker pull)
   const { createCommandLine } = require('./output-blocks');
   console.log(createCommandLine(command));
   console.log();
@@ -781,13 +773,11 @@ function runInDocker(command, options = {}) {
     if (options.detached) {
       // Detached mode: docker run -d --name <name> [--user <user>] <image> <shell> -c '<command>'
       const dockerArgs = ['run', '-d', '--name', containerName];
-
-      // --rm must come before the image name
+      // --rm must come before the image name in args
       if (options.autoRemoveDockerContainer) {
         dockerArgs.splice(2, 0, '--rm');
       }
 
-      // Add --user flag if specified
       if (options.user) {
         dockerArgs.push('--user', options.user);
       }
@@ -846,13 +836,21 @@ function runInDocker(command, options = {}) {
       if (DEBUG) {
         console.log(`[DEBUG] shell: ${shellToUse}`);
       }
-
       const shellCmdArgs = shellInteractiveFlag
         ? [shellToUse, shellInteractiveFlag]
         : [shellToUse];
-      const attachedCmdArgs = isBareShell
-        ? command.trim().split(/\s+/)
-        : [...shellCmdArgs, '-c', command];
+      // Bare shell: pass directly with -i (avoids bash-inside-bash, issue #84; -i ensures interactive).
+      let attachedCmdArgs;
+      if (isBareShell) {
+        const parts = command.trim().split(/\s+/);
+        const bareFlag = getShellInteractiveFlag(parts[0]);
+        attachedCmdArgs =
+          bareFlag && !parts.includes(bareFlag)
+            ? [parts[0], bareFlag, ...parts.slice(1)]
+            : parts;
+      } else {
+        attachedCmdArgs = [...shellCmdArgs, '-c', command];
+      }
       dockerArgs.push(options.image, ...attachedCmdArgs);
 
       if (DEBUG) {
@@ -860,15 +858,25 @@ function runInDocker(command, options = {}) {
       }
 
       return new Promise((resolve) => {
-        const child = spawn('docker', dockerArgs, {
-          stdio: 'inherit',
-        });
+        const startTime = Date.now();
+        const child = spawn('docker', dockerArgs, { stdio: 'inherit' });
 
         child.on('exit', (code) => {
+          const durationMs = Date.now() - startTime;
+          let message = `Docker container "${containerName}" exited with code ${code}`;
+          // Bare shell exited non-zero quickly → startup file error; suggest --norc (issue #84).
+          if (isBareShell && code !== 0 && durationMs < 3000) {
+            const shell0 = command.trim().split(/\s+/)[0];
+            // prettier-ignore
+            const norc = path.basename(shell0) === 'zsh' ? '--no-rcs' : '--norc';
+            const hint = `Hint: The shell exited immediately — its startup file (.bashrc/.zshrc) may have errors.\nTry skipping startup files: ${shell0} ${norc}`;
+            console.log(hint);
+            message += `\n${hint}`;
+          }
           resolve({
             success: code === 0,
             containerName,
-            message: `Docker container "${containerName}" exited with code ${code}`,
+            message,
             exitCode: code,
           });
         });
@@ -951,7 +959,6 @@ function resetScreenVersionCache() {
   screenVersionChecked = false;
 }
 
-// Log utilities and runAsIsolatedUser extracted to isolation-log-utils.js
 const {
   getTimestamp,
   generateLogFilename,
@@ -963,12 +970,6 @@ const {
   runAsIsolatedUser,
 } = require('./isolation-log-utils');
 
-// Re-export docker utilities from docker-utils for backwards compatibility
-const {
-  getDefaultDockerImage,
-  canRunLinuxDockerImages,
-} = require('./docker-utils');
-
 module.exports = {
   isCommandAvailable,
   hasTTY,
@@ -992,7 +993,6 @@ module.exports = {
   supportsLogfileOption,
   resetScreenVersionCache,
   canRunLinuxDockerImages,
-  // Re-exported from docker-utils for backwards compatibility
   getDefaultDockerImage,
   dockerImageExists,
   dockerPullImage,

package/test/regression-84.test.js

@@ -6,32 +6,53 @@
  * `$ --isolated docker -- bash` caused:
  *   docker run ... image /bin/bash -i -c bash   (WRONG: bash inside bash)
  * instead of:
- *   docker run ... image bash                    (CORRECT: bare shell)
+ *   docker run ... image bash -i                 (CORRECT: bare shell with explicit -i)
+ *
+ * The -i flag is required so that bash reliably starts in interactive mode,
+ * since docker's PTY bridging through Node.js spawn may not set up a TTY that
+ * bash auto-detects. Without -i, bash may exit immediately (post-fix regression).
  *
  * The same regression applies to zsh, sh, and all other isolation backends.
  *
+ * Also tests the post-fix regression hint: when a bare shell exits with code 1
+ * quickly (< 3s), a helpful hint suggests `bash --norc` as a workaround for
+ * containers whose .bashrc causes bash to exit non-zero (issue #84, second comment).
+ *
  * Reference: https://github.com/link-foundation/start/issues/84
  * Fixed in: PR #85 (v0.24.1) via isInteractiveShellCommand()
+ * Fixed in: PR #87 adding explicit -i for bare shells in docker attached mode
  */
 
 const { describe, it } = require('node:test');
 const assert = require('assert');
 const { isInteractiveShellCommand } = require('../src/lib/isolation');
+const { isDockerAvailable } = require('../src/lib/docker-utils');
 
 // Helper: mirrors the command-args construction logic used in
-// runInDocker (attached + detached), runInScreen, and runInSsh.
+// runInDocker attached mode.
 // If this helper returns args containing '-c' for a bare shell command,
 // the shell-inside-shell bug is present.
 function buildCmdArgs(command, shellToUse = '/bin/bash') {
+  const path = require('path');
   const shellName = shellToUse.split('/').pop();
   const shellInteractiveFlag =
     shellName === 'bash' || shellName === 'zsh' ? '-i' : null;
   const shellArgs = shellInteractiveFlag
     ? [shellToUse, shellInteractiveFlag]
     : [shellToUse];
-  return isInteractiveShellCommand(command)
-    ? command.trim().split(/\s+/)
-    : [...shellArgs, '-c', command];
+  if (isInteractiveShellCommand(command)) {
+    // Bare shell: pass directly with explicit -i for bash/zsh (issue #84 fix)
+    const parts = command.trim().split(/\s+/);
+    const bareShellFlag =
+      path.basename(parts[0]) === 'bash' || path.basename(parts[0]) === 'zsh'
+        ? '-i'
+        : null;
+    if (bareShellFlag && !parts.includes(bareShellFlag)) {
+      return [parts[0], bareShellFlag, ...parts.slice(1)];
+    }
+    return parts;
+  }
+  return [...shellArgs, '-c', command];
 }
 
 describe('isInteractiveShellCommand additional cases (issue #84)', () => {
@@ -74,15 +95,16 @@ describe('Regression: No Shell-Inside-Shell (issue #84)', () => {
   // Each test verifies that the command-arg construction logic does NOT
   // wrap a bare shell invocation inside another shell with `-c`.
   //
-  // Before fix: buildCmdArgs('bash') → ['/bin/bash', '-i', '-c', 'bash']
-  // After fix:  buildCmdArgs('bash') → ['bash']
+  // Before fix (v0.24.0): buildCmdArgs('bash') → ['/bin/bash', '-i', '-c', 'bash']
+  // After fix (v0.24.1):  buildCmdArgs('bash') → ['bash', '-i']
+  //   (bare shell passed directly with explicit -i for reliable interactive mode)
 
-  it('should pass "bash" directly, not wrap in shell -c', () => {
+  it('should pass "bash" with -i flag, not wrap in shell -c', () => {
     const args = buildCmdArgs('bash');
     assert.deepStrictEqual(
       args,
-      ['bash'],
-      `Expected ["bash"], got: ${JSON.stringify(args)}`
+      ['bash', '-i'],
+      `Expected ["bash", "-i"], got: ${JSON.stringify(args)}`
     );
     assert.ok(
       !args.includes('-c'),
@@ -90,16 +112,16 @@ describe('Regression: No Shell-Inside-Shell (issue #84)', () => {
     );
   });
 
-  it('should pass "zsh" directly, not wrap in shell -c', () => {
+  it('should pass "zsh" with -i flag, not wrap in shell -c', () => {
     const args = buildCmdArgs('zsh');
-    assert.deepStrictEqual(args, ['zsh']);
+    assert.deepStrictEqual(args, ['zsh', '-i']);
     assert.ok(
       !args.includes('-c'),
       'Must not contain -c flag (shell-inside-shell)'
     );
   });
 
-  it('should pass "sh" directly, not wrap in shell -c', () => {
+  it('should pass "sh" directly without -i (sh does not use -i flag), not wrap in shell -c', () => {
     const args = buildCmdArgs('sh', 'sh');
     assert.deepStrictEqual(args, ['sh']);
     assert.ok(
@@ -108,24 +130,24 @@ describe('Regression: No Shell-Inside-Shell (issue #84)', () => {
     );
   });
 
-  it('should pass "/bin/bash" directly, not wrap in shell -c', () => {
+  it('should pass "/bin/bash" with -i flag, not wrap in shell -c', () => {
     const args = buildCmdArgs('/bin/bash');
-    assert.deepStrictEqual(args, ['/bin/bash']);
+    assert.deepStrictEqual(args, ['/bin/bash', '-i']);
     assert.ok(
       !args.includes('-c'),
       'Must not contain -c flag (shell-inside-shell)'
     );
   });
 
-  it('should pass "bash --norc" directly (workaround for broken .bashrc)', () => {
+  it('should pass "bash --norc" with -i flag (workaround for broken .bashrc)', () => {
     const args = buildCmdArgs('bash --norc');
-    assert.deepStrictEqual(args, ['bash', '--norc']);
+    assert.deepStrictEqual(args, ['bash', '-i', '--norc']);
     assert.ok(!args.includes('-c'), 'Must not contain -c flag');
   });
 
-  it('should pass "bash -l" directly (login shell)', () => {
+  it('should pass "bash -l" directly (login shell, already has its own init)', () => {
     const args = buildCmdArgs('bash -l');
-    assert.deepStrictEqual(args, ['bash', '-l']);
+    assert.deepStrictEqual(args, ['bash', '-i', '-l']);
     assert.ok(!args.includes('-c'), 'Must not contain -c flag');
   });
 
@@ -156,4 +178,115 @@ describe('Regression: No Shell-Inside-Shell (issue #84)', () => {
       'bash -c commands should be treated as regular commands'
     );
   });
+
+  it('should not duplicate -i if user already passes "bash -i"', () => {
+    // If user explicitly passes -i, we should not add another -i
+    const args = buildCmdArgs('bash -i');
+    assert.deepStrictEqual(
+      args,
+      ['bash', '-i'],
+      'Should not duplicate -i flag'
+    );
+    assert.ok(!args.includes('-c'), 'Must not contain -c flag');
+  });
+});
+
+describe('Docker daemon availability check (issue #84)', () => {
+  // Verifies that isDockerAvailable returns a boolean (not a crash),
+  // and that the error message for a non-running daemon is helpful.
+
+  it('isDockerAvailable should return a boolean', () => {
+    const result = isDockerAvailable();
+    assert.strictEqual(
+      typeof result,
+      'boolean',
+      'isDockerAvailable() must return a boolean'
+    );
+  });
+
+  it('runInDocker error message for non-running daemon should be actionable', () => {
+    // Mirrors the message in runInDocker when isDockerAvailable() returns false.
+    const message =
+      'Docker is installed but not running. Please start Docker Desktop or the Docker daemon, then try again.';
+    assert.ok(
+      message.includes('not running'),
+      'Message must indicate Docker is not running'
+    );
+    assert.ok(
+      message.includes('Docker Desktop'),
+      'Message must mention Docker Desktop (common on macOS/Windows)'
+    );
+    assert.ok(
+      message.includes('try again'),
+      'Message must tell user what to do next'
+    );
+  });
+});
+
+describe('Post-fix regression hint: --norc suggestion (issue #84)', () => {
+  // These tests verify the hint logic that recommends --norc when a bare shell
+  // exits quickly with code 1 (e.g., broken .bashrc in konard/sandbox image).
+  // The hint is shown in runInDocker attached mode when:
+  //   isBareShell && code !== 0 && durationMs < 3000
+
+  // Helper mirrors the hint construction logic in isolation.js runInDocker.
+  const path = require('path');
+  function buildHint(command) {
+    const shellName = command.trim().split(/\s+/)[0];
+    const noRcFlag = path.basename(shellName) === 'zsh' ? '--no-rcs' : '--norc';
+    return (
+      `Hint: The shell exited immediately — its startup file (.bashrc/.zshrc) may have errors.\n` +
+      `Try skipping startup files: ${shellName} ${noRcFlag}`
+    );
+  }
+
+  it('should suggest --norc for bare bash that exits quickly', () => {
+    const hint = buildHint('bash');
+    assert.ok(hint.includes('--norc'), 'Hint must include --norc for bash');
+    assert.ok(
+      hint.includes('bash --norc'),
+      'Hint must show the full corrected command'
+    );
+    assert.ok(
+      hint.includes('startup file'),
+      'Hint must explain why the shell exited'
+    );
+  });
+
+  it('should suggest --no-rcs for bare zsh that exits quickly', () => {
+    const hint = buildHint('zsh');
+    assert.ok(hint.includes('--no-rcs'), 'Hint must include --no-rcs for zsh');
+    assert.ok(
+      hint.includes('zsh --no-rcs'),
+      'Hint must show the full corrected command'
+    );
+  });
+
+  it('should suggest --norc for /bin/bash path that exits quickly', () => {
+    const hint = buildHint('/bin/bash');
+    assert.ok(
+      hint.includes('/bin/bash --norc'),
+      'Hint must include full path with --norc'
+    );
+  });
+
+  it('should suggest --norc for bare sh that exits quickly', () => {
+    const hint = buildHint('sh');
+    assert.ok(hint.includes('sh --norc'), 'Hint must suggest --norc for sh');
+  });
+
+  it('should confirm workaround: bash --norc is detected as bare shell', () => {
+    // The workaround (bash --norc) must still be recognized as a bare shell
+    // so it gets passed directly to docker without -c wrapping
+    assert.strictEqual(
+      isInteractiveShellCommand('bash --norc'),
+      true,
+      'bash --norc must be a bare shell (no -c wrapping)'
+    );
+    assert.strictEqual(
+      isInteractiveShellCommand('zsh --no-rcs'),
+      true,
+      'zsh --no-rcs must be a bare shell (no -c wrapping)'
+    );
+  });
 });