@push.rocks/smartshell 3.2.3 → 3.3.0

package/readme.md

@@ -1,136 +1,617 @@
-# @push.rocks/smartshell
-shell actions designed as promises
+# @push.rocks/smartshell 🐚
+**Execute shell commands with superpowers in Node.js**
 
-## Install
+[![npm version](https://img.shields.io/npm/v/@push.rocks/smartshell.svg)](https://www.npmjs.com/package/@push.rocks/smartshell)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-To install `@push.rocks/smartshell`, use npm:
+## ⚠️ Security Notice
 
-```sh
+**IMPORTANT:** Please read the [Security Guide](#security-guide) below for critical information about command execution and input handling. Always use `execSpawn` methods for untrusted input.
+
+## Why smartshell? 🚀
+
+Tired of wrestling with Node.js child processes? Meet `@push.rocks/smartshell` - your promise-based shell command companion that makes executing system commands feel like a breeze. Whether you're building automation scripts, CI/CD pipelines, or need fine-grained control over shell execution, smartshell has got you covered.
+
+### ✨ Key Features
+
+- 🎯 **Promise-based API** - Async/await ready for modern codebases
+- 🔇 **Silent execution modes** - Control output verbosity 
+- 📡 **Streaming support** - Real-time output for long-running processes
+- 🎮 **Interactive commands** - Handle user input programmatically
+- 🛡️ **Secure execution** - Shell-free methods for untrusted input
+- ⚡ **Smart execution modes** - Strict, silent, or streaming
+- 🔍 **Pattern matching** - Wait for specific output patterns
+- 🌍 **Environment management** - Custom env vars and PATH handling
+- 💾 **Memory protection** - Built-in buffer limits prevent OOM
+- ⏱️ **Timeout support** - Automatic process termination
+- 🖥️ **PTY support** - Full terminal emulation (optional)
+- 🎨 **Cross-platform** - Windows, macOS, and Linux ready
+- 🛡️ **TypeScript first** - Full type safety and IntelliSense
+
+## Installation 📦
+
+```bash
+# Using npm
 npm install @push.rocks/smartshell --save
+
+# Using yarn 
+yarn add @push.rocks/smartshell
+
+# Using pnpm (recommended)
+pnpm add @push.rocks/smartshell
+
+# Optional: For PTY support (terminal emulation)
+pnpm add --save-optional node-pty
 ```
 
-Or if you prefer using Yarn:
+## Quick Start 🏃‍♂️
 
-```sh
-yarn add @push.rocks/smartshell
+```typescript
+import { Smartshell } from '@push.rocks/smartshell';
+
+// Create your shell instance
+const shell = new Smartshell({
+  executor: 'bash' // or 'sh' for lighter shells
+});
+
+// Run a simple command
+const result = await shell.exec('echo "Hello, World!"');
+console.log(result.stdout); // "Hello, World!"
+console.log(result.signal); // undefined (no signal)
+console.log(result.stderr); // "" (no errors)
 ```
 
-Ensure that you have TypeScript and the related dependencies installed as well since `@push.rocks/smartshell` is designed to work with TypeScript.
+## Security-First Execution 🔒
+
+### Secure Command Execution with execSpawn
 
-## Usage
+When dealing with untrusted input, **always use execSpawn methods** which don't use shell interpretation:
 
-The `@push.rocks/smartshell` package simplifies running shell commands within Node.js applications by wrapping these commands within promises. This approach enhances the readability and maintainability of code that relies on shell execution, making it particularly useful in automation scripts, build processes, and any scenario where interaction with the system shell is required.
+```typescript
+// ❌ DANGEROUS with untrusted input
+const userInput = "file.txt; rm -rf /";
+await shell.exec(`cat ${userInput}`); // Command injection!
 
-### Getting Started with `@push.rocks/smartshell`
+// ✅ SAFE with untrusted input
+await shell.execSpawn('cat', [userInput]); // Arguments are properly escaped
+```
 
-First, ensure that you import `Smartshell` from `@push.rocks/smartshell` using ESM syntax in your TypeScript file:
+### execSpawn Family Methods
 
 ```typescript
-import { Smartshell } from '@push.rocks/smartshell';
+// Basic secure execution
+const result = await shell.execSpawn('ls', ['-la', '/home']);
+
+// Streaming secure execution
+const streaming = await shell.execSpawnStreaming('npm', ['install']);
+await streaming.finalPromise;
+
+// Interactive secure execution
+const interactive = await shell.execSpawnInteractiveControl('cat', []);
+await interactive.sendLine('Hello');
+interactive.endInput();
+await interactive.finalPromise;
+```
+
+## Production Features 🏭
+
+### Resource Management
+
+Prevent memory issues with built-in buffer limits:
+
+```typescript
+const result = await shell.exec('large-output-command', {
+  maxBuffer: 10 * 1024 * 1024, // 10MB limit
+  onData: (chunk) => {
+    // Process chunks as they arrive
+    console.log('Received:', chunk.toString());
+  }
+});
+```
+
+### Timeout Support
+
+Automatically terminate long-running processes:
+
+```typescript
+try {
+  const result = await shell.execSpawn('long-process', [], {
+    timeout: 5000 // 5 second timeout
+  });
+} catch (error) {
+  console.log('Process timed out');
+}
+```
+
+### Debug Mode
+
+Enable detailed logging for troubleshooting:
+
+```typescript
+const result = await shell.exec('command', {
+  debug: true // Logs process lifecycle events
+});
 ```
 
-### Creating a Smartshell Instance
+### Custom Environment
 
-Before executing any shell command, you need to create an instance of `Smartshell`. The constructor accepts configuration options such as the shell executor (`bash` or `sh`), and optionally, paths to source files and directories to include in the shell’s environment.
+Control the execution environment precisely:
 
 ```typescript
-const smartShellInstance = new Smartshell({
-  executor: 'bash', // or 'sh'
+const result = await shell.execSpawn('node', ['script.js'], {
+  env: {
+    NODE_ENV: 'production',
+    PATH: '/usr/bin:/bin',
+    CUSTOM_VAR: 'value'
+  }
 });
 ```
 
-### Executing Commands
+## Interactive Control 🎮
 
-#### Basic Execution
+### Programmatic Input Control
 
-To execute a shell command, use the `exec` method. This method returns a promise that resolves with an execution result object containing `exitCode` and `stdout`.
+Send input to processes programmatically:
 
 ```typescript
-(async () => {
-  const result = await smartShellInstance.exec('echo "Hello, SmartShell"');
-  console.log(result.stdout); // Outputs: Hello, SmartShell
-})();
+const interactive = await shell.execInteractiveControl('cat');
+
+// Send input line by line
+await interactive.sendLine('Line 1');
+await interactive.sendLine('Line 2');
+
+// Send raw input without newline
+await interactive.sendInput('partial');
+
+// Close stdin
+interactive.endInput();
+
+// Wait for completion
+const result = await interactive.finalPromise;
 ```
 
-#### Silent Execution
+### Passthrough Mode
 
-If you prefer not to display the output in the console, use `execSilent`:
+Connect stdin for real keyboard interaction:
 
 ```typescript
-(async () => {
-  const result = await smartShellInstance.execSilent('ls');
-  console.log(result.stdout); // Outputs the list of files and directories
-})();
+// User can type directly
+await shell.execPassthrough('vim file.txt');
 ```
 
-#### Strict Execution
+## PTY Support - Full Terminal Emulation 🖥️
+
+Smartshell provides two modes for executing interactive commands:
+
+1. **Pipe Mode (Default)** - Fast, simple, no dependencies
+2. **PTY Mode** - Full terminal emulation for advanced interactive programs
 
-For scenarios where an execution error should immediately throw an exception, use `execStrict`:
+### When to Use Each Mode
+
+#### Use Pipe Mode (Default) When:
+- Running simple commands that read from stdin
+- Using tools like `cat`, `grep`, `sed`, `awk`
+- Running basic scripts that don't need terminal features
+- You want maximum performance and simplicity
+- You don't want native dependencies
+
+#### Use PTY Mode When:
+- Running commands that require a real terminal:
+  - Password prompts (`sudo`, `ssh`, `su`)
+  - Interactive editors (`vim`, `nano`, `emacs`)
+  - Terminal UIs (`htop`, `less`, `more`)
+  - Programs with fancy prompts (`bash read -p`)
+  - Tab completion and readline features
+- You need terminal features:
+  - ANSI colors and escape sequences
+  - Terminal size control
+  - Signal handling (Ctrl+C, Ctrl+Z)
+  - Line discipline and special key handling
+
+### Installing PTY Support
+
+PTY support requires the optional `node-pty` dependency:
+
+```bash
+# Install as optional dependency
+pnpm add --save-optional node-pty
+
+# Note: node-pty requires compilation and has platform-specific requirements
+# - On Windows: Requires Visual Studio Build Tools
+# - On macOS/Linux: Requires Python and build tools
+```
+
+### PTY Usage Examples
 
 ```typescript
-(async () => {
-  try {
-    const result = await smartShellInstance.execStrict('exit 1');
-  } catch (error) {
-    console.error('Command execution failed');
+// Use PTY for commands that need terminal features
+const ptyInteractive = await shell.execInteractiveControlPty(
+  "bash -c 'read -p \"Enter name: \" name && echo \"Hello, $name\"'"
+);
+await ptyInteractive.sendLine('John');
+const result = await ptyInteractive.finalPromise;
+// With PTY, the prompt "Enter name: " will be visible in stdout
+
+// Streaming with PTY for real-time interaction
+const ptyStreaming = await shell.execStreamingInteractiveControlPty('vim test.txt');
+await ptyStreaming.sendInput('i'); // Enter insert mode
+await ptyStreaming.sendInput('Hello from PTY!');
+await ptyStreaming.sendInput('\x1b'); // ESC key
+await ptyStreaming.sendInput(':wq\r'); // Save and quit
+```
+
+### PTY vs Pipe Mode Comparison
+
+| Feature | Pipe Mode | PTY Mode |
+|---------|-----------|----------|
+| Dependencies | None | node-pty |
+| Terminal Detection | `isatty()` returns false | `isatty()` returns true |
+| Prompt Display | May not show | Always shows |
+| Colors | Often disabled | Enabled |
+| Signal Handling | Basic | Full (Ctrl+C, Ctrl+Z, etc.) |
+| Line Ending | `\n` | `\r` (carriage return) |
+| EOF Signal | Stream end | `\x04` (Ctrl+D) |
+
+### Common PTY Patterns
+
+```typescript
+// Password input (PTY required)
+const sudo = await shell.execInteractiveControlPty('sudo ls /root');
+await sudo.sendLine('mypassword');
+const result = await sudo.finalPromise;
+
+// Interactive REPL with colors
+const node = await shell.execStreamingInteractiveControlPty('node');
+await node.sendLine('console.log("PTY supports colors!")');
+await node.sendLine('.exit');
+
+// Handling terminal colors
+const ls = await shell.execInteractiveControlPty('ls --color=always');
+const result = await ls.finalPromise;
+// result.stdout will contain ANSI color codes
+```
+
+### PTY Fallback Strategy
+
+Always provide a fallback for when PTY isn't available:
+
+```typescript
+try {
+  // Try PTY mode first
+  const result = await shell.execInteractiveControlPty(command);
+  // ...
+} catch (error) {
+  if (error.message.includes('node-pty')) {
+    // Fallback to pipe mode
+    console.warn('PTY not available, using pipe mode');
+    const result = await shell.execInteractiveControl(command);
+    // ...
   }
-})();
+}
 ```
 
-#### Streaming Output
+## Advanced Pattern Matching 🔍
+
+### Enhanced execAndWaitForLine
 
-Some commands benefit from streaming output as they execute, especially long-running tasks. For these cases, use `execStreaming`:
+Wait for patterns with timeout and auto-termination:
 
 ```typescript
-(async () => {
-  const execStreamingResult = await smartShellInstance.execStreaming('tail -f /var/log/system.log');
-  
-  execStreamingResult.childProcess.stdout.on('data', (data) => {
-    console.log(data.toString());
-  });
+// Wait with timeout
+await shell.execAndWaitForLine(
+  'npm start',
+  /Server listening on port/,
+  false, // silent
+  {
+    timeout: 30000,        // 30 second timeout
+    terminateOnMatch: true // Kill process after match
+  }
+);
+```
+
+## Core Concepts 💡
+
+### The Smartshell Instance
+
+The heart of smartshell is the `Smartshell` class. Each instance maintains its own environment and configuration:
 
-  // Remember to handle the process termination as necessary.
-})();
+```typescript
+const shell = new Smartshell({
+  executor: 'bash', // Choose your shell: 'bash' or 'sh'
+  sourceFilePaths: ['/path/to/env.sh'], // Optional: source files on init
+});
 ```
 
