@orkestrel/process 0.0.1 → 0.0.3

package/dist/src/core/index.d.cts

@@ -10,13 +10,66 @@ import { EmitterInterface } from '@orkestrel/emitter';
  */
 export declare function createDuplicateError(id: string): ProcessError;
 
+/**
+ * Creates the failure raised when a public input is refused before anything is spawned.
+ *
+ * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
+ * @param value - The rejected value, carried as `context.value`
+ * @returns A typed validation failure
+ *
+ * @example
+ * ```ts
+ * createInvalidError("option 'grace'", -1).code // 'invalid'
+ * ```
+ */
+export declare function createInvalidError(subject: string, value: unknown): ProcessError;
+
+/**
+ * Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+ *
+ * @param id - The id the refused launch asked for
+ * @returns A typed protocol failure
+ */
+export declare function createProtocolError(id: string): ProcessError;
+
 /**
  * Creates the failure raised when a run does not complete successfully and rejection is requested.
  *
+ * @remarks
+ * The category is `timeout` only when the run's own timeout elapsed; every other failure, including
+ * an abort and an output overflow, is a `spawn` failure carrying its {@link RunResult}.
+ *
  * @param result - The buffered run outcome that failed
+ * @param cause - The underlying host fault, when one ended the run
  * @returns A typed run failure carrying its {@link RunResult}
  */
