smartshell/readme.md

# @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 🏃‍♂️

```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!"
```

## Core Concepts 💡

### The Smartshell Instance

The heart of smartshell is the `Smartshell` class. Each instance maintains its own environment and configuration:

```typescript
const shell = new Smartshell({
  executor: 'bash', // Choose your shell: 'bash' or 'sh'
  sourceFilePaths: ['/path/to/env.sh'], // Optional: source files on init
});
```

## 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
```

### Silent Execution

Run commands without printing to console - ideal for capturing output:

```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
});
```

**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:

```typescript
try {
  await shell.execStrict('critical-command');
  console.log('✅ Command succeeded!');
} catch (error) {
  console.error('❌ Command failed:', error);
}
```

### 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());
});

// 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

```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');
```

### Development Server with Auto-Restart

```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();
});
```

### Docker Compose Helper

```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 }
);

// Run migrations
await shell.execStrict('docker-compose exec app npm run migrate');
console.log('✅ Environment ready!');
```

### 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

| 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>` |

### Result Interfaces

```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 🤫

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:

### How Silent Modes Work

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

### Available Silent Methods

```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
} catch (error) {
  // Handle failure
}

// 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.

### Trademarks

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 🏃‍♂️

```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!"
```

## Core Concepts 💡

### The Smartshell Instance

The heart of smartshell is the `Smartshell` class. Each instance maintains its own environment and configuration:

```typescript
const shell = new Smartshell({
  executor: 'bash', // Choose your shell: 'bash' or 'sh'
  sourceFilePaths: ['/path/to/env.sh'], // Optional: source files on init
});
```

## 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
```

### Silent Execution

Run commands without printing to console - ideal for capturing output:

```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
});
```

**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:

```typescript
try {
  await shell.execStrict('critical-command');
  console.log('✅ Command succeeded!');
} catch (error) {
  console.error('❌ Command failed:', error);
}
```

### 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());
});

// 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

```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');
```

### Development Server with Auto-Restart

```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();
});
```

### Docker Compose Helper

```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 }
);

// Run migrations
await shell.execStrict('docker-compose exec app npm run migrate');
console.log('✅ Environment ready!');
```

### 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

| 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>` |

### Result Interfaces

```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 🤫

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:

### How Silent Modes Work

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

### Available Silent Methods

```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
} catch (error) {
  // Handle failure
}

// 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.

### Trademarks

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.