-### Advanced Usage
+## Execution Modes 🎛️
+
+### Standard Execution
+
+Perfect for general commands where you want to see the output:
+
+```typescript
+const result = await shell.exec('ls -la');
+console.log(result.stdout); // Directory listing
+console.log(result.exitCode); // 0 for success
+console.log(result.signal); // Signal if terminated
+console.log(result.stderr); // Error output
+```
 
-#### Executing With Custom Environment Variables
+### Silent Execution
 
-`smartshell` allows for the execution of commands within a modified environment, facilitating the use of custom variables or altered PATH values:
+Run commands without printing to console - ideal for capturing output:
 
 ```typescript
-(async () => {
-  smartShellInstance.shellEnv.addSourceFiles(['/path/to/envFile']);
-  smartShellInstance.shellEnv.pathDirArray.push('/custom/bin');
+const result = await shell.execSilent('cat /etc/hostname');
+// Output is NOT printed to console but IS captured in result
+console.log(result.stdout);  // Access the captured output here
+```
+
+### Strict Execution
+
+Throws an error if the command fails - great for critical operations:
+
+```typescript
+try {
+  await shell.execStrict('critical-command');
+  console.log('✅ Command succeeded!');
+} catch (error) {
+  console.error('❌ Command failed:', error.message);
+  // Error includes exit code or signal information
+}
+```
+
+### Streaming Execution
+
+For long-running processes or when you need real-time output:
+
+```typescript
+const streaming = await shell.execStreaming('npm install');
+
+// Access the child process directly
+streaming.childProcess.stdout.on('data', (chunk) => {
+  console.log('📦 Installing:', chunk.toString());
+});
+
+// Control the process
+await streaming.terminate(); // SIGTERM
+await streaming.kill();      // SIGKILL
+await streaming.keyboardInterrupt(); // SIGINT
+
+// Wait for completion
+await streaming.finalPromise;
+```
+
+## Real-World Examples 🌍
+
+### Build Pipeline
+
+```typescript
+const shell = new Smartshell({ executor: 'bash' });
+
+// Clean build directory
+await shell.execSilent('rm -rf dist');
+
+// Run TypeScript compiler
+const buildResult = await shell.execStrict('tsc');
+
+// Run tests
+await shell.execStrict('npm test');
+
+// Build succeeded!
+console.log('✅ Build pipeline completed successfully');
+```
+
+### CI/CD with Security
+
+```typescript
+async function deployApp(branch: string, untrustedTag: string) {
+  const shell = new Smartshell({ executor: 'bash' });
+  
+  // Use execSpawn for untrusted input
+  await shell.execSpawnStrict('git', ['checkout', branch]);
+  await shell.execSpawnStrict('git', ['tag', untrustedTag]);
   
-  const result = await smartShellInstance.exec('echo $CUSTOM_VAR');
-  console.log(result.stdout); // Outputs the value of CUSTOM_VAR
-})();
+  // Safe to use exec for hardcoded commands
+  await shell.execStrict('npm run build');
+  await shell.execStrict('npm run deploy');
+}
 ```
 
