@orkestrel/process 0.0.1

package/dist/src/server/index.js

@@ -0,0 +1,704 @@
+import { Buffer } from "node:buffer";
+import { spawn, spawnSync } from "node:child_process";
+import { extname } from "node:path";
+import { PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, createDuplicateError, createRunError } from "../core/index.js";
+import { createInterface } from "node:readline";
+import { StringDecoder } from "node:string_decoder";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/server/helpers.ts
+/**
+* Signals one owned child process, or its detached process group on a POSIX host.
+*
+* @remarks
+* On a POSIX host a child spawned `detached` leads its own process group, so signalling the
+* negated pid reaches the whole tree. On Windows, or when no pid is available, the signal goes to
+* the child directly. A throw during signalling is swallowed: the process can exit and win the
+* signal race, and the child's close event remains the authoritative terminal state.
+*
+* @param child - The child process signal boundary
+* @param signal - The signal to deliver
+* @returns Nothing
+*
+* @example
+* ```ts
+* killProcess(child, 'SIGTERM')
+* ```
+*/
+function killProcess(child, signal) {
+	try {
+		if (process.platform === "win32" || child.pid === void 0) {
+			child.kill(signal);
+			return;
+		}
+		process.kill(-child.pid, signal);
+	} catch {}
+}
+/**
+* Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
+*
+* @remarks
+* Keeps the tail — the diagnostic end of a stderr stream. When the cut point lands inside a
+* multibyte sequence, the start advances past the leading continuation bytes so the retained
+* bytes always begin on a code-point boundary.
+*
+* @param buffer - The accumulated bytes
+* @param limit - The maximum retained byte count
+* @returns The trailing bytes, at most `limit` and never starting mid-sequence
+*
+* @example
+* ```ts
+* trimTail(Buffer.from('hello'), 3) // <Buffer 6c 6c 6f>
+* ```
+*/
+function trimTail(buffer, limit) {
+	if (buffer.byteLength <= limit) return buffer;
+	let start = buffer.byteLength - limit;
+	while (start < buffer.byteLength) {
+		const byte = buffer[start];
+		if (byte === void 0 || (byte & 192) !== 128) break;
+		start += 1;
+	}
+	return Buffer.from(buffer.subarray(start));
+}
+/**
+* Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
+*
+* @remarks
+* Keeps the head — the captured start of a one-shot run's output. When the cut point lands inside
+* a multibyte sequence, the end retreats to the sequence's start so the retained bytes always end
+* on a code-point boundary and decode without a replacement character.
+*
+* @param buffer - The accumulated bytes
+* @param limit - The maximum retained byte count
+* @returns The leading bytes, at most `limit` and never ending mid-sequence
+*
+* @example
+* ```ts
+* trimHead(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
+* ```
+*/
+function trimHead(buffer, limit) {
+	if (buffer.byteLength <= limit) return buffer;
+	let end = limit;
+	while (end > 0) {
+		const byte = buffer[end];
+		if (byte === void 0 || (byte & 192) !== 128) break;
+		end -= 1;
+	}
+	return Buffer.from(buffer.subarray(0, end));
+}
+/**
+* Checks whether a command file must be spawned through a shell on the current host.
+*
+* @remarks
+* Node v22+ refuses to spawn a Windows `.cmd` or `.bat` batch file directly and returns `EINVAL`,
+* and a bare command name such as `git` resolves through `PATHEXT` to a batch shim rather than an
+* executable. Both cases run through the shell. A POSIX host, and a Windows path carrying a real
+* executable extension such as `.exe`, spawn directly. When the result is `true`, treat the
+* command file and arguments as trusted: shell invocation exposes shell metacharacters.
+*
+* @param file - The command executable name or path
+* @returns True when the file must run through a shell; false when it spawns directly
+*
+* @example
+* ```ts
+* requiresShell('git') // true on Windows, false on POSIX
+* ```
+*/
+function requiresShell(file) {
+	if (process.platform !== "win32") return false;
+	const lower = file.toLowerCase();
+	return lower.endsWith(".cmd") || lower.endsWith(".bat") || extname(file) === "";
+}
+/**
+* Renders one command into its diagnostic command line.
+*
+* @param command - The executable and its argument vector
+* @returns The space-joined command line, for a {@link RunResult} and error messages
+*
+* @example
+* ```ts
+* commandLine({ file: 'git', arguments: ['status'] }) // 'git status'
+* ```
+*/
+function commandLine(command) {
+	return [command.file, ...command.arguments].join(" ");
+}
+/**
+* Merges environment overrides over the current process environment.
+*
+* @remarks
+* Later maps override earlier ones and an `undefined` value unsets a key. The base is the parent
+* process environment, so a child inherits it unless a key is overridden or unset.
+*
+* @param base - The command's own environment overrides
+* @param override - Per-invocation overrides applied last
+* @returns The merged environment for a spawn
+*
+* @example
+* ```ts
+* mergeEnvironment({ TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+* ```
+*/
+function mergeEnvironment(base, override) {
+	return {
+		...process.env,
+		...base,
+		...override
+	};
+}
+/**
+* Builds one settled {@link RunResult} from a completed one-shot run's captured bytes and exit.
+*
+* @remarks
+* `failed` is derived: a run failed when it timed out, was ended by a signal, or exited with a
+* code other than `0` — a `null` code from a spawn fault is therefore a failure. Both output
+* buffers are byte-bounded by `limit` before decoding.
+*
+* @param command - The diagnostic command line
+* @param stdout - The captured standard output bytes
+* @param stderr - The captured standard error bytes
+* @param code - The exit code, or `null` when a signal or spawn fault ended the run
+* @param signal - The terminating signal, or `null`
+* @param timedOut - If `true`, the run's own timeout elapsed; if `false`, it did not
+* @param limit - The maximum captured bytes for each stream
+* @returns The frozen run outcome
+*
+* @example
+* ```ts
+* buildRunResult('git status', Buffer.from('ok'), Buffer.alloc(0), 0, null, false, 1024)
+* ```
+*/
+function buildRunResult(command, stdout, stderr, code, signal, timedOut, limit) {
+	return Object.freeze({
+		command,
+		stdout: trimHead(stdout, limit).toString("utf8"),
+		stderr: trimHead(stderr, limit).toString("utf8"),
+		code,
+		signal,
+		failed: timedOut || signal !== null || code !== 0,
+		timedOut
+	});
+}
+/**
+* Runs one command to completion, buffering its output, and settles with the outcome.
+*
+* @remarks
+* The child is spawned through the cross-platform command resolver ({@link requiresShell}) and, on
+* a POSIX host, detached so its whole process group can be terminated. Standard output and error
+* are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` arms a
+* timer that terminates the child through `SIGTERM`, then `SIGKILL` after `grace`
+* (default {@link PROCESS_GRACE}); aborting `signal` terminates the same way. The child's
+* `environment` merges over the parent, then `options.environment` on top, and `options.input`
+* overrides `command.input`. Unless `reject` is `false`, a failed run rejects with a
+* {@link createRunError} carrying the {@link RunResult}.
+*
+* @param command - The executable, arguments, and optional environment and input
+* @param options - Working directory, timeout, grace, signal, capture limit, and reject behavior
+* @returns The settled run outcome
+* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+*
+* @example
+* ```ts
+* const result = await run({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+* ```
+*/
+async function run(command, options) {
+	const limit = options?.limit ?? PROCESS_OUTPUT;
+	const grace = options?.grace ?? PROCESS_GRACE;
+	const timeout = options?.timeout ?? 0;
+	const reject = options?.reject ?? true;
+	const input = options?.input ?? command.input;
+	const line = commandLine(command);
+	const settled = Promise.withResolvers();
+	const terminate = new AbortController();
+	const cleanup = new AbortController();
+	let stdout = Buffer.alloc(0);
+	let stderr = Buffer.alloc(0);
+	let timedOut = false;
+	let killTimer;
+	let timeoutTimer;
+	let done = false;
+	const child = spawn(command.file, [...command.arguments], {
+		cwd: options?.workspace ?? process.cwd(),
+		detached: process.platform !== "win32",
+		env: mergeEnvironment(command.environment, options?.environment),
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		shell: requiresShell(command.file),
+		windowsHide: true
+	});
+	terminate.signal.addEventListener("abort", () => {
+		killProcess(child, "SIGTERM");
+		killTimer = setTimeout(() => killProcess(child, "SIGKILL"), grace);
+	}, { once: true });
+	child.stdin.on("error", () => void 0);
+	child.stdout.on("data", (chunk) => {
+		if (Buffer.isBuffer(chunk)) stdout = trimHead(Buffer.concat([stdout, chunk]), limit);
+	});
+	child.stderr.on("data", (chunk) => {
+		if (Buffer.isBuffer(chunk)) stderr = trimHead(Buffer.concat([stderr, chunk]), limit);
+	});
+	child.once("error", () => {
+		if (done) return;
+		done = true;
+		cleanup.abort();
+		clearTimeout(killTimer);
+		clearTimeout(timeoutTimer);
+		settled.resolve(buildRunResult(line, stdout, stderr, null, null, false, limit));
+	});
+	child.once("close", (code, signal) => {
+		if (done) return;
+		done = true;
+		cleanup.abort();
+		clearTimeout(killTimer);
+		clearTimeout(timeoutTimer);
+		settled.resolve(buildRunResult(line, stdout, stderr, code, signal, timedOut, limit));
+	});
+	if (input !== void 0) child.stdin.write(input);
+	child.stdin.end();
+	if (timeout > 0) timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		terminate.abort();
+	}, timeout);
+	if (options?.signal !== void 0) {
+		const signal = options.signal;
+		signal.addEventListener("abort", () => terminate.abort(), {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (signal.aborted) terminate.abort();
+	}
+	const result = await settled.promise;
+	if (result.failed && reject) throw createRunError(result);
+	return result;
+}
+/**
+* Runs one command to completion synchronously, buffering its output, and returns the outcome.
+*
+* @remarks
+* The synchronous counterpart of {@link run}. The child is spawned through the same cross-platform
+* command resolver ({@link requiresShell}). Standard output and error are each byte-bounded by
+* `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` is enforced by the host, which
+* ends the child with `SIGKILL` when it elapses. The environment and input follow the same merge
+* as {@link run}. Unless `reject` is `false`, a failed run throws a {@link createRunError} carrying
+* the {@link RunResult}.
+*
+* @param command - The executable, arguments, and optional environment and input
+* @param options - Working directory, timeout, signal, capture limit, and reject behavior
+* @returns The run outcome
+* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+*
+* @example
+* ```ts
+* const result = runSync({ file: 'git', arguments: ['--version'] }, { reject: false })
+* ```
+*/
+function runSync(command, options) {
+	const limit = options?.limit ?? PROCESS_OUTPUT;
+	const timeout = options?.timeout ?? 0;
+	const reject = options?.reject ?? true;
+	const input = options?.input ?? command.input;
+	const line = commandLine(command);
+	const outcome = spawnSync(command.file, [...command.arguments], {
+		cwd: options?.workspace ?? process.cwd(),
+		env: mergeEnvironment(command.environment, options?.environment),
+		encoding: "buffer",
+		maxBuffer: limit,
+		shell: requiresShell(command.file),
+		windowsHide: true,
+		...input !== void 0 ? { input } : {},
+		...options?.signal !== void 0 ? { signal: options.signal } : {},
+		...timeout > 0 ? {
+			timeout,
+			killSignal: "SIGKILL"
+		} : {}
+	});
+	const error = outcome.error;
+	const timedOut = error !== void 0 && "code" in error && error.code === "ETIMEDOUT";
+	const result = buildRunResult(line, Buffer.isBuffer(outcome.stdout) ? outcome.stdout : Buffer.alloc(0), Buffer.isBuffer(outcome.stderr) ? outcome.stderr : Buffer.alloc(0), outcome.status, outcome.signal, timedOut, limit);
+	if (result.failed && reject) throw createRunError(result);
+	return result;
+}
+//#endregion
+//#region src/server/Process.ts
+/**
+* One supervised child process with eagerly framed output and bounded termination.
+*
+* @remarks
+* Standard output is drained eagerly through `readline`, so `exit` resolves and a late consumer of
+* `lines` still receives every framed line, including a final line written without a trailing
+* newline. 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 terminal `exit`,
+* alongside the `exit` promise. `stop` terminates the child through `SIGTERM`, then `SIGKILL` after
+* `grace`, and is idempotent; `destroy` stops the child and destroys the emitter last.
+*
+* @example
+* ```ts
+* import { Process } from '@orkestrel/process/server'
+*
+* const child = new Process({
+* 	command: { file: 'node', arguments: ['--version'] },
+* 	workspace: process.cwd(),
+* 	grace: 5000,
+* })
+* const exit = await child.exit
+* await child.destroy()
+* ```
+*/
+var Process = class {
+	#emitter;
+	#child;
+	#reader;
+	#grace;
+	#limit;
+	#decoder = new StringDecoder("utf8");
+	#exit = Promise.withResolvers();
+	#lines;
+	#buffer = [];
+	#waiters = [];
+	#signal;
+	#abort;
+	#tail = Buffer.alloc(0);
+	#closed = false;
+	#ended = false;
+	#stopping;
+	#ending;
+	/**
+	* Spawn one child process and begin eager stream capture.
+	*
+	* @param options - Command, workspace, termination, evidence, stdin, and observation settings
+	*/
+	constructor(options) {
+		const on = options.on;
+		const error = options.error;
+		this.#emitter = new Emitter({
+			...on === void 0 ? {} : { on },
+			...error === void 0 ? {} : { error }
+		});
+		this.#grace = options.grace;
+		this.#limit = options.evidence ?? PROCESS_EVIDENCE;
+		this.#signal = options.signal;
+		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
+		this.#child = spawn(options.command.file, [...options.command.arguments], {
+			cwd: options.workspace,
+			detached: process.platform !== "win32",
+			env: mergeEnvironment(options.command.environment),
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true
+		});
+		this.#reader = createInterface({
+			input: this.#child.stdout,
+			crlfDelay: Infinity
+		});
+		this.#reader.on("line", this.#push.bind(this));
+		this.#reader.once("close", this.#finish.bind(this));
+		this.#child.once("error", () => void 0);
+		this.#child.once("close", this.#close.bind(this));
+		this.#child.stdin.on("error", () => void 0);
+		this.#child.stderr.on("data", this.#retain.bind(this));
+		if (options.command.input !== void 0) this.#child.stdin.write(options.command.input);
+		if (options.writable !== true) this.#child.stdin.end();
+		if (this.#signal !== void 0) {
+			this.#abort = this.#terminate.bind(this);
+			this.#signal.addEventListener("abort", this.#abort, { once: true });
+			if (this.#signal.aborted) this.stop();
+		}
+	}
+	/** The typed lifecycle observation surface. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** The eagerly captured stdout lines, in arrival order, ending when the child's stdout closes. */
+	get lines() {
+		return this.#lines;
+	}
+	/** The decoded byte-bounded stderr tail. */
+	get evidence() {
+		return this.#tail.toString("utf8");
+	}
+	/** The terminal child state, observed once from the close event. */
+	get exit() {
+		return this.#exit.promise;
+	}
+	/**
+	* 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) {
+		if (this.#closed || this.#child.stdin.destroyed || this.#child.stdin.writableEnded) return false;
+		try {
+			return this.#child.stdin.write(`${text}\n`);
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Terminate the child process tree and await its observed exit.
+	*
+	* @returns A promise that resolves after bounded termination
+	*/
+	stop() {
+		if (this.#stopping !== void 0) return this.#stopping;
+		this.#stopping = this.#kill();
+		return this.#stopping;
+	}
+	/**
+	* Stop the child and destroy the observation emitter.
+	*
+	* @returns The stable barrier shared by every call
+	*/
+	destroy() {
+		if (this.#ending !== void 0) return this.#ending;
+		this.#ending = this.#teardown();
+		return this.#ending;
+	}
+	#iterate() {
+		return Object.freeze({ next: this.#next.bind(this) });
+	}
+	#next() {
+		const line = this.#buffer.shift();
+		if (line !== void 0) return Promise.resolve(Object.freeze({
+			done: false,
+			value: line
+		}));
+		if (this.#ended) return Promise.resolve(Object.freeze({
+			done: true,
+			value: void 0
+		}));
+		const waiter = Promise.withResolvers();
+		this.#waiters.push(waiter);
+		return waiter.promise;
+	}
+	#push(line) {
+		if (this.#ended) return;
+		const waiter = this.#waiters.shift();
+		if (waiter === void 0) {
+			this.#buffer.push(line);
+			return;
+		}
+		waiter.resolve(Object.freeze({
+			done: false,
+			value: line
+		}));
+	}
+	#finish() {
+		if (this.#ended) return;
+		this.#ended = true;
+		for (const waiter of this.#waiters) waiter.resolve(Object.freeze({
+			done: true,
+			value: void 0
+		}));
+		this.#waiters.length = 0;
+	}
+	#retain(chunk) {
+		if (!Buffer.isBuffer(chunk) || this.#closed) return;
+		this.#tail = trimTail(Buffer.concat([this.#tail, chunk]), this.#limit);
+		const text = this.#decoder.write(chunk);
+		if (text.length > 0) this.#emitter.emit("stderr", text);
+	}
+	#close(code, signal) {
+		if (this.#closed) return;
+		const suffix = this.#decoder.end();
+		if (suffix.length > 0) this.#emitter.emit("stderr", suffix);
+		this.#closed = true;
+		if (this.#signal !== void 0 && this.#abort !== void 0) this.#signal.removeEventListener("abort", this.#abort);
+		this.#reader.close();
+		const exit = Object.freeze({
+			code,
+			signal
+		});
+		this.#exit.resolve(exit);
+		this.#emitter.emit("exit", exit);
+	}
+	#terminate() {
+		this.stop();
+	}
+	async #kill() {
+		if (this.#closed) return;
+		killProcess(this.#child, "SIGTERM");
+		const grace = Promise.withResolvers();
+		const timer = setTimeout(grace.resolve, this.#grace);
+		await Promise.race([this.#exit.promise, grace.promise]);
+		clearTimeout(timer);
+		if (this.#closed) return;
+		killProcess(this.#child, "SIGKILL");
+		await this.#exit.promise;
+	}
+	async #teardown() {
+		await this.stop();
+		this.#emitter.destroy();
+	}
+};
+//#endregion
+//#region src/server/ProcessManager.ts
+/**
+* A keyed registry of live supervised child processes.
+*
+* @remarks
+* A child launched under an id joins the registry and emits `launch`; when it settles it removes
+* itself and emits `exit`, so `count` and `processes` reflect only live children. `launch` throws
+* a {@link createDuplicateError} when the id is already live — a spawn fault surfaces through the
+* returned child's `exit`, never from `launch`. `destroy` stops every child, then destroys the
+* registry emitter last.
+*
+* @example
+* ```ts
+* import { ProcessManager } from '@orkestrel/process/server'
+*
+* const manager = new ProcessManager()
+* const child = manager.launch('build', {
+* 	command: { file: 'node', arguments: ['build.js'] },
+* 	workspace: process.cwd(),
+* 	grace: 5000,
+* })
+* await child.exit
+* await manager.destroy()
+* ```
+*/
+var ProcessManager = class {
+	#emitter;
+	#children = /* @__PURE__ */ new Map();
+	#ending;
+	/**
+	* Construct a process registry.
+	*
+	* @param options - Initial fleet-level observation hooks and listener-error handling
+	*/
+	constructor(options) {
+		const on = options?.on;
+		const error = options?.error;
+		this.#emitter = new Emitter({
+			...on === void 0 ? {} : { on },
+			...error === void 0 ? {} : { error }
+		});
+	}
+	/** The typed fleet-level observation surface. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** The number of live children. */
+	get count() {
+		return this.#children.size;
+	}
+	/**
+	* The live child under `id`, or `undefined` when none is.
+	*
+	* @param id - The registry key
+	* @returns The child, or `undefined`
+	*/
+	process(id) {
+		return this.#children.get(id);
+	}
+	/**
+	* A snapshot of every live child.
+	*
+	* @returns The live children in launch order
+	*/
+	processes() {
+		return [...this.#children.values()];
+	}
+	/**
+	* 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, options) {
+		if (this.#children.has(id)) throw createDuplicateError(id);
+		const child = new Process(options);
+		this.#children.set(id, child);
+		child.emitter.on("exit", (exit) => this.#evict(id, child, exit));
+		this.#emitter.emit("launch", id);
+		return child;
+	}
+	stop(target) {
+		if (target === void 0) return this.#stopAll();
+		if (typeof target === "string") return this.#stopOne(target);
+		return this.#stopMany(target);
+	}
+	/**
+	* Stop every child, then destroy the registry emitter last.
+	*
+	* @returns The stable barrier shared by every call
+	*/
+	destroy() {
+		if (this.#ending !== void 0) return this.#ending;
+		this.#ending = this.#teardown();
+		return this.#ending;
+	}
+	#evict(id, child, exit) {
+		if (this.#children.get(id) !== child) return;
+		this.#children.delete(id);
+		this.#emitter.emit("exit", id, exit);
+	}
+	async #stopOne(id) {
+		const child = this.#children.get(id);
+		if (child === void 0) return false;
+		await child.stop();
+		return true;
+	}
+	async #stopMany(ids) {
+		return (await Promise.all(ids.map((id) => this.#stopOne(id)))).every((ok) => ok);
+	}
+	async #stopAll() {
+		await Promise.all([...this.#children.values()].map((child) => child.stop()));
+	}
+	async #teardown() {
+		await Promise.all([...this.#children.values()].map((child) => child.destroy()));
+		this.#emitter.destroy();
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Creates one supervised child process.
+*
+* @param options - Command, workspace, termination, evidence, stdin, and observation settings
+* @returns The launched {@link ProcessInterface}
+*
+* @example
+* ```ts
+* import { createProcess } from '@orkestrel/process/server'
+*
+* const child = createProcess({
+* 	command: { file: 'node', arguments: ['--version'] },
+* 	workspace: process.cwd(),
+* 	grace: 5000,
+* })
+* ```
+*/
+function createProcess(options) {
+	return new Process(options);
+}
+/**
+* Creates one keyed registry of supervised child processes.
+*
+* @param options - Initial fleet-level observation hooks and listener-error handling
+* @returns The {@link ProcessManagerInterface} registry
+*
+* @example
+* ```ts
+* import { createProcessManager } from '@orkestrel/process/server'
+*
+* const manager = createProcessManager()
+* ```
+*/
+function createProcessManager(options) {
+	return new ProcessManager(options);
+}
+//#endregion
+export { Process, ProcessManager, buildRunResult, commandLine, createProcess, createProcessManager, killProcess, mergeEnvironment, requiresShell, run, runSync, trimHead, trimTail };
+
+//# sourceMappingURL=index.js.map