Skip to main content
Not Yet Implemented - This hook is planned but not available. The API below is a design spec.

useCommand Hook

import { useCommand } from 'smithers-orchestrator'

function BuildComponent() {
  const { run, output, isRunning, error } = useCommand()
  
  const build = async () => {
    const result = await run('bun', ['run', 'build'])
    console.log(`Done in ${result.durationMs}ms`)
  }
}

API

function useCommand(options?: UseCommandOptions): UseCommandReturn

interface UseCommandOptions {
  cwd?: string                    // Working directory
  env?: Record<string, string>    // Environment variables
  timeout?: number                // Default: 300000 (5 min)
  autoClear?: boolean             // Clear output after success
}

interface UseCommandReturn {
  run: (cmd: string | string[], args?: string[]) => Promise<CommandResult>
  output: string
  error: Error | null
  isRunning: boolean
  exitCode: number | null
  clear: () => void
}

interface CommandResult {
  stdout: string
  stderr: string
  exitCode: number
  durationMs: number
  success: boolean
}

Examples

Sequential Commands

const cmd = useCommand({ cwd: '/project' })

await cmd.run('bun install')
await cmd.run('bun run typecheck')
await cmd.run('bun test')

Conditional Execution

const test = useCommand()
const deploy = useCommand()

const result = await test.run('bun test')
if (result.success) {
  await deploy.run('bun run deploy')
}

Git Workflow

const git = useCommand()

await git.run('git add .')
await git.run('git', ['commit', '-m', message])
await git.run('git push origin main')

Options

OptionTypeDefaultDescription
cwdstringprocess.cwd()Working directory
envRecord<string, string>{}Merged with process.env
timeoutnumber300000Timeout in ms
autoClearbooleanfalseClear output after success

Return Values

PropertyTypeDescription
run(cmd, args?) => Promise<CommandResult>Execute command
outputstringstdout + stderr
errorError | nullLast error
isRunningbooleanCurrently executing
exitCodenumber | nullLast exit code
clear() => voidClear state