-### Interactive Mode
+### Docker Compose Helper
 
-For commands that require interactive terminal input (not typically recommended for automated scripts), you can use `execInteractive`:
+```typescript
+const shell = new Smartshell({ executor: 'bash' });
+
+// Start services and wait for readiness
+console.log('🐳 Starting Docker services...');
+await shell.execAndWaitForLine(
+  'docker-compose up',
+  /All services are ready/,
+  false,
+  { 
+    timeout: 60000,
+    terminateOnMatch: false // Keep running after match
+  }
+);
+
+// Run migrations
+await shell.execStrict('docker-compose exec app npm run migrate');
+console.log('✅ Environment ready!');
+```
+
+### Development Server with Auto-Restart
+
+```typescript
+import { SmartExecution } from '@push.rocks/smartshell';
+
+const shell = new Smartshell({ executor: 'bash' });
+const devServer = new SmartExecution(shell, 'npm run dev');
+
+// Watch for file changes and restart
+fs.watch('./src', async () => {
+  console.log('🔄 Changes detected, restarting...');
+  await devServer.restart();
+});
+```
+
+## API Reference 📚
+
+### Smartshell Class
+
+| Method | Description | Security |
+|--------|-------------|----------|
+| `exec(command)` | Execute with shell | ⚠️ Vulnerable to injection |
+| `execSpawn(cmd, args)` | Execute without shell | ✅ Safe for untrusted input |
+| `execSilent(command)` | Execute without console output | ⚠️ Vulnerable to injection |
+| `execStrict(command)` | Execute, throw on failure | ⚠️ Vulnerable to injection |
+| `execStreaming(command)` | Stream output in real-time | ⚠️ Vulnerable to injection |
+| `execSpawnStreaming(cmd, args)` | Stream without shell | ✅ Safe for untrusted input |
+| `execInteractive(command)` | Interactive terminal mode | ⚠️ Vulnerable to injection |
+| `execInteractiveControl(command)` | Programmatic input control | ⚠️ Vulnerable to injection |
+| `execSpawnInteractiveControl(cmd, args)` | Programmatic control without shell | ✅ Safe for untrusted input |
+| `execPassthrough(command)` | Connect stdin passthrough | ⚠️ Vulnerable to injection |
+| `execInteractiveControlPty(command)` | PTY with programmatic control | ⚠️ Vulnerable to injection |
+| `execStreamingInteractiveControlPty(command)` | PTY streaming with control | ⚠️ Vulnerable to injection |
+| `execAndWaitForLine(cmd, regex, silent, opts)` | Wait for pattern match | ⚠️ Vulnerable to injection |
+
+### Result Interfaces
+
+```typescript
+interface IExecResult {
+  exitCode: number;     // Process exit code
+  stdout: string;       // Standard output
+  signal?: NodeJS.Signals; // Termination signal
+  stderr?: string;      // Error output
+}
+
+interface IExecResultStreaming {
+  childProcess: ChildProcess;  // Node.js ChildProcess instance
+  finalPromise: Promise<IExecResult>; // Resolves when process exits
+  sendInput: (input: string) => Promise<void>;
+  sendLine: (line: string) => Promise<void>;
+  endInput: () => void;
+  kill: () => Promise<void>;
+  terminate: () => Promise<void>;
+  keyboardInterrupt: () => Promise<void>;
+  customSignal: (signal: NodeJS.Signals) => Promise<void>;
+}
+
+interface IExecResultInteractive extends IExecResult {
+  sendInput: (input: string) => Promise<void>;
+  sendLine: (line: string) => Promise<void>;
+  endInput: () => void;
+  finalPromise: Promise<IExecResult>;
+}
+```
+
+### Options Interface
+
+```typescript
+interface IExecOptions {
+  silent?: boolean;          // Suppress console output
+  strict?: boolean;          // Throw on non-zero exit
+  streaming?: boolean;       // Return streaming interface
+  interactive?: boolean;     // Interactive mode
+  passthrough?: boolean;     // Connect stdin
+  interactiveControl?: boolean; // Programmatic input
+  usePty?: boolean;          // Use pseudo-terminal
+  ptyShell?: string;         // Custom PTY shell
+  ptyCols?: number;          // PTY columns (default 120)
+  ptyRows?: number;          // PTY rows (default 30)
+  ptyTerm?: string;          // Terminal type (default 'xterm-256color')
+  maxBuffer?: number;        // Max output buffer (bytes)
+  onData?: (chunk: Buffer | string) => void; // Data callback
+  timeout?: number;          // Execution timeout (ms)
+  debug?: boolean;           // Enable debug logging
+  env?: NodeJS.ProcessEnv;   // Custom environment
+  signal?: AbortSignal;      // Abort signal
+}
+```
+
+## Security Guide
+
+### Command Injection Prevention
+
+The standard `exec` methods use `shell: true`, which can lead to command injection vulnerabilities:
+
+```typescript
+// ❌ DANGEROUS - Never do this with untrusted input
+const userInput = "file.txt; rm -rf /";
+await smartshell.exec(`cat ${userInput}`); // Will execute rm -rf /
+
+// ✅ SAFE - Arguments are properly escaped
+await smartshell.execSpawn('cat', [userInput]); // Will look for literal filename
+```
+
+### Best Practices
+
+1. **Always validate input**: Even with secure methods, validate user input
+2. **Use execSpawn for untrusted data**: Never pass user input to shell-based methods
+3. **Set resource limits**: Use `maxBuffer` and `timeout` for untrusted commands
+4. **Control environment**: Don't inherit all env vars for sensitive operations
+5. **Restrict signals**: Only allow specific signals from user input
+
+### Path Traversal Protection
 
 ```typescript
-(async () => {
-  await smartShellInstance.execInteractive('npm init');
-})();
+// ❌ VULNERABLE
+const file = userInput; // Could be "../../../etc/passwd"
+await shell.exec(`cat ${file}`);
+
+// ✅ SECURE
+const path = require('path');
+const safePath = path.join('/allowed/directory', path.basename(userInput));
+await shell.execSpawn('cat', [safePath]);
 ```
 
