dsh-wsl-workspace 0.1.0

package/lib/wsl-GjkUifnx.js

@@ -0,0 +1,179 @@
+import { i as joinUnc, n as isValidWslUsername, s as parseWslUnc } from "./paths-DBaSmi7x.js";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/shared/wsl-credentials.ts
+/**
+* Per-workspace WSL credentials (host side only). The dialog stores the
+* optional Linux username of a WSL workspace under the harness home; the
+* per-session env contributor and the WSL shell executor read it back so
+* `wsl.exe -u <username>` can run commands as that user. Keys are canonical
+* UNC workspace paths. This module touches node builtins, so the browser
+* half never imports it.
+* @module dsh-wsl-workspace/shared/wsl-credentials
+*/
+/** The store file lives under the harness home so both host halves share it. */
+function storePath() {
+	return join(process.env.DSH_HOME ?? join(homedir(), ".dsh"), "wsl-workspaces.json");
+}
+/** Read the store; a missing or corrupt file reads as empty (never throws). */
+function readStore() {
+	try {
+		const parsed = JSON.parse(readFileSync(storePath(), "utf8"));
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+/**
+* Canonicalize any accepted WSL UNC spelling into the store's key form.
+* @param path - candidate workspace path (either UNC host form).
+* @returns the canonical UNC path, or null when the path is not a WSL UNC.
+*/
+function canonicalWslUnc(path) {
+	const parsed = parseWslUnc(path);
+	return parsed === null ? null : joinUnc(parsed.distro, parsed.linuxPath);
+}
+/**
+* Read the stored username for a WSL workspace.
+* @param uncPath - the workspace path (any accepted WSL UNC spelling).
+* @returns the username, or undefined when none is stored.
+*/
+function getWorkspaceUsername(uncPath) {
+	const key = canonicalWslUnc(uncPath);
+	if (key === null) return void 0;
+	const username = readStore()[key]?.username;
+	return username === void 0 || username === "" ? void 0 : username;
+}
+/**
+* Store (or clear) the username of a WSL workspace.
+* @param uncPath - the workspace path (any accepted WSL UNC spelling).
+* @param username - the username; empty or undefined clears the stored value.
+*/
+function setWorkspaceUsername(uncPath, username) {
+	const key = canonicalWslUnc(uncPath);
+	if (key === null) throw new Error("wsl-workspace: workspace path is not a WSL UNC path");
+	const store = readStore();
+	if (username === void 0 || username.trim() === "") delete store[key];
+	else {
+		const trimmed = username.trim();
+		if (!isValidWslUsername(trimmed)) throw new Error("wsl-workspace: username must match the Linux username pattern [A-Za-z_][A-Za-z0-9_.-]*");
+		store[key] = { username: trimmed };
+	}
+	const path = storePath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(store, null, 2) + "\n", "utf8");
+}
+//#endregion
+//#region src/shared/wsl.ts
+/**
+* WSL discovery helpers (host side): enumerate installed distributions
+* through `wsl.exe -l -q` and read the default distribution from the Lxss
+* registry key. `wsl.exe` output is UTF-16LE on most builds, so decoding
+* sniffs for NUL bytes before choosing an encoding.
+* @module dsh-wsl-workspace/shared/wsl
+*/
+const execFileAsync = promisify(execFile);
+/** Executable timeout for the short discovery calls. */
+const DISCOVERY_TIMEOUT_MS = 1e4;
+const LXSS_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Lxss";
+/** Human text for an unknown rejection. */
+function messageOf(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+/**
+* Decode `wsl.exe -l -q` output. Newer builds emit UTF-8; most emit UTF-16LE
+* with NUL bytes interleaved — the NUL probe picks the right one.
+* @param buffer - the raw captured output.
+* @returns the decoded text.
+*/
+function decodeWslOutput(buffer) {
+	return buffer.includes(0) ? buffer.toString("utf16le") : buffer.toString("utf8");
+}
+/**
+* List installed WSL distributions in `wsl.exe` order.
+* @param wslPath - the `wsl.exe` executable (absolute or PATH name).
+* @returns distribution names, blank lines dropped.
+*/
+async function listDistros(wslPath = "wsl.exe") {
+	let stdout;
+	try {
+		stdout = (await execFileAsync(wslPath, ["-l", "-q"], {
+			encoding: "buffer",
+			timeout: DISCOVERY_TIMEOUT_MS
+		})).stdout;
+	} catch (error) {
+		throw new Error(`wsl-workspace: cannot list WSL distributions (${messageOf(error)}); is WSL installed?`);
+	}
+	return decodeWslOutput(stdout).split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+}
+/**
+* Read the user's default distribution from the Lxss registry. Non-fatal:
+* returns `undefined` when the value is absent or unreadable (the caller
+* falls back to list order).
+* @returns the default distribution name, or `undefined`.
+*/
+async function defaultDistro() {
+	try {
+		const value = await execFileAsync("reg.exe", [
+			"query",
+			LXSS_KEY,
+			"/v",
+			"DefaultDistribution"
+		], { timeout: DISCOVERY_TIMEOUT_MS });
+		const guid = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/i.exec(value.stdout)?.[1];
+		if (guid === void 0) return void 0;
+		const name = await execFileAsync("reg.exe", [
+			"query",
+			`${LXSS_KEY}\\${guid}`,
+			"/v",
+			"DistributionName"
+		], { timeout: DISCOVERY_TIMEOUT_MS });
+		const distro = /DistributionName\s+REG_SZ\s+(.+)/i.exec(name.stdout)?.[1]?.trim();
+		return distro === void 0 || distro === "" ? void 0 : distro;
+	} catch {
+		return;
+	}
+}
+/** Module-level cache for {@link defaultDistroSync} (one registry read per process). */
+let syncDefaultResolved = false;
+let syncDefault;
+/**
+* Synchronous variant of {@link defaultDistro} for executors that must
+* resolve a distribution inside a synchronous plan step. Cached after the
+* first read; non-fatal (returns `undefined` when the registry is
+* unreadable, letting the caller fail loud with its own message).
+* @returns the default distribution name, or `undefined`.
+*/
+function defaultDistroSync() {
+	if (syncDefaultResolved) return syncDefault;
+	syncDefaultResolved = true;
+	try {
+		const value = execFileSync("reg.exe", [
+			"query",
+			LXSS_KEY,
+			"/v",
+			"DefaultDistribution"
+		], { timeout: DISCOVERY_TIMEOUT_MS });
+		const guid = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/i.exec(String(value))?.[1];
+		if (guid === void 0) return void 0;
+		const name = execFileSync("reg.exe", [
+			"query",
+			`${LXSS_KEY}\\${guid}`,
+			"/v",
+			"DistributionName"
+		], { timeout: DISCOVERY_TIMEOUT_MS });
+		const distro = /DistributionName\s+REG_SZ\s+(.+)/i.exec(String(name))?.[1]?.trim();
+		syncDefault = distro === void 0 || distro === "" ? void 0 : distro;
+	} catch {
+		syncDefault = void 0;
+	}
+	return syncDefault;
+}
+//#endregion
+export { getWorkspaceUsername as a, canonicalWslUnc as i, defaultDistroSync as n, setWorkspaceUsername as o, listDistros as r, defaultDistro as t };
+
+//# sourceMappingURL=wsl-GjkUifnx.js.map

package/lib/wsl-GjkUifnx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsl-GjkUifnx.js","names":[],"sources":["../src/shared/wsl-credentials.ts","../src/shared/wsl.ts"],"sourcesContent":["/**\n * Per-workspace WSL credentials (host side only). The dialog stores the\n * optional Linux username of a WSL workspace under the harness home; the\n * per-session env contributor and the WSL shell executor read it back so\n * `wsl.exe -u <username>` can run commands as that user. Keys are canonical\n * UNC workspace paths. This module touches node builtins, so the browser\n * half never imports it.\n * @module dsh-wsl-workspace/shared/wsl-credentials\n */\n\nimport { mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { dirname, join } from 'node:path'\nimport { isValidWslUsername, joinUnc, parseWslUnc } from './paths.ts'\n\n/** One workspace's stored credentials. */\ninterface WorkspaceEntry {\n  /** The Linux user bash runs as inside the distribution (absent = distro default). */\n  username?: string\n}\n\n/** The stored form: canonical UNC workspace path → credentials. */\ntype WorkspaceStore = Record<string, WorkspaceEntry>\n\n/** The store file lives under the harness home so both host halves share it. */\nfunction storePath(): string {\n  const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')\n  return join(dshHome, 'wsl-workspaces.json')\n}\n\n/** Read the store; a missing or corrupt file reads as empty (never throws). */\nfunction readStore(): WorkspaceStore {\n  try {\n    const parsed: unknown = JSON.parse(readFileSync(storePath(), 'utf8'))\n    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return {}\n    return parsed as WorkspaceStore\n  } catch {\n    return {}\n  }\n}\n\n/**\n * Canonicalize any accepted WSL UNC spelling into the store's key form.\n * @param path - candidate workspace path (either UNC host form).\n * @returns the canonical UNC path, or null when the path is not a WSL UNC.\n */\nexport function canonicalWslUnc(path: string): string | null {\n  const parsed = parseWslUnc(path)\n  return parsed === null ? null : joinUnc(parsed.distro, parsed.linuxPath)\n}\n\n/**\n * Read the stored username for a WSL workspace.\n * @param uncPath - the workspace path (any accepted WSL UNC spelling).\n * @returns the username, or undefined when none is stored.\n */\nexport function getWorkspaceUsername(uncPath: string): string | undefined {\n  const key = canonicalWslUnc(uncPath)\n  if (key === null) return undefined\n  const username = readStore()[key]?.username\n  return username === undefined || username === '' ? undefined : username\n}\n\n/**\n * Store (or clear) the username of a WSL workspace.\n * @param uncPath - the workspace path (any accepted WSL UNC spelling).\n * @param username - the username; empty or undefined clears the stored value.\n */\nexport function setWorkspaceUsername(uncPath: string, username: string | undefined): void {\n  const key = canonicalWslUnc(uncPath)\n  if (key === null) throw new Error('wsl-workspace: workspace path is not a WSL UNC path')\n  const store = readStore()\n  if (username === undefined || username.trim() === '') {\n    delete store[key]\n  } else {\n    const trimmed = username.trim()\n    if (!isValidWslUsername(trimmed)) {\n      throw new Error('wsl-workspace: username must match the Linux username pattern [A-Za-z_][A-Za-z0-9_.-]*')\n    }\n    store[key] = { username: trimmed }\n  }\n  const path = storePath()\n  mkdirSync(dirname(path), { recursive: true })\n  writeFileSync(path, JSON.stringify(store, null, 2) + '\\n', 'utf8')\n}\n","/**\n * WSL discovery helpers (host side): enumerate installed distributions\n * through `wsl.exe -l -q` and read the default distribution from the Lxss\n * registry key. `wsl.exe` output is UTF-16LE on most builds, so decoding\n * sniffs for NUL bytes before choosing an encoding.\n * @module dsh-wsl-workspace/shared/wsl\n */\n\nimport { execFile, execFileSync } from 'node:child_process'\nimport { promisify } from 'node:util'\n\nconst execFileAsync = promisify(execFile)\n\n/** Executable timeout for the short discovery calls. */\nconst DISCOVERY_TIMEOUT_MS = 10_000\n\nconst LXSS_KEY = 'HKCU\\\\Software\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Lxss'\n\n/** Human text for an unknown rejection. */\nfunction messageOf(value: unknown): string {\n  return value instanceof Error ? value.message : String(value)\n}\n\n/**\n * Decode `wsl.exe -l -q` output. Newer builds emit UTF-8; most emit UTF-16LE\n * with NUL bytes interleaved — the NUL probe picks the right one.\n * @param buffer - the raw captured output.\n * @returns the decoded text.\n */\nexport function decodeWslOutput(buffer: Buffer): string {\n  return buffer.includes(0) ? buffer.toString('utf16le') : buffer.toString('utf8')\n}\n\n/**\n * List installed WSL distributions in `wsl.exe` order.\n * @param wslPath - the `wsl.exe` executable (absolute or PATH name).\n * @returns distribution names, blank lines dropped.\n */\nexport async function listDistros(wslPath = 'wsl.exe'): Promise<string[]> {\n  let stdout: Buffer\n  try {\n    const result = await execFileAsync(wslPath, ['-l', '-q'], { encoding: 'buffer', timeout: DISCOVERY_TIMEOUT_MS })\n    stdout = result.stdout as Buffer\n  } catch (error) {\n    throw new Error(`wsl-workspace: cannot list WSL distributions (${messageOf(error)}); is WSL installed?`)\n  }\n  return decodeWslOutput(stdout)\n    .split(/\\r?\\n/)\n    .map(line => line.trim())\n    .filter(line => line.length > 0)\n}\n\n/**\n * Read the user's default distribution from the Lxss registry. Non-fatal:\n * returns `undefined` when the value is absent or unreadable (the caller\n * falls back to list order).\n * @returns the default distribution name, or `undefined`.\n */\nexport async function defaultDistro(): Promise<string | undefined> {\n  try {\n    const value = await execFileAsync('reg.exe', ['query', LXSS_KEY, '/v', 'DefaultDistribution'], {\n      timeout: DISCOVERY_TIMEOUT_MS,\n    })\n    const guid = /DefaultDistribution\\s+REG_SZ\\s+(\\{[0-9a-fA-F-]+\\})/i.exec(value.stdout)?.[1]\n    if (guid === undefined) return undefined\n    const name = await execFileAsync('reg.exe', ['query', `${LXSS_KEY}\\\\${guid}`, '/v', 'DistributionName'], {\n      timeout: DISCOVERY_TIMEOUT_MS,\n    })\n    const distro = /DistributionName\\s+REG_SZ\\s+(.+)/i.exec(name.stdout)?.[1]?.trim()\n    return distro === undefined || distro === '' ? undefined : distro\n  } catch {\n    return undefined\n  }\n}\n\n/** Module-level cache for {@link defaultDistroSync} (one registry read per process). */\nlet syncDefaultResolved = false\nlet syncDefault: string | undefined\n\n/**\n * Synchronous variant of {@link defaultDistro} for executors that must\n * resolve a distribution inside a synchronous plan step. Cached after the\n * first read; non-fatal (returns `undefined` when the registry is\n * unreadable, letting the caller fail loud with its own message).\n * @returns the default distribution name, or `undefined`.\n */\nexport function defaultDistroSync(): string | undefined {\n  if (syncDefaultResolved) return syncDefault\n  syncDefaultResolved = true\n  try {\n    const value = execFileSync('reg.exe', ['query', LXSS_KEY, '/v', 'DefaultDistribution'], {\n      timeout: DISCOVERY_TIMEOUT_MS,\n    })\n    const guid = /DefaultDistribution\\s+REG_SZ\\s+(\\{[0-9a-fA-F-]+\\})/i.exec(String(value))?.[1]\n    if (guid === undefined) return undefined\n    const name = execFileSync('reg.exe', ['query', `${LXSS_KEY}\\\\${guid}`, '/v', 'DistributionName'], {\n      timeout: DISCOVERY_TIMEOUT_MS,\n    })\n    const distro = /DistributionName\\s+REG_SZ\\s+(.+)/i.exec(String(name))?.[1]?.trim()\n    syncDefault = distro === undefined || distro === '' ? undefined : distro\n  } catch {\n    syncDefault = undefined\n  }\n  return syncDefault\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "dsh-wsl-workspace",
+  "description": "WSL workspace support for DeepSeek Harness: add a WSL workspace from the web GUI and run the whole agent session (bash + file tools) inside the WSL distribution, VS Code Remote-WSL style. No toolchain install inside WSL required.",
+  "version": "0.1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/6Mikao9/dsh-wsl-workspace.git"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./shell": "./lib/shell.js",
+    "./fs": "./lib/fs.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "wsl",
+    "workspace",
+    "plugin",
+    "windows"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-fs": "*",
+    "@deepseek-ai/dsh-fs-local": "*",
+    "@deepseek-ai/dsh-shell": "*",
+    "@deepseek-ai/dsh-subprocess": "*",
+    "@deepseek-ai/dsh-timeout": "*"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "src",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README.zh.md"
+  ]
+}

package/src/client/AddWslWorkspace.tsx

@@ -0,0 +1,346 @@
+/**
+ * Sidebar footer action that opens the "Add WSL workspace" dialog. In the
+ * wide sidebar it renders a labeled row; in the 56px rail it collapses to a
+ * 36px icon button (both honor the shell's `{ wide }` owner share).
+ *
+ * Registration omits the typed `locale:` seat (the `wslWorkspace` namespace is
+ * not merged into `LocaleNamespaceMap`), so the injected face carries the
+ * bound translate function instead.
+ */
+
+import type * as React from 'react'
+import { useEffect, useRef, useState, type UIEventHandler } from 'react'
+import { isAbsoluteLinuxPath, isValidWslUsername, joinUnc, normalizeLinuxPath } from '../shared/paths.ts'
+import type { WslDirListing, WslPathCheck } from './api.ts'
+
+/** Result-level shape of a browse/check/list call we surface uniformly. */
+interface ApiCall<T> {
+  value: T
+}
+
+/** The inject face: plain data + callbacks the dialog drives. */
+export interface AddWslWorkspaceInjected {
+  /**
+   * Confirm the deployment exposes a healthy `wsl` preset.
+   * @returns undefined when healthy, else a Chinese/English message to show.
+   */
+  checkPreset(): Promise<string | undefined>
+  /** List the WSL distros installed on the host. */
+  listDistros(): Promise<string[]>
+  /** List one Linux directory level inside a distro. */
+  listDir(distro: string, path: string): Promise<WslDirListing>
+  /** Check a Linux path's existence/directory facts. */
+  check(distro: string, path: string): Promise<WslPathCheck>
+  /**
+   * Register a workspace over a WSL UNC path and start a session in it.
+   * @param path - the `\\wsl.localhost\<distro>\...` UNC path.
+   * @param username - optional Linux user for the session (empty = distro default).
+   * @returns undefined on success, else a message to show.
+   */
+  createWorkspace(path: string, username: string): Promise<string | undefined>
+  /** Translate a `wslWorkspace` dictionary key. */
+  t: (key: string, params?: Record<string, unknown>) => string
+}
+
+/** Full component props: the owner share plus the injected face. */
+export interface AddWslWorkspaceProps extends AddWslWorkspaceInjected {
+  /** Whether the sidebar renders wide content (false = 56px rail). */
+  wide: boolean
+}
+
+/**
+ * Build the Linux child path one level below a parent, for the breadcrumb/
+ * browse drill.
+ * @param parent - the currently listed absolute path (`/` for root).
+ * @param name - the child directory name.
+ * @returns the child's absolute Linux path.
+ */
+export function dirChildPath(parent: string, name: string): string {
+  return parent === '/' ? `/${name}` : `${parent}/${name}`
+}
+
+/** A tiny inline terminal glyph for the dialog's directory rows. */
+function WslGlyph({ size = 16 }: { size?: number }): React.ReactElement {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      <rect x="2.5" y="4.5" width="19" height="15" rx="2.5" stroke="currentColor" strokeWidth="1.6" />
+      <path d="M6 9l3.2 2.6L6 14" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M12 14h5" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/**
+ * The "Add WSL workspace…" footer action and its dialog.
+ * @param props - owner share + injected face.
+ */
+export function AddWslWorkspace({ wide, t, checkPreset, listDistros, listDir, check, createWorkspace }: AddWslWorkspaceProps): React.ReactElement | null {
+  const [open, setOpen] = useState(false)
+  const [opening, setOpening] = useState(false)
+  const [distros, setDistros] = useState<string[]>([])
+  const [distro, setDistro] = useState('')
+  const [pathInput, setPathInput] = useState('/home/')
+  const [username, setUsername] = useState('')
+  const [listing, setListing] = useState<WslDirListing | null>(null)
+  const [browsePath, setBrowsePath] = useState('/')
+  const [browsing, setBrowsing] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+  // Monotone browse-request sequence: stale responses for a superseded browse are dropped.
+  const browseSeq = useRef(0)
+
+  const refreshBrowse = async (root: string, targetDistro: string): Promise<void> => {
+    const seq = ++browseSeq.current
+    setBrowsing(true)
+    setBrowsePath(root)
+    try {
+      const value = await listDir(targetDistro, root)
+      if (seq === browseSeq.current) setListing(value)
+    } catch {
+      // A failed browse (permission, missing dir) is non-fatal: keep old listing.
+      if (seq === browseSeq.current) {
+        setListing(null)
+        setError((previous) => previous ?? t('error.loadDir'))
+      }
+    } finally {
+      if (seq === browseSeq.current) setBrowsing(false)
+    }
+  }
+
+  useEffect(() => {
+    if (!open) return
+    let cancelled = false
+    setError(null)
+    setOpening(true)
+    void (async () => {
+      let presetIssue: string | undefined
+      try {
+        presetIssue = await checkPreset()
+      } catch {
+        presetIssue = t('error.loadDistros')
+      }
+      let names: string[]
+      try {
+        names = await listDistros()
+      } catch {
+        if (cancelled) return
+        setOpening(false)
+        setError(t('error.loadDistros'))
+        return
+      }
+      if (cancelled) return
+      setDistros(names)
+      const first = names[0] ?? ''
+      setDistro(first)
+      // The default browse root walks from `/`; the input defaults to `/home/`.
+      setBrowsing(true)
+      setOpening(false)
+      if (presetIssue !== undefined) setError(presetIssue)
+      if (first !== '') void refreshBrowse('/', first)
+    })()
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- run once per open against current t.
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape' && !busy) setOpen(false)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [open, busy])
+
+  if (!open) {
+    // A W-letter action beside Settings at the sidebar foot; the title
+    // carries the label in both wide and rail states.
+    return (
+      <button
+        type="button"
+        className={wide ? 'dww-action dww-action--wide' : 'dww-action dww-action--rail'}
+        title={t('action.title')}
+        aria-label={t('action.title')}
+        onClick={() => setOpen(true)}
+      >
+        <span className="dww-letter" aria-hidden="true">W</span>
+      </button>
+    )
+  }
+
+  const onDrill = (name: string): void => {
+    const next = dirChildPath(listing?.path ?? browsePath, name)
+    setPathInput(next)
+    void refreshBrowse(next, distro)
+  }
+
+  const onUp = (): void => {
+    const parent = listing?.parent ?? null
+    if (parent === null) return
+    setPathInput(parent)
+    void refreshBrowse(parent, distro)
+  }
+
+  const onDistroChange = (value: string): void => {
+    setDistro(value)
+    void refreshBrowse(browsePath, value)
+  }
+
+  const onCheck = async (): Promise<void> => {
+    const path = normalizeLinuxPath(pathInput)
+    setError(null)
+    if (!isAbsoluteLinuxPath(path) || path === '/') {
+      setError(t('error.invalidPath'))
+      return
+    }
+    let facts: WslPathCheck
+    try {
+      facts = await check(distro, path)
+    } catch {
+      setError(t('error.pathNotFound'))
+      return
+    }
+    if (!facts.exists || !facts.isDirectory) {
+      setError(t('error.pathNotFound'))
+      return
+    }
+    void refreshBrowse(path, distro)
+  }
+
+  const onConfirm = async (): Promise<void> => {
+    const path = normalizeLinuxPath(pathInput)
+    setError(null)
+    if (!isAbsoluteLinuxPath(path) || path === '/') {
+      // A workspace at the distribution root would make every session start
+      // at `/`; the check flow rejects it and confirm must agree.
+      setError(t('error.invalidPath'))
+      return
+    }
+    const user = username.trim()
+    if (user !== '' && !isValidWslUsername(user)) {
+      setError(t('error.invalidUsername'))
+      return
+    }
+    setBusy(true)
+    try {
+      let facts: WslPathCheck
+      try {
+        facts = await check(distro, path)
+      } catch {
+        setError(t('error.pathNotFound'))
+        return
+      }
+      if (!facts.exists || !facts.isDirectory) {
+        setError(t('error.pathNotFound'))
+        return
+      }
+      const failure = await createWorkspace(joinUnc(distro, path), user)
+      if (failure !== undefined) {
+        setError(failure)
+        return
+      }
+      setOpen(false)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const children = (listing?.entries.filter(entry => entry.kind === 'directory') ?? []).map(entry => entry.name)
+  const maskClick = (): void => { if (!busy) setOpen(false) }
+  const listScroll: UIEventHandler<HTMLDivElement> = () => { /* scroll container handles overflow */ }
+
+  return (
+    <div className="dww-overlay">
+      <div className="dww-overlay-mask" onClick={maskClick} />
+      <div className="dww-card" role="dialog" aria-modal="true" aria-label={t('dialog.title')}>
+        <div className="dww-header">
+          <h2 className="dww-title">{t('dialog.title')}</h2>
+          <button type="button" className="dww-close" aria-label={t('dialog.cancel')} onClick={maskClick}>
+            ✕
+          </button>
+        </div>
+        <div className="dww-body">
+          {error !== null ? (
+            <div className="dww-error">
+              {error}
+              <button type="button" className="dww-retry" onClick={() => setError(null)}>{t('dialog.retry')}</button>
+            </div>
+          ) : null}
+          <div className="dww-field">
+            <label className="dww-field-label" htmlFor="dww-distro">{t('dialog.distro')}</label>
+            <select
+              id="dww-distro"
+              className="dww-select"
+              value={distro}
+              disabled={opening || busy}
+              onChange={event => onDistroChange(event.target.value)}
+            >
+              {distros.length === 0
+                ? <option value="">{opening ? t('dialog.loading') : ''}</option>
+                : distros.map(name => <option key={name} value={name}>{name}</option>)}
+            </select>
+          </div>
+          <div className="dww-field">
+            <label className="dww-field-label" htmlFor="dww-path">{t('dialog.path')}</label>
+            <div className="dww-input-row">
+              <input
+                id="dww-path"
+                className="dww-input"
+                value={pathInput}
+                placeholder={t('dialog.pathPlaceholder')}
+                disabled={opening || busy}
+                onChange={event => setPathInput(event.target.value)}
+              />
+              <button type="button" className="dww-check-btn" disabled={opening || busy} onClick={() => void onCheck()}>
+                {t('dialog.check')}
+              </button>
+            </div>
+          </div>
+          <div className="dww-field">
+            <label className="dww-field-label" htmlFor="dww-username">{t('dialog.username')}</label>
+            <input
+              id="dww-username"
+              className="dww-input"
+              value={username}
+              placeholder={t('dialog.usernamePlaceholder')}
+              disabled={opening || busy}
+              autoComplete="off"
+              spellCheck={false}
+              onChange={event => setUsername(event.target.value)}
+            />
+          </div>
+          <div className="dww-feedback">
+            <div className="dww-breadcrumb">{browsePath}</div>
+            <div className="dww-dirlist" onScroll={listScroll}>
+              {browsing ? <div className="dww-dir-empty">{t('dialog.loading')}</div> : (
+                listing?.parent !== null && listing !== null
+                  ? (
+                    <button type="button" className="dww-dir-row dww-dir-row--up" onClick={onUp}>
+                      <WslGlyph size={14} />
+                      <span>{t('dialog.upLevel')}</span>
+                    </button>
+                  )
+                  : null
+              )}
+              {!browsing && (children.length === 0)
+                ? <div className="dww-dir-empty">{t('dialog.browseEmpty')}</div>
+                : children.map(name => (
+                  <button type="button" key={name} className="dww-dir-row" onClick={() => onDrill(name)}>
+                    <WslGlyph size={14} />
+                    <span>{name}</span>
+                  </button>
+                ))}
+            </div>
+          </div>
+        </div>
+        <div className="dww-actions">
+          <button type="button" className="dww-btn" disabled={busy} onClick={maskClick}>{t('dialog.cancel')}</button>
+          <button type="button" className="dww-btn dww-btn--primary" disabled={busy || opening} onClick={() => void onConfirm()}>
+            {busy ? t('dialog.loading') : t('dialog.confirm')}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export type { ApiCall }