@push.rocks/smartshell 3.2.4 → 3.3.2

package/readme.md

@@ -4,6 +4,10 @@
 [![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)
 
+## ⚠️ Security Notice
+
+**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.
@@ -13,10 +17,15 @@ Tired of wrestling with Node.js child processes? Meet `@push.rocks/smartshell` -
 - 🎯 **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 when needed
+- 🎮 **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 📦
@@ -30,6 +39,9 @@ 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
 ```
 
 ## Quick Start 🏃‍♂️
@@ -45,413 +57,256 @@ const shell = new Smartshell({
 // 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)
 ```
 
-## Core Concepts 💡
+## Security-First Execution 🔒
 
-### The Smartshell Instance
+### Secure Command Execution with execSpawn
 
-The heart of smartshell is the `Smartshell` class. Each instance maintains its own environment and configuration:
+When dealing with untrusted input, **always use execSpawn methods** which don't use shell interpretation:
 
 ```typescript
-const shell = new Smartshell({
-  executor: 'bash', // Choose your shell: 'bash' or 'sh'
-  sourceFilePaths: ['/path/to/env.sh'], // Optional: source files on init
-});
+// ❌ DANGEROUS with untrusted input
+const userInput = "file.txt; rm -rf /";
+await shell.exec(`cat ${userInput}`); // Command injection!
+
+// ✅ SAFE with untrusted input
+await shell.execSpawn('cat', [userInput]); // Arguments are properly escaped
 ```
 
-## Execution Modes 🎛️
+### execSpawn Family Methods
 
-### Standard Execution
+```typescript
+// Basic secure execution
+const result = await shell.execSpawn('ls', ['-la', '/home']);
 
-Perfect for general commands where you want to see the output:
+// Streaming secure execution
+const streaming = await shell.execSpawnStreaming('npm', ['install']);
+await streaming.finalPromise;
 
-```typescript
-const result = await shell.exec('ls -la');
-console.log(result.stdout); // Directory listing
-console.log(result.exitCode); // 0 for success
+// Interactive secure execution
+const interactive = await shell.execSpawnInteractiveControl('cat', []);
+await interactive.sendLine('Hello');
+interactive.endInput();
+await interactive.finalPromise;
 ```
 
-### Silent Execution
+## Production Features 🏭
 
-Run commands without printing to console - ideal for capturing output:
+### Resource Management
+
+Prevent memory issues with built-in buffer limits:
 
 ```typescript
-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
-console.log(result.exitCode); // Check exit code (0 = success)
-
-// Example: Process output programmatically
-const files = await shell.execSilent('ls -la');
-const fileList = files.stdout.split('
-');
-fileList.forEach(file => {
-  // Process each file entry
+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());
+  }
 });
 ```
 
-**Key Point:** Silent methods (`execSilent`, `execStrictSilent`, `execStreamingSilent`) suppress console output but still capture everything in the result object for programmatic access.
-
-### Strict Execution
+### Timeout Support
 
-Throws an error if the command fails - great for critical operations:
+Automatically terminate long-running processes:
 
 ```typescript
 try {
-  await shell.execStrict('critical-command');
-  console.log('✅ Command succeeded!');
+  const result = await shell.execSpawn('long-process', [], {
+    timeout: 5000 // 5 second timeout
+  });
 } catch (error) {
-  console.error('❌ Command failed:', error);
+  console.log('Process timed out');
 }
 ```
 
-### Streaming Execution
+### Debug Mode
 
-For long-running processes or when you need real-time output:
+Enable detailed logging for troubleshooting:
 
 ```typescript
