Package Exports

@guanghechen/exec

Readme

@guanghechen/exec

Utils for running commands.

Install

npm

npm install --save-dev @guanghechen/exec

yarn
```
yarn add --dev @guanghechen/exec
```

Usage

This package provides utilities for safely executing shell commands with enhanced error handling, logging, and configuration options.

Basic Command Execution

import { safeExec } from '@guanghechen/exec'

// Execute a simple command
const result = await safeExec({
  from: 'build-script',
  cmd: 'npm',
  args: ['run', 'build'],
  cwd: './project-directory'
})

console.log('Output:', result.stdout)

Advanced Configuration

import { safeExec } from '@guanghechen/exec'
import { ChalkLogger } from '@guanghechen/chalk-logger'

const logger = new ChalkLogger({ name: 'exec' })

// Execute with full configuration
const result = await safeExec({
  from: 'deployment',
  cmd: 'docker',
  args: ['build', '-t', 'my-app', '.'],
  cwd: '/path/to/project',
  env: {
    NODE_ENV: 'production',
    API_URL: 'https://api.example.com'
  },
  stdio: 'pipe',
  encoding: 'utf8',
  reporter: logger
})

Git Operations

import { safeExec } from '@guanghechen/exec'

// Get current git branch
const branch = await safeExec({
  from: 'git-utils',
  cmd: 'git',
  args: ['rev-parse', '--abbrev-ref', 'HEAD'],
  cwd: process.cwd()
})

console.log('Current branch:', branch.stdout)

// Clone repository
await safeExec({
  from: 'clone-repo',
  cmd: 'git',
  args: ['clone', 'https://github.com/user/repo.git', 'local-dir'],
  cwd: '/projects'
})

Build Tools Integration

import { safeExec } from '@guanghechen/exec'

// Run TypeScript compilation
await safeExec({
  from: 'build-ts',
  cmd: 'npx',
  args: ['tsc', '--project', './tsconfig.json'],
  cwd: './packages/core'
})

// Run tests
const testResult = await safeExec({
  from: 'test-runner',
  cmd: 'npm',
  args: ['test', '--', '--coverage'],
  cwd: process.cwd(),
  stdio: 'inherit' // Show output in real-time
})

Error Handling

import { safeExec } from '@guanghechen/exec'

try {
  await safeExec({
    from: 'risky-command',
    cmd: 'some-command',
    args: ['--dangerous-flag'],
    cwd: './temp'
  })
} catch (error) {
  console.error('Command failed:', error.message)
  // Error includes stdout/stderr output for debugging
}

Multiple Commands

import { safeExec } from '@guanghechen/exec'

async function buildProject() {
  // Clean
  await safeExec({
    from: 'clean',
    cmd: 'rm',
    args: ['-rf', 'dist'],
    cwd: process.cwd()
  })

  // Install dependencies
  await safeExec({
    from: 'install',
    cmd: 'npm',
    args: ['install'],
    cwd: process.cwd()
  })

  // Build
  await safeExec({
    from: 'build',
    cmd: 'npm',
    args: ['run', 'build'],
    cwd: process.cwd()
  })
}

API Reference

Name	Signature	Description
`safeExec`	`(params: ISafeExecParams) => Promise<ISafeExecResult>`	Executes a shell command safely with enhanced error handling and logging

Detailed Interfaces

`ISafeExecParams`

Parameters for safe command execution.

interface ISafeExecParams {
  from: string                                     // Identifier for logging/debugging
  cmd: string                                      // Command to execute
  args: string[]                                   // Command arguments
  cwd?: string                                    // Working directory (default: process.cwd())
  env?: Record<string, string | undefined>       // Environment variables
  stdio?: 'pipe' | 'overlapped' | 'inherit' | 'ignore'  // Stdio configuration
  encoding?: BufferEncoding                       // Output encoding (default: 'utf8')
  reporter?: IReporter                           // Logger instance for debug/error output
}

`ISafeExecResult`

Result from command execution.

interface ISafeExecResult {
  stdout: string                                 // Command output (trimmed)
}

Parameter Details

`from: string`

An identifier used for logging and debugging. This helps track which part of your application initiated the command execution.

`cmd: string`

The command to execute. Can be a system command, npm script, or any executable available in PATH.

`args: string[]`

Array of arguments to pass to the command. Each argument should be a separate array element.

`cwd?: string`

Working directory where the command should be executed. Defaults to the current working directory.

`env?: Record<string, string | undefined>`

Environment variables to set for the command execution. These are merged with the current process environment.

`stdio?: 'pipe' | 'overlapped' | 'inherit' | 'ignore'`

Controls how the subprocess stdio is configured:

'pipe' (default) - Capture output for programmatic use
'inherit' - Show output in real-time in parent process
'ignore' - Discard output
'overlapped' - Windows-specific option

`encoding?: BufferEncoding`

Character encoding for the output. Defaults to 'utf8'.

`reporter?: IReporter`

Logger instance for debug and error messages. Provides detailed execution information when debugging is enabled.

Features

Enhanced Error Handling

Captures both stdout and stderr
Provides detailed error messages with command context
Graceful handling of process termination
Clear error reporting with execution parameters

Logging Integration

Debug logging of all execution parameters
Error logging with full context
Integration with @guanghechen/reporter framework
Execution tracking via from parameter

Promise-based API

Modern async/await support
Proper error propagation
Clean promise resolution/rejection

Flexible Configuration

Support for different stdio modes
Custom environment variables
Configurable working directory
Customizable output encoding

Common Use Cases

CI/CD Scripts

// Deploy application
await safeExec({
  from: 'deploy',
  cmd: 'kubectl',
  args: ['apply', '-f', 'deployment.yaml'],
  cwd: './k8s'
})

Build Automation

// Bundle assets
await safeExec({
  from: 'webpack',
  cmd: 'npx',
  args: ['webpack', '--mode', 'production'],
  env: { NODE_ENV: 'production' }
})

Development Tools

// Format code
await safeExec({
  from: 'format',
  cmd: 'npx',
  args: ['prettier', '--write', 'src/**/*.ts'],
  stdio: 'inherit'
})