@netlify/agent-runner-cli 1.58.5 → 1.58.7-alpha

package/dist/index.d.ts

@@ -1,7 +1,259 @@
-import { Options, ExecaChildProcess } from 'execa';
+import * as os from 'os';
+import { FdGenericOption as FdGenericOption$1 } from './arguments/specific.js';
+import * as execa from 'execa';
+import { Options, ResultPromise } from 'execa';
+import { FromOption } from './fd-options.js';
+import { Readable, Writable } from 'node:stream';
+import { TransformStream, ReadableStream, WritableStream } from 'node:stream/web';
+import { Unless, And, Not, Or, AndUnless } from '../utils.js';
+import { GeneratorTransform, GeneratorTransformFull, DuplexTransform, WebTransform } from '../transform/normalize.js';
+import * as stream from 'stream';
 
+type VerboseOption = FdGenericOption$1<
+| 'none'
+| 'short'
+| 'full'
+| VerboseFunction
+>;
+
+type VerboseFunction = (verboseLine: string, verboseObject: MinimalVerboseObject) => string | void;
+
+type GenericVerboseObject = {
+	/**
+	Event type. This can be:
+	- `'command'`: subprocess start
+	- `'output'`: `stdout`/`stderr` output
+	- `'ipc'`: IPC output
+	- `'error'`: subprocess failure
+	- `'duration'`: subprocess success or failure
+	*/
+	type: 'command' | 'output' | 'ipc' | 'error' | 'duration';
+
+	/**
+	Depending on `verboseObject.type`, this is:
+	- `'command'`: the `result.escapedCommand`
+	- `'output'`: one line from `result.stdout` or `result.stderr`
+	- `'ipc'`: one IPC message from `result.ipcOutput`
+	- `'error'`: the `error.shortMessage`
+	- `'duration'`: the `result.durationMs`
+	*/
+	message: string;
+
+	/**
+	The file and arguments that were run. This is the same as `result.escapedCommand`.
+	*/
+	escapedCommand: string;
+
+	/**
+	Serial number identifying the subprocess within the current process. It is incremented from `'0'`.
+
+	This is helpful when multiple subprocesses are running at the same time.
+
+	This is similar to a [PID](https://en.wikipedia.org/wiki/Process_identifier) except it has no maximum limit, which means it never repeats. Also, it is usually shorter.
+	*/
+	commandId: string;
+
+	/**
+	Event date/time.
+	*/
+	timestamp: Date;
+
+	/**
+	Whether another subprocess is piped into this subprocess. This is `false` when `result.pipedFrom` is empty.
+	*/
+	piped: boolean;
+};
+
+type MinimalVerboseObject = GenericVerboseObject & {
+	// We cannot use the `CommonOptions` type because it would make this type recursive
+	options: object;
+	result?: never;
+};
+
+// Options which can be fd-specific like `{verbose: {stdout: 'none', stderr: 'full'}}`
+type FdGenericOption<OptionType> = OptionType | GenericOptionObject<OptionType>;
+
+type GenericOptionObject<OptionType> = {
+	readonly [FdName in GenericFromOption]?: OptionType
+};
+
+type GenericFromOption = FromOption | 'ipc';
+
+type DefaultEncodingOption = 'utf8';
+type TextEncodingOption =
+  | DefaultEncodingOption
+  | 'utf16le';
+
+type BufferEncodingOption = 'buffer';
+type BinaryEncodingOption =
+  | BufferEncodingOption
+  | 'hex'
+  | 'base64'
+  | 'base64url'
+  | 'latin1'
+  | 'ascii';
+
+// `options.encoding`
+type EncodingOption =
+	| TextEncodingOption
+	| BinaryEncodingOption
+	| undefined;
+
+// `options.stdio` when it is not an array
+type SimpleStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+	| undefined
+	| 'pipe'
+	| Unless<And<And<Not<IsSync>, IsArray>, IsExtra>, 'inherit'>
+	| Unless<IsArray, 'ignore'>
+	| Unless<IsSync, 'overlapped'>;
+
+// Values available in both `options.stdin|stdio` and `options.stdout|stderr|stdio`
+type CommonStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+	| SimpleStdioOption<IsSync, IsExtra, IsArray>
+	| URL
+	| {readonly file: string; readonly append?: boolean}
+	| GeneratorTransform<IsSync>
+	| GeneratorTransformFull<IsSync>
+	| Unless<And<Not<IsSync>, IsArray>, 3 | 4 | 5 | 6 | 7 | 8 | 9>
+	| Unless<Or<IsSync, IsArray>, 'ipc'>
+	| Unless<IsSync, DuplexTransform | WebTransform | TransformStream>;
+
+// Synchronous iterables excluding strings, Uint8Arrays and Arrays
+type IterableObject<IsArray extends boolean> = Iterable<unknown>
+& object
+& {readonly BYTES_PER_ELEMENT?: never}
+& AndUnless<IsArray, {readonly lastIndexOf?: never}>;
+
+// `process.stdin|stdout|stderr` are `Duplex` with a `fd` property.
+// This ensures they can only be passed to `stdin`/`stdout`/`stderr`, based on their direction.
+type ProcessStdinFd = {readonly fd?: 0};
+type ProcessStdoutStderrFd = {readonly fd?: 1 | 2};
+
+// Values available only in `options.stdin|stdio`
+type InputStdioOption<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	IsArray extends boolean = boolean,
+> =
+	| 0
+	| Unless<And<IsSync, IsExtra>, Uint8Array | IterableObject<IsArray>>
+	| Unless<And<IsSync, IsArray>, Readable & ProcessStdinFd>
+	| Unless<IsSync, (AsyncIterable<unknown> & ProcessStdinFd) | ReadableStream>;
+
+// Values available only in `options.stdout|stderr|stdio`
+type OutputStdioOption<
+	IsSync extends boolean,
+	IsArray extends boolean,
+> =
+	| 1
+	| 2
+	| Unless<And<IsSync, IsArray>, Writable & ProcessStdoutStderrFd>
+	| Unless<IsSync, WritableStream>;
+
+// `options.stdin` array items
+type StdinSingleOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+	| CommonStdioOption<IsSync, IsExtra, IsArray>
+	| InputStdioOption<IsSync, IsExtra, IsArray>;
+
+// `options.stdin`
+type StdinOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+> =
+	| StdinSingleOption<IsSync, IsExtra, false>
+	| ReadonlyArray<StdinSingleOption<IsSync, IsExtra, true>>;
+
+// `options.stdout|stderr` array items
+type StdoutStderrSingleOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+  | CommonStdioOption<IsSync, IsExtra, IsArray>
+  | OutputStdioOption<IsSync, IsArray>;
+
+// `options.stdout|stderr`
+type StdoutStderrOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+> =
+	| StdoutStderrSingleOption<IsSync, IsExtra, false>
+	| ReadonlyArray<StdoutStderrSingleOption<IsSync, IsExtra, true>>;
+
+// `options.stdio[3+]`
+type StdioExtraOptionCommon<IsSync extends boolean> =
+	| StdinOptionCommon<IsSync, true>
+	| StdoutStderrOptionCommon<IsSync, true>;
+
+// `options.stdio` when it is an array
+type StdioOptionsArray<IsSync extends boolean = boolean> = readonly [
+	StdinOptionCommon<IsSync, false>,
+	StdoutStderrOptionCommon<IsSync, false>,
+	StdoutStderrOptionCommon<IsSync, false>,
+	...ReadonlyArray<StdioExtraOptionCommon<IsSync>>,
+];
+
+// `options.stdio`
+type StdioOptionsProperty<IsSync extends boolean = boolean> =
+	| SimpleStdioOption<IsSync, false, false>
+	| StdioOptionsArray<IsSync>;
+
+interface IdleTimeoutOptions {
+    idleTimeout?: number;
+}
 /** Run a command, with arguments being an array */
