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 📦

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

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:

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:

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:

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:

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:

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:

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

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

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:

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

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:

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

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

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

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

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

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

Output is captured, not lost: All stdout content is stored in the result object
Console stays clean: Nothing is printed during execution
Full programmatic access: Process the output however you need

Available Silent Methods

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

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

Choose the right executor: Use bash for full features, sh for minimal overhead
Use strict mode for critical operations: Ensures failures don't go unnoticed
Stream long-running processes: Better UX and memory efficiency
Leverage silent modes: When you only need to capture output
Handle errors gracefully: Always wrap strict executions in try-catch
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 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.

Why smartshell? 🚀

✨ 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 📦

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

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:

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:

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:

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:

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:

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:

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

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

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:

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

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:

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

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

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

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

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

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

Output is captured, not lost: All stdout content is stored in the result object
Console stays clean: Nothing is printed during execution
Full programmatic access: Process the output however you need

Available Silent Methods

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

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

Choose the right executor: Use bash for full features, sh for minimal overhead
Use strict mode for critical operations: Ensures failures don't go unnoticed
Stream long-running processes: Better UX and memory efficiency
Leverage silent modes: When you only need to capture output
Handle errors gracefully: Always wrap strict executions in try-catch
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 file within this repository.

readme.md

@push.rocks/smartshell 🐚

Why smartshell? 🚀

✨ Key Features

Installation 📦

Quick Start 🏃‍♂️

Core Concepts 💡

The Smartshell Instance

Execution Modes 🎛️

Standard Execution

Silent Execution

Strict Execution

Streaming Execution

Interactive Execution

Advanced Features 🔥

Wait for Specific Output

Silent Pattern Waiting

Environment Customization

Smart Execution Utility

Shell Detection

Real-World Examples 🌍

Build Pipeline

Development Server with Auto-Restart

Docker Compose Helper

CI/CD Integration

API Reference 📚

Smartshell Class

Result Interfaces

Understanding Silent Modes 🤫

How Silent Modes Work

Available Silent Methods

Common Use Cases for Silent Execution

Tips & Best Practices 💎

License and Legal Information

Trademarks

Company Information

Why smartshell? 🚀

✨ Key Features

Installation 📦

Quick Start 🏃‍♂️

Core Concepts 💡

The Smartshell Instance

Execution Modes 🎛️

Standard Execution

Silent Execution

Strict Execution

Streaming Execution

Interactive Execution

Advanced Features 🔥

Wait for Specific Output

Silent Pattern Waiting

Environment Customization

Smart Execution Utility

Shell Detection

Real-World Examples 🌍

Build Pipeline

Development Server with Auto-Restart

Docker Compose Helper

CI/CD Integration

API Reference 📚

Smartshell Class

Result Interfaces

Understanding Silent Modes 🤫

How Silent Modes Work

Available Silent Methods

Common Use Cases for Silent Execution

Tips & Best Practices 💎

License and Legal Information

Trademarks

Company Information