start-command 0.13.0 → 0.16.0

package/README.md

@@ -1,339 +0,0 @@
-# start-command (`$`)
-
-Gamification of coding - execute any command with automatic logging and ability to auto-report issues on GitHub.
-
-## Installation
-
-Install using [Bun](https://bun.sh):
-
-```bash
-bun install -g start-command
-```
-
-## Usage
-
-The `$` command acts as a wrapper for any shell command:
-
-```bash
-$ ls -la
-$ cat file.txt
-$ 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`:
-
-```bash
-# Install NPM packages
-$ install lodash npm package                    # -> npm install lodash
-$ install 4.17.21 version of lodash npm package # -> npm install lodash@4.17.21
-$ install lodash npm package globally           # -> npm install -g lodash
-
-# Clone repositories
-$ clone https://github.com/user/repo repository # -> git clone https://github.com/user/repo
-
-# Git operations
-$ checkout main branch                          # -> git checkout main
-$ create feature-x branch                       # -> git checkout -b feature-x
-
-# Common operations
-$ list files                                    # -> ls -la
-$ show current directory                        # -> pwd
-$ create my-project directory                   # -> mkdir -p my-project
-
-# Python packages
-$ install requests python package               # -> pip install requests
-```
-
-If no pattern matches, the command is executed as-is.
-
-## Features
-
-### Natural Language Aliases (Links Notation)
-
-Commands can be expressed in plain English using patterns defined in `substitutions.lino`. This file uses [Links Notation](https://github.com/link-foundation/links-notation) style patterns with variables.
-
-Each pattern is defined as a doublet link - a pair of pattern and replacement wrapped in parentheses:
-
-```
-# Pattern definition in substitutions.lino:
-(
-  install $packageName npm package
-  npm install $packageName
-)
-
-# Usage:
-$ install express npm package
-# Executes: npm install express
-```
-
-Variables like `$packageName`, `$version`, `$repository` are captured and used in the substitution.
-
-### Automatic Logging
-
-All command output is automatically saved to your system's temporary directory with timestamps:
-
-```
-[2024-01-15 10:30:45.123] Starting: npm test
-... command output ...
-[2024-01-15 10:30:52.456] Finished
-Exit code: 0
-Log saved: /tmp/start-command-1705312245123-abc123.log
-```
-
-### Exit Code Display
-
-The exit code is always prominently displayed after command completion, making it clear whether the command succeeded or failed.
-
-### Auto-Reporting on Failure (NPM packages)
-
-When a command fails (non-zero exit code) and it's a globally installed NPM package:
-
-1. **Repository Detection** - Automatically detects the GitHub repository for NPM packages
-2. **Log Upload** - Uploads the full log to GitHub (requires [gh-upload-log](https://github.com/link-foundation/gh-upload-log))
-3. **Issue Creation** - Creates an issue in the package's repository with:
-   - Command that was executed
-   - Exit code
-   - System information
-   - Link to uploaded log
-
-```
-[2024-01-15 10:30:45.123] Starting: some-npm-tool --broken-arg
-... error output ...
-[2024-01-15 10:30:46.789] Finished
-Exit code: 1
-Log saved: /tmp/start-command-1705312246789-def456.log
-
-Detected repository: https://github.com/owner/some-npm-tool
-Log uploaded: https://gist.github.com/user/abc123
-Issue created: https://github.com/owner/some-npm-tool/issues/42
-```
-
-### Process Isolation
-
-Run commands in isolated environments using terminal multiplexers, containers, or remote servers:
-
-```bash
-# Run in tmux (attached by default)
-$ --isolated tmux -- bun start
-
-# Run in screen detached
-$ --isolated screen --detached -- bun start
-
-# Run in docker container
-$ --isolated docker --image oven/bun:latest -- bun install
-
-# Run on remote server via SSH
-$ --isolated ssh --endpoint user@remote.server -- npm test
-
-# Short form with custom session name
-$ -i tmux -s my-session -d bun start
-```
-
-### User Isolation
-
-Create a new isolated user with the same group permissions as your current user to run commands in complete isolation:
-
-```bash
-# Create an isolated user with same permissions and run command
-$ --isolated-user -- npm test
-
-# Specify custom username for the isolated user
-$ --isolated-user myrunner -- npm start
-$ -u myrunner -- npm start
-
-# Combine with process isolation (screen or tmux)
-$ --isolated screen --isolated-user -- npm test
-
-# Keep the user after command completes (don't delete)
-$ --isolated-user --keep-user -- npm start
-
-# The isolated user inherits your group memberships:
-# - sudo group (if you have it)
-# - docker group (if you have it)
-# - wheel, admin, and other privileged groups
-```
-
-The `--isolated-user` option:
-
-- Creates a new system user with the same group memberships as your current user
-- Runs the command as that user
-- Automatically deletes the user after the command completes (unless `--keep-user` is specified)
-- Requires sudo access without password (NOPASSWD configuration)
-- Works with screen and tmux isolation backends (not docker)
-
-This is useful for:
-
-- Running untrusted code in isolation
-- Testing with a clean user environment
-- Ensuring commands don't affect your user's files
-
-#### Supported Backends
-
-| Backend  | Description                                    | Installation                                               |
-| -------- | ---------------------------------------------- | ---------------------------------------------------------- |
-| `screen` | GNU Screen terminal multiplexer                | `apt install screen` / `brew install screen`               |
-| `tmux`   | Modern terminal multiplexer                    | `apt install tmux` / `brew install tmux`                   |
-| `docker` | Container isolation (requires --image)         | [Docker Installation](https://docs.docker.com/get-docker/) |
-| `ssh`    | Remote execution via SSH (requires --endpoint) | `apt install openssh-client` / `brew install openssh`      |
-
-#### Isolation Options
-
-| Option                           | Description                                               |
-| -------------------------------- | --------------------------------------------------------- |
-| `--isolated, -i`                 | Isolation backend (screen, tmux, docker, ssh)             |
-| `--attached, -a`                 | Run in attached/foreground mode (default)                 |
-| `--detached, -d`                 | Run in detached/background mode                           |
-| `--session, -s`                  | Custom session/container name                             |
-| `--image`                        | Docker image (required for docker isolation)              |
-| `--endpoint`                     | SSH endpoint (required for ssh, e.g., user@host)          |
-| `--isolated-user, -u [name]`     | Create isolated user with same permissions (screen/tmux)  |
-| `--keep-user`                    | Keep isolated user after command completes (don't delete) |
-| `--keep-alive, -k`               | Keep session alive after command completes                |
-| `--auto-remove-docker-container` | Auto-remove docker container after exit (docker only)     |
-
-**Note:** Using both `--attached` and `--detached` together will result in an error - you must choose one mode.
-
-#### 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:
-
-- **No `gh` CLI?** - Logs are still saved locally, auto-reporting is skipped
-- **No `gh-upload-log`?** - Issue can still be created with local log reference
-- **Repository not detected?** - Command runs normally with logging
-- **No permission to create issue?** - Skipped with a clear message
-- **Isolation backend not installed?** - Clear error message with installation instructions
-
-## Requirements
-
-### Required
-
-- [Bun](https://bun.sh) >= 1.0.0
-
-### Optional (for full auto-reporting)
-
-- [GitHub CLI (`gh`)](https://cli.github.com/) - For authentication and issue creation
-- [gh-upload-log](https://github.com/link-foundation/gh-upload-log) - For uploading log files
-
-To set up auto-reporting:
-
-```bash
-# Install GitHub CLI and authenticate
-gh auth login
-
-# Install log uploader
-bun install -g gh-upload-log
-```
-
-## How It Works
-
-1. **Command Execution** - Your command is passed directly to the shell (bash/powershell/sh)
-2. **Output Capture** - Both stdout and stderr are captured while still being displayed
-3. **Log File** - Complete output is saved with timestamps and system info
-4. **Failure Handling** - On non-zero exit:
-   - Detects if the command is an NPM package
-   - Looks up the package's GitHub repository
-   - Uploads log (if `gh-upload-log` is available)
-   - Creates an issue (if `gh` is authenticated and has permission)
-
-## Configuration
-
-The following environment variables can be used to customize behavior:
-
-| Variable                      | Description                                                    |
-| ----------------------------- | -------------------------------------------------------------- |
-| `START_DISABLE_AUTO_ISSUE`    | Set to `1` or `true` to disable automatic issue creation       |
-| `START_DISABLE_LOG_UPLOAD`    | Set to `1` or `true` to disable log upload                     |
-| `START_LOG_DIR`               | Custom directory for log files (defaults to OS temp directory) |
-| `START_VERBOSE`               | Set to `1` or `true` for verbose output                        |
-| `START_DISABLE_SUBSTITUTIONS` | Set to `1` or `true` to disable pattern matching/aliases       |
-| `START_SUBSTITUTIONS_PATH`    | Custom path to substitutions.lino file                         |
-
-Example:
-
-```bash
-# Run without auto-issue creation
-START_DISABLE_AUTO_ISSUE=1 $ bun test
-
-# Use custom log directory
-START_LOG_DIR=./logs $ bun test
-
-# Disable substitutions (use raw command)
-START_DISABLE_SUBSTITUTIONS=1 $ install lodash npm package
-
-# Use custom substitutions file
-START_SUBSTITUTIONS_PATH=/path/to/my-rules.lino $ install mypackage npm package
-```
-
-### Custom Substitutions
-
-You can create your own substitution patterns by placing a `substitutions.lino` file in `~/.start-command/substitutions.lino`. User patterns take precedence over the default ones.
-
-## Log File Format
-
-Log files are saved as `start-command-{timestamp}-{random}.log` and contain:
-
-```
-=== Start Command Log ===
-Timestamp: 2024-01-15 10:30:45.123
-Command: bun test
-Shell: /bin/bash
-Platform: linux
-Bun Version: 1.2.0
-Working Directory: /home/user/project
-==================================================
-
-... command output ...
-
-==================================================
-Finished: 2024-01-15 10:30:52.456
-Exit Code: 0
-```
-
-## License
-
-MIT

package/REQUIREMENTS.md

@@ -1,299 +0,0 @@
-# Requirements for `$` Command (start-command)
-
-## Overview
-
-The `$` command is a CLI tool that wraps any shell command and provides automatic logging, error reporting, issue creation capabilities, and natural language command aliases.
-
-## Core Requirements
-
-### 1. Command Proxy Functionality
-
-- Act as a transparent proxy for any shell command
-- Pass all arguments directly to the underlying shell (bash/powershell/sh)
-- Support all standard commands: `$ ls`, `$ cat`, `$ mkdir`, etc.
-- Preserve exit codes from wrapped commands
-- Support natural language command aliases via pattern matching
-
-### 2. Logging Requirements
-
-#### 2.1 Log Storage
-
-- Save full command output (stdout + stderr) to temporary OS directory
-- Use platform-appropriate temp directory:
-  - Linux/macOS: `/tmp/` or `os.tmpdir()`
-  - Windows: `%TEMP%`
-- Log file naming: `start-command-{timestamp}-{random}.log`
-
-#### 2.2 Log Content
-
-- Include timestamp at the start of logging
-- Include timestamp at the end of logging
-- Capture both stdout and stderr
-- Store the complete command that was executed
-- Store the exit code
-
-#### 2.3 Log Display
-
-- Print full log content to console after command finishes
-- Always print the exit code (success or failure)
-- Make exit code prominent as "it may usually be unclear"
-
-### 3. Repository Detection
-
-#### 3.1 NPM Package Detection
-
-- Detect if the executed command is a globally installed NPM package
-- Use `which` (Unix) or `where` (Windows) to find command location
-- Check if command resolves to a path within npm global modules
-- Extract package name from the path
-- Use `npm view <package> repository.url` to get repository URL
-
-#### 3.2 Supported Command Types
-
-- Globally installed NPM packages (primary focus)
-- Future: other package managers (pip, gem, etc.)
-
-### 4. Automatic Issue Reporting (On Failure)
-
-#### 4.1 Preconditions for Auto-Reporting
-
-- Command must have failed (non-zero exit code)
-- Repository must be detected for the command
-- `gh` CLI tool must be authenticated
-- User must have permission to create issues in target repository
-
-#### 4.2 Log Upload
-
-- Use `gh-upload-log` tool to upload the log file
-- Upload as a gist (for logs ≤100MB)
-- Print the uploaded log URL to console
-
-#### 4.3 Issue Creation
-
-- Create an issue in the detected repository
-- Issue title: Include command name and error summary
-- Issue body: Include:
-  - Command that was executed
-  - Exit code
-  - Link to uploaded log
-  - System information (OS, Bun/Node.js version)
-  - Timestamp
-- Print the created issue URL to console
-
-### 5. Graceful Degradation
-
-#### 5.1 When Repository Cannot Be Detected
-
-- Still log everything to temp directory
-- Still print logs and exit code to console
-- Skip log upload and issue creation
-
-#### 5.2 When `gh` Is Not Authenticated
-
-- Still log everything to temp directory
-- Still print logs and exit code to console
-- Print a message that auto-reporting is skipped
-- Skip log upload and issue creation
-
-#### 5.3 When `gh-upload-log` Is Not Installed
-
-- Still log everything to temp directory
-- Still print logs and exit code to console
-- Print a message that log upload is skipped
-- Skip issue creation (no log link available)
-
-### 5. Command Aliases / Substitutions
-
-#### 5.1 Pattern Matching
-
-- Support natural language patterns defined in `substitutions.lino`
-- Use Links Notation style with variables like `$packageName`, `$version`
-- Match input against patterns and substitute with actual commands
-- More specific patterns (more variables, longer patterns) take precedence
-- Non-matching commands pass through unchanged
-
-#### 5.2 Built-in Patterns
-
-- NPM: `install $packageName npm package` -> `npm install $packageName`
-- NPM with version: `install $version version of $packageName npm package` -> `npm install $packageName@$version`
-- Git clone: `clone $repository repository` -> `git clone $repository`
-- Git checkout: `checkout $branch branch` -> `git checkout $branch`
-- Common operations: `list files` -> `ls -la`, `show current directory` -> `pwd`
-
-#### 5.3 Custom Patterns
-
-- Support user-defined patterns in `~/.start-command/substitutions.lino`
-- User patterns take precedence over built-in patterns
-- Support custom path via `START_SUBSTITUTIONS_PATH` environment variable
-
-### 6. Process Isolation
-
-#### 6.1 Command Syntax
-
-Support two patterns for passing wrapper options:
-
-- `$ [wrapper-options] -- [command] [command-options]` (explicit separator)
-- `$ [wrapper-options] command [command-options]` (options before command)
-
-#### 6.2 Isolation Options
-
-- `--isolated, -i <backend>`: Run command in isolated environment
-- `--attached, -a`: Run in attached/foreground mode (default)
-- `--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
-
-- `screen`: GNU Screen terminal multiplexer
-- `tmux`: tmux terminal multiplexer
-- `docker`: Docker containers (requires --image option)
-
-#### 6.4 Mode Behavior
-
-- **Attached mode**: Command runs in foreground, user can interact
-- **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 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
-
-- `START_DISABLE_AUTO_ISSUE`: Disable automatic issue creation
-- `START_DISABLE_LOG_UPLOAD`: Disable log upload
-- `START_LOG_DIR`: Custom log directory
-- `START_VERBOSE`: Enable verbose output
-- `START_DISABLE_SUBSTITUTIONS`: Disable pattern matching/aliases
-- `START_SUBSTITUTIONS_PATH`: Custom path to substitutions file
-
-## Output Format
-
-### Success Case
-
-```
-[2024-01-15 10:30:45] Starting: ls -la
-... command output ...
-[2024-01-15 10:30:45] Finished
-Exit code: 0
-Log saved: /tmp/start-command-1705312245-abc123.log
-```
-
-### Failure Case (With Auto-Reporting)
-
-```
-[2024-01-15 10:30:45] Starting: failing-npm-command --arg
-... command output/error ...
-[2024-01-15 10:30:46] Finished
-Exit code: 1
-Log saved: /tmp/start-command-1705312246-def456.log
-Detected repository: https://github.com/owner/repo
-Log uploaded: https://gist.github.com/...
-Issue created: https://github.com/owner/repo/issues/123
-```
-
-### Failure Case (Without Auto-Reporting)
-
-```
-[2024-01-15 10:30:45] Starting: unknown-command
-... command output/error ...
-[2024-01-15 10:30:45] Finished
-Exit code: 127
-Log saved: /tmp/start-command-1705312245-ghi789.log
-Repository not detected - automatic issue creation skipped
-```
-
-## Dependencies
-
-### Required
-
-- **Bun >= 1.0.0** (primary runtime)
-- `child_process` (built-in)
-- `os` (built-in)
-- `fs` (built-in)
-- `path` (built-in)
-
-### Optional (for full functionality)
-
-- `gh` CLI - GitHub CLI for authentication and issue creation
-- `gh-upload-log` - For uploading log files to GitHub
-
-## Security Considerations
-
-- Do not include sensitive environment variables in logs
-- Do not include authentication tokens in issue reports
-- Respect `.gitignore` patterns when detecting repositories
-- Only create issues in public repositories unless explicitly authorized