-export declare function createRunError(result: RunResult): ProcessError;
+export declare function createRunError(result: RunResult, cause?: unknown): ProcessError;
+
+/**
+ * Options for a detached fire-and-forget spawn.
+ *
+ * @remarks
+ * A detached child owns no stdio and is never awaited, so the contract carries only the directory it
+ * starts in. Its environment comes from the command's own `environment` and `isolated`.
+ */
+export declare interface DetachOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+}
+
+/**
+ * Lookup inputs for resolving a command file to an executable path.
+ *
+ * @remarks
+ * `workspace` is searched before `PATH`, matching Windows command semantics. `environment` is the
+ * child's effective environment, so the lookup reads the same `PATH` and `PATHEXT` the child will.
+ */
+export declare interface ExecutableOptions {
+    /** The directory searched first. Default: the current working directory. */
+    readonly workspace?: string;
+    /** The child's effective environment. Default: the parent process environment. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+}
 
 /**
  * Checks whether an unknown value is a {@link ProcessError}.
@@ -32,46 +85,63 @@ export declare function createRunError(result: RunResult): ProcessError;
  */
 export declare function isProcessError(value: unknown): value is ProcessError;
 
+/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+export declare const PROCESS_BACKLOG = 10485760;
+
+/** The window in milliseconds a termination waits for the child's native exit after the final kill. */
+export declare const PROCESS_CONFIRMATION = 5000;
+
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
-/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 export declare const PROCESS_GRACE = 5000;
 
 /** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */
 export declare const PROCESS_OUTPUT = 10485760;
 
+/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+export declare const PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+/** The largest timer delay in milliseconds the host schedules without truncating it to one. */
+export declare const PROCESS_TIMER = 2147483647;
+
 /**
  * The public contracts for `@orkestrel/process`: a typed child-process toolkit.
  *
  * @remarks
  * Three tiers, smallest to largest:
  *
- * - **{@link ProcessInterface}** — one supervised child with eagerly framed stdout lines, a
- *   byte-bounded stderr tail, a live stderr event, a writable stdin channel, a typed lifecycle
- *   {@link ProcessEventMap} emitter, and bounded `SIGTERM` → grace → `SIGKILL` termination. The
- *   low-level streaming primitive.
+ * - **{@link ProcessInterface}** — one supervised child with framed stdout lines under a bounded
+ *   backlog, a byte-bounded stderr tail, a live stderr event, a writable stdin channel, a typed
+ *   lifecycle {@link ProcessEventMap} emitter, and bounded termination. The low-level streaming
+ *   primitive.
  * - **{@link RunResult} / run** — a one-shot runner that buffers a child to completion and settles
  *   with its output and exit, the ergonomic layer for fire-and-collect commands.
  * - **{@link ProcessManagerInterface}** — a keyed registry of live {@link ProcessInterface}
  *   children, launched and stopped by id, observed through its own {@link ProcessManagerEventMap}.
  *
- * Every contract here is host-independent (`AbortSignal`, `AsyncIterable`, `Promise`, and plain
- * `string` signal names). The Node implementations live in `@orkestrel/process/server`.
+ * Every contract here is host-independent (`AbortSignal`, `AsyncIterable`, `Promise`, `Uint8Array`,
+ * and plain `string` signal names). The Node implementations live in `@orkestrel/process/server`.
  */
 /**
  * One spawnable command: the executable, its argument vector, and optional environment overrides
  * and initial standard input.
  *
  * @remarks
- * `environment` merges over the parent process environment; an `undefined` value unsets a key.
- * `input` is written to the child's stdin immediately after spawn.
+ * `environment` merges over the parent process environment unless `isolated` is `true`, and an
+ * `undefined` value unsets a key. On Windows the merge is case-insensitive and the last writer
+ * wins, matching how the host resolves an environment variable. `input` is written to the child's
+ * stdin immediately after spawn. Every string here is spawn-bound: an empty `file`, or a NUL
+ * character anywhere, is refused with a {@link ProcessError} coded `invalid`.
  */
 export declare interface ProcessCommand {
     readonly file: string;
     readonly arguments: readonly string[];
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly input?: string;
+    /** If `true`, the child environment is `environment` alone; if `false` or omitted, it merges over the parent environment. */
+    readonly isolated?: boolean;
 }
 
 /** A child-process failure with a stable machine-readable category. */
@@ -91,7 +161,7 @@ export declare class ProcessError extends Error {
 }
 
 /** The machine-readable {@link ProcessError} categories. */
-export declare type ProcessErrorCode = 'spawn' | 'timeout' | 'duplicate' | 'protocol';
+export declare type ProcessErrorCode = 'spawn' | 'timeout' | 'duplicate' | 'protocol' | 'invalid';
 
 /** Structured context carried by a {@link ProcessError}. */
 export declare interface ProcessErrorContext {
@@ -124,12 +194,16 @@ export declare interface ProcessErrorOptions {
  * observer subscribes to, alongside the `lines` stream and the `exit` promise.
  *
  * @remarks
- * Declared as a `type` alias so it satisfies the emitter's `EventMap` constraint structurally. A
- * listener throw is isolated by the emitter and routed to its `error` handler, never onto this map.
+ * Declared as a `type` alias so it satisfies the emitter's `EventMap` constraint structurally. The
+ * `error` event carries a child fault — a failure to spawn or a process-level error. It is distinct
+ * from the `error` handler in {@link ProcessOptions}: a listener throw is isolated by the emitter and
+ * routed to that handler, never emitted as this `error` event.
  */
 export declare type ProcessEventMap = {
     /** A decoded standard-error chunk arrived. */
     readonly stderr: readonly [chunk: string];
+    /** The child emitted an error — a spawn fault or process-level failure — carrying its cause. */
+    readonly error: readonly [error: unknown];
     /** The child settled — its terminal state, delivered once. */
     readonly exit: readonly [exit: ProcessExit];
 };
@@ -143,19 +217,25 @@ export declare interface ProcessExit {
 }
 
 /**
- * One supervised child process with eagerly framed output and bounded termination.
+ * One supervised child process with framed output, a bounded backlog, and bounded termination.
  *
  * @remarks
- * `lines` is pumped eagerly: stdout is drained whether or not a consumer iterates, so `exit`
- * resolves and a late consumer still receives every line. `evidence` is the decoded, byte-bounded
- * stderr tail — the diagnostic to attach to a failed exit. The typed `emitter` carries the live
- * `stderr` chunks and the terminal `exit`, alongside the `exit` promise. `send` never throws; it
- * returns whether the line reached an open channel. `stop` is idempotent.
+ * `lines` is pumped as soon as the child writes, and it is a single-consumer stream: each line goes
+ * to exactly one waiting iterator, so two iterators split the output between them rather than each
+ * receiving all of it. The policy for an unconsumed backlog follows
+ * consumer intent. Once an iterator has been requested, stdout pauses at the `backlog` mark and
+ * resumes at half of it, so the consumer loses nothing and the child feels real backpressure. While
+ * no iterator has ever been requested, stdout keeps draining so `exit` still resolves, and retention
+ * stops at the mark: a consumer attaching after that point receives the retained head, a gap, then
+ * the live stream. `evidence` is the decoded, byte-bounded stderr tail — the diagnostic to attach to
+ * a failed exit. The typed `emitter` carries the live `stderr` chunks, the child `error` cause, and
+ * the terminal `exit`, alongside the `exit` promise. `stop` and `destroy` are idempotent and never
+ * reject.
  */
 export declare interface ProcessInterface {
     /** The typed lifecycle observation surface. */
     readonly emitter: EmitterInterface<ProcessEventMap>;
-    /** The eagerly captured stdout lines, in arrival order, ending when the child's stdout closes. */
+    /** The captured stdout lines, in arrival order, for one consumer, ending when the child's stdout closes. */
     readonly lines: AsyncIterable<string>;
     /** The decoded byte-bounded stderr tail. */
     readonly evidence: string;
@@ -164,18 +244,35 @@ export declare interface ProcessInterface {
     /**
      * Write one line to the open standard-input channel.
      *
+     * @remarks
+     * Never rejects. The promise settles when the host reports the line handled, so a line written
+     * to a child that is not reading stays pending until the child drains it or the channel closes.
+     * Every terminal teardown path destroys stdin, so a pending write always settles by teardown. A
+     * caller that needs its own deadline arms a timer and calls `stop`.
+     *
      * @param text - The line text without its trailing newline
-     * @returns True when the channel accepted the line without backpressure; false otherwise
+     * @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
      */
-    send(text: string): boolean;
+    send(text: string): Promise<boolean>;
     /**
      * Terminate the child process tree and await its observed exit.
      *
-     * @returns A promise that resolves after bounded termination
+     * @remarks
+     * Never rejects. On Windows the whole tree is killed immediately through `taskkill`, with a
+     * direct kill as the fallback; on a POSIX host the process group receives `SIGTERM`, then
+     * `SIGKILL` after `grace`. No signal is initiated after the child's native exit is observed; the
+     * window between initiating a signal and the host delivering it belongs to the operating system.
+     *
+     * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
      */
-    stop(): Promise<void>;
+    stop(): Promise<boolean>;
     /**
-     * Stop the child and destroy the observation emitter.
+     * Stop the child, close its standard-input channel, and destroy the observation emitter.
+     *
+     * @remarks
+     * Always resolves, including when termination was never confirmed. Resolving does not imply the
+     * child's stdio has closed: a descendant holding an inherited pipe keeps the close event pending,
+     * so `exit` and `lines` can still be outstanding after this barrier settles.
      *
      * @returns The stable barrier shared by every call
      */
@@ -201,10 +298,12 @@ export declare type ProcessManagerEventMap = {
  *
  * @remarks
  * A child that settles removes itself from the registry, so `count` and `processes` reflect only
- * live children, and its departure emits `exit`. `launch` throws a {@link ProcessError} coded
- * `duplicate` when the id is already live — spawn faults surface through the returned child's
- * `exit`, not from `launch`. The typed `emitter` carries the `launch` and `exit` moments across
- * every child.
+ * live children, and its departure emits `exit`. Eviction follows the child's own `exit` promise,
+ * which no listener can forge, so it lands one microtask after the child's public `exit` event: a
+ * listener on that event still sees the child registered. `launch` throws a {@link ProcessError}
+ * coded `duplicate` when the id is already live and `protocol` after `destroy` has begun — spawn
+ * faults surface through the returned child's `exit`, not from `launch`. The typed `emitter` carries
+ * the `launch` and `exit` moments across every child.
  */
 export declare interface ProcessManagerInterface {
     /** The typed fleet-level observation surface. */
@@ -227,35 +326,49 @@ export declare interface ProcessManagerInterface {
     /**
      * Spawn and register one child under `id`.
      *
+     * @remarks
+     * Every option is read before the child is spawned, so a caller's own option getter runs while
+     * nothing has started and a throw from one strands no process. A getter that begins `destroy`
+     * without throwing is the one remaining race, and it leaves a bounded residual: the child is
+     * already spawned, so the launch is refused with `protocol` and that child is torn down
+     * asynchronously, bounded by `grace` plus the confirmation window. The `destroy` barrier settled
+     * before the refusal, so awaiting it does not cover that teardown.
+     *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
      * @returns The launched child
-     * @throws A {@link ProcessError} coded `duplicate` when `id` is already live
+     * @throws A {@link ProcessError} coded `duplicate` when `id` is already live, `protocol` when the registry is being destroyed, or `invalid` when an option or command string is malformed
      */
     launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
      * Terminate the named children and await their exit.
      *
      * @param ids - The registry keys to stop
-     * @returns True when every named child stopped, false when any id was not live
+     * @returns True when every named child was live and its exit was confirmed; false otherwise
      */
     stop(ids: readonly string[]): Promise<boolean>;
     /**
      * Terminate one child and await its exit.
      *
      * @param id - The registry key to stop
-     * @returns True when the child was live and stopped, false when the id was not live
+     * @returns True when the child was live and its exit was confirmed; false when the id was not live or the confirmation deadline elapsed
      */
     stop(id: string): Promise<boolean>;
     /**
      * Terminate every live child and await their exit.
      *
-     * @returns A promise that resolves after all children stop
+     * @returns A promise that resolves after every child stops
      */
     stop(): Promise<void>;
     /**
      * Stop every child, then destroy the registry emitter last.
      *
+     * @remarks
+     * Always resolves, and refuses a later `launch` with a {@link ProcessError} coded `protocol`.
+     * Every child is destroyed, not merely stopped, so each child's own observation emitter is
+     * destroyed too and every subscription on it goes silently inert. The registry emitter is
+     * destroyed last.
+     *
      * @returns The stable barrier shared by every call
      */
     destroy(): Promise<void>;
@@ -277,10 +390,13 @@ export declare interface ProcessManagerOptions {
  * Construction options for one supervised child process.
  *
  * @remarks
- * `grace` is the sole timing knob: after `stop`, the child is sent `SIGTERM`, then `SIGKILL` if it
- * has not exited within `grace` milliseconds. There is no completion deadline — a caller that wants
- * one arms its own timer and calls `stop`. `on` installs initial {@link ProcessEventMap} listeners
- * and `error` receives isolated listener failures.
+ * `grace` is the cooperative window between `SIGTERM` and `SIGKILL` on a POSIX host; Windows has no
+ * cooperative phase, so the value is unused there. There is no completion deadline — a caller that
+ * wants one arms its own timer and calls `stop`. `backlog` bounds the unconsumed `lines` backlog.
+ * `on` installs initial {@link ProcessEventMap} listeners and `error` receives isolated listener
+ * failures. Every numeric option is validated at construction: a timer value outside
+ * `[0, PROCESS_TIMER]`, a negative or fractional byte value, or a `backlog` below `1` throws a
+ * {@link ProcessError} coded `invalid`.
  */
 export declare interface ProcessOptions {
     readonly on?: EmitterHooks<ProcessEventMap>;
@@ -288,24 +404,58 @@ export declare interface ProcessOptions {
     readonly command: ProcessCommand;
     /** The working directory the child runs in. */
     readonly workspace: string;
-    /** Cooperative termination window in milliseconds between `SIGTERM` and `SIGKILL`. */
-    readonly grace: number;
+    /** Cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`. Default: {@link PROCESS_GRACE}. */
+    readonly grace?: number;
     /** Maximum retained stderr tail in bytes. Default: {@link PROCESS_EVIDENCE}. */
     readonly evidence?: number;
+    /** Soft high-water mark in bytes for the unconsumed `lines` backlog. Default: {@link PROCESS_BACKLOG}. */
+    readonly backlog?: number;
     /** If `true`, stdin stays open for {@link ProcessInterface.send}; if `false` or omitted, stdin closes after any initial `input`. */
     readonly writable?: boolean;
     /** Aborting this signal terminates the child through the same bounded `stop`. */
     readonly signal?: AbortSignal;
 }
 
+/**
+ * The captured bytes and terminal facts one settled {@link RunResult} is built from.
+ *
+ * @remarks
+ * Both byte fields are trimmed to `limit` on a code-point boundary when the result is built, so a
+ * caller passes the raw retained head and never a decoded string. `cause` carries the host fault
+ * that ended the run, when one did; its presence alone marks the run failed.
+ */
+export declare interface RunInput {
+    /** The diagnostic command line. */
+    readonly command: string;
+    /** The retained standard-output bytes. */
+    readonly stdout: Uint8Array;
+    /** The retained standard-error bytes. */
+    readonly stderr: Uint8Array;
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** If `true`, the run's own timeout elapsed; if `false`, it did not. */
+    readonly expired: boolean;
+    /** If `true`, the caller's signal aborted the run; if `false`, it did not. */
+    readonly aborted: boolean;
+    /** If `true`, a stream exceeded `limit`; if `false`, both fit. */
+    readonly truncated: boolean;
+    /** The maximum retained bytes for each stream. */
+    readonly limit: number;
+    /** The host fault that ended the run, when one did. */
+    readonly cause?: unknown;
+}
+
 /**
  * Options for a one-shot run.
  *
  * @remarks
- * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `reject`
- * follows the command-runner convention: by default a non-zero exit rejects with a
- * {@link ProcessError} carrying the {@link RunResult}; `reject: false` resolves with the result
- * instead, so the caller inspects `failed`.
+ * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `strict`
+ * decides how a failure is delivered: by default a non-zero exit rejects with a
+ * {@link ProcessError} carrying the {@link RunResult}; `strict: false` resolves with the result
+ * instead, so the caller inspects `failed`. An invalid option or command rejects before the child is
+ * spawned, with a {@link ProcessError} coded `invalid`. An unbounded run awaits stdio completion
+ * rather than process exit, so give `timeout` a value wherever a descendant may inherit the child's
+ * stdio and hold the pipe open past the child's own exit.
  */
 export declare interface RunOptions {
     /** The working directory. Default: the current working directory. */
@@ -316,12 +466,12 @@ export declare interface RunOptions {
     readonly input?: string;
     /** Milliseconds before the child is terminated. `0` or omitted disables the timeout. */
     readonly timeout?: number;
-    /** Cooperative window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
+    /** Cooperative POSIX window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
     readonly grace?: number;
-    /** Aborting this signal terminates the run. */
+    /** Aborting this signal terminates the run and reports `aborted`. */
     readonly signal?: AbortSignal;
     /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
-    readonly reject?: boolean;
+    readonly strict?: boolean;
     /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
     readonly limit?: number;
 }
@@ -330,22 +480,71 @@ export declare interface RunOptions {
  * The settled outcome of a one-shot run: the buffered output and the terminal state.
  *
  * @remarks
- * `failed` is `true` when the child exited non-zero, was killed by a signal, timed out, or failed to
- * spawn. `timedOut` is `true` only when the run's own `timeout` elapsed.
+ * `failed` is `true` when the child exited non-zero, was killed by a signal, expired, was aborted, or
+ * failed to spawn. `expired` and `aborted` are the two ways the run ended the child rather than the
+ * child ending itself, and only the first of them observed is recorded. `truncated` is independent of
+ * both: it reports that a stream exceeded `limit`, which fails a synchronous run and does not fail an
+ * asynchronous one.
  */
 export declare interface RunResult {
     /** The command line that was run, for diagnostics. */
     readonly command: string;
-    /** The complete captured standard output, byte-bounded by `limit`. */
+    /** The captured standard output, byte-bounded by `limit`. */
     readonly stdout: string;
-    /** The complete captured standard error, byte-bounded by `limit`. */
+    /** The captured standard error, byte-bounded by `limit`. */
     readonly stderr: string;
     readonly code: number | null;
     readonly signal: string | null;
     /** True if the run did not complete successfully. */
     readonly failed: boolean;
     /** True if the run's `timeout` elapsed before completion. */
-    readonly timedOut: boolean;
+    readonly expired: boolean;
+    /** True if the caller's `signal` aborted the run before completion. */
+    readonly aborted: boolean;
+    /** True if either stream exceeded `limit`, so the captured text is the retained head. */
+    readonly truncated: boolean;
+}
+
+/**
+ * Options for a synchronous one-shot run.
+ *
+ * @remarks
+ * The synchronous host offers neither a cooperative termination window nor in-flight cancellation,
+ * so this contract carries no `grace` and no `signal`. A `timeout` and an output overflow both end
+ * the child with `SIGKILL`; an overflow reports `truncated` and `failed` together, which is where
+ * the synchronous and asynchronous runners genuinely differ.
+ */
+export declare interface RunSyncOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Standard input written to the child. */
+    readonly input?: string;
+    /** Milliseconds before the host kills the child. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** If `false`, return the result on failure instead of throwing. Default: `true`. */
+    readonly strict?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
+
+/**
+ * The resolved spawn form of one command: the executable to launch, the argument vector to pass,
+ * and whether the host receives that vector verbatim.
+ *
+ * @remarks
+ * No spawn in this package uses an implicit shell. `verbatim` is `true` only for a Windows `.cmd` or
+ * `.bat` script, which runs through an explicitly quoted `cmd.exe /d /s /c` command line, and an
+ * argument that batch target could corrupt — one carrying `%`, which `cmd.exe` expands before it
+ * parses quotes — is refused rather than passed. A shell metacharacter in an argument is therefore
+ * data rather than syntax on every path.
+ */
+export declare interface SpawnInput {
+    readonly file: string;
+    readonly arguments: readonly string[];
+    /** If `true`, pass the argument vector to the host verbatim; if `false`, let the host quote it. */
+    readonly verbatim: boolean;
 }
 
 export { }