start-command 0.7.5 → 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,27 @@
 # 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
+
+- a5fca3f: Add documentation for piping with `$` command
+  - Created `docs/PIPES.md` with detailed guide on pipe usage
+  - Preferred approach: `echo "hi" | $ agent` (pipe TO the $-wrapped command)
+  - Alternative approach: `$ 'echo "hi" | agent'` (quoting)
+  - Updated `docs/USAGE.md` with brief pipe reference
+  - Updated `README.md` with piping examples
+  - Updated case study for issue #28 with new recommended approach
+
 ## 0.7.5
 
 ### Patch Changes

package/README.md

@@ -21,6 +21,29 @@ $ npm test
 $ git status
 ```
 
+### Piping with `$`
+
+When piping data to a command wrapped with `$`, **put `$` on the receiving command**:
+
+```bash
+# Preferred - pipe TO the $-wrapped command
+echo "hi" | $ agent
+
+# Alternative - quote the entire pipeline (more verbose)
+$ 'echo "hi" | agent'
+```
+
+Both approaches work, but piping TO `$` is simpler and requires fewer quotes.
+
+```bash
+# More examples
+cat file.txt | $ processor
+git diff | $ reviewer
+echo "analyze this" | $ agent --verbose
+```
+
+See [docs/PIPES.md](docs/PIPES.md) for detailed guidance on piping, and [docs/USAGE.md](docs/USAGE.md) for general usage.
+
 ### Natural Language Commands (Aliases)
 
 You can also use natural language to execute common commands. The `$` command supports pattern-based substitutions defined in `substitutions.lino`:
@@ -139,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