@deepseek-ai/dsh-subprocess-local 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/runner.js

@@ -0,0 +1,425 @@
+import { S as loadLinuxExecve, a as resolveWindowsExecutable, b as serializeRunnerError, f as consumeLinuxLaunchRequest, g as linuxLaunchFilesFromLocator, h as isWindowsTerminateRequest, i as parseRunnerTargetArgv, r as consumeRunnerSelection, t as SUBPROCESS_RUNNER_ENV, v as parseWindowsStartRequest, x as writeLinuxStartupError } from "./runner-launch-COYGu0Dl.js";
+import { closeSync } from "node:fs";
+import { Win32Error, closeHandleChecked, isJobEmpty, loadWin32ProcessBindings, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from "@deepseek-ai/dsh-win32-process";
+//#region lib/types/spawn-runner.js
+/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */
+const defaultInternals = {
+	/* v8 ignore next -- source/built/packaged subprocess smoke executes this only in a replaceable child process. */
+	execve: (file, argv, env) => loadLinuxExecve()(file, argv, env),
+	loadWin32ProcessBindings,
+	spawnCurrentTokenJobProcess,
+	closeFileDescriptor: closeSync,
+	resolveWindowsExecutable,
+	pollProcessExit,
+	isJobEmpty,
+	terminateJob,
+	closeHandleChecked
+};
+const NODE_SPAWN_DETAIL_CODES = new Set(["EACCES", "ENOENT"]);
+const WINDOWS_SPAWN_ERROR_CODES = new Map([
+	[2, "ENOENT"],
+	[3, "ENOENT"],
+	[267, "ENOENT"],
+	[5, "EPERM"],
+	[193, "EFTYPE"],
+	[740, "EACCES"]
+]);
+function nodeSpawnError(syscall, code, path) {
+	return {
+		name: "Error",
+		message: `${syscall} ${code}`,
+		code,
+		syscall,
+		...path === void 0 ? {} : { path }
+	};
+}
+function asSpawnError(error, program) {
+	const serialized = serializeRunnerError(error);
+	if (!(error instanceof Win32Error)) return serialized.code === void 0 ? serialized : nodeSpawnError(`spawn ${program}`, serialized.code, program);
+	const code = WINDOWS_SPAWN_ERROR_CODES.get(error.win32Code) ?? "UNKNOWN";
+	if (NODE_SPAWN_DETAIL_CODES.has(code)) return nodeSpawnError(`spawn ${program}`, code, program);
+	return nodeSpawnError("spawn", code);
+}
+function windowsPathNotFoundError(program) {
+	return nodeSpawnError(`spawn ${program}`, "ENOENT", program);
+}
+function windowsStartCancelledError() {
+	return {
+		name: "Error",
+		message: "subprocess target start was cancelled"
+	};
+}
+function linuxPathNotFoundError(program) {
+	return Object.assign(/* @__PURE__ */ new Error(`spawn ${program} ENOENT`), {
+		code: "ENOENT",
+		errno: -2,
+		syscall: `spawn ${program}`,
+		path: program,
+		spawnargs: []
+	});
+}
+function execLinuxFile(file, argv, env, internals) {
+	try {
+		return internals.execve(file, argv, env);
+	} catch (error) {
+		if (error.code !== "ENOEXEC") throw error;
+		return internals.execve("/bin/sh", [
+			"/bin/sh",
+			file,
+			...argv.slice(1)
+		], env);
+	}
+}
+function execLinuxTarget(request, argv, internals) {
+	const program = argv[0];
+	if (program.includes("/")) return execLinuxFile(program, argv, request.env, internals);
+	const path = request.env.PATH ?? "/usr/bin:/bin";
+	let permissionFailure;
+	for (const directory of path.split(":")) {
+		const root = directory.startsWith("/") ? directory : `${request.cwd}${request.cwd.endsWith("/") ? "" : "/"}${directory}`;
+		const candidate = `${root}${root.endsWith("/") ? "" : "/"}${program}`;
+		try {
+			return execLinuxFile(candidate, argv, request.env, internals);
+		} catch (error) {
+			const code = error.code;
+			if (code === "EACCES") {
+				permissionFailure ??= error;
+				continue;
+			}
+			if (code === "ENOENT" || code === "ENOTDIR") continue;
+			throw error;
+		}
+	}
+	throw permissionFailure ?? linuxPathNotFoundError(program);
+}
+function runLinux(locator, argv, host, internals) {
+	const files = linuxLaunchFilesFromLocator(locator);
+	let request;
+	try {
+		request = consumeLinuxLaunchRequest(files.requestPath);
+	} catch (error) {
+		writeLinuxStartupError(files, {
+			type: "error",
+			error: serializeRunnerError(error)
+		});
+		host.exitCode = 127;
+		return;
+	}
+	try {
+		host.chdir(request.cwd);
+		execLinuxTarget({
+			...request,
+			cwd: host.cwd()
+		}, argv, internals);
+	} catch (error) {
+		writeLinuxStartupError(files, {
+			type: "error",
+			error: asSpawnError(error, argv[0])
+		});
+		host.exitCode = 127;
+	}
+}
+function sendMessage(host, result) {
+	return new Promise((resolve, reject) => {
+		if (!host.connected || host.send === void 0) {
+			reject(/* @__PURE__ */ new Error("subprocess runner IPC is not connected"));
+			return;
+		}
+		try {
+			host.send(result, (error) => {
+				if (error === null) resolve();
+				else reject(error);
+			});
+		} catch (error) {
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
+var WindowsJobRunner = class {
+	argv;
+	host;
+	internals;
+	api;
+	processHandle;
+	jobHandle;
+	pollTimer;
+	startSeen = false;
+	terminateRequested = false;
+	resultStarted = false;
+	resultDelivered = false;
+	finished = false;
+	completion = Promise.withResolvers();
+	constructor(argv, host, internals) {
+		this.argv = argv;
+		this.host = host;
+		this.internals = internals;
+	}
+	run() {
+		if (!this.host.connected || this.host.send === void 0) {
+			this.finish(127);
+			return this.completion.promise;
+		}
+		this.host.on("message", this.onMessage);
+		this.host.once("disconnect", this.onDisconnect);
+		return this.completion.promise;
+	}
+	onMessage = (value) => {
+		if (this.finished) return;
+		if (isWindowsTerminateRequest(value)) {
+			this.requestTermination();
+			return;
+		}
+		if (this.startSeen) {
+			this.runnerFailure(/* @__PURE__ */ new Error("subprocess runner received more than one Windows start request"));
+			return;
+		}
+		let request;
+		try {
+			request = parseWindowsStartRequest(value);
+		} catch (error) {
+			this.runnerFailure(error);
+			return;
+		}
+		this.startSeen = true;
+		this.start(request);
+	};
+	onDisconnect = () => {
+		if (this.finished) return;
+		this.releaseOwnedJob();
+		this.finish(127, false);
+	};
+	async start(request) {
+		if (this.terminateRequested) {
+			await this.publishTerminalResult({
+				type: "error",
+				error: windowsStartCancelledError()
+			}, 0);
+			return;
+		}
+		await new Promise((resolveImmediate) => {
+			setImmediate(resolveImmediate);
+		});
+		if (this.finished) return;
+		if (this.terminateRequested) {
+			await this.publishTerminalResult({
+				type: "error",
+				error: windowsStartCancelledError()
+			}, 0);
+			return;
+		}
+		try {
+			const [command, ...args] = this.argv;
+			const applicationName = this.internals.resolveWindowsExecutable(command, request.cwd, request.env, void 0, { ...this.host.env });
+			if (applicationName === void 0) {
+				await this.publishTerminalResult({
+					type: "error",
+					error: windowsPathNotFoundError(command)
+				}, 0);
+				return;
+			}
+			this.api = this.internals.loadWin32ProcessBindings();
+			const spawned = this.internals.spawnCurrentTokenJobProcess(this.api, {
+				command,
+				applicationName,
+				args,
+				cwd: request.cwd,
+				env: request.env,
+				stdio: {
+					stdin: 4,
+					stdout: 5,
+					stderr: 6
+				}
+			});
+			this.processHandle = spawned.process;
+			this.jobHandle = spawned.job;
+			for (const fileDescriptor of [
+				4,
+				5,
+				6
+			]) this.internals.closeFileDescriptor(fileDescriptor);
+			this.pollTimer = setInterval(() => {
+				this.poll();
+			}, 10);
+		} catch (error) {
+			if (this.jobHandle === void 0 && error instanceof Win32Error && error.api === "CreateProcessW") {
+				await this.publishTerminalResult({
+					type: "error",
+					error: asSpawnError(error, this.argv[0])
+				}, 0);
+				return;
+			}
+			await this.runnerFailure(error);
+		}
+	}
+	requestTermination() {
+		if (this.terminateRequested) return;
+		this.terminateRequested = true;
+		try {
+			this.terminateOwnedJob();
+		} catch (error) {
+			this.runnerFailure(error);
+		}
+	}
+	terminateOwnedJob() {
+		const job = this.jobHandle;
+		if (job === void 0) return;
+		/* v8 ignore next -- a Job handle is assigned only after the bindings are loaded;
+		* the guard above is the only reachable empty-owner state. */
+		if (this.api === void 0) return;
+		this.internals.terminateJob(this.api, job, 1);
+	}
+	poll() {
+		if (this.finished) return;
+		/* v8 ignore next -- poll is installed only after start() stores the bindings; retained as a defensive invariant guard. */
+		if (this.api === void 0) return;
+		try {
+			if (this.processHandle !== void 0) {
+				const exitCode = this.internals.pollProcessExit(this.api, this.processHandle);
+				if (exitCode !== void 0) {
+					this.internals.closeHandleChecked(this.api, this.processHandle, "ordinary direct process");
+					this.processHandle = void 0;
+					this.publishTerminalResult({
+						type: "target-exit",
+						exitCode
+					});
+				}
+			}
+			if (this.jobHandle !== void 0 && this.internals.isJobEmpty(this.api, this.jobHandle)) {
+				this.internals.closeHandleChecked(this.api, this.jobHandle, "ordinary process Job");
+				this.jobHandle = void 0;
+				if (this.resultDelivered) this.finish(0);
+			}
+		} catch (error) {
+			this.runnerFailure(error);
+		}
+	}
+	async publishTerminalResult(result, exitCode) {
+		/* v8 ignore next -- each state transition has a single result call site; the guard contains only re-entrant internal defects. */
+		if (this.finished || this.resultStarted) return;
+		this.resultStarted = true;
+		try {
+			await sendMessage(this.host, result);
+			this.resultDelivered = true;
+		} catch {
+			this.releaseOwnedJob();
+			this.finish(127, false);
+			return;
+		}
+		if (exitCode !== void 0) {
+			this.finish(exitCode);
+			return;
+		}
+		if (this.jobHandle === void 0) this.finish(0);
+	}
+	async runnerFailure(error) {
+		/* v8 ignore next -- callers stop/detach on finish; this guard contains only an already-queued internal callback. */
+		if (this.finished) return;
+		if (!this.resultStarted) {
+			this.resultStarted = true;
+			try {
+				await sendMessage(this.host, {
+					type: "error",
+					error: serializeRunnerError(error)
+				});
+				this.resultDelivered = true;
+			} catch {}
+		}
+		this.releaseOwnedJob();
+		this.finish(127);
+	}
+	releaseOwnedJob() {
+		if (this.pollTimer !== void 0) clearInterval(this.pollTimer);
+		this.pollTimer = void 0;
+		const api = this.api;
+		if (api === void 0) return;
+		if (this.jobHandle !== void 0) {
+			try {
+				this.internals.terminateJob(api, this.jobHandle, 1);
+			} catch {}
+			try {
+				this.internals.closeHandleChecked(api, this.jobHandle, "ordinary process Job cleanup");
+			} catch {}
+			this.jobHandle = void 0;
+		}
+		if (this.processHandle !== void 0) {
+			try {
+				this.internals.closeHandleChecked(api, this.processHandle, "ordinary direct process cleanup");
+			} catch {}
+			this.processHandle = void 0;
+		}
+	}
+	finish(exitCode, disconnect = true) {
+		if (this.finished) return;
+		this.finished = true;
+		if (this.pollTimer !== void 0) clearInterval(this.pollTimer);
+		this.pollTimer = void 0;
+		this.host.off("message", this.onMessage);
+		this.host.off("disconnect", this.onDisconnect);
+		this.host.exitCode = exitCode;
+		if (disconnect && this.host.connected) this.host.disconnect();
+		this.completion.resolve();
+	}
+};
+/**
+* Execute the selected Linux bootstrap or Windows Job runner.
+* @param selection - Windows sentinel or Linux launch-request locator.
+* @param argv - private runner arguments beginning with the target delimiter.
+* @param host - process transport and lifecycle host.
+* @param internals - native and filesystem operations used by the runner.
+*/
+async function runSpawnRunner(selection, argv, host = process, internals = defaultInternals) {
+	Reflect.deleteProperty(host.env, SUBPROCESS_RUNNER_ENV);
+	const targetArgv = parseRunnerTargetArgv(argv);
+	if (selection === "windows") {
+		await new WindowsJobRunner(targetArgv, host, internals).run();
+		return;
+	}
+	runLinux(selection, targetArgv, host, internals);
+}
+/**
+* Best-effort reporting for failures before the selected runner established its owner.
+* @param selection - Windows sentinel, Linux launch-request locator, or no selection.
+* @param error - failure raised before normal runner settlement.
+* @param host - process transport and lifecycle host.
+*/
+async function reportSpawnRunnerFailure(selection, error, host = process) {
+	if (selection === "windows") {
+		try {
+			await sendMessage(host, {
+				type: "error",
+				error: serializeRunnerError(error)
+			});
+		} catch {}
+		host.exitCode = 127;
+		if (host.connected) host.disconnect();
+		return;
+	}
+	if (selection !== void 0) try {
+		writeLinuxStartupError(linuxLaunchFilesFromLocator(selection), {
+			type: "error",
+			error: serializeRunnerError(error)
+		});
+	} catch {}
+	host.exitCode = 127;
+}
+//#endregion
+//#region lib/types/bin.js
+/** Thin executable/importable entry for the provider-private runner core. */
+/**
+* Run a selector already removed by a packaging bootstrap.
+* @param selection - private runner selector or Linux launch-request locator.
+*/
+async function runSelectedSubprocessRunner(selection) {
+	try {
+		await runSpawnRunner(selection, process.argv.slice(2));
+	} catch (error) {
+		await reportSpawnRunnerFailure(selection, error);
+	}
+}
+if (import.meta.main) {
+	const selection = consumeRunnerSelection();
+	if (selection === void 0) process.exitCode = 127;
+	else runSelectedSubprocessRunner(selection);
+}
+//#endregion
+export { runSelectedSubprocessRunner };

package/lib/types/bin.d.ts

@@ -0,0 +1,7 @@
+/** Thin executable/importable entry for the provider-private runner core. */
+/**
+ * Run a selector already removed by a packaging bootstrap.
+ * @param selection - private runner selector or Linux launch-request locator.
+ */
+export declare function runSelectedSubprocessRunner(selection: string): Promise<void>;
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/index.d.ts

@@ -1,10 +1,10 @@
 /**
- * Local Service Provider for the subprocess capability seam. Each spawn is a detached
- * process tree with the spec's per-stream stdio dispositions. Normal disposal
- * terminates and joins live trees; Node's synchronous exit phase force-stops
- * any trees the service still owns. It has no config: every disposition and
- * limit arrives on the spec, so the deployment-varying choices stay with the
- * caller's config (the bash executor's, the LSP host's, …).
+ * Local Service Provider for the subprocess capability seam. Each spawn owns a
+ * platform-selected managed range with the spec's per-stream stdio dispositions.
+ * Normal disposal terminates and joins live ranges; Node's synchronous exit
+ * phase force-stops any ranges the service still owns. It has no config: every
+ * disposition and limit arrives on the spec, so deployment-varying choices
+ * stay with the caller's config (the bash executor's, the LSP host's, …).
  * @module @deepseek-ai/dsh-subprocess-local
  */
 import { Context } from '@deepseek-ai/cordis';
@@ -13,19 +13,23 @@ import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, S
 import type { SpawnInternals } from './spawn.ts';
 import type { ProcessInspector } from './process-inspector.ts';
 /**
- * Local subprocess service: detached process trees, Node-shaped stdio
+ * Local subprocess service: platform-selected managed ranges, Node-shaped stdio
  * dispositions (raw pipes, inherit, bounded tail-keep collection with spill
- * files), credential-scrubbed environment, and tree-scoped signalling with
- * SIGTERM→grace→SIGKILL escalation, plus synchronous final termination during
- * JavaScript-observable host exit.
+ * files), credential-scrubbed environment, and provider-owned range signalling.
+ * POSIX paths stage TERM before KILL; Windows paths terminate immediately.
+ * JavaScript-observable host exit also performs synchronous final termination.
  */
 export declare class LocalSubprocessRuntime extends SubprocessRuntime {
     /** Live handles retained for normal disposal and synchronous host-exit finalization. */
     private live;
     /** Live terminals retained through normal quiescence or host-exit finalization. */
     private terminals;
-    /** Test hook: spill and platform knobs forwarded to spawnSubprocess. */
+    /** Test hook: process, spill, and platform operations forwarded to spawnSubprocess. */
     internals: SpawnInternals;
+    /** Provider-lifetime latch suppressing repeated weaker-containment warnings. */
+    private fallbackWarningIssued;
+    /** Positive-only cache for the expensive Linux bootstrap and scope probe. */
+    private linuxDeepProbePassed;
     /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
     terminalInspector: ProcessInspector | undefined;
     constructor(ctx: Context);
@@ -34,6 +38,8 @@ export declare class LocalSubprocessRuntime extends SubprocessRuntime {
     resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
     private executableCandidates;
     spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    private selectContainmentMode;
+    private warnFallback;
     spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
 }
 export default LocalSubprocessRuntime;

package/lib/types/linux-execve.d.ts

@@ -0,0 +1,9 @@
+/** Lazy libc execve and descriptor bindings used by the one-shot Linux bootstrap. */
+/** Replace the current process image while preserving the supplied argv and environment. */
+export type LinuxExecve = (file: string, argv: string[], env: Record<string, string>) => never;
+/**
+ * Load libc's execve and fcntl symbols on first use and retain the native bindings.
+ * @returns a process-replacing execve operation that throws Node-style errors on failure.
+ */
+export declare function loadLinuxExecve(): LinuxExecve;
+//# sourceMappingURL=linux-execve.d.ts.map

package/lib/types/linux-scope.d.ts

@@ -0,0 +1,81 @@
+/** Linux user-systemd scope launch and managed-range ownership. */
+import { spawn, spawnSync } from 'node:child_process';
+import type { SubprocessOutcome, SubprocessSpawnSpec, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import { loadLinuxExecve } from './linux-execve.ts';
+import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts';
+import type { RunnerInvocation } from './runner-launch.ts';
+/** Test seams for systemd command execution. */
+export interface LinuxScopeInternals {
+    spawn?: typeof spawn;
+    spawnSync?: typeof spawnSync;
+    systemctlQuery?: (command: string, args: readonly string[]) => Promise<SystemctlResult>;
+    systemdRun?: string;
+    systemctl?: string;
+    runnerInvocation?: RunnerInvocation;
+    resolveRunnerInvocation?: () => RunnerInvocation;
+    runnerAvailable?: (invocation: RunnerInvocation) => boolean;
+    loadLinuxExecve?: typeof loadLinuxExecve;
+    sleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+interface SystemctlResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+/**
+ * Confirm this exact runner entry and libc execve binding without a probe mode.
+ * @param internals - optional runner and libc-binding seams used by tests.
+ * @returns whether the bootstrap can enter the final target.
+ */
+export declare function probeLinuxBootstrap(internals?: LinuxScopeInternals): boolean;
+/**
+ * Confirm current literal-argv transient-scope support before selecting native launch.
+ * @param internals - optional systemd command seams used by tests.
+ * @returns whether the current user manager supports the required scope invocation.
+ */
+export declare function probeLinuxScope(internals?: LinuxScopeInternals): boolean;
+/**
+ * Confirm that the current user manager remains reachable after a positive deep probe.
+ * @param internals - optional systemctl seam used by tests.
+ * @returns whether one lightweight manager query succeeds.
+ */
+export declare function probeLinuxManager(internals?: LinuxScopeInternals): boolean;
+/**
+ * Re-check every Linux native prerequisite for one eligible spawn.
+ * @param internals - optional native capability seams used by tests.
+ * @returns whether the Linux native containment path is currently available.
+ */
+export declare function probeLinuxNative(internals?: LinuxScopeInternals): boolean;
+interface DirectRange {
+    running(): boolean;
+    signal(signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/** Linux PTY invocation and owner for the exact one-shot scope/bootstrap. */
+export interface LinuxTerminalScopeLaunch {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    bindOwner: (direct: DirectRange) => BoundProcessOwner;
+    resolveOutcome: (outcome: SubprocessOutcome) => SubprocessOutcome;
+    cleanup: () => void;
+}
+/**
+ * Prepare one Linux PTY scope using the same launch request and bootstrap core.
+ * @param spec - terminal target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner and systemd seams used by tests.
+ * @returns invocation facts and ownership callbacks for node-pty.
+ */
+export declare function prepareLinuxTerminalScope(spec: SubprocessTerminalSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): LinuxTerminalScopeLaunch;
+/**
+ * Launch one ordinary target inside a transient user scope.
+ * @param spec - ordinary target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner and systemd seams used by tests.
+ * @returns direct streams, result, and managed-scope owner.
+ */
+export declare function launchLinuxScope(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): ManagedProcessLaunch;
+export {};
+//# sourceMappingURL=linux-scope.d.ts.map

package/lib/types/managed-owner.d.ts

@@ -0,0 +1,30 @@
+/** Minimal managed-range ownership bound to one ordinary subprocess handle. */
+import type { Readable, Writable } from 'node:stream';
+import type { SubprocessOutcome } from '@deepseek-ai/dsh-subprocess';
+/** Platform owner used by termination and whole-range settlement. */
+export interface BoundProcessOwner {
+    /** Signal the managed range; `cancellationReason` is used only before Windows target commit. */
+    signal(signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void;
+    /** Wait for the same managed range to become empty; reject when it cannot be observed. */
+    waitForExit(): Promise<void>;
+    /** Synchronously force final termination during JavaScript-observable host exit. */
+    terminateForHostExit(): void;
+    /** Release provider-private protocol artifacts after outcome and range settlement. */
+    cleanup?(): void;
+}
+/** Platform launch facts consumed by the common stdio and result lifecycle. */
+export interface ManagedProcessLaunch {
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    direct: Promise<SubprocessOutcome>;
+    owner: BoundProcessOwner;
+}
+/**
+ * Apply an optional abort bound to one shared wait promise.
+ * @param pending - managed-range wait shared by all callers.
+ * @param signal - optional caller cancellation signal.
+ * @returns whether the managed-range wait completed before cancellation.
+ */
+export declare function waitWithAbort(pending: Promise<void>, signal?: AbortSignal): Promise<boolean>;
+//# sourceMappingURL=managed-owner.d.ts.map

package/lib/types/runner-launch.d.ts

@@ -0,0 +1,66 @@
+/** Parent-side invocation and bootstrap state for the private native runner. */
+import type { StdioOptions } from 'node:child_process';
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** The one private environment variable consumed before target state is restored. */
+export declare const SUBPROCESS_RUNNER_ENV: "DSH_SUBPROCESS_RUNNER";
+/** Sentinel used by the packaged bootstrap for the Windows IPC runner. */
+export declare const WINDOWS_RUNNER_SELECTION: "windows";
+/** Non-empty command tuple used to launch the private runner entry. */
+export type RunnerInvocation = [string, ...string[]];
+/**
+ * Resolve the source, built, or packaged entry that calls the same runner core.
+ * @returns executable and arguments for the active runtime form.
+ */
+export declare function spawnRunnerInvocation(): RunnerInvocation;
+/**
+ * Check the concrete runner executable and entry paths without executing a probe mode.
+ * @param invocation - resolved executable and runner-entry arguments.
+ * @returns whether every concrete executable or entry path is accessible.
+ */
+export declare function runnerInvocationAvailable(invocation?: RunnerInvocation): boolean;
+/**
+ * Build the bootstrap-safe environment; target overrides arrive through request/IPC.
+ * @param selection - private runner selector or Linux launch-request locator.
+ * @param invocation - resolved runner invocation whose source form needs the workspace paths map.
+ * @returns environment for the runner before target state is restored.
+ */
+export declare function runnerEnvironment(selection: string, invocation?: RunnerInvocation): NodeJS.ProcessEnv;
+/**
+ * Read and delete the private selector before importing or restoring target state.
+ * @param env - mutable environment containing the private selector.
+ * @returns the consumed selector, or undefined when no runner was requested.
+ */
+export declare function consumeRunnerSelection(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Require the private argv delimiter and at least one target argv entry.
+ * @param argv - private runner arguments.
+ * @returns copied target argv after the private delimiter.
+ */
+export declare function parseRunnerTargetArgv(argv: readonly string[]): string[];
+/**
+ * Build direct Linux target stdio, or isolated Windows runner stdio with IPC
+ * on fd 3 and target carriers on fd 4 through fd 6.
+ * @param spec - ordinary subprocess request whose stdio modes are preserved.
+ * @param ipc - whether to isolate the runner and add its private Node IPC descriptor.
+ * @param stdinCarrier - runner fd 4 carrier; Windows ignore passes an opened null-device fd.
+ * @returns child-process stdio options for the runner.
+ */
+export declare function runnerStdio(spec: SubprocessSpawnSpec, ipc: boolean, stdinCarrier?: 'pipe' | number): StdioOptions;
+/**
+ * Resolve the executable path with libuv/Node Windows spawn search order while
+ * preserving the caller's original command-line argv entry separately.
+ * @param command - original target argv[0].
+ * @param cwd - final target working directory used for relative search roots.
+ * @param env - final target environment containing the child PATH.
+ * @param exists - injectable non-directory candidate probe used by tests.
+ * @param currentEnv - runner environment supplying PATH fallback and cwd-search policy.
+ * @returns a resolved application name suitable for `CreateProcessW`, or undefined when no candidate exists.
+ */
+export declare function resolveWindowsExecutable(command: string, cwd: string, env: Readonly<Record<string, string>>, exists?: (candidate: string) => boolean, currentEnv?: Readonly<Record<string, string | undefined>>): string | undefined;
+/**
+ * Materialize and synchronously validate the final target environment.
+ * @param spec - final target argv, cwd, and environment overrides.
+ * @returns complete target environment after Node-equivalent validation.
+ */
+export declare function targetEnvironment(spec: Pick<SubprocessSpawnSpec, 'argv' | 'cwd' | 'env'>): Record<string, string>;
+//# sourceMappingURL=runner-launch.d.ts.map