-const streaming = await shell.execStreaming('npm install');
-
-// Access the child process directly
-streaming.childProcess.stdout.on('data', (chunk) => {
-  console.log('📦 Installing:', chunk.toString());
+const result = await shell.exec('command', {
+  debug: true // Logs process lifecycle events
 });
-
-// Wait for completion
-await streaming.finalPromise;
-```
-
-### Interactive Execution
-
-When commands need user input:
-
-```typescript
-// This will connect to your terminal for input
-await shell.execInteractive('npm init');
 ```
 
-## Advanced Features 🔥
-
-### Wait for Specific Output
+### Custom Environment
 
-Perfect for waiting on services to start:
+Control the execution environment precisely:
 
 ```typescript
-// Wait for a specific line before continuing
-await shell.execAndWaitForLine(
-  'npm run dev',
-  /Server started on port 3000/
-);
-console.log('🚀 Server is ready!');
+const result = await shell.execSpawn('node', ['script.js'], {
+  env: {
+    NODE_ENV: 'production',
+    PATH: '/usr/bin:/bin',
+    CUSTOM_VAR: 'value'
+  }
+});
 ```
 
-### Silent Pattern Waiting
-
-Same as above, but without console output:
+## Interactive Control 🎮
 
-```typescript
-await shell.execAndWaitForLineSilent(
-  'docker-compose up',
-  /database system is ready to accept connections/
-);
-// The command output is suppressed from console but the pattern matching still works
-```
+### Programmatic Input Control
 
-### Environment Customization
-
-Smartshell provides powerful environment management:
+Send input to processes programmatically:
 
 ```typescript
-// 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');
+const interactive = await shell.execInteractiveControl('cat');
 
-// Your custom environment is ready
-const result = await shell.exec('my-custom-command');
-```
-
-### Smart Execution Utility
-
-The `SmartExecution` class enables restartable streaming processes:
-
-```typescript
-import { SmartExecution } from '@push.rocks/smartshell';
+// Send input line by line
+await interactive.sendLine('Line 1');
+await interactive.sendLine('Line 2');
 
-const execution = new SmartExecution(shell, 'npm run watch');
+// Send raw input without newline
+await interactive.sendInput('partial');
 
-// Restart the process whenever needed
-await execution.restart();
+// Close stdin
+interactive.endInput();
 
-// Access the current streaming execution
-if (execution.currentStreamingExecution) {
-  execution.currentStreamingExecution.childProcess.stdout.on('data', (data) => {
-    console.log(data.toString());
-  });
-}
+// Wait for completion
+const result = await interactive.finalPromise;
 ```
 
-### Shell Detection
+### Passthrough Mode
 
-Need to check if a command exists? We export the `which` utility:
+Connect stdin for real keyboard interaction:
 
 ```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');
-}
+// User can type directly
+await shell.execPassthrough('vim file.txt');
 ```
 
-## Real-World Examples 🌍
+## PTY Support - Full Terminal Emulation 🖥️
 
-### Build Pipeline
+Smartshell provides two modes for executing interactive commands:
 
-```typescript
-const shell = new Smartshell({ executor: 'bash' });
+1. **Pipe Mode (Default)** - Fast, simple, no dependencies
+2. **PTY Mode** - Full terminal emulation for advanced interactive programs
 
-// Clean build directory
-await shell.execSilent('rm -rf dist');
+### When to Use Each Mode
 
-// Run TypeScript compiler
-const buildResult = await shell.execStrict('tsc');
+#### 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
 
-// Run tests
-await shell.execStrict('npm test');
+#### 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
 
-// Build succeeded!
-console.log('✅ Build pipeline completed successfully');
-```
+### Installing PTY Support
 
-### Development Server with Auto-Restart
+PTY support requires the optional `node-pty` dependency:
 
-```typescript
-const shell = new Smartshell({ executor: 'bash' });
-const devServer = new SmartExecution(shell, 'npm run dev');
+```bash
+# Install as optional dependency
+pnpm add --save-optional node-pty
 
-// Watch for file changes and restart
-fs.watch('./src', async () => {
-  console.log('🔄 Changes detected, restarting...');
-  await devServer.restart();
-});
+# 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
 ```
 
-### Docker Compose Helper
+### PTY Usage Examples
 
 ```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/,
-  { timeout: 60000 }
+// 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
 
-// Run migrations
-await shell.execStrict('docker-compose exec app npm run migrate');
-console.log('✅ Environment ready!');
+// 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
 ```
 
-### CI/CD Integration
-
-```typescript
-const shell = new Smartshell({ executor: 'bash' });
-
-async function runCIPipeline() {
-  // Install dependencies
-  await shell.execStrict('pnpm install --frozen-lockfile');
-  
-  // Run linting
-  const lintResult = await shell.execSilent('npm run lint');
-  if (lintResult.exitCode !== 0) {
-    throw new Error(`Linting failed:
-${lintResult.stdout}`);
-  }
-  
-  // Run tests with coverage
-  const testResult = await shell.exec('npm run test:coverage');
-  
-  // Build project
-  await shell.execStrict('npm run build');
-  
-  // Deploy if on main branch
-  if (process.env.BRANCH === 'main') {
-    await shell.execStrict('npm run deploy');
-  }
-}
-```
-
-## API Reference 📚
-
-### Smartshell Class
+### PTY vs Pipe Mode Comparison
 
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `exec(command)` | Execute command with output | `Promise<IExecResult>` |
-| `execSilent(command)` | Execute without console output | `Promise<IExecResult>` |
-| `execStrict(command)` | Execute, throw on failure | `Promise<IExecResult>` |
-| `execStrictSilent(command)` | Strict + silent execution | `Promise<IExecResult>` |
-| `execStreaming(command)` | Stream output in real-time | `Promise<IExecResultStreaming>` |
-| `execStreamingSilent(command)` | Stream without console output | `Promise<IExecResultStreaming>` |
-| `execInteractive(command)` | Interactive terminal mode | `Promise<void>` |
-| `execAndWaitForLine(command, regex)` | Wait for pattern match | `Promise<void>` |
-| `execAndWaitForLineSilent(command, regex)` | Silent pattern waiting | `Promise<void>` |
+| 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) |
 
