@orkestrel/process 0.0.11 → 0.0.13

package/dist/src/server/index.d.cts

@@ -25,15 +25,15 @@ import type { SpawnInput } from '@orkestrel/process';
  *
  * @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
@@ -107,6 +107,10 @@ export declare function buildPlatformSpawn(command: ProcessCommand, file: string
 /**
  * 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
@@ -755,6 +759,10 @@ export declare function readVariable(environment: Readonly<Record<string, string
  * 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
  * @returns The resolved absolute path, or `undefined` when no candidate is a regular file

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

@@ -25,15 +25,15 @@ import type { SpawnInput } from '@orkestrel/process';
  *
  * @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
@@ -107,6 +107,10 @@ export declare function buildPlatformSpawn(command: ProcessCommand, file: string
 /**
  * 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
@@ -755,6 +759,10 @@ export declare function readVariable(environment: Readonly<Record<string, string
  * 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
  * @returns The resolved absolute path, or `undefined` when no candidate is a regular file

package/dist/src/server/index.js

@@ -3,7 +3,7 @@ import { spawn, spawnSync } from "node:child_process";
 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 { boundsOf, holds, isError, isNonEmptyString, isNonNegativeInteger, isString } from "@orkestrel/contract";
 import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, 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 { Emitter } from "@orkestrel/emitter";
@@ -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) {
@@ -309,6 +310,10 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
 * 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
 * @returns The resolved absolute path, or `undefined` when no candidate is a regular file
@@ -393,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
@@ -570,7 +579,7 @@ function killProcess(child, signal) {
 		}
 		process.kill(-child.pid, signal);
 	} catch (error) {
-		if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+		if (isError(error) && "code" in error && error.code === "ESRCH") {
 			holds(() => child.kill(signal));
 			return;
 		}
@@ -1845,7 +1854,7 @@ var ProcessManager = class {
 	}
 	stop(target) {
 		if (target === void 0) return this.#stopAll();
-		if (typeof target === "string") return this.#stopOne(target);
+		if (isString(target)) return this.#stopOne(target);
 		return this.#stopMany(target);
 	}
 	/**