@ebowwa/bash-ops

Comprehensive bash/shell operations module for power developers.

Installation

npm install @ebowwa/bash-ops
# or
bun add @ebowwa/bash-ops
# or
pnpm add @ebowwa/bash-ops

Features

• Type-safe: Full TypeScript support with comprehensive types
• Modular: Import only what you need
• Cross-platform: Works on Linux, macOS, and Windows (WSL)
• Modern: Built with async/await and latest Node.js APIs

Modules

Filesystem Operations

import { 
  listDirectory, 
  createDirectory, 
  copyFile, 
  move, 
  removeFile,
  getFileInfo,
  findFiles 
} from '@ebowwa/bash-ops/filesystem';

// List directory with options
const files = await listDirectory('/path', { 
  recursive: true, 
  stats: true,
  hidden: false 
});

// Get file information
const info = await getFileInfo('/path/to/file');
console.log(info.size, info.type, info.permissions);

// Copy and move files
await copyFile('/source', '/destination');
await move('/old/path', '/new/path');

Process Operations

import { 
  exec, 
  execStdout, 
  spawnProcess,
  findProcesses,
  commandExists 
} from '@ebowwa/bash-ops/process';

// Execute commands
const result = await exec('ls -la', { 
  cwd: '/home/user',
  timeout: 5000 
});

console.log(result.stdout, result.exitCode);

// Quick stdout only
const output = await execStdout('echo "hello"');

// Find and manage processes
const nodeProcs = await findProcesses('node');

Network Operations

import { 
  httpGet, 
  httpPost,
  downloadFile,
  ping,
  isReachable,
  getExternalIP,
  scanPorts 
} from '@ebowwa/bash-ops/network';

// HTTP requests
const response = await httpGet('https://api.example.com/data');
console.log(response.statusCode, response.json);

const posted = await httpPost('https://api.example.com', { 
  key: 'value' 
});

// Network checks
const alive = await ping('example.com');
const reachable = await isReachable('localhost', 3000);

// Port scanning
const openPorts = await scanPorts('example.com', [80, 443, 8080]);

Text Processing

import { 
  grep, 
  sort, 
  uniq,
  base64Encode,
  formatBytes,
  createProgressBar 
} from '@ebowwa/bash-ops/text';

// Search in files
const matches = await grep('pattern', '/path/to/files', {
  ignoreCase: true,
  recursive: true,
  lineNumbers: true
});

// Text operations
const sorted = await sort(['b', 'a', 'c'], { unique: true });
const encoded = base64Encode('hello world');
const formatted = formatBytes(1024000); // "1.00 MB"

// Progress bar
const progress = createProgressBar(100);
console.log(progress.update(50)); // "[====================....................] 50%"

System Operations

import { 
  getSystemInfo,
  getDiskUsage,
  getServiceStatus,
  detectPackageManager,
  startService 
} from '@ebowwa/bash-ops/system';

// System information
const sysInfo = await getSystemInfo();
console.log(sysInfo.cpu, sysInfo.memory, sysInfo.uptime);

// Disk usage
const disk = await getDiskUsage('/');
console.log(`${disk.used / disk.total * 100}% used`);

// Service management (systemd)
const service = await getServiceStatus('nginx');
if (service?.state === 'stopped') {
  await startService('nginx');
}

API Reference

ExecOptions

interface ExecOptions {
  cwd?: string;              // Working directory
  env?: Record<string, string>; // Environment variables
  shell?: 'bash' | 'zsh' | 'sh' | 'fish'; // Shell type
  timeout?: number;          // Timeout in ms (default: 30000)
  input?: string | Buffer;   // stdin input
  reject?: boolean;          // Throw on non-zero exit (default: true)
  capture?: boolean;         // Capture stdout (default: true)
  captureError?: boolean;    // Capture stderr (default: true)
  verbose?: boolean;         // Print output (default: false)
}

ProcessResult

interface ProcessResult {
  command: string;
  exitCode: number;
  stdout: string;
  stderr: string;
  succeeded: boolean;
  failed: boolean;
  duration: number;
  pid?: number;
  signal?: NodeJS.Signals;
}

Examples

File Backup Script

import { 
  copyDirectory, 
  createTempDirectory, 
  createTar,
  formatDate 
} from '@ebowwa/bash-ops';

const backup = async () => {
  const tempDir = await createTempDirectory('backup-');
  const timestamp = formatDate(new Date(), 'unix');
  
  await copyDirectory('/home/user/projects', tempDir);
  await createTar(tempDir, `/backups/projects-${timestamp}.tar.gz`, { 
    gzip: true 
  });
  
  console.log('Backup complete!');
};

Process Monitor

import { findProcesses, killProcessesByName, sleep } from '@ebowwa/bash-ops/process';

const monitor = async () => {
  while (true) {
    const procs = await findProcesses('memory-hog');
    
    if (procs.length > 0) {
      console.log('Found', procs.length, 'memory hog processes');
      await killProcessesByName('memory-hog');
    }
    
    await sleep(60000); // Check every minute
  }
};

HTTP Health Check

import { httpGet, ping } from '@ebowwa/bash-ops/network';

const healthCheck = async (url: string, host?: string) => {
  try {
    const response = await httpGet(url, { timeout: 5000 });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.statusCode}`);
    }
    
    if (host) {
      const pingResult = await ping(host);
      console.log(`Latency: ${pingResult.time}ms`);
    }
    
    return { healthy: true, latency: response.duration };
  } catch (error) {
    return { healthy: false, error: (error as Error).message };
  }
};

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Support

For issues and questions, please use the GitHub issue tracker.