-### Result Interfaces
+### Common PTY Patterns
 
 ```typescript
-interface IExecResult {
-  exitCode: number;    // Process exit code
-  stdout: string;      // Standard output
-}
-
-interface IExecResultStreaming {
-  childProcess: ChildProcess;  // Node.js ChildProcess instance
-  finalPromise: Promise<void>; // Resolves when process exits
-}
-```
-
-## Understanding Silent Modes 🤫
+// Password input (PTY required)
+const sudo = await shell.execInteractiveControlPty('sudo ls /root');
+await sudo.sendLine('mypassword');
+const result = await sudo.finalPromise;
 
-Silent execution modes are perfect when you need to capture command output for processing without cluttering the console. Here's what you need to know:
+// Interactive REPL with colors
+const node = await shell.execStreamingInteractiveControlPty('node');
+await node.sendLine('console.log("PTY supports colors!")');
+await node.sendLine('.exit');
 
-### How Silent Modes Work
+// Handling terminal colors
+const ls = await shell.execInteractiveControlPty('ls --color=always');
+const result = await ls.finalPromise;
+// result.stdout will contain ANSI color codes
+```
 
-1. **Output is captured, not lost**: All stdout content is stored in the result object
-2. **Console stays clean**: Nothing is printed during execution  
-3. **Full programmatic access**: Process the output however you need
+### PTY Fallback Strategy
 
-### Available Silent Methods
+Always provide a fallback for when PTY isn't available:
 
 ```typescript
