@atomist/automation-client/lib/util/child_process.d.ts

/// <reference types="node" />
import { SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "child_process";
import * as spawn from "cross-spawn";
export { spawn };
/**
 * Convert child process into an informative string.
 *
 * @param cmd Command being run.
 * @param args Arguments to command.
 * @param opts Standard child_process.SpawnOptions.
 */
export declare function childProcessString(cmd: string, args?: string[], opts?: SpawnOptions): string;
/**
 * Cross-platform kill a process and all its children using tree-kill.
 * On win32, signal is ignored since win32 does not support different
 * signals.
 *
 * @param pid ID of process to kill.
 * @param signal optional signal name or number, Node.js default is used if not provided
 */
export declare function killProcess(pid: number, signal?: string | number): void;
/**
 * Interface for a writable log that provides a function to write to
 * the log.
 */
export interface WritableLog {
    /**
     * The content already written to the log.  This is optional as
     * some implementations may choose to not expose their log as a
     * string as it could be too long.
     */
    log?: string;
    /**
     * Set to true if ANSI escape characters should be stripped from
     * the data before writing to log.
     */
    stripAnsi?: boolean;
    /** Function that appends to the log. */
    write(what: string): void;
}
/**
 * Add logging to standard SpawnSyncoptions.  If no `encoding` is
 * provided, it is set to "buffer" if `log` is defined and "utf8"
 * otherwise.
 */
export interface SpawnPromiseOptions extends SpawnSyncOptions {
    /**
     * Optional logger to write stdout and stderr to.  If this is
     * provided, the encoding for it is taken from the `encoding`
     * option property and that property is set to "bufffer".  If no
     * `encoding` is defined, the default encoding for the log is
     * "utf8".
     */
    log?: WritableLog;
    /**
     * Set to true if you want the command line sent to the
     * Writablelog provided to spawnPromise.  Set to false if the
     * command or its arguments contain sensitive information.
     */
    logCommand?: boolean;
}
export interface SpawnPromiseReturns extends SpawnSyncReturns<string> {
    /** Stringified command. */
    cmdString: string;
}
/**
 * Call cross-spawn and return a Promise of its result.  The result
 * has the same shape as the object returned by
 * `child_process.spawnSync()`, which means errors are not thrown but
 * returned in the `error` property of the returned object.  If your
 * command will produce lots of output, provide a log to write it to.
 *
 * @param cmd Command to run.  If it is just an executable name, paths
 *            with be searched, batch and command files will be checked,
 *            etc.  See cross-spawn documentation for details.
 * @param args Arguments to command.
 * @param opts Standard child_process.SpawnOptions plus a few specific
 *             to this implementation.
 * @return a Promise that provides information on the child process and
 *         its execution result.  If an error occurs, the `error` property
 *         of [[SpawnPromiseReturns]] will be populated.
 */
export declare function spawnPromise(cmd: string, args?: string[], opts?: SpawnPromiseOptions): Promise<SpawnPromiseReturns>;
/**
 * Standard output and standard error from executing a child process.
 * No code or signal is provided because if you receive this value,
 * the child process completed successfully, i.e., exited normally
 * with a status of 0.
 */
export interface ExecPromiseResult {
    /** Child process standard output. */
    stdout: string;
    /** Child process standard error. */
    stderr: string;
}
/**
 * Error thrown when a command cannot be executed, the command is
 * killed by a signal, or returns a non-zero exit status.
 */
export declare class ExecPromiseError extends Error implements ExecPromiseResult {
    /** Message describing reason for failure. */
    message: string;
    /** Command PID. */
    pid: number;
    /** stdio */
    output: string[];
    /** Child process standard output. */
    stdout: string;
    /** Child process standard error. */
    stderr: string;
    /** Child process exit status. */
    status: number;
    /** Signal that killed the process, if any. */
    signal: string;
    /** Create an ExecError from a SpawnSyncReturns<string> */
    static fromSpawnReturns(r: SpawnSyncReturns<string>): ExecPromiseError;
    constructor(
    /** Message describing reason for failure. */
    message: string, 
    /** Command PID. */
    pid: number, 
    /** stdio */
    output: string[], 
    /** Child process standard output. */
    stdout: string, 
    /** Child process standard error. */
    stderr: string, 
    /** Child process exit status. */
    status: number, 
    /** Signal that killed the process, if any. */
    signal: string);
}
/**
 * Run a child process using cross-spawn, capturing and returning
 * stdout and stderr, like exec, in a promise.  If an error occurs,
 * the process is killed by a signal, or the process exits with a
 * non-zero status, the Promise is rejected.  Any provided `stdio`
 * option is ignored, being overwritten with `["pipe","pipe","pipe"]`.
 * Like with child_process.exec, this is not a good choice if the
 * command produces a large amount of data on stdout or stderr.
 *
 * @param cmd name of command, can be a shell script or MS Windows
 *            .bat or .cmd
 * @param args command arguments
 * @param opts standard child_process.SpawnOptions
 * @return Promise resolving to exec-like callback arguments having
 *         stdout and stderr properties.  If an error occurs, exits
 *         with a non-zero status, and killed with a signal, the
 *         Promise is rejected with an [[ExecPromiseError]].
 */
export declare function execPromise(cmd: string, args?: string[], opts?: SpawnSyncOptions): Promise<ExecPromiseResult>;
//# sourceMappingURL=child_process.d.ts.map