start-command 0.9.0 → 0.11.0

package/.github/workflows/release.yml

@@ -122,6 +122,40 @@ jobs:
       - name: Run tests
         run: bun test
 
+      # SSH Integration Tests - Linux only (most reliable for SSH testing)
+      - name: Setup SSH server for integration tests (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          # Install openssh-server if not present
+          sudo apt-get install -y openssh-server
+
+          # Start SSH service
+          sudo systemctl start ssh
+
+          # Generate SSH key without passphrase for testing
+          ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "ci-test-key"
+
+          # Add the public key to authorized_keys for passwordless login
+          cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
+          chmod 600 ~/.ssh/authorized_keys
+
+          # Configure SSH to accept localhost connections without prompts
+          mkdir -p ~/.ssh
+          cat >> ~/.ssh/config << 'EOF'
+          Host localhost
+            StrictHostKeyChecking no
+            UserKnownHostsFile /dev/null
+            LogLevel ERROR
+          EOF
+          chmod 600 ~/.ssh/config
+
+          # Test SSH connectivity
+          ssh localhost "echo 'SSH connection successful'"
+
+      - name: Run SSH integration tests (Linux)
+        if: runner.os == 'Linux'
+        run: bun test test/ssh-integration.test.js
+
   # Release - only runs on main after tests pass (for push events)
   release:
     name: Release

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # start-command
 
+## 0.11.0
+
+### Minor Changes
+
+- 1240a29: Add SSH isolation support for remote command execution.
+  - Implements SSH backend for executing commands on remote servers via SSH, similar to screen/tmux/docker isolation
+  - Uses `--endpoint` option to specify SSH target (e.g., `--endpoint user@remote.server`)
+  - Supports both attached (interactive) and detached (background) modes
+  - Includes comprehensive SSH integration tests in CI with a local SSH server
+
+## 0.10.0
+
+### Minor Changes
+
+- 8ea5659: Add user isolation support with --isolated-user and --keep-user options
+
+  Implements user isolation that creates a new isolated user to run commands:
+
+  ## --isolated-user option (create isolated user with same permissions)
+  - Add --isolated-user, -u option to create a new isolated user automatically
+  - New user inherits group memberships from current user (sudo, docker, wheel, etc.)
+  - User is automatically deleted after command completes (unless --keep-user)
+  - Works with screen and tmux isolation backends (not docker)
+  - Optional custom username via --isolated-user=myname or -u myname
+  - For screen/tmux: Wraps commands with sudo -n -u <user>
+  - Requires sudo NOPASSWD configuration for useradd/userdel/sudo
+
+  ## --keep-user option
+  - Add --keep-user option to prevent user deletion after command completes
+  - Useful when you need to inspect files created during execution
+  - User must be manually deleted with: sudo userdel -r <username>
+
+  ## Other improvements
+  - Add comprehensive tests for user isolation
+  - Update documentation with user isolation examples
+  - Integrate --keep-alive and --auto-remove-docker-container from main branch
+
+  Usage:
+  - $ --isolated-user -- npm test # Auto-generated username, auto-deleted
+  - $ --isolated-user myrunner -- npm start # Custom username
+  - $ -u myrunner -- npm start # Short form
+  - $ --isolated screen --isolated-user -- npm test # Combine with process isolation
+  - $ --isolated-user --keep-user -- npm test # Keep user after completion
+
+  Note: User isolation requires sudo NOPASSWD configuration.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -136,7 +136,7 @@ Issue created: https://github.com/owner/some-npm-tool/issues/42
 
 ### Process Isolation
 
-Run commands in isolated environments using terminal multiplexers or containers:
+Run commands in isolated environments using terminal multiplexers, containers, or remote servers:
 
 ```bash
 # Run in tmux (attached by default)
@@ -148,29 +148,74 @@ $ --isolated screen --detached -- bun start
 # Run in docker container
 $ --isolated docker --image oven/bun:latest -- bun install
 
+# Run on remote server via SSH
+$ --isolated ssh --endpoint user@remote.server -- npm test
+
 # Short form with custom session name
 $ -i tmux -s my-session -d bun start
 ```
 
+### User Isolation
+
+Create a new isolated user with the same group permissions as your current user to run commands in complete isolation:
+
+```bash
+# Create an isolated user with same permissions and run command
+$ --isolated-user -- npm test
+
+# Specify custom username for the isolated user
+$ --isolated-user myrunner -- npm start
+$ -u myrunner -- npm start
+
+# Combine with process isolation (screen or tmux)
+$ --isolated screen --isolated-user -- npm test
+
+# Keep the user after command completes (don't delete)
+$ --isolated-user --keep-user -- npm start
+
+# The isolated user inherits your group memberships:
+# - sudo group (if you have it)
+# - docker group (if you have it)
+# - wheel, admin, and other privileged groups
+```
+
+The `--isolated-user` option:
+
+- Creates a new system user with the same group memberships as your current user
+- Runs the command as that user
+- Automatically deletes the user after the command completes (unless `--keep-user` is specified)
+- Requires sudo access without password (NOPASSWD configuration)
+- Works with screen and tmux isolation backends (not docker)
+
+This is useful for:
+
+- Running untrusted code in isolation
+- Testing with a clean user environment
+- Ensuring commands don't affect your user's files
+
 #### Supported Backends
 
-| Backend  | Description                            | Installation                                               |
-| -------- | -------------------------------------- | ---------------------------------------------------------- |
-| `screen` | GNU Screen terminal multiplexer        | `apt install screen` / `brew install screen`               |
-| `tmux`   | Modern terminal multiplexer            | `apt install tmux` / `brew install tmux`                   |
-| `docker` | Container isolation (requires --image) | [Docker Installation](https://docs.docker.com/get-docker/) |
+| Backend  | Description                                    | Installation                                               |
+| -------- | ---------------------------------------------- | ---------------------------------------------------------- |
+| `screen` | GNU Screen terminal multiplexer                | `apt install screen` / `brew install screen`               |
+| `tmux`   | Modern terminal multiplexer                    | `apt install tmux` / `brew install tmux`                   |
+| `docker` | Container isolation (requires --image)         | [Docker Installation](https://docs.docker.com/get-docker/) |
+| `ssh`    | Remote execution via SSH (requires --endpoint) | `apt install openssh-client` / `brew install openssh`      |
 
 #### Isolation Options
 
-| Option                           | Description                                           |
-| -------------------------------- | ----------------------------------------------------- |
-| `--isolated, -i`                 | Isolation backend (screen, tmux, docker)              |
-| `--attached, -a`                 | Run in attached/foreground mode (default)             |
-| `--detached, -d`                 | Run in detached/background mode                       |
-| `--session, -s`                  | Custom session/container name                         |
-| `--image`                        | Docker image (required for docker isolation)          |
-| `--keep-alive, -k`               | Keep session alive after command completes            |
-| `--auto-remove-docker-container` | Auto-remove docker container after exit (docker only) |
+| Option                           | Description                                               |
+| -------------------------------- | --------------------------------------------------------- |
+| `--isolated, -i`                 | Isolation backend (screen, tmux, docker, ssh)             |
+| `--attached, -a`                 | Run in attached/foreground mode (default)                 |
+| `--detached, -d`                 | Run in detached/background mode                           |
+| `--session, -s`                  | Custom session/container name                             |
+| `--image`                        | Docker image (required for docker isolation)              |
+| `--endpoint`                     | SSH endpoint (required for ssh, e.g., user@host)          |
+| `--isolated-user, -u [name]`     | Create isolated user with same permissions (screen/tmux)  |
+| `--keep-user`                    | Keep isolated user after command completes (don't delete) |
+| `--keep-alive, -k`               | Keep session alive after command completes                |
+| `--auto-remove-docker-container` | Auto-remove docker container after exit (docker only)     |
 
 **Note:** Using both `--attached` and `--detached` together will result in an error - you must choose one mode.
 

package/REQUIREMENTS.md

@@ -142,6 +142,8 @@ Support two patterns for passing wrapper options:
 - `--detached, -d`: Run in detached/background mode
 - `--session, -s <name>`: Custom session name
 - `--image <image>`: Docker image (required for docker backend)
+- `--isolated-user, -u [username]`: Create new isolated user with same group permissions as current user
+- `--keep-user`: Keep isolated user after command completes (don't delete)
 - `--keep-alive, -k`: Keep isolation environment alive after command exits (disabled by default)
 - `--auto-remove-docker-container`: Automatically remove docker container after exit (disabled by default, only valid with --isolated docker)
 
@@ -157,7 +159,50 @@ Support two patterns for passing wrapper options:
 - **Detached mode**: Command runs in background, session info displayed for reattachment
 - **Conflict handling**: If both --attached and --detached are specified, show error asking user to choose one
 
-#### 6.5 Auto-Exit Behavior
+#### 6.5 User Isolation
+
+- `--isolated-user, -u [username]`: Create a new isolated user with same permissions
+- Creates user with same group memberships as current user (sudo, docker, wheel, etc.)
+- Automatically generates username if not specified
+- User is automatically deleted after command completes (unless `--keep-user` is specified)
+- For screen/tmux: Wraps command with `sudo -n -u <username>`
+- Requires sudo NOPASSWD for useradd/userdel commands
+- Works with screen and tmux isolation (not docker)
+
+#### 6.6 Keep User Option
+
+- `--keep-user`: Keep the isolated user after command completes
+- Only valid with `--isolated-user` option
+- User must be manually deleted later with `sudo userdel -r <username>`
+
+Example usage:
+
+```bash
+# Create isolated user and run command (user auto-deleted after)
+$ --isolated-user -- npm test
+
+# Custom username for isolated user
+$ --isolated-user myrunner -- npm start
+$ -u myrunner -- npm start
+
+# Combine with screen isolation
+$ --isolated screen --isolated-user -- npm test
+
+# Combine with tmux detached mode
+$ -i tmux -d --isolated-user testuser -- npm run build
+
+# Keep user after command completes
+$ --isolated-user --keep-user -- npm test
+```
+
+Benefits:
+
+- Clean user environment for each run
+- Inherits sudo/docker access from current user
+- Files created during execution belong to isolated user
+- Automatic cleanup after execution (unless --keep-user)
+
+#### 6.7 Auto-Exit Behavior
 
 By default, all isolation environments (screen, tmux, docker) automatically exit after the target command completes execution. This ensures:
 
@@ -180,10 +225,11 @@ The `--auto-remove-docker-container` flag enables automatic removal of the conta
 
 Note: `--auto-remove-docker-container` is only valid with `--isolated docker` and is independent of the `--keep-alive` flag.
 
-#### 6.6 Graceful Degradation
+#### 6.8 Graceful Degradation
 
 - If isolation backend is not installed, show informative error with installation instructions
 - If session creation fails, report error with details
+- If sudo fails due to password requirement, command will fail with sudo error
 
 ## Configuration Options
 

package/experiments/user-isolation-research.md

@@ -0,0 +1,83 @@
+# User Isolation Research
+
+## Issue #30: Support user isolation
+
+### Understanding the Requirement
+
+Based on the issue description:
+
+> We need to find a way to support not only isolation in screen, but also isolation by user at the same time.
+
+And the clarification from the user:
+
+> No, there is no way to use existing user to run the command, user isolation should mean we create user - run command using this user, after command have finished we can delete user, unless we have `--keep-user` option.
+
+This means:
+
+1. Running commands in isolated environments (screen, tmux, docker) - **ALREADY IMPLEMENTED**
+2. Creating new isolated users with same permissions as current user - **IMPLEMENTED**
+3. Automatic cleanup of isolated users after command completes - **IMPLEMENTED**
+4. Option to keep the user (`--keep-user`) - **IMPLEMENTED**
+
+### Related Issues
+
+- Issue #31: Support ssh isolation (execute commands on remote ssh servers)
+- Issue #9: Isolation support (closed - implemented screen/tmux/docker)
+
+### Final Implementation
+
+The `--isolated-user` option creates a new isolated user with the same group memberships as the current user:
+
+```bash
+# Create isolated user and run command (user auto-deleted after)
+$ --isolated-user -- npm test
+
+# Custom username for isolated user
+$ --isolated-user myrunner -- npm start
+$ -u myrunner -- npm start
+
+# Combine with screen isolation
+$ --isolated screen --isolated-user -- npm test
+
+# Combine with tmux detached mode
+$ -i tmux -d --isolated-user testuser -- npm run build
+
+# Keep user after command completes
+$ --isolated-user --keep-user -- npm test
+```
+
+### How It Works
+
+1. **User Creation**
+   - Creates new system user with same group memberships as current user
+   - Inherits sudo, docker, wheel, admin, and other groups
+   - Uses `sudo useradd` with `-G` flag for groups
+
+2. **Command Execution**
+   - For screen/tmux: Wraps command with `sudo -n -u <user>`
+   - For standalone (no isolation backend): Uses `sudo -n -u <user> sh -c '<command>'`
+
+3. **Cleanup**
+   - After command completes, user is deleted with `sudo userdel -r <user>`
+   - Unless `--keep-user` flag is specified
+
+### Requirements
+
+- `sudo` access with NOPASSWD configuration for:
+  - `useradd` - to create the isolated user
+  - `userdel` - to delete the isolated user
+  - `sudo -u` - to run commands as the isolated user
+
+### Benefits
+
+- Clean user environment for each run
+- Inherits sudo/docker access from current user
+- Files created during execution belong to isolated user
+- Automatic cleanup after execution (unless --keep-user)
+- Prevents untrusted code from affecting your user's files
+
+### Limitations
+
+- Not supported with Docker isolation (Docker has its own user isolation mechanism)
+- Requires sudo NOPASSWD configuration
+- Only works on Unix-like systems (Linux, macOS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "index.js",
   "bin": {

package/src/bin/cli.js

@@ -15,12 +15,19 @@ const {
 } = require('../lib/args-parser');
 const {
   runIsolated,
+  runAsIsolatedUser,
   getTimestamp,
   createLogHeader,
   createLogFooter,
   writeLogFile,
   createLogPath,
 } = require('../lib/isolation');
+const {
+  createIsolatedUser,
+  deleteUser,
+  hasSudoAccess,
+  getCurrentUserGroups,
+} = require('../lib/user-manager');
 
 // Configuration from environment variables
 const config = {
@@ -211,37 +218,35 @@ function getToolVersion(toolName, versionFlag, verbose = false) {
   return firstLine || null;
 }
 
-/**
- * Print usage information
- */
+/** Print usage information */
 function printUsage() {
-  console.log('Usage: $ [options] [--] <command> [args...]');
-  console.log('       $ <command> [args...]');
-  console.log('');
-  console.log('Options:');
-  console.log(
-    '  --isolated, -i <environment>      Run in isolated environment (screen, tmux, docker)'
-  );
-  console.log('  --attached, -a            Run in attached mode (foreground)');
-  console.log('  --detached, -d            Run in detached mode (background)');
-  console.log('  --session, -s <name>      Session name for isolation');
-  console.log(
-    '  --image <image>           Docker image (required for docker isolation)'
-  );
-  console.log(
-    '  --keep-alive, -k          Keep isolation environment alive after command exits'
-  );
-  console.log(
-    '  --auto-remove-docker-container  Automatically remove docker container after exit (disabled by default)'
-  );
-  console.log('  --version, -v             Show version information');
-  console.log('');
-  console.log('Examples:');
-  console.log('  $ echo "Hello World"');
-  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(`Usage: $ [options] [--] <command> [args...]
+       $ <command> [args...]
+
+Options:
+  --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
+  --attached, -a        Run in attached mode (foreground)
+  --detached, -d        Run in detached mode (background)
+  --session, -s <name>  Session name for isolation
+  --image <image>       Docker image (required for docker isolation)
+  --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
+  --isolated-user, -u [name]  Create isolated user with same permissions
+  --keep-user           Keep isolated user after command completes
+  --keep-alive, -k      Keep isolation environment alive after command exits
+  --auto-remove-docker-container  Auto-remove docker container after exit
+  --version, -v         Show version information
+
+Examples:
+  $ echo "Hello World"
+  $ bun test
+  $ --isolated tmux -- bun start
+  $ -i screen -d bun start
+  $ --isolated docker --image oven/bun:latest -- bun install
+  $ --isolated ssh --endpoint user@remote.server -- ls -la
+  $ --isolated-user -- npm test            # Create isolated user
+  $ -u myuser -- npm start                 # Custom username
+  $ -i screen --isolated-user -- npm test  # Combine with process isolation
+  $ --isolated-user --keep-user -- npm start`);
   console.log('');
   console.log('Piping with $:');
   console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');
@@ -311,8 +316,8 @@ if (!config.disableSubstitutions) {
 
 // Main execution
 (async () => {
-  // Check if running in isolation mode
-  if (hasIsolation(wrapperOptions)) {
+  // Check if running in isolation mode or with user isolation
+  if (hasIsolation(wrapperOptions) || wrapperOptions.user) {
     await runWithIsolation(wrapperOptions, command);
   } else {
     await runDirect(command);
@@ -330,45 +335,116 @@ async function runWithIsolation(options, cmd) {
   const startTime = getTimestamp();
 
   // Create log file path
-  const logFilePath = createLogPath(environment);
+  const logFilePath = createLogPath(environment || 'direct');
 
   // Get session name (will be generated by runIsolated if not provided)
   const sessionName =
     options.session ||
-    `${environment}-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    `${environment || 'start'}-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+
+  // Handle --isolated-user option: create a new user with same permissions
+  let createdUser = null;
+
+  if (options.user) {
+    // Check for sudo access
+    if (!hasSudoAccess()) {
+      console.error(
+        'Error: --isolated-user requires sudo access without password.'
+      );
+      console.error(
+        'Configure NOPASSWD in sudoers or run with appropriate permissions.'
+      );
+      process.exit(1);
+    }
+
+    // Get current user groups to show what will be inherited
+    const currentGroups = getCurrentUserGroups();
+    const importantGroups = ['sudo', 'docker', 'wheel', 'admin'].filter((g) =>
+      currentGroups.includes(g)
+    );
+
+    console.log(`[User Isolation] Creating new user with same permissions...`);
+    if (importantGroups.length > 0) {
+      console.log(
+        `[User Isolation] Inheriting groups: ${importantGroups.join(', ')}`
+      );
+    }
+
+    // Create the isolated user
+    const userResult = createIsolatedUser(options.userName);
+    if (!userResult.success) {
+      console.error(
+        `Error: Failed to create isolated user: ${userResult.message}`
+      );
+      process.exit(1);
+    }
+
+    createdUser = userResult.username;
+    console.log(`[User Isolation] Created user: ${createdUser}`);
+    if (userResult.groups && userResult.groups.length > 0) {
+      console.log(
+        `[User Isolation] User groups: ${userResult.groups.join(', ')}`
+      );
+    }
+    if (options.keepUser) {
+      console.log(`[User Isolation] User will be kept after command completes`);
+    }
+    console.log('');
+  }
 
   // Print start message (unified format)
   console.log(`[${startTime}] Starting: ${cmd}`);
   console.log('');
 
   // Log isolation info
-  console.log(`[Isolation] Environment: ${environment}, Mode: ${mode}`);
+  if (environment) {
+    console.log(`[Isolation] Environment: ${environment}, Mode: ${mode}`);
+  }
   if (options.session) {
     console.log(`[Isolation] Session: ${options.session}`);
   }
   if (options.image) {
     console.log(`[Isolation] Image: ${options.image}`);
   }
+  if (options.endpoint) {
+    console.log(`[Isolation] Endpoint: ${options.endpoint}`);
+  }
+  if (createdUser) {
+    console.log(`[Isolation] User: ${createdUser} (isolated)`);
+  }
   console.log('');
 
   // Create log content
   let logContent = createLogHeader({
     command: cmd,
-    environment,
+    environment: environment || 'direct',
     mode,
     sessionName,
     image: options.image,
+    user: createdUser,
     startTime,
   });
 
-  // Run in isolation
-  const result = await runIsolated(environment, cmd, {
-    session: options.session,
-    image: options.image,
-    detached: mode === 'detached',
-    keepAlive: options.keepAlive,
-    autoRemoveDockerContainer: options.autoRemoveDockerContainer,
-  });
+  let result;
+
+  if (environment) {
+    // Run in isolation backend (screen, tmux, docker, ssh)
+    result = await runIsolated(environment, cmd, {
+      session: options.session,
+      image: options.image,
+      endpoint: options.endpoint,
+      detached: mode === 'detached',
+      user: createdUser,
+      keepAlive: options.keepAlive,
+      autoRemoveDockerContainer: options.autoRemoveDockerContainer,
+    });
+  } else if (createdUser) {
+    // Run directly as the created user (no isolation backend)
+    result = await runAsIsolatedUser(cmd, createdUser);
+  } else {
+    // This shouldn't happen in isolation mode, but handle gracefully
+    result = { success: false, message: 'No isolation configuration provided' };
+  }
 
   // Get exit code
   const exitCode =
@@ -390,6 +466,23 @@ async function runWithIsolation(options, cmd) {
   console.log(`Exit code: ${exitCode}`);
   console.log(`Log saved: ${logFilePath}`);
 
+  // Cleanup: delete the created user if we created one (unless --keep-user)
+  if (createdUser && !options.keepUser) {
+    console.log('');
+    console.log(`[User Isolation] Cleaning up user: ${createdUser}`);
+    const deleteResult = deleteUser(createdUser, { removeHome: true });
+    if (deleteResult.success) {
+      console.log(`[User Isolation] User deleted successfully`);
+    } else {
+      console.log(`[User Isolation] Warning: ${deleteResult.message}`);
+    }
+  } else if (createdUser && options.keepUser) {
+    console.log('');
+    console.log(
+      `[User Isolation] Keeping user: ${createdUser} (use 'sudo userdel -r ${createdUser}' to delete)`
+    );
+  }
+
   process.exit(exitCode);
 }