-// Basic silent execution
-const result = await shell.execSilent('ls -la');
-console.log(result.stdout); // Access captured output
-console.log(result.exitCode); // Check success/failure
-
-// Strict + Silent (throws on error)
 try {
-  const result = await shell.execStrictSilent('important-command');
-  const output = result.stdout; // Process the output
+  // Try PTY mode first
+  const result = await shell.execInteractiveControlPty(command);
+  // ...
 } catch (error) {
-  // Handle failure
+  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 + Silent
-const streaming = await shell.execStreamingSilent('long-running-process');
-streaming.childProcess.stdout.on('data', (chunk) => {
-  // Process chunks as they arrive
-  const data = chunk.toString();
-});
-
-// Pattern matching + Silent
-await shell.execAndWaitForLineSilent('server-start', /Ready on port/);
-```
-
-### Common Use Cases for Silent Execution
-
-```typescript
-// Parse JSON output
-const jsonResult = await shell.execSilent('aws s3 ls --output json');
-const buckets = JSON.parse(jsonResult.stdout);
-
-// Count lines
-const wcResult = await shell.execSilent('wc -l huge-file.txt');
-const lineCount = parseInt(wcResult.stdout.split(' ')[0]);
-
-// Check if command exists
-const whichResult = await shell.execSilent('which docker');
-const dockerPath = whichResult.exitCode === 0 ? whichResult.stdout.trim() : null;
-
-// Collect system info
-const unameResult = await shell.execSilent('uname -a');
-const systemInfo = unameResult.stdout.trim();
 ```
 
-## Tips & Best Practices 💎
-
-1. **Choose the right executor**: Use `bash` for full features, `sh` for minimal overhead
-2. **Use strict mode for critical operations**: Ensures failures don't go unnoticed
-3. **Stream long-running processes**: Better UX and memory efficiency
-4. **Leverage silent modes**: When you only need to capture output
-5. **Handle errors gracefully**: Always wrap strict executions in try-catch
-6. **Clean up resources**: Streaming processes should be properly terminated
-
-## License and Legal Information
-
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
-
-**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+## Advanced Pattern Matching 🔍
 
-### Trademarks
+### Enhanced execAndWaitForLine
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
-
-### Company Information
-
-Task Venture Capital GmbH  
-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.# @push.rocks/smartshell 🐚
-**Execute shell commands with superpowers in Node.js**
-
-[![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)
-
-## 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 when needed
-- ⚡ **Smart execution modes** - Strict, silent, or streaming
-- 🔍 **Pattern matching** - Wait for specific output patterns
-- 🌍 **Environment management** - Custom env vars and PATH handling
-- 🛡️ **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
-```
-
-## Quick Start 🏃‍♂️
+Wait for patterns with timeout and auto-termination:
 
 ```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!"
+// 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 💡
@@ -477,6 +332,8 @@ Perfect for general commands where you want to see the output:
 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
 ```
 
 ### Silent Execution
@@ -487,19 +344,8 @@ Run commands without printing to console - ideal for capturing output:
 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
-console.log(result.exitCode); // Check exit code (0 = success)
-
-// Example: Process output programmatically
-const files = await shell.execSilent('ls -la');
-const fileList = files.stdout.split('
-');
-fileList.forEach(file => {
-  // Process each file entry
-});
 ```
 
-**Key Point:** Silent methods (`execSilent`, `execStrictSilent`, `execStreamingSilent`) suppress console output but still capture everything in the result object for programmatic access.
-
 ### Strict Execution
 
 Throws an error if the command fails - great for critical operations:
@@ -509,7 +355,8 @@ try {
   await shell.execStrict('critical-command');
   console.log('✅ Command succeeded!');
 } catch (error) {
-  console.error('❌ Command failed:', error);
+  console.error('❌ Command failed:', error.message);
+  // Error includes exit code or signal information
 }
 ```
 
@@ -525,100 +372,15 @@ 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;
 ```
 
-### Interactive Execution
-
-When commands need user input:
-
-```typescript
-// This will connect to your terminal for input
-await shell.execInteractive('npm init');
-```
-
-## Advanced Features 🔥
-
-### Wait for Specific Output
-
-Perfect for waiting on services to start:
-
-```typescript
-// Wait for a specific line before continuing
-await shell.execAndWaitForLine(
-  'npm run dev',
-  /Server started on port 3000/
-);
-console.log('🚀 Server is ready!');
-```
-
-### Silent Pattern Waiting
-
-Same as above, but without console output:
-
-```typescript
-await shell.execAndWaitForLineSilent(
-  'docker-compose up',
-  /database system is ready to accept connections/
-);
-// The command output is suppressed from console but the pattern matching still works
-```
-
-### Environment Customization
-
-Smartshell provides powerful environment management:
-
-```typescript
-// 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');
-```
-
-### Smart Execution Utility
-
-The `SmartExecution` class enables restartable streaming processes:
-
-```typescript
-import { SmartExecution } from '@push.rocks/smartshell';
-
-const execution = new SmartExecution(shell, 'npm run watch');
-
-// Restart the process whenever needed
-await execution.restart();
-
-// Access the current streaming execution
-if (execution.currentStreamingExecution) {
-  execution.currentStreamingExecution.childProcess.stdout.on('data', (data) => {
-    console.log(data.toString());
-  });
-}
-```
-
-### 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');
-}
-```
-
 ## Real-World Examples 🌍
 
 ### Build Pipeline
@@ -639,17 +401,20 @@ await shell.execStrict('npm test');
 console.log('✅ Build pipeline completed successfully');
 ```
 
-### Development Server with Auto-Restart
+### CI/CD with Security
 
 ```typescript
-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();
-});
+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]);
+  
+  // Safe to use exec for hardcoded commands
+  await shell.execStrict('npm run build');
+  await shell.execStrict('npm run deploy');
+}
 ```
 
 ### Docker Compose Helper
@@ -662,7 +427,11 @@ console.log('🐳 Starting Docker services...');
 await shell.execAndWaitForLine(
   'docker-compose up',
   /All services are ready/,
-  { timeout: 60000 }
+  false,
+  { 
+    timeout: 60000,
+    terminateOnMatch: false // Keep running after match
+  }
 );
 
 // Run migrations
@@ -670,130 +439,179 @@ await shell.execStrict('docker-compose exec app npm run migrate');
 console.log('✅ Environment ready!');
 ```
 
