@orkestrel/process 0.0.10 → 0.0.12

package/dist/src/server/index.js

@@ -273,15 +273,15 @@ function isFile(target) {
 *
 * @remarks
 * Windows alone needs this list: the host searches the working directory before `PATH` and applies
-* `PATHEXT`, and Node reproduces neither for a direct spawn. Within each searched directory the
-* literal name is tried first and each `PATHEXT` candidate after it, whether or not the name already
-* carries an extension — so `report.txt` resolves to a `report.txt` file where one exists and to
-* `report.txt.cmd` where none does. The lookup reads the child's effective environment, so an
-* overridden `PATH` selects the executable the child would have found. A POSIX host resolves the
-* file itself, so the candidate list there is empty. An appended extension is spelled the way
-* `PATHEXT` spells it rather than the way the directory entry does, which the case-insensitive host
-* treats as the same file. A non-Windows platform returns an empty list because `execvp` performs
-* its own lookup.
+* `PATHEXT`, and Node reproduces neither for a direct spawn. Within each searched directory,
+* {@link buildExecutableCandidates} enumerates `PATHEXT` candidates for an extensionless name. For
+* an extension-bearing name, it enumerates the literal path before `PATHEXT` candidates, so
+* `report.txt` resolves to a `report.txt` file where one exists and to `report.txt.cmd` where none
+* does. The lookup reads the child's effective environment, so an overridden `PATH` selects the
+* executable the child would have found. A POSIX host resolves the file itself, so the candidate
+* list there is empty. A `PATHEXT` candidate keeps the extension spelling from `PATHEXT`, which the
+* case-insensitive host treats as the same file. A non-Windows platform returns an empty list
+* because `execvp` performs its own lookup.
 *
 * @param file - The command executable name or path
 * @param workspace - The directory searched first
@@ -296,7 +296,8 @@ function isFile(target) {
 */
 function buildExecutableCandidates(file, workspace, environment, platform) {
 	if (platform !== "win32") return Object.freeze([]);
-	const candidates = [file, ...(readPlatformVariable(environment, "PATHEXT", platform) ?? PROCESS_PATHEXT).split(";").filter((extension) => extension.length > 0).map((extension) => `${file}${extension}`)];
+	const extensions = (readPlatformVariable(environment, "PATHEXT", platform) ?? PROCESS_PATHEXT).split(";").filter((extension) => extension.length > 0);
+	const candidates = win32.extname(file).length === 0 ? extensions.map((extension) => `${file}${extension}`) : [file, ...extensions.map((extension) => `${file}${extension}`)];
 	const directories = file.includes("/") || file.includes("\\") ? [workspace] : [workspace, ...(readPlatformVariable(environment, "PATH", platform) ?? "").split(";")];
 	const targets = [];
 	for (const directory of directories) {
@@ -306,7 +307,12 @@ 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.
+*
+* @remarks
+* A Windows lookup miss also returns `undefined`. {@link buildSpawn} preserves the command file as
+* written for native spawning.
 *
 * @param file - The command executable name or path
 * @param options - The directory searched first and the child's effective environment
@@ -392,6 +398,10 @@ function buildPlatformSpawn(command, file, environment, platform) {
 /**
 * Builds the resolved spawn form of one command for the current host.
 *
+* @remarks
+* When executable lookup returns no regular-file candidate, {@link buildSpawn} preserves the
+* command file as written for native spawning.
+*
 * @param command - The executable and its argument vector
 * @param options - The directory searched first and the child's effective environment
 * @returns The file, argument vector, and verbatim flag to spawn with
@@ -1445,7 +1455,8 @@ var Supervisor = class {
 //#endregion
 //#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
@@ -1734,7 +1745,8 @@ var Process = class {
 //#endregion
 //#region src/server/processes/ProcessManager.ts
 /**
-* Represents 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
@@ -2080,27 +2092,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}
@@ -2120,7 +2142,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