import * as Context from "effect/Context";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import { ChildProcess, ChildProcessSpawner } from "effect/process";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { buildRemoteNodeEnvScript } from "@t3tools/ssh/tunnel";
import { satisfiesSemverRange } from "@t3tools/shared/semver";
import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
import * as DesktopManagedPolicy from "../app/DesktopManagedPolicy.ts";
import { parseWslDistroList, type WslDistro } from "./wslPathParsing.ts";
const PROCESS_TERMINATE_GRACE = Duration.seconds(1);
const LIST_TIMEOUT = Duration.seconds(8);
// Booting a stopped distro needs more time than converting paths in a running one.
const PRE_WARM_TIMEOUT = Duration.seconds(30);
const WSLPATH_TIMEOUT = Duration.seconds(10);
const PROBE_TIMEOUT = Duration.seconds(10);
const TOOLCHAIN_TIMEOUT = Duration.seconds(10);
const BUILD_TIMEOUT = Duration.minutes(5);
const RUNTIME_INSTALL_TIMEOUT = Duration.minutes(2);
const RUNTIME_PRUNE_TIMEOUT = Duration.seconds(30);
const RUNTIME_INVALIDATE_TIMEOUT = Duration.seconds(15);
const USER_HOME_TIMEOUT = Duration.seconds(5);
const TOOLCHAIN_TRANSPORT_RETRY_LIMIT = 12;
const BUILD_TRANSPORT_RETRY_LIMIT = 2;
export interface EnsureWslNodePtyOptions {
readonly allowBuild?: boolean;
readonly nodeEngineRange?: string | null;
}
export interface WslRuntimeArchive {
readonly windowsPath: string;
readonly runtimeId: string;
readonly sha256: string;
}
export type PrepareWslRuntimeResult =
| {
readonly ok: true;
readonly linuxAppRoot: string;
}
| {
readonly ok: false;
readonly reason: string;
};
export type EnsureWslNodePtyResult =
| {
readonly ok: true;
readonly nodePath: string;
readonly resolvedPath: string;
}
| {
readonly ok: false;
readonly reason: string;
readonly fatal: boolean;
readonly retryLimit?: number;
};
export type ProbeWslRuntimeResult =
| {
readonly ok: true;
readonly resolvedPath: string;
}
| {
readonly ok: false;
readonly reason: string;
};
export class DesktopWslDistroListError extends Schema.TaggedError<DesktopWslDistroListError>()(
"DesktopWslDistroListError",
{ reason: Schema.String },
) {
override get message(): string {
return this.reason;
}
}
const isDesktopWslDistroListError = Schema.is(DesktopWslDistroListError);
export class DesktopWslEnvironment extends Context.Service<
DesktopWslEnvironment,
{
readonly isAvailable: Effect.Effect<boolean>;
// UX-only best effort; health checks need probeDistros to distinguish failures from an empty installation.
readonly listDistros: Effect.Effect<readonly WslDistro[]>;
readonly probeDistros: Effect.Effect<readonly WslDistro[], DesktopWslDistroListError>;
readonly preWarm: (distro: string | null) => Effect.Effect<void>;
readonly windowsToWslPath: (
distro: string | null,
windowsPath: string,
) => Effect.Effect<Option.Option<string>>;
readonly getUserHome: (distro: string | null) => Effect.Effect<Option.Option<string>>;
// Use the distro IP to avoid unreliable wslhost localhost forwarding.
readonly getDistroIp: (distro: string | null) => Effect.Effect<Option.Option<string>>;
readonly prepareRuntime: (
distro: string | null,
archive: WslRuntimeArchive,
) => Effect.Effect<PrepareWslRuntimeResult>;
readonly pruneRuntimes: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
readonly invalidateRuntime: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
readonly probeRuntime: (
distro: string | null,
linuxAppRoot: string,
) => Effect.Effect<ProbeWslRuntimeResult>;
readonly ensureNodePty: (
distro: string | null,
linuxAppRoot: string,
options?: EnsureWslNodePtyOptions,
) => Effect.Effect<EnsureWslNodePtyResult>;
}
>()("@t3tools/desktop/wsl/DesktopWslEnvironment") {}
const buildDistroArgs = (distro: string | null): ReadonlyArray<string> =>
distro ? ["-d", distro] : [];
const concatChunks = (arrays: ReadonlyArray<Uint8Array>): Uint8Array => {
let totalLength = 0;
for (const arr of arrays) totalLength += arr.byteLength;
const out = new Uint8Array(totalLength);
let offset = 0;
for (const arr of arrays) {
out.set(arr, offset);
offset += arr.byteLength;
}
return out;
};
const decodeUtf8 = (bytes: Uint8Array): string => new TextDecoder("utf-8").decode(bytes);
interface ShellResult {
readonly exitCode: number;
readonly stdout: string;
readonly stderr: string;
readonly transportFailure: "timeout" | "spawn" | "process" | null;
}
const TIMEOUT_RESULT: ShellResult = {
exitCode: 124,
stdout: "",
stderr: "\n[timeout]",
transportFailure: "timeout",
};
const formatWslShellTransportFailureReason = (
failure: ShellResult["transportFailure"],
subject = "Node.js",
): string | null => {
switch (failure) {
case "timeout":
return `WSL backend preflight timed out while probing for ${subject}. WSL may be slow to start; retry, or check that the distro is healthy.`;
case "spawn":
return `WSL backend preflight could not start wsl.exe to probe for ${subject}. Check that WSL is installed and the distro is accessible.`;
case "process":
return `WSL backend preflight lost communication with wsl.exe while probing for ${subject}. Retry, or check that the distro is healthy.`;
case null:
return null;
}
};
const buildWslNodeEnvPreamble = (
nodeEngineRange?: string | null,
): string => `${buildRemoteNodeEnvScript({ nodeEngineRange: nodeEngineRange ?? null })}
ensure_remote_node_path || true
`;
// wsl.exe re-escaping mangles quotes inside bash -lc scripts.
const runWslShell = (
distro: string | null,
bashScript: string,
timeout: Duration.Duration,
options: {
readonly nodeEngineRange?: string | null;
readonly resolveNode?: boolean;
} = {},
): Effect.Effect<ShellResult, never, ChildProcessSpawner.ChildProcessSpawner> => {
const spawner = ChildProcessSpawner.ChildProcessSpawner;
const resolveNode = options.resolveNode !== false;
const command = ChildProcess.make(
"wsl.exe",
resolveNode
? [...buildDistroArgs(distro), "--", "bash", "-l", "-s"]
: [...buildDistroArgs(distro), "--exec", "sh", "-s"],
{
stdin: Stream.encodeText(
Stream.make(
resolveNode
? `${buildWslNodeEnvPreamble(options.nodeEngineRange)}${bashScript}`
: bashScript,
),
),
stdout: "pipe",
stderr: "pipe",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
},
);
return Effect.scoped(
Effect.gen(function* () {
const spawnerService = yield* spawner;
const spawnResult = yield* spawnerService.spawn(command).pipe(
Effect.match({
onFailure: (error) => ({ _tag: "Failure", error }) as const,
onSuccess: (handle) => ({ _tag: "Success", handle }) as const,
}),
);
if (spawnResult._tag === "Failure") {
return {
exitCode: 127,
stdout: "",
stderr: `\n${spawnResult.error.message}`,
transportFailure: "spawn",
} satisfies ShellResult;
}
const handle = spawnResult.handle;
// Drain both pipes concurrently to prevent node-gyp output from blocking the child.
const [stdoutBytes, stderrBytes, exitCode] = yield* Effect.all(
[Stream.runCollect(handle.stdout), Stream.runCollect(handle.stderr), handle.exitCode],
{ concurrency: "unbounded" },
);
return {
exitCode: exitCode as unknown as number,
stdout: decodeUtf8(concatChunks(stdoutBytes)),
stderr: decodeUtf8(concatChunks(stderrBytes)),
transportFailure: null,
} satisfies ShellResult;
}),
).pipe(
Effect.timeoutOption(timeout),
Effect.map(Option.getOrElse((): ShellResult => TIMEOUT_RESULT)),
Effect.catch((error) =>
Effect.succeed<ShellResult>({
exitCode: 127,
stdout: "",
stderr: `\n${error.message}`,
transportFailure: "process",
}),
),
);
};
const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
const WSL_RUNTIME_READY_MARKER = ".t3code-wsl-runtime-ready";
const WSL_RUNTIME_SELECTED_MARKER = ".t3code-wsl-runtime-selected";
const WSL_RUNTIME_SELECTION_GRACE_MINUTES = 5;
const sanitizeWslRuntimeId = (value: string): string => value.replace(/[^A-Za-z0-9._-]/g, "_");
export const buildWslRuntimeInstallScript = (
linuxArchivePath: string,
runtimeId: string,
archiveSha256: string,
): string => {
const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
return [
"set -eu",
'runtime_parent="$HOME/.t3/wsl-runtime"',
`runtime_root="$runtime_parent/${safeRuntimeId}"`,
`ready_marker="$runtime_root/${WSL_RUNTIME_READY_MARKER}"`,
"runtime_entry_runs() {",
' [ -x "$1/t3" ] && "$1/t3" --version >/dev/null',
"}",
// Hash the entry to detect a swapped or partially written executable, even if it still runs.
"runtime_server_entry_digest() {",
` sha256sum "$1/t3" 2>/dev/null | cut -d ' ' -f 1`,
"}",
"runtime_is_ready() {",
' [ -f "$ready_marker" ] &&',
' runtime_entry_runs "$runtime_root" 2>/dev/null &&',
` recorded_entry_digest=$(tr -d '[:space:]' < "$ready_marker" 2>/dev/null) &&`,
' [ -n "$recorded_entry_digest" ] &&',
' [ "$recorded_entry_digest" = "$(runtime_server_entry_digest "$runtime_root")" ]',
"}",
'mkdir -p "$runtime_parent"',
`runtime_lock="$runtime_parent/.${safeRuntimeId}.install.lock"`,
"trap 'exit 1' HUP INT TERM",
'exec 9> "$runtime_lock"',
"flock -x 9",
"if runtime_is_ready; then",
` touch "$runtime_root/${WSL_RUNTIME_SELECTED_MARKER}"`,
` printf 'runtimeRoot:%s\\n' "$runtime_root"`,
" exit 0",
"fi",
`archive_sha=$(sha256sum ${shellQuote(linuxArchivePath)} | cut -d ' ' -f 1)`,
`if [ "$archive_sha" != ${shellQuote(archiveSha256)} ]; then`,
` printf 'WSL runtime archive does not match its recorded SHA-256 (expected %s, got %s)\\n' ${shellQuote(archiveSha256)} "$archive_sha" >&2`,
" exit 1",
"fi",
// Deletion can remove a live backend's lazy imports; check cmdline before rename preserves its old path.
"runtime_in_use() {",
// Without /proc, assume the runtime may still be in use.
" [ -d /proc/1 ] || return 0",
' grep -qF -- "$1/" /proc/[0-9]*/cmdline 2>/dev/null',
"}",
'if [ -e "$runtime_root" ]; then',
' if runtime_in_use "$runtime_root"; then',
" runtime_root_in_use=1",
" else",
" runtime_root_in_use=0",
" fi",
` runtime_stale=$(mktemp -d "$runtime_parent/.${safeRuntimeId}.stale.XXXXXX")`,
' rmdir "$runtime_stale"',
' if mv -T "$runtime_root" "$runtime_stale" 2>/dev/null; then',
' if [ "$runtime_root_in_use" = 1 ]; then',
// Renaming keeps the directory's old mtime, so restart the cleanup clock.
' touch "$runtime_stale"',
" else",
' rm -rf "$runtime_stale"',
" fi",
" fi",
"fi",
`runtime_tmp=$(mktemp -d "$runtime_parent/.${safeRuntimeId}.tmp.XXXXXX")`,
'cleanup_runtime_install() { rm -rf "$runtime_tmp"; }',
"trap cleanup_runtime_install EXIT",
`tar -xzf ${shellQuote(linuxArchivePath)} -C "$runtime_tmp" --strip-components=1`,
'if ! runtime_entry_runs "$runtime_tmp"; then',
" printf 'WSL runtime archive does not contain a working t3 executable\\n' >&2",
" exit 1",
"fi",
'installed_entry_digest=$(runtime_server_entry_digest "$runtime_tmp")',
'if [ -z "$installed_entry_digest" ]; then',
" printf 'Could not hash the WSL runtime server entry\\n' >&2",
" exit 1",
"fi",
`printf '%s\\n' "$installed_entry_digest" > "$runtime_tmp/${WSL_RUNTIME_READY_MARKER}"`,
'if mv -T "$runtime_tmp" "$runtime_root" 2>/dev/null; then',
" :",
"elif runtime_is_ready; then",
' rm -rf "$runtime_tmp"',
"else",
` printf 'Could not promote WSL runtime cache at %s\\n' "$runtime_root" >&2`,
" exit 1",
"fi",
`touch "$runtime_root/${WSL_RUNTIME_SELECTED_MARKER}"`,
`printf 'runtimeRoot:%s\\n' "$runtime_root"`,
].join("\n");
};
// Two hours exceeds cold-install time while bounding orphan retention.
const ORPHANED_RUNTIME_SCRATCH_MAX_AGE_MINUTES = 120;
export const buildWslRuntimePruneScript = (runtimeId: string): string => {
const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
return [
"set -eu",
'runtime_parent="$HOME/.t3/wsl-runtime"',
`current_runtime="$runtime_parent/${safeRuntimeId}"`,
'[ -d "$runtime_parent" ] || exit 0',
// Serialize pruning so backends cannot select and delete different previous caches.
'prune_lock="$runtime_parent/.prune.lock"',
'exec 8> "$prune_lock"',
"flock -x 8",
// Without /proc, retention cannot distinguish caches used by live backends.
"[ -d /proc/1 ] || exit 0",
"runtime_in_use() {",
' grep -qF -- "$1/" /proc/[0-9]*/cmdline 2>/dev/null',
"}",
'previous_runtime=""',
'for candidate in "$runtime_parent"/sha256-*; do',
' [ -d "$candidate" ] || continue',
' [ "$candidate" != "$current_runtime" ] || continue',
` [ -f "$candidate/${WSL_RUNTIME_READY_MARKER}" ] || continue`,
' if [ -z "$previous_runtime" ] || [ "$candidate" -nt "$previous_runtime" ]; then',
' previous_runtime="$candidate"',
" fi",
"done",
'for candidate in "$runtime_parent"/sha256-*; do',
' [ -d "$candidate" ] || continue',
' [ "$candidate" != "$current_runtime" ] || continue',
' [ "$candidate" != "$previous_runtime" ] || continue',
' ! runtime_in_use "$candidate" || continue',
" candidate_name=${candidate##*/}",
' candidate_lock="$runtime_parent/.${candidate_name}.install.lock"',
' exec 9> "$candidate_lock"',
" flock -n 9 || continue",
` selected_marker="$candidate/${WSL_RUNTIME_SELECTED_MARKER}"`,
` if [ -f "$selected_marker" ] && find "$selected_marker" -maxdepth 0 -mmin -${String(WSL_RUNTIME_SELECTION_GRACE_MINUTES)} -print -quit | grep -q .; then`,
" flock -u 9",
" continue",
" fi",
' rm -rf -- "$candidate"',
" flock -u 9",
"done",
'for scratch in "$runtime_parent"/.*.tmp.* "$runtime_parent"/.*.stale.*; do',
' [ -d "$scratch" ] || continue',
` find "$scratch" -maxdepth 0 -mmin +${String(ORPHANED_RUNTIME_SCRATCH_MAX_AGE_MINUTES)} -print -quit | grep -q . || continue`,
' rm -rf -- "$scratch"',
"done",
].join("\n");
};
// Invalidate trees that pass install checks but fail launch probes, or each launch reuses the broken cache.
export const buildWslRuntimeInvalidateScript = (runtimeId: string): string => {
const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
return [
"set -eu",
`rm -f "$HOME/.t3/wsl-runtime/${safeRuntimeId}/${WSL_RUNTIME_READY_MARKER}"`,
].join("\n");
};
export const parseWslRuntimeRoot = (stdout: string): string | null => {
const prefix = "runtimeRoot:";
const line = stdout.split("\n").find((candidate) => candidate.startsWith(prefix));
if (line === undefined) return null;
const runtimeRoot = line.slice(prefix.length).replace(/\r$/, "");
return runtimeRoot.startsWith("/") ? runtimeRoot : null;
};
const NODE_PTY_BINARY_MISSING_EXIT_CODE = 4;
const formatNodePtyProbeFailureReason = (exitCode: number): string | null =>
exitCode === NODE_PTY_BINARY_MISSING_EXIT_CODE
? "WSL support is missing from this T3 Code build: the packaged Linux node-pty binary was not included. Install a build that includes WSL support."
: null;
// Capture login-shell PATH because the server launches provider CLIs by name.
const RESOLVED_PATH_LINE = `printf 'resolvedPath:%s\\n' "$PATH"`;
const NODE_PTY_PROBE_SCRIPT = (
linuxServerDir: string,
) => `printf 'nodePath:%s\\n' "$(command -v node 2>/dev/null)"
printf 'nodeVersion:%s\\n' "$(node -p 'process.versions.node' 2>/dev/null)"
${RESOLVED_PATH_LINE}
cd ${shellQuote(linuxServerDir)} && node <<'NODE' >/dev/null 2>&1
// The WSL Node can't read inside app.asar, so confirm what the server needs is
// unpacked on the real filesystem before reporting the backend healthy. Exit 3
// marks this distinct from a node-pty binary problem so the caller can report
// it accurately instead of letting the server crash on ERR_MODULE_NOT_FOUND at
// launch (which, in wsl-only mode, would just fail to launch with no fallback).
//
// The sentinel must be a package the CLI bundle leaves external. The bundle
// inlines its JS dependencies, so only the native packages exist on disk.
// Resolving node-pty is what actually validates the unpacked tree.
try { require.resolve("node-pty/package.json"); } catch (_e) { process.exit(3); }
const fs = require("node:fs");
const path = require("node:path");
const pkgDir = path.dirname(require.resolve("node-pty/package.json"));
// node-pty 1.x is N-API based, so a single Linux pty.node is ABI-stable across
// Node versions, so require() succeeding IS the real compatibility test. Look in
// the same places node-pty's own loader does.
const candidates = [
path.join(pkgDir, "build", "Release", "pty.node"),
path.join(pkgDir, "prebuilds", "linux-" + process.arch, "pty.node"),
];
if (!candidates.some((candidate) => fs.existsSync(candidate))) process.exit(${NODE_PTY_BINARY_MISSING_EXIT_CODE});
require("node-pty");
NODE`;
// Resolve version-managed Node for providers without making runtime readiness depend on it.
export const buildWslRuntimeProbeScript = (linuxAppRoot: string) =>
[
`bash -lc ${shellQuote(`${buildWslNodeEnvPreamble()}${RESOLVED_PATH_LINE}`)} 2>/dev/null || ${RESOLVED_PATH_LINE}`,
`${shellQuote(`${linuxAppRoot}/t3`)} --version >/dev/null 2>&1`,
].join("\n");
const TOOLCHAIN_CHECK_SCRIPT = [
"for tool in node make g++ python3; do",
' command -v "$tool" >/dev/null 2>&1 || echo "missing:$tool"',
"done",
"if command -v node >/dev/null 2>&1; then",
` ver="$(node -p 'process.versions.node' 2>/dev/null)"`,
' if [ -n "$ver" ]; then printf "nodeVersion:%s\\n" "$ver"; fi',
"fi",
].join("\n");
const NODE_PTY_BUILD_SCRIPT = (linuxServerDir: string) =>
[
"set -e",
`cd ${shellQuote(linuxServerDir)}`,
`pkg_dir=$(node -p "require('node:path').dirname(require.resolve('node-pty/package.json'))")`,
`cd "$pkg_dir"`,
"npx --yes node-gyp rebuild",
`node -e 'require("node-pty")'`,
].join("\n");
export interface ToolchainReport {
readonly missingTools: ReadonlyArray<string>;
readonly nodeVersion: string | null;
}
const parseToolchainReport = (stdout: string): ToolchainReport => {
const lines = stdout
.split("\n")
.map((line) => line.trim())
.filter((line) => line.length > 0);
const missingTools = lines
.filter((line) => line.startsWith("missing:"))
.map((line) => line.slice("missing:".length));
const nodeVersionLine = lines.find((line) => line.startsWith("nodeVersion:"));
const nodeVersion = nodeVersionLine
? nodeVersionLine.slice("nodeVersion:".length).trim() || null
: null;
return { missingTools, nodeVersion };
};
const parseNodePath = (stdout: string): string | null => {
const path = stdout
.split("\n")
.map((line) => line.trim())
.filter((line) => line.startsWith("nodePath:"))
.map((line) => line.slice("nodePath:".length).trim())
.find((value) => value.length > 0);
return path ?? null;
};
const parseNodeVersion = (stdout: string): string | null => {
const version = stdout
.split("\n")
.map((line) => line.trim())
.filter((line) => line.startsWith("nodeVersion:"))
.map((line) => line.slice("nodeVersion:".length).trim())
.find((value) => value.length > 0);
return version ?? null;
};
// Strip only Windows CR; spaces and apostrophes must survive as one env argument.
export const parseResolvedPath = (stdout: string): string | null => {
const prefix = "resolvedPath:";
const line = stdout.split("\n").find((candidate) => candidate.startsWith(prefix));
if (line === undefined) return null;
const resolvedPath = line.slice(prefix.length).replace(/\r$/, "");
return resolvedPath.length > 0 ? resolvedPath : null;
};
const formatMissingToolsReason = (
report: ToolchainReport,
requiredRange: string | null,
): string | null => {
const nodeMissing = report.missingTools.includes("node");
const nodeOutOfRange =
!nodeMissing &&
requiredRange !== null &&
report.nodeVersion !== null &&
!satisfiesSemverRange(report.nodeVersion, requiredRange);
const buildToolsMissing = report.missingTools.filter((tool) => tool !== "node");
if (!nodeMissing && !nodeOutOfRange && buildToolsMissing.length === 0) {
return null;
}
const issues: string[] = [];
const remediations: string[] = [];
if (nodeMissing) {
issues.push("node");
remediations.push(
`Node.js${requiredRange ? ` satisfying \`${requiredRange}\`` : " 18+"} (e.g. via nvm)`,
);
} else if (nodeOutOfRange) {
issues.push(`node ${report.nodeVersion} (requires ${requiredRange})`);
remediations.push(
`a newer Node.js satisfying \`${requiredRange}\` (e.g. \`nvm install 24 && nvm alias default 24\`)`,
);
}
if (buildToolsMissing.length > 0) {
issues.push(...buildToolsMissing);
remediations.push(
"the build toolchain (e.g. `sudo apt install -y build-essential python3` on Ubuntu/Debian)",
);
}
return `WSL distro is missing required tools: ${issues.join(", ")}. Install ${remediations.join(" and ")}, then retry.`;
};
const probeWslRuntimeImpl = Effect.fn("DesktopWslEnvironment.probeWslRuntimeImpl")(function* (
distro: string | null,
linuxAppRoot: string,
): Effect.fn.Return<ProbeWslRuntimeResult, never, ChildProcessSpawner.ChildProcessSpawner> {
const probe = yield* runWslShell(
distro,
buildWslRuntimeProbeScript(linuxAppRoot),
PROBE_TIMEOUT,
{
resolveNode: false,
},
);
const transportFailureReason = formatWslShellTransportFailureReason(
probe.transportFailure,
"the staged runtime",
);
if (transportFailureReason !== null) {
return { ok: false, reason: transportFailureReason } as const;
}
if (probe.exitCode !== 0) {
const trimmedTail = probe.stderr.trim().slice(-500);
return {
ok: false,
reason: `${linuxAppRoot}/t3 --version failed (exit ${probe.exitCode})${trimmedTail ? `: ${trimmedTail}` : ""}`,
} as const;
}
const resolvedPath = parseResolvedPath(probe.stdout);
if (resolvedPath === null) {
return {
ok: false,
reason: "WSL login-shell PATH could not be resolved during backend preflight.",
} as const;
}
return { ok: true, resolvedPath } as const;
});
const ensureNodePtyImpl = Effect.fn("DesktopWslEnvironment.ensureNodePtyImpl")(function* (
distro: string | null,
linuxRepoRoot: string,
options: EnsureWslNodePtyOptions = {},
): Effect.fn.Return<EnsureWslNodePtyResult, never, ChildProcessSpawner.ChildProcessSpawner> {
// node-pty lives in the apps/server workspace's node_modules; resolve from
// there rather than the monorepo root, where Bun's hoist layout omits it.
const linuxServerDir = `${linuxRepoRoot}/apps/server`;
const probe = yield* runWslShell(
distro,
NODE_PTY_PROBE_SCRIPT(linuxServerDir),
PROBE_TIMEOUT,
options,
);
const nodePath = parseNodePath(probe.stdout);
const resolvedPath = parseResolvedPath(probe.stdout);
const transportFailureReason = formatWslShellTransportFailureReason(probe.transportFailure);
if (transportFailureReason !== null) {
return {
ok: false,
reason: transportFailureReason,
fatal: false,
} as const;
}
if (nodePath === null) {
const toolchainCheck = yield* runWslShell(
distro,
TOOLCHAIN_CHECK_SCRIPT,
TOOLCHAIN_TIMEOUT,
options,
);
const toolchainTransportFailure = formatWslShellTransportFailureReason(
toolchainCheck.transportFailure,
);
if (toolchainTransportFailure !== null) {
return {
ok: false,
reason: toolchainTransportFailure,
fatal: false,
retryLimit: TOOLCHAIN_TRANSPORT_RETRY_LIMIT,
} as const;
}
const report = parseToolchainReport(toolchainCheck.stdout);
const reason =
formatMissingToolsReason(report, options.nodeEngineRange?.trim() || null) ??
"Node.js was not found in the WSL distro. Install it (e.g. via nvm) and restart the desktop app.";
return { ok: false, reason, fatal: true } as const;
}
if (resolvedPath === null) {
return {
ok: false,
reason: "WSL login-shell PATH could not be resolved during backend preflight.",
fatal: true,
} as const;
}
if (probe.exitCode === 3) {
return {
ok: false,
reason:
'WSL server dependencies could not be loaded (for example "node-pty"). The native packages the server needs are not unpacked where the WSL distro\'s Node can read them. This is a packaging problem with this build. Please report it.',
fatal: true,
} as const;
}
if (probe.exitCode === 0) {
const rawVersion = parseNodeVersion(probe.stdout);
if (
rawVersion !== null &&
options.nodeEngineRange &&
!satisfiesSemverRange(rawVersion, options.nodeEngineRange.trim())
) {
const range = options.nodeEngineRange.trim();
return {
ok: false,
reason: `WSL Node.js ${rawVersion} does not satisfy the server's required engine range (${range}). Install a compatible version, and restart the desktop app.`,
fatal: true,
} as const;
}
return { ok: true, nodePath, resolvedPath } as const;
}
if (options.allowBuild !== true) {
const packagedProbeFailure = formatNodePtyProbeFailureReason(probe.exitCode);
if (packagedProbeFailure !== null) {
return {
ok: false,
reason: packagedProbeFailure,
fatal: true,
} as const;
}
}
const toolchainCheck = yield* runWslShell(
distro,
TOOLCHAIN_CHECK_SCRIPT,
TOOLCHAIN_TIMEOUT,
options,
);
const toolchainTransportFailure = formatWslShellTransportFailureReason(
toolchainCheck.transportFailure,
);
if (toolchainTransportFailure !== null) {
return {
ok: false,
reason: toolchainTransportFailure,
fatal: false,
retryLimit: TOOLCHAIN_TRANSPORT_RETRY_LIMIT,
} as const;
}
const report = parseToolchainReport(toolchainCheck.stdout);
if (options.allowBuild !== true) {
// Packaged builds ship a prebuilt Linux node-pty, so no compiler, node-gyp,
// or network is needed — and we must not nag the user to install build
// tools they don't need.
const nodeOnlyReason = formatMissingToolsReason(
{
missingTools: report.missingTools.filter((tool) => tool === "node"),
nodeVersion: report.nodeVersion,
},
options.nodeEngineRange?.trim() || null,
);
return {
ok: false,
reason:
nodeOnlyReason ??
"The bundled WSL backend binary (node-pty) could not be loaded in this distro. This usually means an unsupported CPU architecture or incompatible system libraries (glibc). Use a glibc-based x64/arm64 WSL distro such as Ubuntu; if you already are, please report this with your distro and the output of `uname -m`.",
fatal: true,
} as const;
}
const missingReason = formatMissingToolsReason(report, options.nodeEngineRange?.trim() || null);
if (missingReason !== null) {
return { ok: false, reason: missingReason, fatal: true } as const;
}
const build = yield* runWslShell(
distro,
NODE_PTY_BUILD_SCRIPT(linuxServerDir),
BUILD_TIMEOUT,
options,
);
const buildTransportFailure = formatWslShellTransportFailureReason(build.transportFailure);
if (buildTransportFailure !== null) {
return {
ok: false,
reason: buildTransportFailure,
fatal: false,
retryLimit: BUILD_TRANSPORT_RETRY_LIMIT,
} as const;
}
if (build.exitCode === 0) return { ok: true, nodePath, resolvedPath } as const;
const trimmedTail = `${build.stdout}${build.stderr}`.trim().slice(-500);
return {
ok: false,
reason: `node-pty Linux build failed (exit ${build.exitCode}): ${trimmedTail || "no stderr captured"}`,
fatal: true,
} as const;
});
const prepareWslRuntimeImpl = Effect.fn("desktop.wsl.prepareRuntimeImpl")(function* (
distro: string | null,
archive: WslRuntimeArchive,
windowsToWslPath: (
distro: string | null,
windowsPath: string,
) => Effect.Effect<Option.Option<string>>,
): Effect.fn.Return<PrepareWslRuntimeResult, never, ChildProcessSpawner.ChildProcessSpawner> {
const linuxArchivePath = yield* windowsToWslPath(distro, archive.windowsPath);
if (Option.isNone(linuxArchivePath)) {
return {
ok: false,
reason: `wslpath conversion failed for ${archive.windowsPath}`,
} as const;
}
const install = yield* runWslShell(
distro,
buildWslRuntimeInstallScript(linuxArchivePath.value, archive.runtimeId, archive.sha256),
RUNTIME_INSTALL_TIMEOUT,
{ resolveNode: false },
);
if (install.transportFailure !== null) {
return {
ok: false,
reason:
install.transportFailure === "timeout"
? "WSL runtime installation timed out. Check that the distro has free disk space, then retry."
: "WSL runtime installation lost communication with wsl.exe. Retry, or check that the distro is healthy.",
} as const;
}
if (install.exitCode !== 0) {
const trimmedTail = `${install.stdout}${install.stderr}`.trim().slice(-500);
return {
ok: false,
reason: `WSL runtime installation failed (exit ${install.exitCode}): ${trimmedTail || "no stderr captured"}`,
} as const;
}
const linuxAppRoot = parseWslRuntimeRoot(install.stdout);
return linuxAppRoot === null
? {
ok: false,
reason: "WSL runtime installation completed without reporting its cache path.",
}
: { ok: true, linuxAppRoot };
});
const pruneWslRuntimesImpl = Effect.fn("desktop.wsl.pruneRuntimesImpl")(function* (
distro: string | null,
runtimeId: string,
): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
const result = yield* runWslShell(
distro,
buildWslRuntimePruneScript(runtimeId),
RUNTIME_PRUNE_TIMEOUT,
{ resolveNode: false },
);
if (result.transportFailure === null && result.exitCode === 0) return;
const detail = `${result.stdout}${result.stderr}`.trim().slice(-500);
yield* Effect.logWarning("Could not prune old WSL runtime caches.", {
distro,
runtimeId,
detail: detail || `exit ${result.exitCode}`,
});
});
const invalidateWslRuntimeImpl = Effect.fn("desktop.wsl.invalidateRuntimeImpl")(function* (
distro: string | null,
runtimeId: string,
): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
const result = yield* runWslShell(
distro,
buildWslRuntimeInvalidateScript(runtimeId),
RUNTIME_INVALIDATE_TIMEOUT,
{ resolveNode: false },
);
if (result.transportFailure === null && result.exitCode === 0) return;
const detail = `${result.stdout}${result.stderr}`.trim().slice(-500);
yield* Effect.logWarning("Could not invalidate the staged WSL runtime cache.", {
distro,
runtimeId,
detail: detail || `exit ${result.exitCode}`,
});
});
const probeWslDistros: Effect.Effect<
readonly WslDistro[],
DesktopWslDistroListError,
ChildProcessSpawner.ChildProcessSpawner
> = Effect.scoped(
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const command = ChildProcess.make("wsl.exe", ["--list", "--verbose"], {
stdin: "ignore",
stdout: "pipe",
stderr: "ignore",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
});
const handle = yield* spawner.spawn(command);
const stdoutBytes = yield* Stream.runCollect(handle.stdout);
const exitCode = yield* handle.exitCode;
if ((exitCode as unknown as number) !== 0) {
return yield* new DesktopWslDistroListError({
reason: `wsl.exe --list --verbose exited with code ${String(exitCode)}`,
});
}
return parseWslDistroList(Buffer.from(concatChunks(stdoutBytes)));
}),
).pipe(
Effect.mapError((error) =>
isDesktopWslDistroListError(error)
? error
: new DesktopWslDistroListError({
reason: `Failed to run wsl.exe --list --verbose: ${error.message}`,
}),
),
Effect.timeoutOption(LIST_TIMEOUT),
Effect.flatMap(
Option.match({
onNone: () =>
new DesktopWslDistroListError({
reason: "wsl.exe --list --verbose timed out",
}),
onSome: Effect.succeed,
}),
),
);
const preWarmImpl = (
distro: string | null,
): Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner> =>
Effect.scoped(
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const command = ChildProcess.make("wsl.exe", [...buildDistroArgs(distro), "--", "true"], {
stdin: "ignore",
stdout: "ignore",
stderr: "ignore",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
});
const handle = yield* spawner.spawn(command);
yield* handle.exitCode;
}),
).pipe(Effect.timeoutOption(PRE_WARM_TIMEOUT), Effect.ignore);
const windowsToWslPathImpl = (
distro: string | null,
windowsPath: string,
): Effect.Effect<Option.Option<string>, never, ChildProcessSpawner.ChildProcessSpawner> => {
// wsl.exe interprets backslashes as escape chars; normalize to forward slashes.
const normalized = windowsPath.replaceAll("\\", "/");
return Effect.scoped(
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const command = ChildProcess.make(
"wsl.exe",
[...buildDistroArgs(distro), "--", "wslpath", "-u", normalized],
{
stdin: "ignore",
stdout: "pipe",
stderr: "ignore",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
},
);
const handle = yield* spawner.spawn(command);
const stdoutBytes = yield* Stream.runCollect(handle.stdout);
const exitCode = yield* handle.exitCode;
if ((exitCode as unknown as number) !== 0) return Option.none<string>();
const converted = decodeUtf8(concatChunks(stdoutBytes)).trim();
return converted.length > 0 ? Option.some(converted) : Option.none<string>();
}),
).pipe(
Effect.timeoutOption(WSLPATH_TIMEOUT),
Effect.map(Option.flatten),
Effect.orElseSucceed(() => Option.none<string>()),
);
};
const IPV4_PATTERN = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
const getDistroIpImpl = (
distro: string | null,
): Effect.Effect<Option.Option<string>, never, ChildProcessSpawner.ChildProcessSpawner> =>
Effect.scoped(
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
// WSL2's first hostname -I address is reachable directly from Windows without wslhost forwarding.
const command = ChildProcess.make(
"wsl.exe",
[...buildDistroArgs(distro), "--", "sh", "-c", "hostname -I"],
{
stdin: "ignore",
stdout: "pipe",
stderr: "ignore",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
},
);
const handle = yield* spawner.spawn(command);
const stdoutBytes = yield* Stream.runCollect(handle.stdout);
const exitCode = yield* handle.exitCode;
if ((exitCode as unknown as number) !== 0) return Option.none<string>();
const raw = decodeUtf8(concatChunks(stdoutBytes)).trim();
const candidate = raw.split(/\s+/).find((part) => IPV4_PATTERN.test(part));
return candidate ? Option.some(candidate) : Option.none<string>();
}),
).pipe(
Effect.timeoutOption(USER_HOME_TIMEOUT),
Effect.map(Option.flatten),
Effect.orElseSucceed(() => Option.none<string>()),
);
const getUserHomeImpl = (
distro: string | null,
): Effect.Effect<Option.Option<string>, never, ChildProcessSpawner.ChildProcessSpawner> =>
Effect.scoped(
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const command = ChildProcess.make(
"wsl.exe",
[
...buildDistroArgs(distro),
"--",
"sh",
"-c",
'printf "%s" "$(getent passwd "$(id -un)" | cut -d: -f6)"',
],
{
stdin: "ignore",
stdout: "pipe",
stderr: "ignore",
killSignal: "SIGTERM",
forceKillAfter: PROCESS_TERMINATE_GRACE,
},
);
const handle = yield* spawner.spawn(command);
const stdoutBytes = yield* Stream.runCollect(handle.stdout);
const exitCode = yield* handle.exitCode;
if ((exitCode as unknown as number) !== 0) return Option.none<string>();
const home = decodeUtf8(concatChunks(stdoutBytes)).trim();
return home.startsWith("/") ? Option.some(home) : Option.none<string>();
}),
).pipe(
Effect.timeoutOption(USER_HOME_TIMEOUT),
Effect.map(Option.flatten),
Effect.orElseSucceed(() => Option.none<string>()),
);
export const makeIsAvailable = Effect.fn("DesktopWslEnvironment.makeIsAvailable")(function* (
platform: NodeJS.Platform,
windir: string,
): Effect.fn.Return<
boolean,
never,
FileSystem.FileSystem | Path.Path | DesktopManagedPolicy.DesktopManagedPolicy
> {
if (platform !== "win32") return false;
const path = yield* Path.Path;
const fileSystem = yield* FileSystem.FileSystem;
const wslExePath = path.join(windir, "System32", "wsl.exe");
if (!(yield* fileSystem.exists(wslExePath).pipe(Effect.orElseSucceed(() => false)))) {
return false;
}
// A server in WSL reads Linux's policy, never this machine's, so a managed machine runs none.
return yield* (yield* DesktopManagedPolicy.DesktopManagedPolicy).read.pipe(
Effect.map((found) => found === undefined),
Effect.orElseSucceed(() => false),
);
});
export interface DesktopWslEnvironmentTestStub {
readonly isAvailable?: boolean;
readonly distros?: ReadonlyArray<WslDistro>;
readonly distroListError?: DesktopWslDistroListError;
readonly windowsToWslPath?: (distro: string | null, windowsPath: string) => Option.Option<string>;
readonly getUserHome?: (distro: string | null) => Option.Option<string>;
readonly getDistroIp?: (distro: string | null) => Option.Option<string>;
readonly prepareRuntime?: (
distro: string | null,
archive: WslRuntimeArchive,
) => PrepareWslRuntimeResult;
readonly pruneRuntimes?: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
readonly invalidateRuntime?: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
readonly probeRuntime?: (distro: string | null, linuxAppRoot: string) => ProbeWslRuntimeResult;
readonly ensureNodePty?: (
distro: string | null,
linuxAppRoot: string,
options?: EnsureWslNodePtyOptions,
) => EnsureWslNodePtyResult;
}
export const layerTest = (stub: DesktopWslEnvironmentTestStub = {}) => {
const probeDistros: Effect.Effect<readonly WslDistro[], DesktopWslDistroListError> =
stub.distroListError ? Effect.fail(stub.distroListError) : Effect.succeed(stub.distros ?? []);
return Layer.succeed(
DesktopWslEnvironment,
DesktopWslEnvironment.of({
isAvailable: Effect.succeed(stub.isAvailable ?? false),
listDistros: probeDistros.pipe(Effect.orElseSucceed(() => [])),
probeDistros,
preWarm: Effect.fn("DesktopWslEnvironment.preWarm")(function () {
return Effect.void;
}),
windowsToWslPath: Effect.fn("DesktopWslEnvironment.windowsToWslPath")(
function (distro, windowsPath) {
return Effect.succeed(stub.windowsToWslPath?.(distro, windowsPath) ?? Option.none());
},
),
getUserHome: Effect.fn("DesktopWslEnvironment.getUserHome")(function (distro) {
return Effect.succeed(stub.getUserHome?.(distro) ?? Option.none<string>());
}),
getDistroIp: Effect.fn("DesktopWslEnvironment.getDistroIp")(function (distro) {
return Effect.succeed(stub.getDistroIp?.(distro) ?? Option.none<string>());
}),
prepareRuntime: Effect.fn("DesktopWslEnvironment.prepareRuntime")(function (distro, archive) {
return Effect.succeed(
stub.prepareRuntime?.(distro, archive) ?? {
ok: false,
reason: "prepareRuntime stub not configured",
},
);
}),
pruneRuntimes: Effect.fn("DesktopWslEnvironment.pruneRuntimes")(function (distro, runtimeId) {
return stub.pruneRuntimes?.(distro, runtimeId) ?? Effect.void;
}),
invalidateRuntime: Effect.fn("DesktopWslEnvironment.invalidateRuntime")(
function (distro, runtimeId) {
return stub.invalidateRuntime?.(distro, runtimeId) ?? Effect.void;
},
),
probeRuntime: Effect.fn("DesktopWslEnvironment.probeRuntime")(
function (distro, linuxAppRoot) {
return Effect.succeed(
stub.probeRuntime?.(distro, linuxAppRoot) ?? {
ok: true,
resolvedPath: "/usr/bin:/bin",
},
);
},
),
ensureNodePty: Effect.fn("DesktopWslEnvironment.ensureNodePty")(
function (distro, linuxAppRoot, options) {
return Effect.succeed(
stub.ensureNodePty?.(distro, linuxAppRoot, options) ?? {
ok: false,
reason: "ensureNodePty stub not configured",
fatal: true,
},
);
},
),
}),
);
};
export const layer = Layer.effect(
DesktopWslEnvironment,
Effect.gen(function* () {
const environment = yield* DesktopEnvironment.DesktopEnvironment;
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const fileSystem = yield* FileSystem.FileSystem;
// Not Config: Windows variable names are case-insensitive only on the live process.env.
const windir = (yield* HostProcess.Environment).WINDIR ?? "C:\\Windows";
const provideSpawner = <A, E>(
effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
): Effect.Effect<A, E> =>
effect.pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner));
// Cache availability so synchronous IPC bootstrap can read it without yielding to filesystem I/O.
const wslAvailable = yield* makeIsAvailable(environment.platform, windir).pipe(
Effect.provideService(FileSystem.FileSystem, fileSystem),
Effect.provideService(Path.Path, environment.path),
Effect.provideService(
DesktopManagedPolicy.DesktopManagedPolicy,
yield* DesktopManagedPolicy.DesktopManagedPolicy,
),
Effect.withSpan("desktop.wsl.isAvailable"),
);
const isAvailable = Effect.succeed(wslAvailable);
const windowsToWslPath = (distro: string | null, windowsPath: string) =>
provideSpawner(windowsToWslPathImpl(distro, windowsPath)).pipe(
Effect.withSpan("desktop.wsl.windowsToWslPath"),
);
const userHomeCache = new Map<string, string>();
const getUserHome = Effect.fn("desktop.wsl.getUserHome")(function* (distro: string | null) {
const key = distro ?? "__default__";
const cached = userHomeCache.get(key);
if (cached !== undefined) return Option.some(cached);
const resolved = yield* provideSpawner(getUserHomeImpl(distro));
if (Option.isSome(resolved)) userHomeCache.set(key, resolved.value);
return resolved;
});
const getDistroIp = (distro: string | null) =>
provideSpawner(getDistroIpImpl(distro)).pipe(Effect.withSpan("desktop.wsl.getDistroIp"));
const probeDistros = provideSpawner(probeWslDistros).pipe(
Effect.withSpan("desktop.wsl.probeDistros"),
);
return DesktopWslEnvironment.of({
isAvailable,
listDistros: probeDistros.pipe(
Effect.orElseSucceed(() => []),
Effect.withSpan("desktop.wsl.listDistros"),
),
probeDistros,
preWarm: Effect.fn("desktop.wsl.preWarm")(function (distro) {
return provideSpawner(preWarmImpl(distro));
}),
windowsToWslPath,
getUserHome,
getDistroIp,
prepareRuntime: Effect.fn("desktop.wsl.prepareRuntime")(function (distro, archive) {
return provideSpawner(prepareWslRuntimeImpl(distro, archive, windowsToWslPath));
}),
pruneRuntimes: Effect.fn("desktop.wsl.pruneRuntimes")(function (distro, runtimeId) {
return provideSpawner(pruneWslRuntimesImpl(distro, runtimeId));
}),
invalidateRuntime: Effect.fn("desktop.wsl.invalidateRuntime")(function (distro, runtimeId) {
return provideSpawner(invalidateWslRuntimeImpl(distro, runtimeId));
}),
probeRuntime: Effect.fn("desktop.wsl.probeRuntime")(function (distro, linuxAppRoot) {
return provideSpawner(probeWslRuntimeImpl(distro, linuxAppRoot));
}),
ensureNodePty: Effect.fn("desktop.wsl.ensureNodePty")(
function (distro, linuxAppRoot, options) {
return provideSpawner(ensureNodePtyImpl(distro, linuxAppRoot, options));
},
),
});
}),
);