@atomist/sdm/lib/api-helper/misc/child_process.d.ts

Atomist Software Delivery Machine SDK

/// <reference types="node" />
import { HandlerResult } from "@atomist/automation-client/lib/HandlerResult";
import { execPromise, ExecPromiseError, ExecPromiseResult, killProcess, spawn, spawnPromise, SpawnPromiseOptions, SpawnPromiseReturns, WritableLog } from "@atomist/automation-client/lib/util/child_process";
import { ChildProcess } from "child_process";
import { ProgressLog } from "../../spi/log/ProgressLog";
/** Re-export child process objects from automation-client. */
export { execPromise, ExecPromiseError, ExecPromiseResult, killProcess, spawn, spawnPromise, SpawnPromiseOptions, SpawnPromiseReturns, WritableLog, };
/**
 * Type that can react to the exit of a spawned child process, after
 * Node has terminated without reporting an error.  This is necessary
 * only for commands that can return a zero exit status on failure or
 * non-zero exit code on success.  Implementations should return
 * `true` if an error is found, `false` otherwise.
 */
export declare type ErrorFinder = (code: number, signal: string, log: WritableLog) => boolean;
/**
 * Default ErrorFinder that regards everything but a return code of 0
 * as failure.
 *
 * @param code process exit status
 * @return true if exit status is not zero
 */
export declare const SuccessIsReturn0ErrorFinder: ErrorFinder;
/**
 * Add an error finder to SpawnPromietOptions to allow for
 * poorly-behaved command-line tools that do not properly reflect
 * their status in their return code.
 */
export interface SpawnLogOptions extends SpawnPromiseOptions {
    /**
     * If your command can return zero on failure or non-zero on
     * success, you can override the default behavior of determining
     * success or failure using this option.  For example, if your
     * command returns zero for certain types of errors, you can scan
     * the log content from the command to determine if an error
     * occurs.  If this function finds an error, the `error` property
     * will be populated with an `Error`.
     */
    errorFinder?: ErrorFinder;
    /**
     * Make SpawnPromiseOptions log mandatory and a ProgressLog.
     */
    log: ProgressLog;
}
/**
 * Interface containing the arguments to spawnAndLog.
 */
export interface SpawnLogCommand {
    /** Executable able to be run by cross-spawn. */
    command: string;
    /** Arguments to command */
    args?: string[];
    /** Options to customize how command is run. */
    options?: SpawnLogOptions;
}
/**
 * Interface similar to [[SpawnLogCommand]] but making the log
 * property optional since that can typically be obtained other ways
 * when commands are invoked from within goals.
 */
export interface SpawnLogInvocation {
    /** Executable able to be run by cross-spawn. */
    command: string;
    /** Arguments to command */
    args?: string[];
    /** Options to customize how command is run. */
    options?: Partial<SpawnLogOptions>;
}
/**
 * Result returned by spawnAndLog after running a child process.  It
 * is compatible with handler results.  To support both HandlerResult
 * and SpawnPromiseReturns, the value of code and status are
 * identical.
 */
export declare type SpawnLogResult = HandlerResult & SpawnPromiseReturns;
/**
 * Spawn a process, logging its standard output and standard error,
 * and return a Promise of its results.  The command is spawned using
 * cross-spawn.  A DelimitedWriteProgressLogDecorator, using newlines
 * as delimiters, is created from the provided `opts.log`.  The default
 * command timeout is 10 minutes.  The default
 * [[SpawnLogOptions#errorFinder]] sets the `error` property if the
 * command exits with a non-zero status or is killed by a signal.  If
 * the process is killed due to a signal or the `errorFinder` returns
 * `true`, the returned `code` property will be non-zero.
 *
 * @param cmd Command to run.
 * @param args Arguments to command.
 * @param opts Options for spawn, spawnPromise, and spawnLog.
 * @return A promise that provides information on the child process and
 *         its execution result, including if the exit status was non-zero
 *         or the process was killed by a signal.  The promise is only
 *         rejected with an `ExecPromiseError` if there is an error
 *         spawning the process.
 */
export declare function spawnLog(cmd: string, args: string[], opts: SpawnLogOptions): Promise<SpawnLogResult>;
/**
 * Kill the process and wait for it to shut down. This can take a
 * while as processes may have shut down hooks.  On win32, the process
 * is killed and the Promise is rejected if the process does not exit
 * within `wait` milliseconds.  On other platforms, first the process
 * is sent the default signal, SIGTERM.  After `wait` milliseconds, it
 * is sent SIGKILL.  After another `wait` milliseconds, an error is
 * thrown.
 *
 * @param childProcess Child process to kill
 * @param wait Number of milliseconds to wait before sending SIGKILL and
 *             then erroring, default is 30000 ms
 */
export declare function killAndWait(childProcess: ChildProcess, wait?: number): Promise<void>;
//# sourceMappingURL=child_process.d.ts.map