-declare const run: (file: string, args?: string[] | object, options?: Options) => ExecaChildProcess<string>;
+declare const run: (file: string, args?: string[] | object, options?: Options & IdleTimeoutOptions) => ResultPromise<{
+    preferLocal?: boolean;
+    localDir?: string | URL;
+    node?: boolean;
+    nodeOptions?: readonly string[];
+    nodePath?: string | URL;
+    shell?: boolean | string | URL;
+    cwd?: string | URL;
+    env?: Readonly<Partial<Record<string, string>>>;
+    extendEnv?: boolean;
+    input?: string | Uint8Array | stream.Readable;
+    inputFile?: string | URL;
+    stdin?: StdinOptionCommon<false>;
+    stdout?: StdoutStderrOptionCommon<false>;
+    stderr?: StdoutStderrOptionCommon<false>;
+    stdio?: StdioOptionsProperty<false>;
+    all?: boolean;
+    encoding?: EncodingOption;
+    lines?: FdGenericOption<boolean>;
+    stripFinalNewline?: FdGenericOption<boolean>;
+    maxBuffer?: FdGenericOption<number>;
+    buffer?: FdGenericOption<boolean>;
+    ipc?: boolean | undefined;
+    serialization?: "json" | "advanced" | undefined;
+    ipcInput?: execa.Message | undefined;
+    verbose?: VerboseOption;
+    reject?: boolean;
+    timeout?: number;
+    cancelSignal?: AbortSignal | undefined;
+    gracefulCancel?: boolean | undefined;
+    forceKillAfterDelay?: number | boolean | undefined;
+    killSignal?: keyof os.SignalConstants | number;
+    detached?: boolean | undefined;
+    cleanup?: boolean | undefined;
+    uid?: number;
+    gid?: number;
+    argv0?: string;
+    windowsHide?: boolean;
+    windowsVerbatimArguments?: boolean;
+}>;
 
 interface RunnerConfig {
     id: string;