Canonical external-process execution — external

Create validated external-command specifications and execute them through a canonical runner that captures output, timing, exit state, and provenance.

Usage

new_external_command(
  executable,
  args = character(),
  working_directory = getwd(),
  environment = character(),
  label = basename(executable)
)

validate_external_command(command)

# S3 method for class 'PopgenVCFExternalCommand'
print(x, ...)

run_external_command(command)

# S3 method for class 'PopgenVCFExternalProcessResult'
print(x, ...)

Arguments

executable: Executable name or path.
args: Character vector of command-line arguments.
working_directory: Existing working directory used for execution.
environment: Optional uniquely named character vector of environment overrides.
label: Stable command label recorded in provenance.
command: A PopgenVCFExternalCommand object.
x: A command specification or process result.
...: Unused.

Value

new_external_command() returns a validated PopgenVCFExternalCommand. run_external_command() returns a PopgenVCFExternalProcessResult containing the normalized status, exit status, standard output, standard error, UTC timestamps, elapsed time, resolved executable, command fingerprint, and any launch error.

Details

Executable and argument fields remain separate rather than being represented as a shell command string. Environment entries are sorted before fingerprinting so semantically identical specifications have identical provenance.

The runner reports one of three initial states: success, nonzero_exit, or launch_failed. Non-zero output is retained for diagnosis but does not represent accepted scientific output. Process-level timeouts, cancellation, process-tree termination, and operating-system resource enforcement are later Phase 8.8 supervision layers.