@orkestrel/process 0.0.4 → 0.0.5

package/dist/src/server/index.js

@@ -4,7 +4,7 @@ import { statSync } from "node:fs";
 import { join, posix, win32 } from "node:path";
 import { platform } from "node:process";
 import { boundsOf, holds, isNonEmptyString, isNonNegativeInteger, isString } from "@orkestrel/contract";
-import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
+import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
 import { createInterface } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { Emitter } from "@orkestrel/emitter";
@@ -683,8 +683,11 @@ function buildExecuteResult(input) {
 * overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
 * reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
 * and `truncated` reports the omission. Standard error is decoded and forwarded live as the `stderr`
-* event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries the
-* child `error` cause on a spawn fault and the terminal `exit`, alongside the `exit` promise. `pid`,
+* event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries a
+* child `error` cause on a spawn fault, a `protocol` {@link ProcessError} on a host-reported stdin
+* fault after the constructor input phase, and the terminal `exit`, alongside the `exit` promise.
+* A fault arising from the constructor-supplied `input` write or its closing `end` stays quiet
+* because the package initiated that sequence. `pid`,
 * `code`, and `signal` read the spawned child directly, so the native exit is readable before the
 * `exit` promise settles on stdio close. `stop` ends the whole tree and reports whether the native
 * exit was observed; `destroy` stops the child, destroys stdin so every pending `send` settles, and
@@ -710,6 +713,7 @@ var Process = class {
 	#grace;
 	#evidence;
 	#backlog;
+	#delivery;
 	#decoder = new StringDecoder("utf8");
 	#exit = Promise.withResolvers();
 	#lines;
@@ -717,6 +721,7 @@ var Process = class {
 	#waiters = [];
 	#signal;
 	#abort;
+	#writes = /* @__PURE__ */ new Map();
 	#tail = Buffer.alloc(0);
 	#head = 0;
 	#pending = 0;
@@ -726,6 +731,8 @@ var Process = class {
 	#terminating = false;
 	#closed = false;
 	#ended = false;
+	#input = 0;
+	#failure;
 	#stopping;
 	#ending;
 	/**
@@ -740,6 +747,7 @@ var Process = class {
 		const grace = options.grace;
 		const evidence = options.evidence;
 		const backlog = options.backlog;
+		const delivery = options.delivery;
 		const writable = options.writable;
 		const signal = options.signal;
 		const on = options.on;
@@ -749,6 +757,7 @@ var Process = class {
 		validateCommand(command);
 		validateWorkspace(workspace);
 		validateTimer(grace, "option 'grace'");
+		validateTimer(delivery, "option 'delivery'");
 		validateBytes(evidence, "option 'evidence'", 0);
 		validateBytes(backlog, "option 'backlog'", 1);
 		this.#emitter = new Emitter({
@@ -758,6 +767,7 @@ var Process = class {
 		this.#grace = grace ?? PROCESS_GRACE;
 		this.#evidence = evidence ?? PROCESS_EVIDENCE;
 		this.#backlog = backlog ?? PROCESS_BACKLOG;
+		this.#delivery = delivery ?? 0;
 		this.#signal = signal;
 		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
 		const childEnvironment = mergeEnvironment(command.isolated === true, command.environment);
@@ -785,10 +795,16 @@ var Process = class {
 		this.#reader.once("close", this.#finish.bind(this));
 		this.#child.once("error", (cause) => this.#emitter.emit("error", cause));
 		this.#child.once("close", this.#close.bind(this));
-		this.#child.stdin.on("error", () => void 0);
+		this.#child.stdin.on("error", (cause) => this.#failInputStream(cause));
 		this.#child.stderr.on("data", this.#retain.bind(this));
-		if (input !== void 0) this.#child.stdin.write(input);
-		if (writable !== true) this.#child.stdin.end();
+		if (input !== void 0) {
+			this.#input += 1;
+			this.#child.stdin.write(input, this.#completeInput.bind(this));
+		}
+		if (writable !== true) {
+			this.#input += 1;
+			this.#child.stdin.end(this.#completeInput.bind(this));
+		}
 		if (signal !== void 0) {
 			this.#abort = this.#terminate.bind(this);
 			signal.addEventListener("abort", this.#abort, { once: true });
@@ -831,24 +847,34 @@ var Process = class {
 	* 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`.
+	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
+	* prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
+	* full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
+	* terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
+	* 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
+	* the write can settle `true` without a callback error or a stream error while the child remains
+	* alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
+	* that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
+	* for bytes the package is about to discard.
 	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
+	* @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`
 	*/
 	send(text) {
 		const stdin = this.#child.stdin;
-		if (this.#closed || !stdin.writable) return Promise.resolve(false);
+		if (this.#closed || this.#terminating || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
 		const settled = Promise.withResolvers();
+		this.#writes.set(settled, void 0);
 		try {
-			stdin.write(`${text}\n`, (error) => {
-				settled.resolve(error === void 0 || error === null);
-			});
+			stdin.write(`${text}\n`, this.#confirmWrite.bind(this, settled));
 		} catch {
-			return Promise.resolve(false);
+			this.#settleWrite(settled, false);
+			return settled.promise;
+		}
+		if (this.#delivery > 0 && this.#writes.has(settled)) {
+			const timer = setTimeout(() => this.#settleWrite(settled, false), this.#delivery);
+			timer.unref();
+			this.#writes.set(settled, timer);
 		}
 		return settled.promise;
 	}
@@ -979,6 +1005,42 @@ var Process = class {
 		if (this.#signal === void 0 || this.#abort === void 0) return;
 		this.#signal.removeEventListener("abort", this.#abort);
 	}
+	#confirmWrite(settled, error) {
+		if (error === void 0 || error === null) {
+			this.#settleWrite(settled, true);
+			return;
+		}
+		this.#failInputCallback(error);
+	}
+	#completeInput() {
+		this.#input -= 1;
+	}
+	#settleWrite(settled, accepted) {
+		if (!this.#writes.has(settled)) return;
+		const timer = this.#writes.get(settled);
+		this.#writes.delete(settled);
+		clearTimeout(timer);
+		settled.resolve(accepted);
+	}
+	#settleWrites() {
+		for (const settled of this.#writes.keys()) this.#settleWrite(settled, false);
+	}
+	#failInputStream(cause) {
+		if (this.#child.stdin.writableEnded || this.#input > 0) {
+			this.#settleWrites();
+			return;
+		}
+		this.#failInputCallback(cause);
+	}
+	#failInputCallback(cause) {
+		if (this.#failure !== void 0 || this.#terminating) return;
+		this.#failure = cause;
+		this.#settleWrites();
+		this.#emitter.emit("error", new ProcessError("The standard-input channel failed", {
+			code: "protocol",
+			cause
+		}));
+	}
 	#capBacklog() {
 		const limit = this.#backlog * 2;
 		while (this.#pending > limit && this.#queue.length > this.#head) {
@@ -993,6 +1055,7 @@ var Process = class {
 		this.#capBacklog();
 		this.#relieve();
 		const confirmed = await stopChild(this.#child, this.#grace, PROCESS_CONFIRMATION);
+		this.#settleWrites();
 		this.#child.stdin.destroy();
 		return confirmed;
 	}
@@ -1257,9 +1320,13 @@ var Retention = class {
 * rather than on process exit, so a descendant that inherited the child's stdio holds the run open
 * after the child itself has gone. Give such a run a `timeout`. The child's `environment` merges over
 * the parent unless the command is `isolated`, then `options.environment` on top, and `options.input`
-* overrides `command.input`. Unless `strict` is `false`, a failed run rejects with a
-* {@link createExecuteError} carrying the {@link ExecuteResult}. An invalid option or command string rejects
-* before the child is spawned, because an async function cannot throw synchronously.
+* overrides `command.input`. A host fault while writing that input terminates the run by design and
+* marks its result failed; a strict rejection carries the host fault as its cause. This differs
+* from `Process` constructor input, whose package-initiated input phase stays quiet. Unless `strict`
+* is `false`, a failed run rejects with a {@link ProcessError} carrying the {@link ExecuteResult};
+* {@link createExecuteError} constructs every rejection outside the input-fault door. An invalid
+* option or command string rejects before the child is spawned, because an async function cannot
+* throw synchronously.
 *
 * @param command - The executable, arguments, and optional environment and input
 * @param options - Working directory, timeout, grace, signal, capture limit, and failure delivery
@@ -1303,6 +1370,7 @@ async function execute(command, options) {
 	const terminate = new AbortController();
 	const cleanup = new AbortController();
 	const finish = new AbortController();
+	const inputFailure = new AbortController();
 	const outChunks = [];
 	const errChunks = [];
 	const outRetention = new Retention();
@@ -1350,7 +1418,12 @@ async function execute(command, options) {
 			confirmTimer = setTimeout(() => finish.abort(), PROCESS_CONFIRMATION);
 		});
 	}, { once: true });
-	child.stdin.on("error", () => void 0);
+	inputFailure.signal.addEventListener("abort", () => {
+		if (finish.signal.aborted) return;
+		cause = inputFailure.signal.reason;
+		terminate.abort();
+	}, { once: true });
+	child.stdin.on("error", (error) => inputFailure.abort(error));
 	child.stdout.on("data", (chunk) => {
 		const retained = outRetention.retain(chunk, limit);
 		if (retained !== void 0) outChunks.push(retained);
@@ -1368,7 +1441,9 @@ async function execute(command, options) {
 		finish.abort();
 	});
 	child.once("close", () => finish.abort());
-	if (text !== void 0) child.stdin.write(text);
+	if (text !== void 0) child.stdin.write(text, (error) => {
+		if (error !== void 0 && error !== null) inputFailure.abort(error);
+	});
 	child.stdin.end();
 	if (timeout > 0) timeoutTimer = setTimeout(() => {
 		expired = true;
@@ -1388,7 +1463,19 @@ async function execute(command, options) {
 		}
 	}
 	const result = await settled.promise;
-	if (result.failed && strict) throw createExecuteError(result, cause);
+	if (result.failed && strict) {
+		if (cause !== void 0 && cause === inputFailure.signal.reason) throw new ProcessError(`Command '${result.command}' failed while writing standard input`, {
+			code: "input",
+			context: {
+				command: result.command,
+				code: result.code,
+				signal: result.signal
+			},
+			cause: inputFailure.signal.reason,
+			result
+		});
+		throw createExecuteError(result, cause);
+	}
 	return result;
 }
 //#endregion