-### CI/CD Integration
+### 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');
 
-async function runCIPipeline() {
-  // Install dependencies
-  await shell.execStrict('pnpm install --frozen-lockfile');
-  
-  // Run linting
-  const lintResult = await shell.execSilent('npm run lint');
-  if (lintResult.exitCode !== 0) {
-    throw new Error(`Linting failed:
-${lintResult.stdout}`);
-  }
-  
-  // Run tests with coverage
-  const testResult = await shell.exec('npm run test:coverage');
-  
-  // Build project
-  await shell.execStrict('npm run build');
-  
-  // Deploy if on main branch
-  if (process.env.BRANCH === 'main') {
-    await shell.execStrict('npm run deploy');
-  }
-}
+// Watch for file changes and restart
+fs.watch('./src', async () => {
+  console.log('🔄 Changes detected, restarting...');
+  await devServer.restart();
+});
 ```
 
 ## API Reference 📚
 
 ### Smartshell Class
 
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `exec(command)` | Execute command with output | `Promise<IExecResult>` |
-| `execSilent(command)` | Execute without console output | `Promise<IExecResult>` |
-| `execStrict(command)` | Execute, throw on failure | `Promise<IExecResult>` |
-| `execStrictSilent(command)` | Strict + silent execution | `Promise<IExecResult>` |
-| `execStreaming(command)` | Stream output in real-time | `Promise<IExecResultStreaming>` |
-| `execStreamingSilent(command)` | Stream without console output | `Promise<IExecResultStreaming>` |
-| `execInteractive(command)` | Interactive terminal mode | `Promise<void>` |
-| `execAndWaitForLine(command, regex)` | Wait for pattern match | `Promise<void>` |
-| `execAndWaitForLineSilent(command, regex)` | Silent pattern waiting | `Promise<void>` |
+| 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
+  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<void>; // Resolves when process exits
+  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>;
 }
-```
 