-### Waiting for Specific Output
+## Tips & Best Practices 💎
+
+1. **Security first**: Use `execSpawn` for any untrusted input
+2. **Set resource limits**: Always use `maxBuffer` and `timeout` for untrusted commands
+3. **Choose the right executor**: Use `bash` for full features, `sh` for minimal overhead
+4. **Use strict mode for critical operations**: Ensures failures don't go unnoticed
+5. **Stream long-running processes**: Better UX and memory efficiency
+6. **Leverage silent modes**: When you only need to capture output
+7. **Handle errors gracefully**: Check both `exitCode` and `signal`
+8. **Clean up resources**: Streaming processes should be properly terminated
+9. **Control environment**: Don't inherit all env vars for sensitive operations
+10. **Enable debug mode**: For development and troubleshooting
+11. **Use PTY for terminal UIs**: When programs need real terminal features
+12. **Provide fallbacks**: Always handle PTY unavailability gracefully
+
+## Environment Customization
 
-To wait for a specific line before proceeding, you might use `execAndWaitForLine`. This is useful for waiting on a process to log a certain message:
+Smartshell provides powerful environment management:
 
 ```typescript
-(async () => {
-  await smartShellInstance.execAndWaitForLine('npm run watch', /Compilation complete./);
-  console.log('The watch process has finished compiling.');
-})();
+// Add custom source files
+shell.shellEnv.addSourceFiles([
+  '/home/user/.custom_env',
+  './project.env.sh'
+]);
+
+// Modify PATH
+shell.shellEnv.pathDirArray.push('/custom/bin');
+shell.shellEnv.pathDirArray.push('/usr/local/special');
+
+// Your custom environment is ready
+const result = await shell.exec('my-custom-command');
 ```
 
-Given the vast array of features offered by `@push.rocks/smartshell`, integrating shell operations into your TypeScript applications becomes both straightforward and powerful. By harnessing promises and async/await syntax, `smartshell` effectively streamlines shell interactions, making your code cleaner and more intuitive.
+## Shell Detection
+
+Need to check if a command exists? We export the `which` utility:
+
+```typescript
+import { which } from '@push.rocks/smartshell';
+
+try {
+  const gitPath = await which('git');
+  console.log(`Git found at: ${gitPath}`);
+} catch (error) {
+  console.log('Git is not installed');
+}
+```
 
 ## License and Legal Information
 
@@ -149,4 +630,4 @@ Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.