@orkestrel/process 0.0.9 → 0.0.11

package/dist/src/server/index.cjs

@@ -9,6 +9,42 @@ let _src_core = require("../core/index.cjs");
 let node_readline = require("node:readline");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let node_string_decoder = require("node:string_decoder");
+//#region src/server/cloners.ts
+/**
+* Takes one owned frozen snapshot of a caller's command.
+*
+* @remarks
+* Every public entry point snapshots before it validates, so the object validated is the object
+* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
+* command whose `file` changes between reads would otherwise validate one executable and spawn
+* another. The argument vector and the environment record are copied and frozen, so a caller
+* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
+* becoming an explicit `undefined`.
+*
+* @param command - The caller's command, whose properties may be getters
+* @returns A frozen command carrying the values read at this instant
+*
+* @example
+* ```ts
+* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
+* ```
+*/
+function snapshotCommand(command) {
+	const file = command.file;
+	const argumentsList = Object.freeze([...command.arguments]);
+	const sourceEnvironment = command.environment;
+	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
+	const input = command.input;
+	const isolated = command.isolated;
+	return Object.freeze({
+		file,
+		arguments: argumentsList,
+		...environment === void 0 ? {} : { environment },
+		...input === void 0 ? {} : { input },
+		...isolated === void 0 ? {} : { isolated }
+	});
+}
+//#endregion
 //#region src/server/helpers.ts
 /**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -107,40 +143,6 @@ function captureChunk(chunk, room) {
 	return node_buffer.Buffer.from(chunk.subarray(0, room));
 }
 /**
-* Takes one owned frozen snapshot of a caller's command.
-*
-* @remarks
-* Every public entry point snapshots before it validates, so the object validated is the object
-* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
-* command whose `file` changes between reads would otherwise validate one executable and spawn
-* another. The argument vector and the environment record are copied and frozen, so a caller
-* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
-* becoming an explicit `undefined`.
-*
-* @param command - The caller's command, whose properties may be getters
-* @returns A frozen command carrying the values read at this instant
-*
-* @example
-* ```ts
-* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
-* ```
-*/
-function snapshotCommand(command) {
-	const file = command.file;
-	const argumentsList = Object.freeze([...command.arguments]);
-	const sourceEnvironment = command.environment;
-	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
-	const input = command.input;
-	const isolated = command.isolated;
-	return Object.freeze({
-		file,
-		arguments: argumentsList,
-		...environment === void 0 ? {} : { environment },
-		...input === void 0 ? {} : { input },
-		...isolated === void 0 ? {} : { isolated }
-	});
-}
-/**
 * Renders one command into its diagnostic command line.
 *
 * @param command - The executable and its argument vector
@@ -257,7 +259,7 @@ function mergeEnvironment(isolated, base, override) {
 * command. An unreadable or malformed path reports `false` rather than throwing.
 *
 * @param target - The absolute or relative path to inspect
-* @returns True when the path resolves to a regular file; false otherwise
+* @returns True if the path resolves to a regular file; false otherwise
 *
 * @example
 * ```ts
@@ -305,7 +307,8 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
 	return Object.freeze(targets);
 }
 /**
-* Resolves a command file to the executable path the host would launch.
+* Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+* host, which performs its own lookup.
 *
 * @param file - The command executable name or path
 * @param options - The directory searched first and the child's effective environment
@@ -530,7 +533,7 @@ function validateWorkspace(workspace) {
 * initiated against a pid the host may have reused.
 *
 * @param child - The child boundary
-* @returns True when the process has exited; false while it is live
+* @returns True if the process has exited; false otherwise
 *
 * @example
 * ```ts
@@ -586,7 +589,7 @@ function killProcess(child, signal) {
 *
 * @param pid - The root process id of the tree to end
 * @param timeout - The milliseconds the utility is given before it is killed
-* @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
+* @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
 *
 * @example
 * ```ts
@@ -637,7 +640,7 @@ function waitForExit(child, timeout) {
 *
 * @param child - The child boundary
 * @param timeout - The milliseconds to wait before giving up
-* @returns True when the host close arrived inside the deadline; false otherwise
+* @returns True if the host close arrived inside the deadline; false otherwise
 *
 * @example
 * ```ts
@@ -672,7 +675,7 @@ function waitForClose(child, timeout) {
 * @param child - The child boundary
 * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
 * @param confirm - The milliseconds the native exit is awaited after the final kill
-* @returns True when the native exit was observed; false when `confirm` elapsed without it
+* @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
 *
 * @example
 * ```ts
@@ -1030,7 +1033,7 @@ function detach(command, options) {
 	child.unref();
 }
 //#endregion
-//#region src/server/Supervisor.ts
+//#region src/server/processes/Supervisor.ts
 /**
 * Supervises one child process and reports each lifecycle moment to the face composing it.
 *
@@ -1059,6 +1062,25 @@ function detach(command, options) {
 * termination completes. `relieve` is optional because a face that never pauses the child's output
 * holds no backpressure to release, and a face with nothing to do there would otherwise declare an
 * empty method to say so.
+*
+* @example
+* ```ts
+* import { Supervisor } from '@orkestrel/process/server'
+*
+* const engine = new Supervisor(
+* 	{ command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
+* 	{
+* 		chunk: () => undefined,
+* 		fault: () => undefined,
+* 		close: () => undefined,
+* 		terminal: () => undefined,
+* 		teardown: () => undefined,
+* 	},
+* )
+* const exit = await engine.exit
+* exit.code // 0
+* await engine.destroy()
+* ```
 */
 var Supervisor = class {
 	#chunk;
@@ -1088,7 +1110,7 @@ var Supervisor = class {
 	#termination;
 	#destruction;
 	/**
-	* Spawn one child process and begin standard-error capture.
+	* Spawns one child process and begins standard-error capture.
 	*
 	* @remarks
 	* The face's callbacks are captured before anything is read or spawned, so the first moment the
@@ -1165,36 +1187,36 @@ var Supervisor = class {
 			if (signal.aborted) this.stop();
 		}
 	}
-	/** The child's standard-output stream, for the composing face to attach its own consumer to. */
+	/** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
 	get stdout() {
 		return this.#child.stdout;
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#child.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#child.exitCode;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#child.signalCode;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#tail.toString("utf8");
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#stopping;
 	}
 	/**
-	* The child's own ending, awaited without the terminal moment's drain window.
+	* Settles at the child's own ending, awaited without the terminal moment's drain window.
 	*
 	* @remarks
 	* Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
@@ -1204,7 +1226,7 @@ var Supervisor = class {
 	get ending() {
 		return this.#ending.promise;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#exit.promise;
 	}
@@ -1221,7 +1243,30 @@ var Supervisor = class {
 	* discard.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
+	*
+	* @example
+	* ```ts
+	* import { Supervisor } from '@orkestrel/process/server'
+	*
+	* const engine = new Supervisor(
+	* 	{
+	* 		command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+	* 		workspace: process.cwd(),
+	* 		writable: true,
+	* 	},
+	* 	{
+	* 		chunk: () => undefined,
+	* 		fault: () => undefined,
+	* 		close: () => undefined,
+	* 		terminal: () => undefined,
+	* 		teardown: () => undefined,
+	* 	},
+	* )
+	* const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
+	* accepted // true
+	* await engine.destroy()
+	* ```
 	*/
 	deliver(bytes) {
 		const stdin = this.#child.stdin;
@@ -1272,7 +1317,7 @@ var Supervisor = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		if (this.#termination !== void 0) return this.#termination;
@@ -1400,9 +1445,10 @@ var Supervisor = class {
 	}
 };
 //#endregion
-//#region src/server/Process.ts
+//#region src/server/processes/Process.ts
 /**
-* Supervises one child while keeping every observation channel aligned at termination.
+* Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+* every observation channel aligned at termination.
 *
 * @remarks
 * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -1447,7 +1493,7 @@ var Process = class {
 	#truncated = false;
 	#ended = false;
 	/**
-	* Spawn one child process and begin stream capture.
+	* Spawns one child process and begins stream capture.
 	*
 	* @param options - Command, workspace, termination, capture, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1502,48 +1548,48 @@ var Process = class {
 		this.#reader.on("line", this.#push.bind(this));
 		this.#reader.once("close", this.#finish.bind(this));
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
+	/** Yields the captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
 	get lines() {
 		return this.#lines;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True when the `lines` stream omitted output after a retention bound was reached. */
+	/** Reports whether the `lines` stream omitted output after a retention bound was reached. */
 	get truncated() {
 		return this.#truncated;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
 	/**
-	* Write one line to the open standard-input channel.
+	* Writes one line to the open standard-input channel.
 	*
 	* @remarks
 	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
@@ -1557,7 +1603,7 @@ var Process = class {
 	* for bytes the package is about to discard.
 	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	send(text) {
 		return this.#engine.deliver(node_buffer.Buffer.from(`${text}\n`, "utf8"));
@@ -1571,7 +1617,7 @@ var Process = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -1689,9 +1735,10 @@ var Process = class {
 	}
 };
 //#endregion
-//#region src/server/ProcessManager.ts
+//#region src/server/processes/ProcessManager.ts
 /**
-* A keyed registry of live supervised child processes.
+* Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+* every live child on teardown.
 *
 * @remarks
 * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -1727,7 +1774,7 @@ var ProcessManager = class {
 	#destroying = false;
 	#ending;
 	/**
-	* Construct a process registry.
+	* Constructs a process registry.
 	*
 	* @param options - Initial fleet-level observation hooks and listener-error handling
 	*/
@@ -1739,16 +1786,16 @@ var ProcessManager = class {
 			...error === void 0 ? {} : { error }
 		});
 	}
-	/** The typed fleet-level observation surface. */
+	/** Holds the typed fleet-level observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The number of live children. */
+	/** Counts the live children. */
 	get count() {
 		return this.#children.size;
 	}
 	/**
-	* The live child under `id`, or `undefined` when none is.
+	* Returns the live child under `id`, or `undefined` when none is.
 	*
 	* @param id - The registry key
 	* @returns The child, or `undefined`
@@ -1757,7 +1804,7 @@ var ProcessManager = class {
 		return this.#children.get(id);
 	}
 	/**
-	* A snapshot of every live child.
+	* Returns a snapshot of every live child.
 	*
 	* @returns The live children in launch order
 	*/
@@ -1765,7 +1812,7 @@ var ProcessManager = class {
 		return [...this.#children.values()];
 	}
 	/**
-	* Spawn and register one child under `id`.
+	* Spawns and registers one child under `id`.
 	*
 	* @remarks
 	* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
@@ -1803,7 +1850,7 @@ var ProcessManager = class {
 		return this.#stopMany(target);
 	}
 	/**
-	* Stop every child, then destroy the registry emitter last.
+	* Stops every child, then destroys the registry emitter last.
 	*
 	* @remarks
 	* Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
@@ -1856,7 +1903,7 @@ var ProcessManager = class {
 	}
 };
 //#endregion
-//#region src/server/Session.ts
+//#region src/server/processes/Session.ts
 /**
 * Supervises one child and publishes its standard output as raw bytes.
 *
@@ -1893,7 +1940,7 @@ var Session = class {
 	#engine;
 	#output;
 	/**
-	* Spawn one child process and begin byte capture.
+	* Spawns one child process and begins byte capture.
 	*
 	* @param options - Command, workspace, termination, evidence, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1931,39 +1978,39 @@ var Session = class {
 		});
 		this.#engine.stdout.on("data", this.#output);
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. `end` never turns it true. */
+	/** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The child's own ending, awaited without the terminal moment's drain window. */
+	/** Settles at the child's own ending, awaited without the terminal moment's drain window. */
 	get ending() {
 		return this.#engine.ending;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
@@ -1977,7 +2024,7 @@ var Session = class {
 	* returned promise settles.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	write(bytes) {
 		return this.#engine.deliver(bytes);
@@ -2001,7 +2048,7 @@ var Session = class {
 	* @remarks
 	* Never rejects, and every call shares one termination bounded by `grace` and `drain`.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -2037,27 +2084,37 @@ var Session = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates one supervised child process.
+* Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+* holds the published contract rather than the `Process` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link ProcessInterface}
 *
-* @example
+* @example Supervise a child and read its lines
 * ```ts
 * import { createProcess } from '@orkestrel/process/server'
 *
 * const child = createProcess({
-* 	command: { file: 'node', arguments: ['--version'] },
+* 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
 * 	workspace: process.cwd(),
-* 	grace: 5000,
+* 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
 * })
+*
+* const lines: string[] = []
+* for await (const line of child.lines) lines.push(line)
+* lines // ['ready', 'done']
+*
+* const exit = await child.exit
+* exit.code // 0
+* await child.destroy()
 * ```
 */
 function createProcess(options) {
 	return new Process(options);
 }
 /**
-* Creates one raw byte session over a supervised child process.
+* Creates one raw byte session over a supervised child process and returns it as a
+* {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link SessionInterface}
@@ -2077,7 +2134,9 @@ function createSession(options) {
 	return new Session(options);
 }
 /**
-* Creates one keyed registry of supervised child processes.
+* Creates one empty keyed registry of supervised child processes and returns it as a
+* {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+* `ProcessManager` class.
 *
 * @param options - Initial fleet-level observation hooks and listener-error handling
 * @returns The {@link ProcessManagerInterface} registry
@@ -2096,6 +2155,7 @@ function createProcessManager(options) {
 exports.Process = Process;
 exports.ProcessManager = ProcessManager;
 exports.Session = Session;
+exports.Supervisor = Supervisor;
 exports.buildExecutableCandidates = buildExecutableCandidates;
 exports.buildExecuteResult = buildExecuteResult;
 exports.buildPlatformSpawn = buildPlatformSpawn;