dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/lib/wsl.js

@@ -6,15 +6,16 @@
  * own Loader entry and must not drag the shell executor's and filesystem
  * backend's peer dependencies into that row.
  *
+ * This is a TypeScript source built to `lib/wsl.js`; edit THIS file and run
+ * `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
  * @module dsh-plugin-wsl/wsl
  */
-
 import { execFile } from "node:child_process";
 import { posixToUnc } from "./paths.js";
-
 /** Default executable name; resolution is left to PATH. */
 export const DEFAULT_WSL_PATH = "wsl.exe";
-
 /**
  * The deadline every `wsl.exe` call runs under, when the caller names none.
  *
@@ -26,7 +27,6 @@ export const DEFAULT_WSL_PATH = "wsl.exe";
  * genuinely wants to wait forever.
  */
 export const DEFAULT_WSL_DEADLINE_MS = 60_000;
-
 /**
  * Run one host command and capture UTF-8 output.
  *
@@ -36,76 +36,81 @@ export const DEFAULT_WSL_DEADLINE_MS = 60_000;
  *
  * @param argv - executable plus arguments, spawned without a shell.
  * @param signal - optional cancellation.
- * @param deadlineMs - kill the call after this many milliseconds; the default
- *   is {@link DEFAULT_WSL_DEADLINE_MS}, and `0` waits forever.
+ * @param deadlineMs - kill the call after this many milliseconds; the
+ *   default is {@link DEFAULT_WSL_DEADLINE_MS}, and `0` waits forever.
  * @returns captured stdout.
  * @throws the execFile error, with a hint attached when the cause is the sandbox.
  */
 export function runCapture(argv, signal, deadlineMs = DEFAULT_WSL_DEADLINE_MS) {
-  const [file, ...args] = argv;
-  return new Promise((resolve, reject) => {
-    execFile(
-      file,
-      args,
-      { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8", timeout: deadlineMs },
-      (error, stdout, stderr) => {
-        if (error) {
-          // A denied WSL call is the likeliest failure here and its own message
-          // is unhelpful, so name the cause when it is recognisable.
-          const detail = `${stdout ?? ""}${stderr ?? ""}`.replace(/\u0000/g, "").trim();
-          const denied = /E_ACCESSDENIED/i.test(detail) || error.code === "EACCES";
-          const missing = error.code === "ENOENT";
-          // The deadline kill arrives as a SIGTERM with no WSL diagnostic, so
-          // it must be named for what it is — not left looking like WSL's own
-          // failure. An abort is cancellation, not a deadline.
-          const stuck = error.killed === true && error.name !== "AbortError";
-          error.message = `${file} failed: ${detail || error.message}${
-            denied
-              ? " (WSL is unreachable from a sandboxed process: DSH's Windows ACL sandbox runs commands under a restricted low-integrity token. Compose the non-sandboxing providers.)"
-              : ""
-          }${
-            missing
-              ? ` (the executable "${file}" could not be started: check \`wslPath\` in this row, and that WSL is installed)`
-              : ""
-          }${
-            stuck
-              ? ` (no completion within ${deadlineMs}ms — the WSL service may be wedged; retry once, then \`wsl.exe --shutdown\` and reopen)`
-              : ""
-          }`;
-          reject(error);
-          return;
-        }
-        resolve(String(stdout ?? "").replace(/\u0000/g, ""));
-      },
-    );
-  });
+    const [file, ...args] = argv;
+    if (file === undefined)
+        throw new Error("wsl: runCapture needs a program to run");
+    return new Promise((resolve, reject) => {
+        execFile(file, args, { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8", timeout: deadlineMs }, (error, stdout, stderr) => {
+            if (error) {
+                // A denied WSL call is the likeliest failure here and its own message
+                // is unhelpful, so name the cause when it is recognisable.
+                const detail = `${stdout ?? ""}${stderr ?? ""}`.replace(/\u0000/g, "").trim();
+                const denied = /E_ACCESSDENIED/i.test(detail) || error.code === "EACCES";
+                const missing = error.code === "ENOENT";
+                // The deadline kill arrives as a SIGTERM with no WSL diagnostic, so
+                // it must be named for what it is — not left looking like WSL's own
+                // failure. An abort is cancellation, not a deadline.
+                const stuck = error.killed === true && error.name !== "AbortError";
+                error.message = `${file} failed: ${detail || error.message}${denied
+                    ? " (WSL is unreachable from a sandboxed process: DSH's Windows ACL sandbox runs commands under a restricted low-integrity token. Compose the non-sandboxing providers.)"
+                    : ""}${missing
+                    ? ` (the executable "${file}" could not be started: check \`wslPath\` in this row, and that WSL is installed)`
+                    : ""}${stuck
+                    ? ` (no completion within ${deadlineMs}ms — the WSL service may be wedged; retry once, then \`wsl.exe --shutdown\` and reopen)`
+                    : ""}`;
+                reject(error);
+                return;
+            }
+            resolve(String(stdout ?? "").replace(/\u0000/g, ""));
+        });
+    });
 }
-
 /**
  * List installed distros with `wsl.exe -l -q`.
+ *
  * @param options - the `wsl.exe` path and optional cancellation.
  * @returns distro names in WSL's own order, default distro first.
  */
 export async function listDistros(options = {}) {
-  const stdout = await runCapture([options.wslPath ?? DEFAULT_WSL_PATH, "-l", "-q"], options.signal);
-  return stdout
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
+    const stdout = await runCapture([options.wslPath ?? DEFAULT_WSL_PATH, "-l", "-q"], options.signal);
+    return parseDistroList(stdout);
+}
+/**
+ * Parse `wsl.exe -l -q` output into distro names. A pure seam so the CRLF and
+ * blank-line shapes of the real output are unit-testable on hosts without
+ * `wsl.exe`.
+ *
+ * @param stdout - the raw `wsl.exe -l -q` stdout.
+ * @returns distro names, default distro first.
+ */
+export function parseDistroList(stdout) {
+    return String(stdout)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
 }
-
 /**
  * Resolve the distro to use when none is configured: WSL's own default.
+ *
  * @param options - the `wsl.exe` path and optional cancellation.
  * @returns the first entry of {@link listDistros}.
  * @throws when no distro is installed.
  */
 export async function defaultDistro(options = {}) {
-  const [first] = await listDistros(options);
-  if (first === undefined) throw new Error("dsh-plugin-wsl: no WSL distro is installed (`wsl.exe -l -q` returned nothing)");
-  return first;
+    const [first] = await listDistros(options);
+    if (first === undefined) {
+        throw new Error("dsh-plugin-wsl: no WSL distro is installed (`wsl.exe -l -q` returned nothing). " +
+            "Install one: `wsl.exe --list --online` lists the available names, then `wsl --install -d <name>`, " +
+            "or point this row's `distro` at an existing one.");
+    }
+    return first;
 }
-
 /**
  * The Linux home directory of a distro's default user, as a Linux path. `$HOME`
  * is set by `wsl.exe` itself from the distro's default user, so this needs no
@@ -117,17 +122,26 @@ export async function defaultDistro(options = {}) {
  * @throws when the distro cannot be queried or reports no home.
  */
 export async function linuxHomePath(distro, options = {}) {
-  const stdout = await runCapture(
-    [options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", "sh", "-c", 'printf %s "$HOME"'],
-    options.signal,
-  );
-  const home = stdout.trim();
-  if (home.length === 0 || !home.startsWith("/")) {
-    throw new Error(`dsh-plugin-wsl: distro "${distro}" reported no usable $HOME (got "${home}")`);
-  }
-  return home;
+    const stdout = await runCapture([options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", "sh", "-c", 'printf %s "$HOME"'], options.signal);
+    return parseHomePath(distro, stdout);
+}
+/**
+ * Validate the distro's reported $HOME. A pure seam: the failure shapes
+ * (empty output, a Windows path, mojibake) are unit-testable without
+ * `wsl.exe`.
+ *
+ * @param distro - the distro name, for the error message.
+ * @param stdout - the raw `printf %s "$HOME"` output.
+ * @returns the Linux home path.
+ */
+export function parseHomePath(distro, stdout) {
+    const home = String(stdout).trim();
+    if (home.length === 0 || !home.startsWith("/")) {
+        throw new Error(`dsh-plugin-wsl: distro "${distro}" reported no usable $HOME (got "${home}"). ` +
+            `Check the distro's default user in /etc/wsl.conf, and that the user's /etc/passwd entry carries a home directory.`);
+    }
+    return home;
 }
-
 /**
  * The same home in the world coordinate system, which is what a host-side
  * consumer needs.
@@ -138,27 +152,8 @@ export async function linuxHomePath(distro, options = {}) {
  * @throws when the distro cannot be queried or reports no home.
  */
 export async function linuxHome(distro, options = {}) {
-  return posixToUnc(distro, await linuxHomePath(distro, options));
+    return posixToUnc(distro, await linuxHomePath(distro, options));
 }
-
-/**
- * Resolve a Linux path to its canonical form INSIDE the distro with
- * `readlink -f`.
- *
- * This exists because the UNC share cannot traverse Linux symlinks: the share
- * exposes one as a Windows reparse point whose relative POSIX target has no
- * meaning to Windows path resolution, so `stat`/`realpath`/`read` on a path such
- * as `/etc/os-release` (-> ../usr/lib/os-release) or `/lib` (-> usr/lib) fail
- * with `ENOENT`, even though `lstat` reaches the link. Asking the distro for the
- * real path is the only reliable answer, at one process per distinct path.
- *
- * @param distro - distro name.
- * @param linuxPath - the Linux path to canonicalize.
- * @param options - the `wsl.exe` path and optional cancellation.
- * @returns the canonical absolute Linux path, or undefined when it cannot be
- *   determined (missing file, broken link, or a failed query).
- */
-
 /**
  * Shells known to accept the combined POSIX `-lc` login-plus-command form.
  *
@@ -168,7 +163,6 @@ export async function linuxHome(distro, options = {}) {
  * — it just does not get login-shell semantics.
  */
 const POSIX_LOGIN_SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "ksh93", "mksh", "ash", "busybox"]);
-
 /**
  * The argv flags that make `shell` run `command`, with login semantics when the
  * shell supports them.
@@ -177,6 +171,12 @@ const POSIX_LOGIN_SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "ksh93",
  * @param login - whether login-shell semantics were requested.
  * @returns the flags to place before the command string.
  */
+export function shellArgs(shellPath, login) {
+    const name = String(shellPath).slice(String(shellPath).lastIndexOf("/") + 1).toLowerCase();
+    if (!POSIX_LOGIN_SHELLS.has(name))
+        return ["-c"];
+    return login ? ["-lc"] : ["-c"];
+}
 /**
  * The working directory `wsl.exe` could not enter, when its relay said so.
  *
@@ -190,22 +190,15 @@ const POSIX_LOGIN_SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "ksh93",
  * run into an error. Verified against `wsl.exe -d <distro> --cd /missing --exec sh`:
  * exit 0, `hi` on stdout, this shape on stderr.
  *
- * @param stdout - a command's captured stdout.
- * @param stderr - its captured stderr.
+ * @param stdout - a command's captured stdout; absent reads as empty.
+ * @param stderr - its captured stderr; absent reads as empty.
  * @returns the directory that could not be entered, or undefined.
  */
 export function workdirFailure(stdout, stderr) {
-  const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
-  const match = /<3>WSL[^\n]*CreateProcessCommon[^\n]*chdir\(([^)]*)\) failed/.exec(text);
-  return match?.[1];
+    const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
+    const match = /<3>WSL[^\n]*CreateProcessCommon[^\n]*chdir\(([^)]*)\) failed/.exec(text);
+    return match?.[1];
 }
-
-export function shellArgs(shellPath, login) {
-  const name = String(shellPath).slice(String(shellPath).lastIndexOf("/") + 1).toLowerCase();
-  if (!POSIX_LOGIN_SHELLS.has(name)) return ["-c"];
-  return login ? ["-lc"] : ["-c"];
-}
-
 /**
  * Shells whose `-l` flag means a login shell.
  *
@@ -215,7 +208,6 @@ export function shellArgs(shellPath, login) {
  * nushell/xonsh use long flags, so they deliberately get nothing.
  */
 const LOGIN_FLAG_SHELLS = new Set([...POSIX_LOGIN_SHELLS, "fish"]);
-
 /**
  * The flags that make an interactive shell a login shell.
  *
@@ -228,10 +220,9 @@ const LOGIN_FLAG_SHELLS = new Set([...POSIX_LOGIN_SHELLS, "fish"]);
  * @returns `["-l"]`, or an empty array for a shell whose login flag differs.
  */
 export function interactiveShellArgs(shellPath, login) {
-  const name = String(shellPath).slice(String(shellPath).lastIndexOf("/") + 1).toLowerCase();
-  return login && LOGIN_FLAG_SHELLS.has(name) ? ["-l"] : [];
+    const name = String(shellPath).slice(String(shellPath).lastIndexOf("/") + 1).toLowerCase();
+    return login && LOGIN_FLAG_SHELLS.has(name) ? ["-l"] : [];
 }
-
 /**
  * The `wsl.exe` argv that opens one interactive shell inside a distro.
  *
@@ -250,19 +241,17 @@ export function interactiveShellArgs(shellPath, login) {
  *     rejects an empty `--cd` argument whereas its own default starts in the
  *     distro user's home.
  *
- * @param options - the `wsl.exe` path, distro, optional shell, its args, cwd and login mode.
+ * @param options - the launch description.
  * @returns the argv to spawn on the host.
  */
 export function wslTerminalArgv(options) {
-  const { wslPath = DEFAULT_WSL_PATH, distro = "", shellPath, args = [], linuxCwd, login = true } = options;
-  const directory = typeof linuxCwd === "string" && linuxCwd.length > 0 ? ["--cd", linuxCwd] : [];
-  const shell =
-    typeof shellPath === "string" && shellPath.length > 0
-      ? ["--exec", shellPath, ...interactiveShellArgs(shellPath, login), ...args]
-      : [];
-  return [wslPath, ...(distro.length > 0 ? ["-d", distro] : []), ...directory, ...shell];
+    const { wslPath = DEFAULT_WSL_PATH, distro = "", shellPath, args = [], linuxCwd, login = true } = options;
+    const directory = typeof linuxCwd === "string" && linuxCwd.length > 0 ? ["--cd", linuxCwd] : [];
+    const shell = typeof shellPath === "string" && shellPath.length > 0
+        ? ["--exec", shellPath, ...interactiveShellArgs(shellPath, login), ...args]
+        : [];
+    return [wslPath, ...(distro.length > 0 ? ["-d", distro] : []), ...directory, ...shell];
 }
-
 /**
  * Managed facts of the `DSH_*` namespace that carry a Windows path. WSL's
  * `WSLENV` `/p` flag translates them on the way into the distro, so a command
@@ -270,7 +259,6 @@ export function wslTerminalArgv(options) {
  * absent: it is already a POSIX path, and translating it would corrupt it.
  */
 const PATH_TRANSLATED_ENV = new Set(["DSH_HOME", "DSH_PROFILE_DIR"]);
-
 /**
  * Render WSLENV's value from the env names a call wants the distro to import.
  *
@@ -281,21 +269,8 @@ const PATH_TRANSLATED_ENV = new Set(["DSH_HOME", "DSH_PROFILE_DIR"]);
  * @returns the `:`-joined WSLENV value.
  */
 export function wslEnvValue(names) {
-  return names.map((name) => (PATH_TRANSLATED_ENV.has(name) ? `${name}/p` : name)).join(":");
+    return names.map((name) => (PATH_TRANSLATED_ENV.has(name) ? `${name}/p` : name)).join(":");
 }
-
-/**
- * Resolve the shell a distro's user actually gets, rather than assuming bash.
- *
- * The authoritative source is the login shell field of the user's passwd entry;
- * `$SHELL` (which `wsl.exe` derives from it) is the fallback for distros without
- * `getent`, and bash is the last resort. The passwd field is preferred because a
- * user can export a different `SHELL` without changing their login shell.
- *
- * @param distro - distro name.
- * @param options - the `wsl.exe` path and optional cancellation.
- * @returns an absolute path to the shell inside the distro.
- */
 /**
  * The `WSL_E_*` code inside `wsl.exe`'s own output, when it reported one.
  *
@@ -306,49 +281,69 @@ export function wslEnvValue(names) {
  * `wsl.exe -d nosuchdistro --exec …` exits 255 with an empty stderr and
  * `Wsl/Service/WSL_E_DISTRO_NOT_FOUND` on stdout.
  *
- * @param stdout - a command's captured stdout.
- * @param stderr - its captured stderr.
+ * @param stdout - a command's captured stdout; absent reads as empty.
+ * @param stderr - its captured stderr; absent reads as empty.
  * @returns the code, for example `WSL_E_DISTRO_NOT_FOUND`, or undefined.
  */
 export function wslErrorCode(stdout, stderr) {
-  const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
-  return /WSL_E_[A-Z0-9_]+/.exec(text)?.[0];
+    const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
+    return /WSL_E_[A-Z0-9_]+/.exec(text)?.[0];
 }
-
+/**
+ * Resolve the shell a distro's user actually gets, rather than assuming bash.
+ *
+ * The authoritative source is the login shell field of the user's passwd entry;
+ * `$SHELL` (which `wsl.exe` derives from it) is the fallback for distros without
+ * `getent`, and bash is the last resort. The passwd field is preferred because a
+ * user can export a different `SHELL` without changing their login shell.
+ *
+ * @param distro - distro name.
+ * @param options - the `wsl.exe` path and optional cancellation.
+ * @returns an absolute path to the shell inside the distro, or undefined when
+ *   both probes failed.
+ */
 export async function defaultShell(distro, options = {}) {
-  const wslPath = options.wslPath ?? DEFAULT_WSL_PATH;
-  const ask = async (script) => {
-    try {
-      const value = (await runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", script], options.signal)).trim();
-      return value.startsWith("/") ? value : undefined;
-    } catch {
-      return undefined;
-    }
-  };
-  // No "bash" placeholder: a failed probe (a cold distro, a flaky first
-  // `wsl.exe` call) used to be pinned as the literal shell for the
-  // executor's lifetime. `undefined` tells the caller both answers failed;
-  // it may retry later or fall back itself.
-  return (
-    (await ask('getent passwd "$(id -u)" | cut -d: -f7')) ??
-    (await ask('printf %s "$SHELL"')) ??
-    undefined
-  );
+    const wslPath = options.wslPath ?? DEFAULT_WSL_PATH;
+    /**
+     * Ask the distro one `sh -c` question; only absolute paths count as answers.
+     *
+     * @param script - the shell snippet to run.
+     * @returns the trimmed answer, or undefined.
+     */
+    const ask = async (script) => {
+        try {
+            const value = (await runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", script], options.signal)).trim();
+            return value.startsWith("/") ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // No "bash" placeholder: a failed probe (a cold distro, a flaky first
+    // `wsl.exe` call) used to be pinned as the literal shell for the
+    // executor's lifetime. `undefined` tells the caller both answers failed;
+    // it may retry later or fall back itself.
+    return ((await ask('getent passwd "$(id -u)" | cut -d: -f7')) ??
+        (await ask('printf %s "$SHELL"')) ??
+        undefined);
 }
-
 /**
  * Run one command inside a distro and return raw stdout. Used by callers that
  * want Linux semantics instead of the UNC share's.
  *
  * @param distro - distro name.
  * @param command - a shell command string.
- * @param options - the `wsl.exe` path, an explicit `shell`, and optional cancellation.
+ * @param options - the `wsl.exe` path, an explicit `shell`, and optional
+ *   cancellation.
  * @returns captured stdout.
+ * @throws when neither the caller nor the distro names a usable shell.
  */
 export async function runInDistro(distro, command, options = {}) {
-  const shell = options.shell ?? (await defaultShell(distro, options));
-  return runCapture(
-    [options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", shell, ...shellArgs(shell, options.loginShell !== false), command],
-    options.signal,
-  );
+    const shell = options.shell ?? (await defaultShell(distro, options));
+    if (shell === undefined) {
+        throw new Error(`dsh-plugin-wsl: distro "${distro}" named no usable shell (passwd probe and $SHELL both failed). ` +
+            `Check the user's login shell in /etc/passwd (\`getent passwd "$(id -u)"\` inside the distro), ` +
+            `or point this row's \`shell\` at an existing absolute path.`);
+    }
+    return runCapture([options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", shell, ...shellArgs(shell, options.loginShell !== false), command], options.signal);
 }

package/locale/preflight/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL sandbox preflight",
+    "description": "Probes bubblewrap when a distro session opens and surfaces a missing or unusable bwrap as a warning with the exact remedy — instead of the first command's fail-closed error being the discovery moment. Advisory only; never installs anything."
+  }
+}

