dsh-wsl-workspace 0.2.2 → 0.3.0

package/lib/shell.js

@@ -1,382 +1,383 @@
-import { c as windowsToMntPath, i as joinUnc, n as isValidWslUsername, r as isWindowsPathShaped, s as parseWslUnc } from "./paths-DBaSmi7x.js";
-import { a as getWorkspaceUsername, n as defaultDistroSync } from "./wsl-GjkUifnx.js";
-import z from "@deepseek-ai/schemastery";
-import { ShellExecutor } from "@deepseek-ai/dsh-shell";
-import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
-//#region \0@oxc-project+runtime@0.135.0/helpers/esm/usingCtx.js
-function _usingCtx() {
-	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
-		var n = Error();
-		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
-	}, e = {}, n = [];
-	function using(r, e) {
-		if (null != e) {
-			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
-			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
-			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
-			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
-			t && (o = function o() {
-				try {
-					t.call(e);
-				} catch (r) {
-					return Promise.reject(r);
-				}
-			}), n.push({
-				v: e,
-				d: o,
-				a: r
-			});
-		} else r && n.push({
-			d: e,
-			a: r
-		});
-		return e;
-	}
-	return {
-		e,
-		u: using.bind(null, !1),
-		a: using.bind(null, !0),
-		d: function d() {
-			var o, t = this.e, s = 0;
-			function next() {
-				for (; o = n.pop();) try {
-					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
-					if (o.d) {
-						var r = o.d.call(o.v);
-						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
-					} else s |= 1;
-				} catch (r) {
-					return err(r);
-				}
-				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
-				if (t !== e) throw t;
-			}
-			function err(n) {
-				return t = t !== e ? new r(n, t) : n, next();
-			}
-			return next();
-		}
-	};
-}
-//#endregion
-//#region src/shell.ts
-/**
-* Model-friendly environment overrides (same set `dsh-bash-local` hardcodes):
-* disable colors, pagers, and interactive terminal features that would garble
-* tool output. These values cross into the Linux process through WSLENV.
-*/
-const ENV_OVERRIDES = {
-	NO_COLOR: "1",
-	TERM: "dumb",
-	PAGER: "cat",
-	GIT_PAGER: "cat"
-};
-/** Default SIGTERM→SIGKILL grace period (matches `dsh-bash-local`). */
-const DEFAULT_GRACE_MS = 3e3;
-/** Default per-stream spill cap (matches `dsh-bash-local`). */
-const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024;
-/** Project a settled collect-mode reader into the final CollectedOutput shape. */
-function finalOutput(reader) {
-	const read = reader.readFrom(0);
-	return {
-		text: read.text,
-		truncated: read.lossy,
-		...read.spillPath !== void 0 ? { spillPath: read.spillPath } : {}
-	};
-}
-function assertPositiveFinite(name, value) {
-	if (!Number.isFinite(value) || value <= 0) throw new Error(`wsl-shell: ${name} must be a positive finite number`);
-}
-/**
-* Reject a resolved configuration this executor could not run with, so a
-* stored value is refused where it is written instead of failing at the next
-* command.
-* @param config - the schema-validated configuration.
-* @throws Error naming the field that cannot be used.
-*/
-function assertServiceableWslConfig(config) {
-	const resolved = config;
-	assertPositiveFinite("timeoutMs", resolved.timeoutMs);
-	assertPositiveFinite("maxTimeoutMs", resolved.maxTimeoutMs);
-	assertPositiveFinite("maxOutputBytes", resolved.maxOutputBytes);
-	assertPositiveFinite("maxSpillBytes", resolved.maxSpillBytes);
-	assertPositiveFinite("graceMs", resolved.graceMs);
-	if (resolved.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`wsl-shell: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
-	if (resolved.distro !== void 0 && resolved.distro.trim() === "") throw new Error("wsl-shell: distro must be a non-empty distribution name");
-	if (resolved.username !== void 0 && resolved.username !== "" && !isValidWslUsername(resolved.username)) throw new Error("wsl-shell: username must match the Linux username pattern [A-Za-z_][A-Za-z0-9_.-]*");
-}
-/**
-* WSL bash executor over the LOCAL subprocess service: `wsl.exe` is a Windows
-* executable, so the Windows-side spawn, bounded output, spill files, and
-* process-group termination are the local subprocess seam's mechanics; this
-* executor supplies the Linux-world argv, cwd translation, and WSLENV.
-*/
-var WslShellExecutor = class WslShellExecutor extends ShellExecutor {
-	static inject = ["subprocess"];
-	static Config = z.object({
-		cwd: z.string(),
-		distro: z.string(),
-		username: z.string(),
-		wslPath: z.string().default("wsl.exe"),
-		loginShell: z.boolean().default(true),
-		timeoutMs: z.number().default(12e4),
-		maxTimeoutMs: z.number().default(6e5),
-		maxOutputBytes: z.number().default(64e3),
-		maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
-		graceMs: z.number().default(DEFAULT_GRACE_MS)
-	});
-	resolved;
-	/** Validated config (schemastery applied the defaults before construction). */
-	get config() {
-		return this.resolved;
-	}
-	constructor(ctx, config) {
-		super(ctx);
-		const entry = config;
-		assertServiceableWslConfig(entry);
-		this.resolved = entry;
-	}
-	/**
-	* Resolve a request into a fully-specified spec: fill `workdir` from
-	* `config.cwd`, and `timeoutMs` from `config.timeoutMs`, capped at
-	* `config.maxTimeoutMs`. The tool layer calls this before
-	* {@link run}/{@link start}, so those methods receive explicit values.
-	*/
-	resolve(request) {
-		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "wsl-shell: request.timeoutMs");
-		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
-		assertPositiveFinite("request.stdoutMaxBytes", stdoutMaxBytes);
-		return {
-			command: request.command,
-			workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
-			timeoutMs,
-			stdoutMaxBytes,
-			...request.signal ? { signal: request.signal } : {},
-			...request.stdin !== void 0 ? { stdin: request.stdin } : {},
-			...request.env !== void 0 ? { env: request.env } : {},
-			...request.dshEnv !== void 0 ? { dshEnv: request.dshEnv } : {},
-			sandboxPolicy: request.sandboxPolicy
-		};
-	}
-	/**
-	* Translate a resolved spec into the Linux execution plan. Fails loud on a
-	* workdir that names neither the WSL world (UNC or Linux path) nor a
-	* Windows drive path (reached through `/mnt/<drive>`).
-	* @param spec - the resolved execution spec.
-	* @returns the translated plan, including the complete argv.
-	*/
-	plan(spec) {
-		const workdir = spec.workdir;
-		let distro;
-		let linuxCwd;
-		let windowsCwd;
-		let username;
-		const unc = parseWslUnc(workdir);
-		if (unc !== null) {
-			distro = unc.distro;
-			linuxCwd = unc.linuxPath;
-			windowsCwd = process.env.SystemRoot ?? process.cwd();
-			username = this.resolveUser(spec, joinUnc(unc.distro, unc.linuxPath));
-		} else if (workdir.startsWith("/")) {
-			distro = this.resolveDistro(spec);
-			linuxCwd = workdir;
-			windowsCwd = process.cwd();
-			username = this.resolveUser(spec, void 0);
-		} else {
-			const mnt = windowsToMntPath(workdir);
-			if (mnt === null) throw new Error(`wsl-shell: workdir "${workdir}" is not in the WSL execution world`);
-			distro = this.resolveDistro(spec);
-			linuxCwd = mnt;
-			windowsCwd = workdir;
-			username = this.resolveUser(spec, void 0);
-		}
-		const env = this.withWslEnv(spec);
-		const argv = [
-			this.config.wslPath,
-			"-d",
-			distro,
-			...username !== void 0 && username !== "" ? ["-u", username] : [],
-			"--cd",
-			linuxCwd,
-			"-e",
-			"bash",
-			this.config.loginShell ? "-lc" : "-c",
-			spec.command
-		];
-		return {
-			distro,
-			linuxCwd,
-			windowsCwd,
-			env,
-			argv
-		};
-	}
-	/**
-	* Resolve the distribution for a workdir that carries none. The chain:
-	* the calling session's distribution (`DSH_WSL_DISTRO`, contributed by the
-	* host half from the session's UNC workspace cwd — the common case for a
-	* model passing a Linux `workdir`), then the configured `distro`, then the
-	* host's default distribution (cached registry read) as a last resort for
-	* plugin-driven calls with no session. Fails loud when every source is
-	* absent rather than guessing a distro the path does not belong to.
-	* @param spec - the resolved execution spec (its dshEnv carries the session fact).
-	* @returns the distribution name.
-	*/
-	resolveDistro(spec) {
-		const fromEnv = spec.dshEnv?.DSH_WSL_DISTRO;
-		if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
-		const configured = this.config.distro;
-		if (configured !== void 0 && configured !== "") return configured;
-		const fallback = defaultDistroSync();
-		if (fallback !== void 0) return fallback;
-		throw new Error("wsl-shell: Linux workdir carries no distribution; no session DSH_WSL_DISTRO, distro config, or default distribution is available");
-	}
-	/**
-	* Resolve the Linux user bash runs as. The chain: the calling session's
-	* workspace user (`DSH_WSL_USER`, contributed by the host half), then the
-	* workspace's stored username when the workdir is a UNC path, then the
-	* configured `username`. Absent everywhere, the distribution's default
-	* user runs. Invalid values are skipped (they were validated on write;
-	* the guard is defense in depth).
-	* @param spec - the resolved execution spec (its dshEnv carries the session fact).
-	* @param uncKey - canonical UNC key of the workdir when it is a UNC path.
-	* @returns the username, or undefined for the distro default user.
-	*/
-	resolveUser(spec, uncKey) {
-		const candidates = [
-			spec.dshEnv?.DSH_WSL_USER,
-			uncKey === void 0 ? void 0 : getWorkspaceUsername(uncKey),
-			this.config.username
-		];
-		for (const candidate of candidates) if (candidate !== void 0 && candidate !== "" && isValidWslUsername(candidate)) return candidate;
-	}
-	/**
-	* Merge the caller env layers and inject `WSLENV` so the Windows-side
-	* values reach the Linux process. Windows-path-shaped values get the `/p`
-	* translation flag (they become `/mnt/<drive>/…` inside WSL); the ambient
-	* `WSLENV` value is preserved and extended.
-	* @param spec - the resolved execution spec.
-	* @returns the explicit environment map for the spawn.
-	*/
-	withWslEnv(spec) {
-		const env = {
-			...ENV_OVERRIDES,
-			...spec.env,
-			...spec.dshEnv
-		};
-		const flags = [];
-		for (const [key, value] of Object.entries(env)) {
-			if (key.toUpperCase() === "WSLENV") continue;
-			flags.push(isWindowsPathShaped(value) ? `${key}/p` : key);
-		}
-		env.WSLENV = [process.env.WSLENV, flags.join(":")].filter((part) => part !== void 0 && part !== "").join(":");
-		return env;
-	}
-	/** Map a plan onto a fully-specified subprocess spawn. */
-	spawnSpec(plan, spec, stdoutMaxBytes, signal) {
-		const collect = (maxBytes) => ({
-			maxBytes,
-			spill: { maxBytes: this.config.maxSpillBytes }
-		});
-		return {
-			argv: plan.argv,
-			cwd: plan.windowsCwd,
-			stdio: {
-				stdin: spec.stdin !== void 0 ? { data: spec.stdin } : "ignore",
-				stdout: collect(stdoutMaxBytes),
-				stderr: collect(this.config.maxOutputBytes)
-			},
-			graceMs: this.config.graceMs,
-			signal,
-			env: plan.env
-		};
-	}
-	/** The collect-mode readers this executor requested (present by construction). */
-	static collected(handle) {
-		const { stdout, stderr } = handle.collected;
-		/* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
-		if (stdout === void 0 || stderr === void 0) throw new Error("wsl-shell: subprocess implementation dropped a requested collect stream");
-		/* v8 ignore stop */
-		return {
-			stdout,
-			stderr
-		};
-	}
-	/** Run one command in the foreground. */
-	async run(spec) {
-		try {
-			var _usingCtx$1 = _usingCtx();
-			const plan = this.plan(spec);
-			const d = _usingCtx$1.u(deadline(spec.signal, spec.timeoutMs, "WSL_BASH_TIMEOUT"));
-			const handle = this.ctx.subprocess.spawn(this.spawnSpec(plan, spec, spec.stdoutMaxBytes, d.signal));
-			const outcome = await handle.done;
-			const collected = WslShellExecutor.collected(handle);
-			const timedOut = timeoutOf(d.signal, "WSL_BASH_TIMEOUT") !== void 0;
-			const aborted = d.signal.aborted && !timedOut;
-			return {
-				...outcome,
-				timedOut,
-				aborted,
-				timeoutMs: spec.timeoutMs,
-				stdout: finalOutput(collected.stdout),
-				stderr: finalOutput(collected.stderr)
-			};
-		} catch (_) {
-			_usingCtx$1.e = _;
-		} finally {
-			_usingCtx$1.d();
-		}
-	}
-	/** Start one command in the background and return its live handle. */
-	start(spec) {
-		const plan = this.plan(spec);
-		const running = this.ctx.subprocess.spawn(this.spawnSpec(plan, spec, this.config.maxOutputBytes, spec.signal));
-		const collected = WslShellExecutor.collected(running);
-		let spawnFailureNote;
-		const consumeSpawnFailure = () => {
-			const note = spawnFailureNote ?? "";
-			spawnFailureNote = void 0;
-			return note;
-		};
-		let stdoutOffset = 0;
-		let stderrOffset = 0;
-		const proc = {
-			status: "running",
-			exitCode: null,
-			signal: null,
-			done: running.done.then((outcome) => {
-				if (proc.status === "running") proc.status = spec.signal?.aborted === true || outcome.signal !== null ? "killed" : "completed";
-				proc.exitCode = outcome.exitCode;
-				proc.signal = outcome.signal;
-			}, (error) => {
-				proc.status = "killed";
-				spawnFailureNote = `spawn failed: ${String(error)}`;
-			}),
-			readOutput: () => {
-				const out = collected.stdout.readFrom(stdoutOffset);
-				const err = collected.stderr.readFrom(stderrOffset);
-				stdoutOffset = out.nextOffset;
-				stderrOffset = err.nextOffset;
-				const errText = err.text.length > 0 ? err.text : consumeSpawnFailure();
-				const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
-				return {
-					delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
-					lossy: out.lossy || err.lossy,
-					...out.spillPath !== void 0 ? { stdoutSpillPath: out.spillPath } : {},
-					...err.spillPath !== void 0 ? { stderrSpillPath: err.spillPath } : {}
-				};
-			},
-			kill: () => {
-				if (proc.status !== "running") return false;
-				proc.status = "killed";
-				running.terminate();
-				return true;
-			}
-		};
-		return proc;
-	}
-};
-//#endregion
-export { WslShellExecutor, WslShellExecutor as default, assertServiceableWslConfig };
-
+import { c as joinUnc, d as parseWslUnc, f as windowsToMntPath, n as defaultDistroSync, o as isValidWslUsername, s as isWindowsPathShaped } from "./wsl-C5_mxGPM.js";
+import { r as getWorkspaceUsername } from "./wsl-credentials-BI4v5TNZ.js";
+import z from "@deepseek-ai/schemastery";
+import { ShellExecutor } from "@deepseek-ai/dsh-shell";
+import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+//#region \0@oxc-project+runtime@0.135.0/helpers/esm/usingCtx.js
+function _usingCtx() {
+	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
+		var n = Error();
+		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
+	}, e = {}, n = [];
+	function using(r, e) {
+		if (null != e) {
+			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
+			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
+			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
+			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
+			t && (o = function o() {
+				try {
+					t.call(e);
+				} catch (r) {
+					return Promise.reject(r);
+				}
+			}), n.push({
+				v: e,
+				d: o,
+				a: r
+			});
+		} else r && n.push({
+			d: e,
+			a: r
+		});
+		return e;
+	}
+	return {
+		e,
+		u: using.bind(null, !1),
+		a: using.bind(null, !0),
+		d: function d() {
+			var o, t = this.e, s = 0;
+			function next() {
+				for (; o = n.pop();) try {
+					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
+					if (o.d) {
+						var r = o.d.call(o.v);
+						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
+					} else s |= 1;
+				} catch (r) {
+					return err(r);
+				}
+				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
+				if (t !== e) throw t;
+			}
+			function err(n) {
+				return t = t !== e ? new r(n, t) : n, next();
+			}
+			return next();
+		}
+	};
+}
+//#endregion
+//#region src/shell.ts
+/**
+* Model-friendly environment overrides (same set `dsh-bash-local` hardcodes):
+* disable colors, pagers, and interactive terminal features that would garble
+* tool output. These values cross into the Linux process through WSLENV.
+*/
+const ENV_OVERRIDES = {
+	NO_COLOR: "1",
+	TERM: "dumb",
+	PAGER: "cat",
+	GIT_PAGER: "cat"
+};
+/** Default SIGTERM→SIGKILL grace period (matches `dsh-bash-local`). */
+const DEFAULT_GRACE_MS = 3e3;
+/** Default per-stream spill cap (matches `dsh-bash-local`). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024;
+/** Project a settled collect-mode reader into the final CollectedOutput shape. */
+function finalOutput(reader) {
+	const read = reader.readFrom(0);
+	return {
+		text: read.text,
+		truncated: read.lossy,
+		...read.spillPath !== void 0 ? { spillPath: read.spillPath } : {}
+	};
+}
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`wsl-shell: ${name} must be a positive finite number`);
+}
+/**
+* Reject a resolved configuration this executor could not run with, so a
+* stored value is refused where it is written instead of failing at the next
+* command.
+* @param config - the schema-validated configuration.
+* @throws Error naming the field that cannot be used.
+*/
+function assertServiceableWslConfig(config) {
+	const resolved = config;
+	assertPositiveFinite("timeoutMs", resolved.timeoutMs);
+	assertPositiveFinite("maxTimeoutMs", resolved.maxTimeoutMs);
+	assertPositiveFinite("maxOutputBytes", resolved.maxOutputBytes);
+	assertPositiveFinite("maxSpillBytes", resolved.maxSpillBytes);
+	assertPositiveFinite("graceMs", resolved.graceMs);
+	if (resolved.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`wsl-shell: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (resolved.distro !== void 0 && resolved.distro.trim() === "") throw new Error("wsl-shell: distro must be a non-empty distribution name");
+	if (resolved.username !== void 0 && resolved.username !== "" && !isValidWslUsername(resolved.username)) throw new Error("wsl-shell: username must match the Linux username pattern [A-Za-z_][A-Za-z0-9_.-]*");
+}
+/**
+* WSL bash executor over the LOCAL subprocess service: `wsl.exe` is a Windows
+* executable, so the Windows-side spawn, bounded output, spill files, and
+* process-group termination are the local subprocess seam's mechanics; this
+* executor supplies the Linux-world argv, cwd translation, and WSLENV.
+*/
+var WslShellExecutor = class WslShellExecutor extends ShellExecutor {
+	static inject = ["subprocess"];
+	static Config = z.object({
+		cwd: z.string(),
+		distro: z.string(),
+		username: z.string(),
+		wslPath: z.string().default("wsl.exe"),
+		loginShell: z.boolean().default(true),
+		timeoutMs: z.number().default(12e4),
+		maxTimeoutMs: z.number().default(6e5),
+		maxOutputBytes: z.number().default(64e3),
+		maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
+		graceMs: z.number().default(DEFAULT_GRACE_MS)
+	});
+	resolved;
+	/** Validated config (schemastery applied the defaults before construction). */
+	get config() {
+		return this.resolved;
+	}
+	constructor(ctx, config) {
+		super(ctx);
+		const entry = config;
+		assertServiceableWslConfig(entry);
+		this.resolved = entry;
+	}
+	/**
+	* Resolve a request into a fully-specified spec: fill `workdir` from
+	* `config.cwd`, and `timeoutMs` from `config.timeoutMs`, capped at
+	* `config.maxTimeoutMs`. The tool layer calls this before
+	* {@link run}/{@link start}, so those methods receive explicit values.
+	*/
+	resolve(request) {
+		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "wsl-shell: request.timeoutMs");
+		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
+		assertPositiveFinite("request.stdoutMaxBytes", stdoutMaxBytes);
+		return {
+			command: request.command,
+			workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
+			timeoutMs,
+			stdoutMaxBytes,
+			...request.signal ? { signal: request.signal } : {},
+			...request.stdin !== void 0 ? { stdin: request.stdin } : {},
+			...request.env !== void 0 ? { env: request.env } : {},
+			...request.dshEnv !== void 0 ? { dshEnv: request.dshEnv } : {},
+			sandboxPolicy: request.sandboxPolicy
+		};
+	}
+	/**
+	* Translate a resolved spec into the Linux execution plan. Fails loud on a
+	* workdir that names neither the WSL world (UNC or Linux path) nor a
+	* Windows drive path (reached through `/mnt/<drive>`).
+	* @param spec - the resolved execution spec.
+	* @returns the translated plan, including the complete argv.
+	*/
+	plan(spec) {
+		const workdir = spec.workdir;
+		let distro;
+		let linuxCwd;
+		let windowsCwd;
+		let username;
+		const unc = parseWslUnc(workdir);
+		if (unc !== null) {
+			distro = unc.distro;
+			linuxCwd = unc.linuxPath;
+			windowsCwd = process.env.SystemRoot ?? process.cwd();
+			username = this.resolveUser(spec, joinUnc(unc.distro, unc.linuxPath));
+		} else if (workdir.startsWith("/")) {
+			distro = this.resolveDistro(spec);
+			linuxCwd = workdir;
+			windowsCwd = process.cwd();
+			username = this.resolveUser(spec, void 0);
+		} else {
+			const mnt = windowsToMntPath(workdir);
+			if (mnt === null) throw new Error(`wsl-shell: workdir "${workdir}" is not in the WSL execution world`);
+			distro = this.resolveDistro(spec);
+			linuxCwd = mnt;
+			windowsCwd = workdir;
+			username = this.resolveUser(spec, void 0);
+		}
+		const env = this.withWslEnv(spec);
+		const command = this.config.loginShell ? `cd '${linuxCwd.replace(/'/g, `'\\''`)}' && ${spec.command}` : spec.command;
+		const argv = [
+			this.config.wslPath,
+			"-d",
+			distro,
+			...username !== void 0 && username !== "" ? ["-u", username] : [],
+			"--cd",
+			linuxCwd,
+			"-e",
+			"bash",
+			this.config.loginShell ? "-lc" : "-c",
+			command
+		];
+		return {
+			distro,
+			linuxCwd,
+			windowsCwd,
+			env,
+			argv
+		};
+	}
+	/**
+	* Resolve the distribution for a workdir that carries none. The chain:
+	* the calling session's distribution (`DSH_WSL_DISTRO`, contributed by the
+	* host half from the session's UNC workspace cwd — the common case for a
+	* model passing a Linux `workdir`), then the configured `distro`, then the
+	* host's default distribution (cached registry read) as a last resort for
+	* plugin-driven calls with no session. Fails loud when every source is
+	* absent rather than guessing a distro the path does not belong to.
+	* @param spec - the resolved execution spec (its dshEnv carries the session fact).
+	* @returns the distribution name.
+	*/
+	resolveDistro(spec) {
+		const fromEnv = spec.dshEnv?.DSH_WSL_DISTRO;
+		if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
+		const configured = this.config.distro;
+		if (configured !== void 0 && configured !== "") return configured;
+		const fallback = defaultDistroSync();
+		if (fallback !== void 0) return fallback;
+		throw new Error("wsl-shell: Linux workdir carries no distribution; no session DSH_WSL_DISTRO, distro config, or default distribution is available");
+	}
+	/**
+	* Resolve the Linux user bash runs as. The chain: the calling session's
+	* workspace user (`DSH_WSL_USER`, contributed by the host half), then the
+	* workspace's stored username when the workdir is a UNC path, then the
+	* configured `username`. Absent everywhere, the distribution's default
+	* user runs. Invalid values are skipped (they were validated on write;
+	* the guard is defense in depth).
+	* @param spec - the resolved execution spec (its dshEnv carries the session fact).
+	* @param uncKey - canonical UNC key of the workdir when it is a UNC path.
+	* @returns the username, or undefined for the distro default user.
+	*/
+	resolveUser(spec, uncKey) {
+		const candidates = [
+			spec.dshEnv?.DSH_WSL_USER,
+			uncKey === void 0 ? void 0 : getWorkspaceUsername(uncKey),
+			this.config.username
+		];
+		for (const candidate of candidates) if (candidate !== void 0 && candidate !== "" && isValidWslUsername(candidate)) return candidate;
+	}
+	/**
+	* Merge the caller env layers and inject `WSLENV` so the Windows-side
+	* values reach the Linux process. Windows-path-shaped values get the `/p`
+	* translation flag (they become `/mnt/<drive>/…` inside WSL); the ambient
+	* `WSLENV` value is preserved and extended.
+	* @param spec - the resolved execution spec.
+	* @returns the explicit environment map for the spawn.
+	*/
+	withWslEnv(spec) {
+		const env = {
+			...ENV_OVERRIDES,
+			...spec.env,
+			...spec.dshEnv
+		};
+		const flags = [];
+		for (const [key, value] of Object.entries(env)) {
+			if (key.toUpperCase() === "WSLENV") continue;
+			flags.push(isWindowsPathShaped(value) ? `${key}/p` : key);
+		}
+		env.WSLENV = [process.env.WSLENV, flags.join(":")].filter((part) => part !== void 0 && part !== "").join(":");
+		return env;
+	}
+	/** Map a plan onto a fully-specified subprocess spawn. */
+	spawnSpec(plan, spec, stdoutMaxBytes, signal) {
+		const collect = (maxBytes) => ({
+			maxBytes,
+			spill: { maxBytes: this.config.maxSpillBytes }
+		});
+		return {
+			argv: plan.argv,
+			cwd: plan.windowsCwd,
+			stdio: {
+				stdin: spec.stdin !== void 0 ? { data: spec.stdin } : "ignore",
+				stdout: collect(stdoutMaxBytes),
+				stderr: collect(this.config.maxOutputBytes)
+			},
+			graceMs: this.config.graceMs,
+			signal,
+			env: plan.env
+		};
+	}
+	/** The collect-mode readers this executor requested (present by construction). */
+	static collected(handle) {
+		const { stdout, stderr } = handle.collected;
+		/* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
+		if (stdout === void 0 || stderr === void 0) throw new Error("wsl-shell: subprocess implementation dropped a requested collect stream");
+		/* v8 ignore stop */
+		return {
+			stdout,
+			stderr
+		};
+	}
+	/** Run one command in the foreground. */
+	async run(spec) {
+		try {
+			var _usingCtx$1 = _usingCtx();
+			const plan = this.plan(spec);
+			const d = _usingCtx$1.u(deadline(spec.signal, spec.timeoutMs, "WSL_BASH_TIMEOUT"));
+			const handle = this.ctx.subprocess.spawn(this.spawnSpec(plan, spec, spec.stdoutMaxBytes, d.signal));
+			const outcome = await handle.done;
+			const collected = WslShellExecutor.collected(handle);
+			const timedOut = timeoutOf(d.signal, "WSL_BASH_TIMEOUT") !== void 0;
+			const aborted = d.signal.aborted && !timedOut;
+			return {
+				...outcome,
+				timedOut,
+				aborted,
+				timeoutMs: spec.timeoutMs,
+				stdout: finalOutput(collected.stdout),
+				stderr: finalOutput(collected.stderr)
+			};
+		} catch (_) {
+			_usingCtx$1.e = _;
+		} finally {
+			_usingCtx$1.d();
+		}
+	}
+	/** Start one command in the background and return its live handle. */
+	start(spec) {
+		const plan = this.plan(spec);
+		const running = this.ctx.subprocess.spawn(this.spawnSpec(plan, spec, this.config.maxOutputBytes, spec.signal));
+		const collected = WslShellExecutor.collected(running);
+		let spawnFailureNote;
+		const consumeSpawnFailure = () => {
+			const note = spawnFailureNote ?? "";
+			spawnFailureNote = void 0;
+			return note;
+		};
+		let stdoutOffset = 0;
+		let stderrOffset = 0;
+		const proc = {
+			status: "running",
+			exitCode: null,
+			signal: null,
+			done: running.done.then((outcome) => {
+				if (proc.status === "running") proc.status = spec.signal?.aborted === true || outcome.signal !== null ? "killed" : "completed";
+				proc.exitCode = outcome.exitCode;
+				proc.signal = outcome.signal;
+			}, (error) => {
+				proc.status = "killed";
+				spawnFailureNote = `spawn failed: ${String(error)}`;
+			}),
+			readOutput: () => {
+				const out = collected.stdout.readFrom(stdoutOffset);
+				const err = collected.stderr.readFrom(stderrOffset);
+				stdoutOffset = out.nextOffset;
+				stderrOffset = err.nextOffset;
+				const errText = err.text.length > 0 ? err.text : consumeSpawnFailure();
+				const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
+				return {
+					delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
+					lossy: out.lossy || err.lossy,
+					...out.spillPath !== void 0 ? { stdoutSpillPath: out.spillPath } : {},
+					...err.spillPath !== void 0 ? { stderrSpillPath: err.spillPath } : {}
+				};
+			},
+			kill: () => {
+				if (proc.status !== "running") return false;
+				proc.status = "killed";
+				running.terminate();
+				return true;
+			}
+		};
+		return proc;
+	}
+};
+//#endregion
+export { WslShellExecutor, WslShellExecutor as default, assertServiceableWslConfig };
+
 //# sourceMappingURL=shell.js.map