start-command 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # start-command
 
+## 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

@@ -152,6 +152,44 @@ $ --isolated docker --image oven/bun:latest -- bun install
 $ -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                                               |
@@ -162,15 +200,17 @@ $ -i tmux -s my-session -d bun start
 
 #### 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)                  |
+| `--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)              |
+| `--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.10.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,33 @@ 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)
+  --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)
+  --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-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 +314,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 +333,112 @@ 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 (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)
+    result = await runIsolated(environment, cmd, {
+      session: options.session,
+      image: options.image,
+      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 +460,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);
 }
 

package/src/lib/args-parser.js

@@ -11,6 +11,8 @@
  * --detached, -d                   Run in detached mode (background)
  * --session, -s <name>             Session name for isolation
  * --image <image>                  Docker image (required for docker isolation)
+ * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
+ * --keep-user                      Keep isolated user after command completes (don't delete)
  * --keep-alive, -k                 Keep isolation environment alive after command exits
  * --auto-remove-docker-container   Automatically remove docker container after exit (disabled by default)
  */
@@ -36,6 +38,9 @@ function parseArgs(args) {
     detached: false, // Run in detached mode
     session: null, // Session name
     image: null, // Docker image
+    user: false, // Create isolated user
+    userName: null, // Optional custom username for isolated user
+    keepUser: false, // Keep isolated user after command completes (don't delete)
     keepAlive: false, // Keep environment alive after command exits
     autoRemoveDockerContainer: false, // Auto-remove docker container after exit
   };
@@ -175,6 +180,35 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --isolated-user or -u [optional-username] - creates isolated user with same permissions
+  if (arg === '--isolated-user' || arg === '-u') {
+    options.user = true;
+    // Check if next arg is an optional username (not starting with -)
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      // Check if next arg looks like a username (not a command)
+      const nextArg = args[index + 1];
+      // If next arg matches username format, consume it
+      if (/^[a-zA-Z0-9_-]+$/.test(nextArg) && nextArg.length <= 32) {
+        options.userName = nextArg;
+        return 2;
+      }
+    }
+    return 1;
+  }
+
+  // --isolated-user=<value>
+  if (arg.startsWith('--isolated-user=')) {
+    options.user = true;
+    options.userName = arg.split('=')[1];
+    return 1;
+  }
+
+  // --keep-user - keep isolated user after command completes
+  if (arg === '--keep-user') {
+    options.keepUser = true;
+    return 1;
+  }
+
   // --keep-alive or -k
   if (arg === '--keep-alive' || arg === '-k') {
     options.keepAlive = true;
@@ -241,6 +275,34 @@ function validateOptions(options) {
       '--auto-remove-docker-container option is only valid with --isolated docker'
     );
   }
+
+  // User isolation validation
+  if (options.user) {
+    // User isolation is not supported with Docker (Docker has its own user mechanism)
+    if (options.isolated === 'docker') {
+      throw new Error(
+        '--isolated-user is not supported with Docker isolation. Docker uses its own user namespace for isolation.'
+      );
+    }
+    // Validate custom username if provided
+    if (options.userName) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(options.userName)) {
+        throw new Error(
+          `Invalid username format for --isolated-user: "${options.userName}". Username should contain only letters, numbers, hyphens, and underscores.`
+        );
+      }
+      if (options.userName.length > 32) {
+        throw new Error(
+          `Username too long for --isolated-user: "${options.userName}". Maximum length is 32 characters.`
+        );
+      }
+    }
+  }
+
+  // Keep-user validation
+  if (options.keepUser && !options.user) {
+    throw new Error('--keep-user option is only valid with --isolated-user');
+  }
 }
 
 /**