dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/paths.js

@@ -13,89 +13,106 @@
  * These helpers are pure and dependency-free so they can be unit-tested without
  * booting Cordis.
  *
+ * This is a TypeScript source built to `lib/paths.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/paths
  */
-
 /** The WSL UNC share prefix Node can read. `\\wsl$\<distro>\...` is the legacy spelling. */
 const UNC_RE = /^\\\\wsl(?:\.localhost|\$)\\([^\\]+)(?:\\([\s\S]*))?$/i;
 const DRIVE_RE = /^([A-Za-z]):[\\/]([\s\S]*)$/;
-
-/** Normalize Windows separators without touching a POSIX path. */
+/**
+ * Normalize Windows separators without touching a POSIX path.
+ *
+ * @param value - the path to normalize.
+ * @returns the same path with `/` written as `\`.
+ */
 function toWindowsSlashes(value) {
-  return String(value).replace(/\//g, "\\");
+    return String(value).replace(/\//g, "\\");
 }
-
 /**
  * Whether a string is the WSL UNC share rather than an ordinary Windows path.
+ *
  * @param value - candidate path.
  * @returns true for `\\wsl.localhost\...` and `\\wsl$\...`.
  */
 export function isWslUnc(value) {
-  return UNC_RE.test(String(value));
+    return UNC_RE.test(String(value));
 }
-
 /**
  * Whether a string is POSIX-absolute. On Windows `path.isAbsolute('/home/x')`
  * is also true, so the WSL mapper must test this before falling back to the
  * host helpers.
+ *
  * @param value - candidate path.
  * @returns true when the path starts with a single forward slash.
  */
 export function isPosixAbsolute(value) {
-  return /^\/(?!\/)/.test(String(value));
+    return /^\/(?!\/)/.test(String(value));
 }
-
 /**
  * Whether a path names a location only relative to a base. The fs provider
  * consults its default workdir exactly for this input; every absolute form —
  * POSIX, drive, WSL UNC, or any other UNC share — is a location in its own
  * right and short-circuits before a base is ever needed.
+ *
  * @param value - candidate path.
  * @returns true when the path names no absolute location.
  */
 export function isRelativeWorldPath(value) {
-  const text = String(value ?? "");
-  if (text.length === 0) return false;
-  return !isWslUnc(text) && !isPosixAbsolute(text) && !DRIVE_RE.test(text) && !text.startsWith("\\");
+    const text = String(value ?? "");
+    if (text.length === 0)
+        return false;
+    return !isWslUnc(text) && !isPosixAbsolute(text) && !DRIVE_RE.test(text) && !text.startsWith("\\");
 }
-
-/** Drop trailing separators, keeping a bare root (`C:\`, `\\wsl.localhost\x\`) meaningful. */
+/**
+ * Drop trailing separators, keeping a bare root (`C:\`, `\\wsl.localhost\x\`) meaningful.
+ *
+ * @param value - the path to trim.
+ * @returns the path without its trailing separators.
+ */
 function trimTrailingSeparators(value) {
-  return value.replace(/[\\/]+$/, "") || value;
+    return value.replace(/[\\/]+$/, "") || value;
 }
-
 /**
  * A UNC, drive, or (with a distro) Linux path as a comparable Windows key.
  * Windows semantics are case-insensitive and separator-tolerant, so the key is
  * lowercased and backslashed; a Linux path maps onto the distro's UNC share so
  * it can be compared with a target reached through that share.
+ *
  * @param value - the path to key.
  * @param distro - the distro whose share a Linux path maps onto, if any.
  * @returns the key, or undefined when the path is not in that vocabulary.
  */
 function toWindowsKey(value, distro) {
-  const text = String(value ?? "");
-  if (text.length === 0) return undefined;
-  if (DRIVE_RE.test(text) || isWslUnc(text)) {
-    const key = trimTrailingSeparators(toWindowsSlashes(text)).toLowerCase();
-    // A drive root trims to `c:`; without its separator back the prefix test
-    // would accept a sibling like `C:\ish` as a child of `C:\`.
-    return /^[a-z]:$/.test(key) ? `${key}\\` : key;
-  }
-  if (distro !== undefined && distro !== "" && isPosixAbsolute(text)) {
-    return trimTrailingSeparators(toWindowsSlashes(posixToUnc(distro, text))).toLowerCase();
-  }
-  return undefined;
+    const text = String(value ?? "");
+    if (text.length === 0)
+        return undefined;
+    if (DRIVE_RE.test(text) || isWslUnc(text)) {
+        const key = trimTrailingSeparators(toWindowsSlashes(text)).toLowerCase();
+        // A drive root trims to `c:`; without its separator back the prefix test
+        // would accept a sibling like `C:\ish` as a child of `C:\`.
+        return /^[a-z]:$/.test(key) ? `${key}\\` : key;
+    }
+    if (distro !== undefined && distro !== "" && isPosixAbsolute(text)) {
+        return trimTrailingSeparators(toWindowsSlashes(posixToUnc(distro, text))).toLowerCase();
+    }
+    return undefined;
 }
-
-/** A POSIX-absolute path as a comparable key, without its trailing separators. */
+/**
+ * A POSIX-absolute path as a comparable key, without its trailing separators.
+ *
+ * @param value - the path to key.
+ * @returns the key, or undefined when the path is not POSIX-absolute.
+ */
 function toPosixKey(value) {
-  const text = String(value ?? "");
-  if (!isPosixAbsolute(text)) return undefined;
-  const trimmed = text.replace(/\/+$/, "");
-  return trimmed.length === 0 ? "/" : trimmed;
+    const text = String(value ?? "");
+    if (!isPosixAbsolute(text))
+        return undefined;
+    const trimmed = text.replace(/\/+$/, "");
+    return trimmed.length === 0 ? "/" : trimmed;
 }
-
 /**
  * Whether a world path is a granted root or lies beneath it, compared in the
  * coordinate system the two spellings share.
@@ -113,83 +130,86 @@ function toPosixKey(value) {
  * @returns true when target is root itself or a descendant of it.
  */
 export function isWorldPathUnder(target, root, options = {}) {
-  const winTarget = toWindowsKey(target, options.distro);
-  const winRoot = toWindowsKey(root, options.distro);
-  if (winTarget !== undefined && winRoot !== undefined) {
-    // A drive root keeps its separator in the key, so the child boundary is
-    // "root already ends with one" rather than "append another".
-    const prefix = winRoot.endsWith("\\") ? winRoot : `${winRoot}\\`;
-    return winTarget === winRoot || winTarget.startsWith(prefix);
-  }
-  const posixTarget = toPosixKey(target);
-  const posixRoot = toPosixKey(root);
-  if (posixTarget !== undefined && posixRoot !== undefined) {
-    return posixRoot === "/" || posixTarget === posixRoot || posixTarget.startsWith(`${posixRoot}/`);
-  }
-  return false;
+    const winTarget = toWindowsKey(target, options.distro);
+    const winRoot = toWindowsKey(root, options.distro);
+    if (winTarget !== undefined && winRoot !== undefined) {
+        // A drive root keeps its separator in the key, so the child boundary is
+        // "root already ends with one" rather than "append another".
+        const prefix = winRoot.endsWith("\\") ? winRoot : `${winRoot}\\`;
+        return winTarget === winRoot || winTarget.startsWith(prefix);
+    }
+    const posixTarget = toPosixKey(target);
+    const posixRoot = toPosixKey(root);
+    if (posixTarget !== undefined && posixRoot !== undefined) {
+        return posixRoot === "/" || posixTarget === posixRoot || posixTarget.startsWith(`${posixRoot}/`);
+    }
+    return false;
 }
-
 /**
  * Map a Linux path inside a distro onto the UNC path the host can read.
+ *
  * @param distro - distro name, e.g. `ubuntu`.
  * @param linuxPath - absolute Linux path, e.g. `/home/andy/proj`.
  * @returns the equivalent `\\wsl.localhost\<distro>\...` path.
  */
 export function posixToUnc(distro, linuxPath) {
-  const rest = String(linuxPath).replace(/^\/+/, "").replace(/\//g, "\\");
-  return `\\\\wsl.localhost\\${distro}\\${rest}`.replace(/\\+$/, "\\");
+    const rest = String(linuxPath).replace(/^\/+/, "").replace(/\//g, "\\");
+    return `\\\\wsl.localhost\\${distro}\\${rest}`.replace(/\\+$/, "\\");
 }
-
 /**
  * Map a WSL UNC path back onto the distro and Linux path it names.
- * @param uncPath - a `\\wsl.localhost\<distro>\...` path.
- * @returns `{ distro, linuxPath }`, or undefined for any other path.
+ *
+ * @param uncPath - a `\\wsl.localhost\<distro>\...` path; absent is not a UNC path.
+ * @returns the distro and Linux path, or undefined for any other path.
  */
 export function uncToPosix(uncPath) {
-  const match = UNC_RE.exec(String(uncPath));
-  if (!match?.[1]) return undefined;
-  const rest = (match[2] ?? "").replace(/\\/g, "/");
-  return { distro: match[1], linuxPath: rest.length > 0 ? `/${rest}` : "/" };
+    const match = UNC_RE.exec(String(uncPath));
+    if (!match?.[1])
+        return undefined;
+    const rest = (match[2] ?? "").replace(/\\/g, "/");
+    return { distro: match[1], linuxPath: rest.length > 0 ? `/${rest}` : "/" };
 }
-
 /**
  * Whether a UNC path belongs to the named distro. Used to confine the WSL
  * filesystem backend to one distro instead of silently serving every mounted
  * share.
+ *
  * @param uncPath - candidate UNC path.
  * @param distro - the distro this session is pinned to.
  * @returns true when the path is the same distro (case-insensitive).
  */
 export function isUnderDistro(uncPath, distro) {
-  const parsed = uncToPosix(uncPath);
-  return parsed !== undefined && parsed.distro.toLowerCase() === String(distro).toLowerCase();
+    const parsed = uncToPosix(uncPath);
+    return parsed !== undefined && parsed.distro.toLowerCase() === String(distro).toLowerCase();
 }
-
 /**
  * A WSL UNC that names a distro OTHER than the pinned one — the shape both
  * shell seams refuse: the shell executor will not run commands in it (running
  * there would mean silently switching distros on path similarity), and the
  * shell-env facts describe only the pinned distro, so a foreign session gets
  * no facts rather than another distro's home and shell.
- * @param uncPath - the candidate path (any spelling; non-UNC values are not foreign).
+ *
+ * @param value - the candidate path (any spelling; non-UNC values are not foreign).
  * @param distro - the pinned distro name.
  * @returns true when the value is a WSL UNC under a different distro.
  */
 export function isAnotherDistrosUnc(value, distro) {
-  return isWslUnc(value) && !isUnderDistro(value, distro);
+    return isWslUnc(value) && !isUnderDistro(value, distro);
 }
-
 /**
  * Translate a Windows drive path into its WSL interop mount.
+ *
  * @param winPath - e.g. `C:\Users\andyz\Documents`.
  * @returns e.g. `/mnt/c/Users/andyz/Documents`, or undefined for a non-drive path.
  */
 export function windowsToLinuxMount(winPath) {
-  const match = DRIVE_RE.exec(String(winPath));
-  if (!match?.[1]) return undefined;
-  return `/mnt/${match[1].toLowerCase()}/${match[2].replace(/\\/g, "/")}`;
+    const match = DRIVE_RE.exec(String(winPath));
+    const drive = match?.[1];
+    const rest = match?.[2];
+    if (drive === undefined || rest === undefined)
+        return undefined;
+    return `/mnt/${drive.toLowerCase()}/${rest.replace(/\\/g, "/")}`;
 }
-
 /**
  * Resolve a caller-supplied workdir into a path `wsl.exe --cd` accepts.
  *
@@ -202,19 +222,22 @@ export function windowsToLinuxMount(winPath) {
  * @returns an absolute Linux path, or the input unchanged when it cannot be mapped.
  */
 export function toLinuxPath(value, options) {
-  const text = String(value ?? "");
-  if (text.length === 0) return text;
-  const parsed = uncToPosix(text);
-  if (parsed !== undefined) return parsed.linuxPath;
-  if (isPosixAbsolute(text)) return text;
-  const mounted = windowsToLinuxMount(text);
-  if (mounted !== undefined) return mounted;
-  // Relative input is resolved against the configured default workdir.
-  const base = options?.cwd ?? "/";
-  const baseLinux = toLinuxPath(base, { distro: options?.distro });
-  return `${baseLinux.replace(/\/+$/, "")}/${text.replace(/^\.\//, "")}`;
+    const text = String(value ?? "");
+    if (text.length === 0)
+        return text;
+    const parsed = uncToPosix(text);
+    if (parsed !== undefined)
+        return parsed.linuxPath;
+    if (isPosixAbsolute(text))
+        return text;
+    const mounted = windowsToLinuxMount(text);
+    if (mounted !== undefined)
+        return mounted;
+    // Relative input is resolved against the configured default workdir.
+    const base = options?.cwd ?? "/";
+    const baseLinux = toLinuxPath(base, { distro: options?.distro });
+    return `${baseLinux.replace(/\/+$/, "")}/${text.replace(/^\.\//, "")}`;
 }
-
 /**
  * Resolve a caller-supplied path into the UNC coordinate system the host's fs
  * calls use. Linux paths from the model, UNC paths from the harness, and
@@ -226,25 +249,29 @@ export function toLinuxPath(value, options) {
  * @returns an absolute host path (UNC for anything inside the distro).
  */
 export function toWorldPath(value, options) {
-  const text = String(value ?? "");
-  if (text.length === 0) return text;
-  if (isWslUnc(text)) return toWindowsSlashes(text);
-  // No distro fallback: an identity minted under a guessed distro name would
-  // address a filesystem that does not exist.
-  if (isPosixAbsolute(text)) {
-    if (!options?.distro) return text;
-    return posixToUnc(options.distro, text);
-  }
-  if (DRIVE_RE.test(text)) return toWindowsSlashes(text);
-  // Any other UNC share is already a world path in its own right — the host
-  // can open it directly, and joining it onto a base would name a file that
-  // exists nowhere.
-  if (text.startsWith("\\")) return toWindowsSlashes(text);
-  const base = options?.cwd ?? process.cwd();
-  const baseWorld = toWorldPath(base, { distro: options?.distro });
-  return `${baseWorld.replace(/[\\/]+$/, "")}\\${toWindowsSlashes(text).replace(/^\.\\/, "")}`;
+    const text = String(value ?? "");
+    if (text.length === 0)
+        return text;
+    if (isWslUnc(text))
+        return toWindowsSlashes(text);
+    // No distro fallback: an identity minted under a guessed distro name would
+    // address a filesystem that does not exist.
+    if (isPosixAbsolute(text)) {
+        if (!options?.distro)
+            return text;
+        return posixToUnc(options.distro, text);
+    }
+    if (DRIVE_RE.test(text))
+        return toWindowsSlashes(text);
+    // Any other UNC share is already a world path in its own right — the host
+    // can open it directly, and joining it onto a base would name a file that
+    // exists nowhere.
+    if (text.startsWith("\\"))
+        return toWindowsSlashes(text);
+    const base = options?.cwd ?? process.cwd();
+    const baseWorld = toWorldPath(base, { distro: options?.distro });
+    return `${baseWorld.replace(/[\\/]+$/, "")}\\${toWindowsSlashes(text).replace(/^\.\\/, "")}`;
 }
-
 /**
  * Render a world path back into the form the model and the UI should see: a
  * Linux path inside the distro, and the ordinary Windows path everywhere else.
@@ -256,14 +283,13 @@ export function toWorldPath(value, options) {
  * @returns the display path.
  */
 export function toDisplayPath(worldPath, distro) {
-  const parsed = uncToPosix(worldPath);
-  if (parsed !== undefined && parsed.distro.toLowerCase() === String(distro).toLowerCase()) return parsed.linuxPath;
-  return String(worldPath);
+    const parsed = uncToPosix(worldPath);
+    if (parsed !== undefined && parsed.distro.toLowerCase() === String(distro).toLowerCase())
+        return parsed.linuxPath;
+    return String(worldPath);
 }
-
 /** The provider root of the WSL UNC share — the level that holds one entry per distro. */
 export const UNC_PROVIDER_ROOT = "\\\\wsl.localhost";
-
 /**
  * The UNC root of one distro, which is the mount point of that distro's `/`.
  * This is a complete UNC path (`\\server\share`), which is what the directory
@@ -274,9 +300,8 @@ export const UNC_PROVIDER_ROOT = "\\\\wsl.localhost";
  * @returns e.g. `\\wsl.localhost\ubuntu`.
  */
 export function distroRoot(distro) {
-  return `${UNC_PROVIDER_ROOT}\\${distro}`;
+    return `${UNC_PROVIDER_ROOT}\\${distro}`;
 }
-
 /**
  * Whether a path names the WSL share's root rather than a distro inside it.
  * Both share spellings and a trailing separator are accepted.
@@ -285,6 +310,6 @@ export function distroRoot(distro) {
  * @returns true for `\\wsl.localhost` and `\\wsl$` in any casing.
  */
 export function isProviderRoot(value) {
-  const trimmed = String(value).replace(/[\\/]+$/, "").toLowerCase();
-  return trimmed === UNC_PROVIDER_ROOT.toLowerCase() || trimmed === "\\\\wsl$";
+    const trimmed = String(value).replace(/[\\/]+$/, "").toLowerCase();
+    return trimmed === UNC_PROVIDER_ROOT.toLowerCase() || trimmed === "\\\\wsl$";
 }

package/lib/picker.d.ts

@@ -0,0 +1,266 @@
+/**
+ * WSL-aware directory picker: the `ctx.directoryPicker` backend that makes the
+ * Web GUI's "Select Workspace Directory" dialog open inside a distro.
+ *
+ * ## Why this serves `kind: 'browse'` instead of declaring a `wsl` kind
+ *
+ * The seam's capability is a merge-extensible discriminated union, so adding a
+ * `wsl` kind looks like the natural move. It does not work, and the reason is
+ * worth stating plainly: the capability is **not** what crosses the wire.
+ * `dsh-api-workspace-controller` exposes exactly three Remote verbs and pins
+ * each to a literal kind —
+ *
+ *     pick(signal)             -> requireCapability('native', 'pick')
+ *     list(path, signal)       -> requireCapability('browse', 'list')
+ *     createDirectory(...)     -> requireCapability('browse', 'createDirectory')
+ *
+ * — and refuses anything else with `directory-picker/unavailable`. A backend
+ * reporting `{ kind: 'wsl', ... }` would therefore break the very verbs it
+ * needs, because `requireCapability('browse', ...)` would no longer match. The
+ * wire vocabulary lives in a shipped, versioned package inside `app.asar`, so
+ * adding a third kind means patching an asar package that the next app update
+ * overwrites.
+ *
+ * Serving `browse` is not a workaround, it is the fit: `browse`'s primitives are
+ * "list one absolute directory level" and "create one child directory", which is
+ * exactly what browsing a distro needs. The only thing the shipped browse
+ * backend lacks is *discoverability* of WSL — it opens at the Windows home
+ * directory. This backend closes that gap:
+ *
+ *   - the root level lists the installed distros (`wsl.exe -l -q`), so WSL is
+ *     the entry point rather than something you must know a UNC path for;
+ *   - the breadcrumb "WSL" row jumps back to that distro list;
+ *   - the dialog's Home affordance targets the preferred distro's Linux `$HOME`;
+ *   - every other level inside a distro is listed BY THE DISTRO — the resident
+ *     agent's `ls` when it is up, a one-shot `wsl.exe --exec ls` when it is
+ *     out — because the host's own listing used to walk the 9p share in its
+ *     slow direction, one metadata round trip per entry; a Windows path keeps
+ *     the host's own walk, which is native there.
+ *
+ * Because the client surface is unchanged, this row composes with the **shipped**
+ * `@deepseek-ai/dsh-client-ui-directory-picker-browse` dialog: no client code,
+ * no wire change, no asar patch.
+ *
+ * This is a TypeScript source built to `lib/picker.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/picker
+ */
+import z from "@deepseek-ai/schemastery";
+import { DirectoryPicker } from "@deepseek-ai/dsh-host-directory-picker";
+import type { Context } from "@deepseek-ai/cordis";
+import type { DirectoryEntry, DirectoryListing, DirectoryPickerBrowseCapability } from "@deepseek-ai/dsh-host-directory-picker";
+/**
+ * The resolved service configuration, as {@link WslDirectoryPicker.Config} yields.
+ */
+export interface PickerConfig {
+    /** Path to `wsl.exe`; overridable for a non-standard install. */
+    wslPath: string;
+    /**
+     * Distro listed first and used for the Home affordance; empty means WSL's
+     * own default distro.
+     */
+    preferredDistro: string;
+    /**
+     * Whether the Windows home is also offered at the root level.
+     */
+    includeHostHome: boolean;
+    /**
+     * Bound on the directory rows one `list` call may return; the level is
+     * flagged truncated beyond it.
+     */
+    maxEntries: number;
+    /** How long a resolved distro list stays fresh. */
+    distroCacheMs: number;
+}
+/**
+ * Await `operation`, but reject with the signal's reason the moment it aborts.
+ * Node's filesystem reads are not retractable, so the operation itself keeps
+ * running against a handle the caller then closes; its late settlement is
+ * swallowed so an abandoned read cannot surface as an unhandled rejection.
+ *
+ * @template T
+ * @param operation - the in-flight filesystem step.
+ * @param signal - caller lifetime; absent means plain awaiting.
+ * @returns the operation's value.
+ */
+export declare function raceAbort<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T>;
+/**
+ * The `ctx.directoryPicker` WSL implementation.
+ *
+ * The capability object is built once per service lifetime because consumers may
+ * capture it across calls.
+ */
+export declare class WslDirectoryPicker extends DirectoryPicker {
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        /** Path to `wsl.exe`; overridable for a non-standard install. */
+        wslPath: z<string, string, "defined">;
+        /**
+         * Distro listed first and used for the Home affordance. Empty means WSL's
+         * own default distro.
+         */
+        preferredDistro: z<string, string, "defined">;
+        /**
+         * Also offer the Windows home directory at the root level, so a normal
+         * host folder stays reachable without typing a path. The dialog's editable
+         * path zone accepts any Windows path either way.
+         */
+        includeHostHome: z<boolean, boolean, "defined">;
+        /** Bound on the directory rows one `list` call may return; the level is flagged truncated. */
+        maxEntries: z<number, number, "defined">;
+        /** How long a resolved distro list stays fresh. */
+        distroCacheMs: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        /** Path to `wsl.exe`; overridable for a non-standard install. */
+        wslPath: z<string, string, "defined">;
+        /**
+         * Distro listed first and used for the Home affordance. Empty means WSL's
+         * own default distro.
+         */
+        preferredDistro: z<string, string, "defined">;
+        /**
+         * Also offer the Windows home directory at the root level, so a normal
+         * host folder stays reachable without typing a path. The dialog's editable
+         * path zone accepts any Windows path either way.
+         */
+        includeHostHome: z<boolean, boolean, "defined">;
+        /** Bound on the directory rows one `list` call may return; the level is flagged truncated. */
+        maxEntries: z<number, number, "defined">;
+        /** How long a resolved distro list stays fresh. */
+        distroCacheMs: z<number, number, "defined">;
+    }>>, "plain">;
+    /** The resolved {@link WslDirectoryPicker.Config}. */
+    config: PickerConfig;
+    /** Last distro listing, so navigating to the root does not spawn `wsl.exe` every time. */
+    distroCache: {
+        at: number;
+        value: string[];
+    } | undefined;
+    /** Per-distro Linux home, resolved once (a distro's default user does not change under a running session). */
+    homeCache: Map<string, string>;
+    /**
+     * @param ctx - the owning context.
+     * @param config - the resolved {@link WslDirectoryPicker.Config}.
+     */
+    constructor(ctx: Context, config: PickerConfig);
+    /**
+     * The browse interaction capability.
+     *
+     * Deliberately `browse` and not a `wsl` kind: see the module comment. The
+     * distro listing is exposed as {@link WslDirectoryPicker.distros} for
+     * programmatic callers instead of through the capability union, because a
+     * capability kind the wire controller does not recognise would disable the
+     * verbs above rather than add a new one.
+     *
+     * @returns the stable `browse` capability object.
+     */
+    capability(): DirectoryPickerBrowseCapability;
+    browseCapability: DirectoryPickerBrowseCapability;
+    /**
+     * Installed distros, cached briefly.
+     *
+     * @param signal - optional cancellation.
+     * @returns distro names, default distro first.
+     */
+    distros(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * The distro this picker leads with: the configured one when installed, else
+     * WSL's default, else the first installed.
+     *
+     * @param signal - optional cancellation.
+     * @returns a distro name, or empty when none is installed.
+     */
+    preferredDistro(signal?: AbortSignal): Promise<string>;
+    /**
+     * A distro's Linux home directory as a UNC path, best effort: a distro that
+     * cannot be queried (stopped, and unable to start) falls back to its root so
+     * the dialog still opens somewhere real.
+     *
+     * @param distro - distro name.
+     * @param signal - optional cancellation.
+     * @returns the UNC home path.
+     */
+    homeOf(distro: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * The root level: one row per installed distro, plus the Windows home when
+     * configured. `path` is the preferred distro's root rather than the share
+     * root, so adopting the level with nothing selected still yields a real
+     * directory; the breadcrumb's "WSL" row carries the share root and returns
+     * here.
+     *
+     * @param signal - optional cancellation.
+     * @returns the root listing.
+     */
+    rootLevel(signal?: AbortSignal): Promise<DirectoryListing>;
+    /**
+     * Breadcrumb rows for a level, headed by the WSL row.
+     *
+     * @param target - the directory being listed.
+     * @returns breadcrumb rows.
+     */
+    crumbsFor(target: string): DirectoryEntry[];
+    /**
+     * List one directory level.
+     *
+     * @param path - absolute directory; absent or the share root lists the distros.
+     * @param signal - caller lifetime.
+     * @returns the level's listing with its ancestry.
+     * @throws DirectoryPickerError with code `directory-unreadable`.
+     */
+    list(path?: string, signal?: AbortSignal): Promise<DirectoryListing>;
+    /**
+     * List one level inside the distro, where the files live.
+     *
+     * The resident agent answers in one round trip; when it is out — distro
+     * stopped, or the resident's rebuild budget spent — the same `ls` runs
+     * through a one-shot `wsl.exe`. Neither path touches the 9p share, which is
+     * what the host walk it replaces used: one metadata round trip per entry,
+     * in the share's slow direction, plus one more per symlink.
+     *
+     * @param target - the absolute UNC directory to list.
+     * @param signal - caller lifetime.
+     * @returns the level's rows and truncation flag.
+     * @throws DirectoryPickerError with code `directory-unreadable`.
+     */
+    listDistroLevel(target: string, signal?: AbortSignal): Promise<{
+        rows: DirectoryEntry[];
+        truncated: boolean;
+    }>;
+    /**
+     * List one Windows level with the host's own walk — native I/O on a native
+     * filesystem, unchanged from the shipped browse behaviour.
+     *
+     * @param target - the absolute Windows directory to list.
+     * @param signal - caller lifetime.
+     * @returns the level's rows and truncation flag.
+     * @throws DirectoryPickerError with code `directory-unreadable`.
+     */
+    listHostLevel(target: string, signal?: AbortSignal): Promise<{
+        rows: DirectoryEntry[];
+        truncated: boolean;
+    }>;
+    /**
+     * Create one child directory inside the listed level.
+     *
+     * @param path - absolute existing parent directory.
+     * @param name - single non-blank path segment.
+     * @returns the created directory's absolute path.
+     * @throws DirectoryPickerError with code `directory-exists` or `directory-create-failed`.
+     */
+    createDirectory(path: string, name: string): Promise<string>;
+    /**
+     * Create one child directory inside the distro — the resident agent's
+     * `mkdir` when it is up, a one-shot `wsl.exe --exec mkdir` when it is out;
+     * the host's `mkdir` over the 9p share is what this replaces.
+     *
+     * @param parent - the absolute UNC parent directory.
+     * @param name - the validated single path segment to create.
+     * @param target - the UNC path the caller receives on success.
+     * @returns the created directory's absolute path.
+     * @throws DirectoryPickerError with code `directory-exists` or `directory-create-failed`.
+     */
+    createDistroDirectory(parent: string, name: string, target: string): Promise<string>;
+}
+export default WslDirectoryPicker;
+export { ancestryCrumbs, boundedInsert, breadcrumbs, fullyQualified } from "./listing.js";