-## Understanding Silent Modes 🤫
+interface IExecResultInteractive extends IExecResult {
+  sendInput: (input: string) => Promise<void>;
+  sendLine: (line: string) => Promise<void>;
+  endInput: () => void;
+  finalPromise: Promise<IExecResult>;
+}
+```
 
-Silent execution modes are perfect when you need to capture command output for processing without cluttering the console. Here's what you need to know:
+### 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
+}
+```
 
-### How Silent Modes Work
+## Security Guide
 
-1. **Output is captured, not lost**: All stdout content is stored in the result object
-2. **Console stays clean**: Nothing is printed during execution  
-3. **Full programmatic access**: Process the output however you need
+### Command Injection Prevention
 
-### Available Silent Methods
+The standard `exec` methods use `shell: true`, which can lead to command injection vulnerabilities:
 
 ```typescript
-// Basic silent execution
-const result = await shell.execSilent('ls -la');
-console.log(result.stdout); // Access captured output
-console.log(result.exitCode); // Check success/failure
+// ❌ DANGEROUS - Never do this with untrusted input
+const userInput = "file.txt; rm -rf /";
+await smartshell.exec(`cat ${userInput}`); // Will execute rm -rf /
 
-// Strict + Silent (throws on error)
-try {
-  const result = await shell.execStrictSilent('important-command');
-  const output = result.stdout; // Process the output
-} catch (error) {
-  // Handle failure
-}
+// ✅ SAFE - Arguments are properly escaped
+await smartshell.execSpawn('cat', [userInput]); // Will look for literal filename
+```
 
-// Streaming + Silent
-const streaming = await shell.execStreamingSilent('long-running-process');
-streaming.childProcess.stdout.on('data', (chunk) => {
-  // Process chunks as they arrive
-  const data = chunk.toString();
-});
+### Best Practices
 
-// Pattern matching + Silent
-await shell.execAndWaitForLineSilent('server-start', /Ready on port/);
-```
+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
 
-### Common Use Cases for Silent Execution
+### Path Traversal Protection
 
 ```typescript
-// Parse JSON output
-const jsonResult = await shell.execSilent('aws s3 ls --output json');
-const buckets = JSON.parse(jsonResult.stdout);
+// ❌ 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]);
+```
 
-// Count lines
-const wcResult = await shell.execSilent('wc -l huge-file.txt');
-const lineCount = parseInt(wcResult.stdout.split(' ')[0]);
+## Tips & Best Practices 💎
 
-// Check if command exists
-const whichResult = await shell.execSilent('which docker');
-const dockerPath = whichResult.exitCode === 0 ? whichResult.stdout.trim() : null;
+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
 
-// Collect system info
-const unameResult = await shell.execSilent('uname -a');
-const systemInfo = unameResult.stdout.trim();
+Smartshell provides powerful environment management:
+
+```typescript
+// 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');
 ```
 
-## Tips & Best Practices 💎
+## Shell Detection
+
+Need to check if a command exists? We export the `which` utility:
+
+```typescript
+import { which } from '@push.rocks/smartshell';
 
-1. **Choose the right executor**: Use `bash` for full features, `sh` for minimal overhead
-2. **Use strict mode for critical operations**: Ensures failures don't go unnoticed
-3. **Stream long-running processes**: Better UX and memory efficiency
-4. **Leverage silent modes**: When you only need to capture output
-5. **Handle errors gracefully**: Always wrap strict executions in try-catch
-6. **Clean up resources**: Streaming processes should be properly terminated
+try {
+  const gitPath = await which('git');
+  console.log(`Git found at: ${gitPath}`);
+} catch (error) {
+  console.log('Git is not installed');
+}
+```
 
 ## License and Legal Information