start-command 0.7.6 → 0.9.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,15 @@
 # start-command
 
+## 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

@@ -162,16 +162,37 @@ $ -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)          |
+| `--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,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)
+- `--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,7 +157,30 @@ 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 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.6 Graceful Degradation
 
 - If isolation backend is not installed, show informative error with installation instructions
 - If session creation fails, report error with details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.7.6",
+  "version": "0.9.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

@@ -228,6 +228,12 @@ function printUsage() {
   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:');
@@ -360,6 +366,8 @@ async function runWithIsolation(options, cmd) {
     session: options.session,
     image: options.image,
     detached: mode === 'detached',
+    keepAlive: options.keepAlive,
+    autoRemoveDockerContainer: options.autoRemoveDockerContainer,
   });
 
   // Get exit code

package/src/lib/args-parser.js

@@ -6,11 +6,13 @@
  * 2. $ [wrapper-options] command [command-options]
  *
  * Wrapper Options:
- * --isolated, -i <backend>  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, -i <backend>         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)
+ * --keep-alive, -k                 Keep isolation environment alive after command exits
+ * --auto-remove-docker-container   Automatically remove docker container after exit (disabled by default)
  */
 
 // Debug mode from environment
@@ -34,6 +36,8 @@ function parseArgs(args) {
     detached: false, // Run in detached mode
     session: null, // Session name
     image: null, // Docker image
+    keepAlive: false, // Keep environment alive after command exits
+    autoRemoveDockerContainer: false, // Auto-remove docker container after exit
   };
 
   let commandArgs = [];
@@ -171,6 +175,18 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --keep-alive or -k
+  if (arg === '--keep-alive' || arg === '-k') {
+    options.keepAlive = true;
+    return 1;
+  }
+
+  // --auto-remove-docker-container
+  if (arg === '--auto-remove-docker-container') {
+    options.autoRemoveDockerContainer = true;
+    return 1;
+  }
+
   // Not a recognized wrapper option
   return 0;
 }
@@ -213,6 +229,18 @@ function validateOptions(options) {
   if (options.image && options.isolated !== 'docker') {
     throw new Error('--image option is only valid with --isolated docker');
   }
+
+  // Keep-alive is only valid with isolation
+  if (options.keepAlive && !options.isolated) {
+    throw new Error('--keep-alive option is only valid with --isolated');
+  }
+
+  // Auto-remove-docker-container is only valid with docker isolation
+  if (options.autoRemoveDockerContainer && options.isolated !== 'docker') {
+    throw new Error(
+      '--auto-remove-docker-container option is only valid with --isolated docker'
+    );
+  }
 }
 
 /**