start-command 0.7.6 → 0.10.0

package/ARCHITECTURE.md

@@ -0,0 +1,297 @@
+# Architecture
+
+This document describes the architecture of the `$` command (start-command).
+
+## Overview
+
+The start-command is a CLI tool that wraps shell commands to provide automatic logging, error reporting, natural language aliases, and process isolation capabilities.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         User Command                                 │
+│                    $ [options] command [args]                        │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         CLI Entry Point                              │
+│                        src/bin/cli.js                                │
+├─────────────────────────────────────────────────────────────────────┤
+│  • Parse command line arguments                                      │
+│  • Handle --version, --help flags                                    │
+│  • Route to isolation or direct execution                           │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │
+              ┌────────────────┴────────────────┐
+              │                                 │
+              ▼                                 ▼
+┌─────────────────────────┐      ┌─────────────────────────────────────┐
+│   Direct Execution      │      │     Isolated Execution              │
+│   (no --isolated)       │      │     (--isolated screen/tmux/docker) │
+├─────────────────────────┤      ├─────────────────────────────────────┤
+│ • Spawn shell process   │      │ src/lib/isolation.js                │
+│ • Capture stdout/stderr │      │ • runInScreen()                     │
+│ • Log to temp file      │      │ • runInTmux()                       │
+│ • Report failures       │      │ • runInDocker()                     │
+└─────────────────────────┘      └─────────────────────────────────────┘
+```
+
+## Core Modules
+
+### 1. CLI Entry Point (`src/bin/cli.js`)
+
+The main entry point that:
+
+- Parses command line arguments using `args-parser.js`
+- Processes command substitutions using `substitution.js`
+- Routes execution to direct mode or isolation mode
+- Handles logging and error reporting
+
+### 2. Argument Parser (`src/lib/args-parser.js`)
+
+Parses wrapper options and extracts the command to execute:
+
+```javascript
+{
+  isolated: null,     // 'screen' | 'tmux' | 'docker' | null
+  attached: false,    // Run in attached/foreground mode
+  detached: false,    // Run in detached/background mode
+  session: null,      // Custom session name
+  image: null,        // Docker image name
+  keepAlive: false,   // Keep environment alive after command exits
+}
+```
+
+### 3. Substitution Engine (`src/lib/substitution.js`)
+
+Provides natural language command aliases:
+
+- Loads patterns from `substitutions.lino`
+- Matches user input against patterns with variables
+- Returns substituted command or original if no match
+
+### 4. Isolation Module (`src/lib/isolation.js`)
+
+Handles process isolation in terminal multiplexers and containers:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                    runIsolated()                            │
+│              (dispatcher function)                          │
+└───────────────┬───────────────┬───────────────┬────────────┘
+                │               │               │
+        ┌───────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐
+        │  runInScreen  │ │runInTmux  │ │ runInDocker   │
+        │               │ │           │ │               │
+        │ GNU Screen    │ │ tmux      │ │ Docker        │
+        │ multiplexer   │ │ terminal  │ │ containers    │
+        └───────────────┘ └───────────┘ └───────────────┘
+```
+
+## Isolation Architecture
+
+### Execution Modes
+
+| Mode         | Description                                 | Default Behavior               |
+| ------------ | ------------------------------------------- | ------------------------------ |
+| Attached     | Command runs in foreground, interactive     | Session exits after completion |
+| Detached     | Command runs in background                  | Session exits after completion |
+| + Keep-Alive | Session stays alive after command completes | Requires `--keep-alive` flag   |
+
+### Auto-Exit Behavior
+
+By default, all isolation environments automatically exit after command completion:
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                    Default (keepAlive=false)                  │
+├───────────────────────────────────────────────────────────────┤
+│  1. Start isolation environment                               │
+│  2. Execute command                                           │
+│  3. Capture output (if attached mode)                         │
+│  4. Environment exits automatically                           │
+│  5. Resources freed                                           │
+└───────────────────────────────────────────────────────────────┘
+
+┌───────────────────────────────────────────────────────────────┐
+│                    With --keep-alive                          │
+├───────────────────────────────────────────────────────────────┤
+│  1. Start isolation environment                               │
+│  2. Execute command                                           │
+│  3. Command completes                                         │
+│  4. Shell stays running in session                           │
+│  5. User can reattach and interact                           │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Screen Isolation
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Screen Execution Flow                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Attached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ Uses detached mode with log capture internally           │    │
+│  │ • Start: screen -dmS <session> -L -Logfile <log>        │    │
+│  │ • Poll for session completion                            │    │
+│  │ • Read and display captured output                       │    │
+│  │ • Clean up log file                                      │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  Detached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ • Without keep-alive: screen -dmS <session> sh -c cmd   │    │
+│  │ • With keep-alive: screen -dmS <session> sh -c "cmd; sh"│    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### tmux Isolation
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      tmux Execution Flow                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Attached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ • tmux new-session -s <session> <command>               │    │
+│  │ • Interactive, exits when command completes             │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  Detached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ • Without keep-alive: tmux new-session -d -s <session>  │    │
+│  │ • With keep-alive: command followed by shell exec       │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Docker Isolation
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Docker Execution Flow                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Attached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ • docker run -it --rm --name <name> <image> sh -c cmd   │    │
+│  │ • Interactive, container auto-removed on exit           │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  Detached Mode:                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ • Without keep-alive: docker run -d --name <name> ...   │    │
+│  │ • With keep-alive: command followed by shell exec       │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Logging Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       Logging Flow                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌─────────────┐    ┌──────────────┐    ┌───────────────────┐   │
+│  │ Command     │───▶│ Capture      │───▶│ Write to          │   │
+│  │ Execution   │    │ stdout/stderr│    │ Temp Log File     │   │
+│  └─────────────┘    └──────────────┘    └───────────────────┘   │
+│                                                                  │
+│  Log File Format:                                                │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ === Start Command Log ===                                │    │
+│  │ Timestamp: 2024-01-15 10:30:45                          │    │
+│  │ Command: <command>                                       │    │
+│  │ Shell: /bin/bash                                        │    │
+│  │ Platform: linux                                          │    │
+│  │ ==================================================      │    │
+│  │ <command output>                                         │    │
+│  │ ==================================================      │    │
+│  │ Finished: 2024-01-15 10:30:46                           │    │
+│  │ Exit Code: 0                                             │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## File Structure
+
+```
+start-command/
+├── src/
+│   ├── bin/
+│   │   └── cli.js              # Main entry point
+│   └── lib/
+│       ├── args-parser.js      # Argument parsing
+│       ├── isolation.js        # Isolation backends
+│       ├── substitution.js     # Command aliases
+│       └── substitutions.lino  # Alias patterns
+├── test/
+│   ├── cli.test.js            # CLI tests
+│   ├── isolation.test.js      # Isolation tests
+│   ├── args-parser.test.js    # Parser tests
+│   └── substitution.test.js   # Substitution tests
+├── docs/
+│   ├── PIPES.md               # Piping documentation
+│   └── USAGE.md               # Usage examples
+├── experiments/               # Experimental scripts
+├── REQUIREMENTS.md            # Requirements specification
+├── ARCHITECTURE.md            # This file
+└── README.md                  # Project overview
+```
+
+## Design Decisions
+
+### 1. Auto-Exit by Default
+
+All isolation environments exit automatically after command completion to:
+
+- Prevent resource leaks from orphaned sessions
+- Ensure consistent behavior across backends
+- Match user expectations for command execution
+
+### 2. Log Capture in Attached Screen Mode
+
+Screen's attached mode uses internal detached mode with log capture because:
+
+- Direct attached mode loses output for quick commands
+- Screen's virtual terminal is destroyed before output is visible
+- Log capture ensures reliable output preservation
+
+### 3. Keep-Alive as Opt-In
+
+The `--keep-alive` flag is disabled by default because:
+
+- Most use cases don't require persistent sessions
+- Prevents accidental resource consumption
+- Explicit opt-in for advanced workflows
+
+### 4. Uniform Backend Interface
+
+All isolation backends share a consistent interface:
+
+```javascript
+async function runInBackend(command, options) {
+  return {
+    success: boolean,
+    sessionName: string,
+    message: string,
+    exitCode?: number,
+    output?: string
+  };
+}
+```
+
+This enables:
+
+- Easy addition of new backends
+- Consistent error handling
+- Unified logging format

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 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
+
+- c484149: Add --keep-alive option for isolation environments
+  - All isolation environments (screen, tmux, docker) now automatically exit after command completion by default
+  - New --keep-alive (-k) flag keeps the isolation environment running after command completes
+  - Add ARCHITECTURE.md documentation describing system design
+  - Update REQUIREMENTS.md with new option and auto-exit behavior documentation
+
 ## 0.7.6
 
 ### Patch 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,16 +200,39 @@ $ -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) |