package/locale/preflight/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL 沙箱预检",
+    "description": "发行版会话打开时探测 bubblewrap，把缺失或不可用的 bwrap 连同确切的修复指引作为警告提前给出——而不是让第一条命令的 fail-closed 报错充当发现时刻。纯建议性，绝不安装任何东西。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.7.5",
+  "version": "0.9.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -11,32 +11,78 @@
     "windows"
   ],
   "type": "module",
+  "types": "./lib/shell.d.ts",
   "main": "lib/shell.js",
   "exports": {
-    ".": "./lib/shell.js",
-    "./agent": "./lib/agent.js",
-    "./auto-preset": "./lib/auto-preset.js",
+    ".": {
+      "types": "./lib/shell.d.ts",
+      "default": "./lib/shell.js"
+    },
+    "./agent": {
+      "types": "./lib/agent.d.ts",
+      "default": "./lib/agent.js"
+    },
+    "./auto-preset": {
+      "types": "./lib/auto-preset.d.ts",
+      "default": "./lib/auto-preset.js"
+    },
     "./auto-preset/locale/en.json": "./locale/auto-preset/en.json",
     "./auto-preset/locale/zh.json": "./locale/auto-preset/zh.json",
-    "./file-reference-wsl": "./lib/file-reference-wsl.js",
-    "./fs": "./lib/fs.js",
-    "./fs-routing": "./lib/fs-routing.js",
+    "./file-reference-wsl": {
+      "types": "./lib/file-reference-wsl.d.ts",
+      "default": "./lib/file-reference-wsl.js"
+    },
+    "./fs": {
+      "types": "./lib/fs.d.ts",
+      "default": "./lib/fs.js"
+    },
+    "./fs-routing": {
+      "types": "./lib/fs-routing.d.ts",
+      "default": "./lib/fs-routing.js"
+    },
     "./locale/en.json": "./locale/en.json",
     "./locale/zh.json": "./locale/zh.json",
     "./package.json": "./package.json",
-    "./paths": "./lib/paths.js",
-    "./picker": "./lib/picker.js",
+    "./paths": {
+      "types": "./lib/paths.d.ts",
+      "default": "./lib/paths.js"
+    },
+    "./preflight": {
+      "types": "./lib/preflight.d.ts",
+      "default": "./lib/preflight.js"
+    },
+    "./picker": {
+      "types": "./lib/picker.d.ts",
+      "default": "./lib/picker.js"
+    },
     "./picker/locale/en.json": "./locale/picker/en.json",
     "./picker/locale/zh.json": "./locale/picker/zh.json",
-    "./shell": "./lib/shell.js",
-    "./shell-env": "./lib/shell-env.js",
+    "./preflight/locale/en.json": "./locale/preflight/en.json",
+    "./preflight/locale/zh.json": "./locale/preflight/zh.json",
+    "./shell": {
+      "types": "./lib/shell.d.ts",
+      "default": "./lib/shell.js"
+    },
+    "./shell-env": {
+      "types": "./lib/shell-env.d.ts",
+      "default": "./lib/shell-env.js"
+    },
     "./shell-env/locale/en.json": "./locale/shell-env/en.json",
     "./shell-env/locale/zh.json": "./locale/shell-env/zh.json",
-    "./subprocess": "./lib/subprocess.js",
+    "./subprocess": {
+      "types": "./lib/subprocess.d.ts",
+      "default": "./lib/subprocess.js"
+    },
     "./subprocess/locale/en.json": "./locale/subprocess/en.json",
     "./subprocess/locale/zh.json": "./locale/subprocess/zh.json",
-    "./workspace-files-wsl": "./lib/workspace-files-wsl.js",
-    "./wsl": "./lib/wsl.js"
+    "./workspace-files-wsl": {
+      "types": "./lib/workspace-files-wsl.d.ts",
+      "default": "./lib/workspace-files-wsl.js"
+    },
+    "./wsl": {
+      "types": "./lib/wsl.d.ts",
+      "default": "./lib/wsl.js"
+    }
   },
   "dsh": {
     "bundle": {
@@ -45,6 +91,7 @@
   },
   "files": [
     "lib/**/*.js",
+    "lib/**/*.d.ts",
     "agent/*.sh",
     "locale/**/*.json",
     "cordis.patch.yml",
@@ -63,15 +110,19 @@
     "SECURITY.md",
     "SUPPORT.md",
     "LICENSE",
-    "scripts/bootstrap.sh"
+    "scripts/bootstrap.sh",
+    "scripts/diagnose.sh"
   ],
   "scripts": {
-    "test": "npm run lint:style && npm run test:syntax && npm run test:unit",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/fs.boot.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
+    "test": "pnpm run lint:style && pnpm run test:syntax && pnpm run lint:build && pnpm run lint:types && pnpm run test:unit",
+    "lint:types": "tsc --noEmit",
+    "build": "node scripts/build.mjs",
+    "lint:build": "node test/build-freshness.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=84 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
+    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
     "lint:style": "node test/style.mjs",
-    "prepublishOnly": "npm test",
+    "prepublishOnly": "pnpm test",
     "probe": "bash test/probe/run.sh",
     "probe:missing-wsl": "bash test/probe/missing-wsl.sh",
     "probe:mode": "bash test/probe/mode.sh",
@@ -85,10 +136,12 @@
     "probe:agent": "bash test/probe/agent.sh",
     "probe:substrate": "bash test/probe/substrate.sh",
     "probe:exec": "bash test/probe/exec.sh",
-    "bootstrap": "bash scripts/bootstrap.sh"
+    "bootstrap": "bash scripts/bootstrap.sh",
+    "diagnose": "bash scripts/diagnose.sh"
   },
+  "packageManager": "pnpm@11.7.0",
   "engines": {
-    "node": ">=20"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "author": {
     "name": "Andy Zhao",
@@ -122,7 +175,10 @@
     "@deepseek-ai/dsh-subprocess": "0.2.0-rc.2",
     "@deepseek-ai/dsh-subprocess-local": "0.2.0-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
-    "js-yaml": "4.1.0"
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "~22.20.5",
+    "js-yaml": "4.3.2",
+    "typescript": "~6.0.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",