@orkestrel/process 0.0.1

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

@@ -0,0 +1,351 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * Creates the failure raised when a manager launch reuses a live id.
+ *
+ * @param id - The id already occupied by a live child
+ * @returns A typed duplicate-id failure
+ */
+export declare function createDuplicateError(id: string): ProcessError;
+
+/**
+ * Creates the failure raised when a run does not complete successfully and rejection is requested.
+ *
+ * @param result - The buffered run outcome that failed
+ * @returns A typed run failure carrying its {@link RunResult}
+ */
+export declare function createRunError(result: RunResult): ProcessError;
+
+/**
+ * Checks whether an unknown value is a {@link ProcessError}.
+ *
+ * @param value - The value to inspect
+ * @returns True only for a `ProcessError` instance; false otherwise
+ *
+ * @example
+ * ```ts
+ * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true
+ * isProcessError(new Error('spawn failed')) // false
+ * ```
+ */
+export declare function isProcessError(value: unknown): value is ProcessError;
+
+/** 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. */
+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 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 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`.
+ */
+/**
+ * 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.
+ */
+export declare interface ProcessCommand {
+    readonly file: string;
+    readonly arguments: readonly string[];
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly input?: string;
+}
+
+/** A child-process failure with a stable machine-readable category. */
+export declare class ProcessError extends Error {
+    readonly name = "ProcessError";
+    readonly code: ProcessErrorCode;
+    readonly context?: ProcessErrorContext;
+    /** The buffered run outcome, present when a one-shot run produced the failure. */
+    readonly result?: RunResult;
+    /**
+     * Create a process error.
+     *
+     * @param message - Human-readable failure description
+     * @param options - Machine-readable category, optional context, optional cause, and optional run result
+     */
+    constructor(message: string, options: ProcessErrorOptions);
+}
+
+/** The machine-readable {@link ProcessError} categories. */
+export declare type ProcessErrorCode = 'spawn' | 'timeout' | 'duplicate' | 'protocol';
+
+/** Structured context carried by a {@link ProcessError}. */
+export declare interface ProcessErrorContext {
+    /** The registry id involved, for a manager failure. */
+    readonly id?: string;
+    /** The command line involved, for a run or spawn failure. */
+    readonly command?: string;
+    /** The child's exit code, when one was observed. */
+    readonly code?: number | null;
+    /** The terminating signal, when one ended the child. */
+    readonly signal?: string | null;
+    /** The rejected public input, for an input-validation failure. */
+    readonly value?: unknown;
+}
+
+/** Construction options for a {@link ProcessError}. */
+export declare interface ProcessErrorOptions {
+    /** The stable machine-readable category. */
+    readonly code: ProcessErrorCode;
+    /** Structured detail about the failure. */
+    readonly context?: ProcessErrorContext;
+    /** The underlying cause, when one exists. */
+    readonly cause?: unknown;
+    /** The buffered run outcome, present when a {@link RunResult} produced the failure. */
+    readonly result?: RunResult;
+}
+
+/**
+ * The push observation surface of a {@link ProcessInterface} — the moments a fire-and-forget
+ * 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.
+ */
+export declare type ProcessEventMap = {
+    /** A decoded standard-error chunk arrived. */
+    readonly stderr: readonly [chunk: string];
+    /** The child settled — its terminal state, delivered once. */
+    readonly exit: readonly [exit: ProcessExit];
+};
+
+/** The observed terminal state of a child process: its exit code, or the signal that ended it. */
+export declare interface ProcessExit {
+    /** The exit code, or `null` when a signal ended the process. */
+    readonly code: number | null;
+    /** The terminating signal name, or `null` when the process exited on its own. */
+    readonly signal: string | null;
+}
+
+/**
+ * One supervised child process with eagerly framed output 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.
+ */
+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. */
+    readonly lines: AsyncIterable<string>;
+    /** The decoded byte-bounded stderr tail. */
+    readonly evidence: string;
+    /** The terminal child state, observed once from the close event. */
+    readonly exit: Promise<ProcessExit>;
+    /**
+     * Write one line to the open standard-input channel.
+     *
+     * @param text - The line text without its trailing newline
+     * @returns True when the channel accepted the line without backpressure; false otherwise
+     */
+    send(text: string): boolean;
+    /**
+     * Terminate the child process tree and await its observed exit.
+     *
+     * @returns A promise that resolves after bounded termination
+     */
+    stop(): Promise<void>;
+    /**
+     * Stop the child and destroy the observation emitter.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * The push observation surface of a {@link ProcessManagerInterface} — the fleet-level moments a
+ * fire-and-forget observer subscribes to.
+ *
+ * @remarks
+ * Declared as a `type` alias so it satisfies the emitter's `EventMap` constraint structurally.
+ */
+export declare type ProcessManagerEventMap = {
+    /** A child was launched under its id. */
+    readonly launch: readonly [id: string];
+    /** A child settled and left the registry — its id and terminal state. */
+    readonly exit: readonly [id: string, exit: ProcessExit];
+};
+
+/**
+ * A keyed registry of live supervised child processes.
+ *
+ * @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.
+ */
+export declare interface ProcessManagerInterface {
+    /** The typed fleet-level observation surface. */
+    readonly emitter: EmitterInterface<ProcessManagerEventMap>;
+    /** The number of live children. */
+    readonly count: number;
+    /**
+     * The live child under `id`, or `undefined` when none is.
+     *
+     * @param id - The registry key
+     * @returns The child, or `undefined`
+     */
+    process(id: string): ProcessInterface | undefined;
+    /**
+     * A snapshot of every live child.
+     *
+     * @returns The live children in launch order
+     */
+    processes(): readonly ProcessInterface[];
+    /**
+     * Spawn and register one child under `id`.
+     *
+     * @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
+     */
+    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
+     */
+    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
+     */
+    stop(id: string): Promise<boolean>;
+    /**
+     * Terminate every live child and await their exit.
+     *
+     * @returns A promise that resolves after all children stop
+     */
+    stop(): Promise<void>;
+    /**
+     * Stop every child, then destroy the registry emitter last.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Construction options for a {@link ProcessManagerInterface}.
+ *
+ * @remarks
+ * `on` installs initial {@link ProcessManagerEventMap} listeners and `error` receives isolated
+ * listener failures.
+ */
+export declare interface ProcessManagerOptions {
+    readonly on?: EmitterHooks<ProcessManagerEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/**
+ * 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.
+ */
+export declare interface ProcessOptions {
+    readonly on?: EmitterHooks<ProcessEventMap>;
+    readonly error?: EmitterErrorHandler;
+    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;
+    /** Maximum retained stderr tail in bytes. Default: {@link PROCESS_EVIDENCE}. */
+    readonly evidence?: 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;
+}
+
+/**
+ * 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`.
+ */
+export declare interface RunOptions {
+    /** 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 child is terminated. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** Cooperative window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
+    readonly grace?: number;
+    /** Aborting this signal terminates the run. */
+    readonly signal?: AbortSignal;
+    /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
+    readonly reject?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
+
+/**
+ * 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.
+ */
+export declare interface RunResult {
+    /** The command line that was run, for diagnostics. */
+    readonly command: string;
+    /** The complete captured standard output, byte-bounded by `limit`. */
+    readonly stdout: string;
+    /** The complete 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;
+}
+
+export { }

package/dist/src/core/index.js

@@ -0,0 +1,80 @@
+import { holds } from "@orkestrel/contract";
+//#region src/core/constants.ts
+/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+var PROCESS_GRACE = 5e3;
+/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+var PROCESS_EVIDENCE = 2048;
+/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+var PROCESS_OUTPUT = 10485760;
+//#endregion
+//#region src/core/errors.ts
+/** A child-process failure with a stable machine-readable category. */
+var ProcessError = class extends Error {
+	name = "ProcessError";
+	code;
+	context;
+	/** The buffered run outcome, present when a one-shot run produced the failure. */
+	result;
+	/**
+	* Create a process error.
+	*
+	* @param message - Human-readable failure description
+	* @param options - Machine-readable category, optional context, optional cause, and optional run result
+	*/
+	constructor(message, options) {
+		const cause = options.cause;
+		super(message, cause === void 0 ? void 0 : { cause });
+		this.code = options.code;
+		if (options.context !== void 0) this.context = options.context;
+		if (options.result !== void 0) this.result = options.result;
+	}
+};
+/**
+* Checks whether an unknown value is a {@link ProcessError}.
+*
+* @param value - The value to inspect
+* @returns True only for a `ProcessError` instance; false otherwise
+*
+* @example
+* ```ts
+* isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true
+* isProcessError(new Error('spawn failed')) // false
+* ```
+*/
+function isProcessError(value) {
+	return holds(() => value instanceof ProcessError);
+}
+/**
+* Creates the failure raised when a manager launch reuses a live id.
+*
+* @param id - The id already occupied by a live child
+* @returns A typed duplicate-id failure
+*/
+function createDuplicateError(id) {
+	return new ProcessError(`Process '${id}' is already live`, {
+		code: "duplicate",
+		context: { id }
+	});
+}
+/**
+* Creates the failure raised when a run does not complete successfully and rejection is requested.
+*
+* @param result - The buffered run outcome that failed
+* @returns A typed run failure carrying its {@link RunResult}
+*/
+function createRunError(result) {
+	const reason = result.timedOut ? "timed out" : result.signal !== null ? `was killed by ${result.signal}` : `exited with code ${String(result.code)}`;
+	return new ProcessError(`Command '${result.command}' ${reason}`, {
+		code: result.timedOut ? "timeout" : "spawn",
+		context: {
+			command: result.command,
+			code: result.code,
+			signal: result.signal
+		},
+		result
+	});
+}
+//#endregion
+export { PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, ProcessError, createDuplicateError, createRunError, isProcessError };
+
+//# sourceMappingURL=index.js.map

package/dist/src/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n","import { holds } from '@orkestrel/contract'\nimport type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tRunResult,\n} from './types.js'\n\n/** A child-process failure with a stable machine-readable category. */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** The buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: RunResult\n\n\t/**\n\t * Create a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @param value - The value to inspect\n * @returns True only for a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\treturn holds(() => value instanceof ProcessError)\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @param result - The buffered run outcome that failed\n * @returns A typed run failure carrying its {@link RunResult}\n */\nexport function createRunError(result: RunResult): ProcessError {\n\tconst reason = result.timedOut\n\t\t? 'timed out'\n\t\t: result.signal !== null\n\t\t\t? `was killed by ${result.signal}`\n\t\t\t: `exited with code ${String(result.code)}`\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.timedOut ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,iBAAiB;;;;ACE9B,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;AAcA,SAAgB,eAAe,OAAuC;CACrE,OAAO,YAAY,iBAAiB,YAAY;AACjD;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,eAAe,QAAiC;CAC/D,MAAM,SAAS,OAAO,WACnB,cACA,OAAO,WAAW,OACjB,iBAAiB,OAAO,WACxB,oBAAoB,OAAO,OAAO,IAAI;CAC1C,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,WAAW,YAAY;EACpC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E;CACD,CAAC;AACF"}