+| 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.
 
+#### Auto-Exit Behavior
+
+By default, all isolation environments (screen, tmux, docker) automatically exit after the target command completes. This ensures resources are freed immediately and provides uniform behavior across all backends.
+
+Use `--keep-alive` (`-k`) to keep the session running after command completion:
+
+```bash
+# Default: session exits after command completes
+$ -i screen -d -- echo "hello"
+# Session will exit automatically after command completes.
+
+# With --keep-alive: session stays running for interaction
+$ -i screen -d -k -- echo "hello"
+# Session will stay alive after command completes.
+# You can reattach with: screen -r <session-name>
+```
+
+For Docker containers, by default the container filesystem is preserved (appears in `docker ps -a`) so you can re-enter it later. Use `--auto-remove-docker-container` to remove the container immediately after exit.
+
 ### Graceful Degradation
 
 The tool works in any environment:

package/REQUIREMENTS.md

@@ -142,6 +142,10 @@ 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)
 
 #### 6.3 Supported Backends
 
@@ -155,10 +159,77 @@ 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 Graceful Degradation
+#### 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:
+
+- Resources are freed immediately after command execution
+- No orphaned sessions/containers remain running
+- Uniform behavior across all isolation backends
+- Command output is still captured and logged before exit
+
+The `--keep-alive` flag can be used to override this behavior and keep the isolation environment running after command completion, useful for debugging or interactive workflows.
+
+**Docker Container Filesystem Preservation:**
+By default, when using Docker isolation, the container filesystem is preserved after the container exits. This allows you to re-enter the container and access any files created during command execution, which is useful for retrieving additional output files or debugging. The container appears in `docker ps -a` in an "exited" state but is not removed.
+
+The `--auto-remove-docker-container` flag enables automatic removal of the container after exit, which is useful when you don't need to preserve the container filesystem and want to clean up resources completely. When this flag is enabled:
+
+- The container is removed immediately after exiting (using docker's `--rm` flag)
+- The container will not appear in `docker ps -a` after command completion
+- You cannot re-enter the container to access files
+- Resources are freed more aggressively
+
+Note: `--auto-remove-docker-container` is only valid with `--isolated docker` and is independent of the `--keep-alive` flag.
+
+#### 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.7.6",
+  "version": "0.10.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "index.js",
   "bin": {