start-command 0.11.0 → 0.15.0

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

package/docs/PIPES.md

@@ -1,243 +0,0 @@
-# Piping with start-command (`$`)
-
-This document explains how to use pipes with the `$` command effectively.
-
-## Table of Contents
-
-- [Quick Summary](#quick-summary)
-- [The Preferred Way: Pipe TO `$`](#the-preferred-way-pipe-to-)
-- [Alternative: Quoting](#alternative-quoting)
-- [Why This Matters](#why-this-matters)
-- [Examples](#examples)
-- [Troubleshooting](#troubleshooting)
-
-## Quick Summary
-
-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.
-
-## The Preferred Way: Pipe TO `$`
-
-The cleanest way to use pipes with `$` is to place `$` on the command that **receives** the piped input:
-
-```bash
-# Data flows: echo "hi" -> agent (wrapped with $)
-echo "hi" | $ agent
-```
-
-This works because:
-
-1. The shell creates a pipeline: `echo "hi"` piped to `$ agent`
-2. `$ agent` receives "hi" on stdin
-3. The `$` command wraps `agent`, which processes the input
-
-### Real-World Examples
-
-```bash
-# Pipe text to an AI agent
-echo "Explain this code" | $ agent
-
-# Pipe file contents to a processor
-cat file.txt | $ processor
-
-# Pipe command output to an analyzer
-ls -la | $ analyzer
-
-# Chain multiple commands, wrap the final one
-cat data.json | jq '.items[]' | $ handler
-```
-
-### When to Use This Approach
-
-Use `command | $ target` when:
-
-- You want to pipe data INTO a command that `$` wraps
-- You want the `$` logging and monitoring for the receiving command
-- You prefer minimal quoting
-
-## Alternative: Quoting
-
-You can also wrap the entire pipeline in quotes:
-
-```bash
-# Single quotes preserve the pipe literally
-$ 'echo "hi" | agent'
-
-# The $ command receives the whole pipeline as one argument
-$ 'cat file.txt | grep pattern | wc -l'
-```
-
-### When to Use Quoting
-
-Use quotes when:
-
-- You want `$` to wrap the ENTIRE pipeline (logging all commands)
-- You need the pipeline to run as a single tracked unit
-- You want a single log file for the whole operation
-
-### Quote Types
-
-| Quote Type | Behavior           | Example                |
-| ---------- | ------------------ | ---------------------- |
-| `'single'` | Everything literal | `$ 'echo $HOME \| wc'` |
-| `"double"` | Variables expand   | `$ "echo $HOME \| wc"` |
-
-## Why This Matters
-
-### Shell Parsing Order
-
-When you type a command, the shell parses it **before** any program runs:
-
-```
-Without quotes or positioning:
-    $ echo "hi" | agent
-    └───┬────┘   └──┬──┘
-        │           │
-   Command 1    Command 2
-   ($ echo "hi")   (agent)
-
-   Result: agent receives $ output, not "hi"
-```
-
-The pipe `|` is a shell operator, so the shell splits the command at that point.
-
-### Solution Comparison
-
-```
-Preferred - Pipe TO $:
-    echo "hi" | $ agent
-    └───┬────┘   └──┬──┘
-        │           │
-   Command 1    Command 2
-   (echo "hi")    ($ agent)
-
-   Result: $ agent receives "hi" - correct!
-
-Alternative - Quoting:
-    $ 'echo "hi" | agent'
-    └─────────┬──────────┘
-              │
-        Single command
-        (pipeline runs inside $)
-
-   Result: agent receives "hi" - correct!
-```
-
-## Examples
-
-### Basic Piping
-
-```bash
-# Pipe text to a command
-echo "hello world" | $ processor
-
-# Pipe file contents
-cat config.json | $ validator
-
-# Pipe command output
-git diff | $ reviewer
-```
-
-### Multiple Pipes
-
-```bash
-# $ wraps only the final command
-cat file.txt | grep "error" | $ reporter
-
-# $ wraps the entire pipeline (quoted)
-$ 'cat file.txt | grep "error" | wc -l'
-```
-
-### With Variables
-
-```bash
-# Variable expands before piping (shell handles it)
-echo "$HOME" | $ agent
-
-# Variable preserved literally (single quotes)
-$ 'echo $HOME | wc -c'
-```
-
-### Complex Commands
-
-```bash
-# Process JSON and pipe to handler
-curl -s https://api.example.com/data | jq '.items' | $ handler
-
-# Pipe to a command with arguments
-echo "analyze this" | $ agent --verbose --format json
-```
-
-## Troubleshooting
-
-### Problem: Output goes to wrong place
-
-**Symptom:** Running `$ cmd1 | cmd2` and cmd2 receives unexpected output.
-
-**Cause:** Shell parses `|` before `$` runs, so cmd2 gets `$` output.
-
-**Solutions:**
-
-1. Pipe TO $: `cmd1 | $ cmd2`
-2. Quote: `$ 'cmd1 | cmd2'`
-
-### Problem: Command not receiving stdin
-
-**Symptom:** `echo "data" | $ cmd` but cmd doesn't see the data.
-
-**Check:** Does `cmd` read from stdin? Not all commands do.
-
-**Test:** Try `echo "data" | cmd` without `$` first.
-
-### Problem: Quotes inside quotes
-
-**Symptom:** `$ 'echo "hello 'world'"'` causes errors.
-
-**Solutions:**
-
-```bash
-# Use double quotes with escaping
-$ "echo \"hello 'world'\""
-
-# Or mix quote styles
-echo "hello 'world'" | $ processor
-```
-
-### Problem: Variables not expanding
-
-**Symptom:** `$ 'echo $HOME'` prints literal "$HOME".
-
-**Cause:** Single quotes prevent expansion.
-
-**Solutions:**
-
-```bash
-# Use double quotes (escape the pipe)
-$ "echo $HOME | wc -c"
-
-# Or pipe TO $ (variable expands in source command)
-echo "$HOME" | $ wc -c
-```
-
-## Summary
-
-| Approach  | Syntax             | Best For                    |
-| --------- | ------------------ | --------------------------- |
-| Pipe TO $ | `cmd1 \| $ cmd2`   | Simple piping, less quoting |
-| Quoted    | `$ 'cmd1 \| cmd2'` | Logging entire pipeline     |
-
-The preferred approach is **piping TO `$`** - it's simpler and avoids quote complexity.
-
-## See Also
-
-- [USAGE.md](USAGE.md) - General usage guide
-- [Case Study: Issue #28](case-studies/issue-28/README.md) - Detailed analysis