dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/lib/listing.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Pure listing helpers for the WSL directory picker, kept dependency-free so
+ * they can be unit-tested without installing the DSH peers the service itself
+ * imports. Ported from `@deepseek-ai/dsh-host-directory-picker-browse` so the
+ * picker behaves exactly like the shipped browse backend on ordinary paths.
+ *
+ * This is a TypeScript source built to `lib/listing.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/listing
+ */
+/** One picker row: a display name, its jump target, and the dot-entry flag. */
+export interface ListingRow {
+    /** The row's display name. */
+    name: string;
+    /** The row's jump target, Windows spelling. */
+    path: string;
+    /** Whether the entry is a dot-entry. */
+    hidden: boolean;
+}
+/**
+ * Whether a path names one fixed filesystem location regardless of process
+ * state. On Windows only drive-qualified (`C:\…`) or complete UNC
+ * (`\\server\share…`) forms qualify — which is what lets a distro root like
+ * `\\wsl.localhost\ubuntu` be adopted as a workspace, while the bare share root
+ * `\\wsl.localhost` is correctly rejected as a directory.
+ *
+ * @param path - candidate path.
+ * @returns whether the path is fully qualified.
+ */
+export declare function fullyQualified(path: string): boolean;
+/**
+ * Ancestor chain from the filesystem root to `target` inclusive — the
+ * breadcrumb rows of a listing, every one a jump target. On a UNC path the walk
+ * terminates at the share root, whose `dirname` is itself.
+ *
+ * The `win32` flavour is explicit, not the platform default: these helpers
+ * serve Windows paths only, and the bare `node:path` functions are POSIX on
+ * Linux, where a UNC path parses as a single relative segment and the chain
+ * collapses to `['.', <whole path>]`. Walking up from inside a distro also
+ * yields the share root WITH its trailing separator (`\\wsl.localhost\ubuntu\`)
+ * — canonicalized by {@link breadcrumbs}, and asserted by the tests.
+ *
+ * `win32.basename` of a drive root (`C:\`) is empty, so the root crumb falls
+ * back to its own path rather than rendering blank.
+ *
+ * @param target - an absolute Windows path.
+ * @returns the ancestry, outermost first.
+ */
+export declare function ancestryCrumbs(target: string): ListingRow[];
+/**
+ * Breadcrumb rows for a level, with the WSL share head prepended for anything
+ * inside a distro.
+ *
+ * Two Windows path quirks make this more than a relabel. `win32.dirname` treats
+ * `\\server\share` as a volume root and never yields the share itself, so the
+ * WSL row has to be synthesized; and `win32.basename` of that same share root is
+ * the empty string, so the distro row is named from the parsed distro instead.
+ * Without both fixes, browsing into a distro would render a blank breadcrumb and
+ * offer no way back to the distro list.
+ *
+ * @param target - the directory being listed.
+ * @param providerRoot - the share root acting as the WSL row's jump target.
+ * @returns breadcrumb rows, outermost first.
+ */
+export declare function breadcrumbs(target: string, providerRoot: string): ListingRow[];
+/**
+ * Insert a streamed candidate into the name-sorted bounded window, evicting the
+ * name-largest candidate when the window exceeds `keep`. Keeps memory O(keep)
+ * regardless of how many children a level holds, so a pathological directory
+ * cannot make the picker allocate one row per entry.
+ *
+ * @template {{name: string}} T
+ * @param window - the name-ascending window, mutated in place.
+ * @param candidate - the streamed candidate to place.
+ * @param keep - the window bound.
+ * @returns true when an eviction happened (the level has more candidates).
+ */
+export declare function boundedInsert<T extends {
+    name: string;
+}>(window: T[], candidate: T, keep: number): boolean;
+/**
+ * The distro-side argv one picker level is listed with.
+ *
+ * `-1` is one entry per line, `-A` keeps dot-entries but drops `.` and `..`,
+ * `-L` follows symlinks so a link to a directory reports as a directory and a
+ * broken link drops out (exactly what the per-entry `stat` the host path used
+ * to pay one 9p round trip for), and `-p` marks directories with the trailing
+ * `/` the parser keys on.
+ *
+ * @param linuxDir - the absolute Linux directory to list.
+ * @returns the argv for the agent or a `wsl.exe --exec` launch.
+ */
+export declare function lsListingArgv(linuxDir: string): string[];
+/**
+ * Parse one `ls -1ALp` listing into the picker's rows.
+ *
+ * A line is a row when it ends with `/` — a directory, or a symlink `-L`
+ * resolved to one; files and dangling links are skipped, matching the host
+ * path's behaviour. The parse reads the listing as UTF-8 lines, so a filename
+ * containing a newline would split into two rows — the same limitation class
+ * the one-shot transport has always had, accepted here with the 9p walk it
+ * replaces.
+ *
+ * @param stdout - the listing's raw stdout.
+ * @param parent - the listed directory, in the UNC form the rows carry.
+ * @param maxEntries - the row bound; a level with more is flagged truncated.
+ * @returns the first `maxEntries` rows and whether the level had more.
+ */
+export declare function parseLsListing(stdout: string | Buffer, parent: string, maxEntries: number): {
+    rows: ListingRow[];
+    truncated: boolean;
+};

package/lib/listing.js

@@ -4,12 +4,14 @@
  * imports. Ported from `@deepseek-ai/dsh-host-directory-picker-browse` so the
  * picker behaves exactly like the shipped browse backend on ordinary paths.
  *
+ * This is a TypeScript source built to `lib/listing.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/listing
  */
-
 import { win32 } from "node:path";
 import { isWslUnc, uncToPosix } from "./paths.js";
-
 /**
  * Whether a path names one fixed filesystem location regardless of process
  * state. On Windows only drive-qualified (`C:\…`) or complete UNC
@@ -21,9 +23,8 @@ import { isWslUnc, uncToPosix } from "./paths.js";
  * @returns whether the path is fully qualified.
  */
 export function fullyQualified(path) {
-  return win32.isAbsolute(path) && /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(path);
+    return win32.isAbsolute(path) && /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(path);
 }
-
 /**
  * Ancestor chain from the filesystem root to `target` inclusive — the
  * breadcrumb rows of a listing, every one a jump target. On a UNC path the walk
@@ -43,18 +44,18 @@ export function fullyQualified(path) {
  * @returns the ancestry, outermost first.
  */
 export function ancestryCrumbs(target) {
-  const crumbs = [];
-  let current = target;
-  for (;;) {
-    const parent = win32.dirname(current);
-    // `basename` of a volume root is empty (`C:\`), so the root crumb falls
-    // back to its own path rather than rendering blank.
-    crumbs.unshift({ name: win32.basename(current) || current, path: current, hidden: false });
-    if (parent === current) return crumbs;
-    current = parent;
-  }
+    const crumbs = [];
+    let current = target;
+    for (;;) {
+        const parent = win32.dirname(current);
+        // `basename` of a volume root is empty (`C:\`), so the root crumb falls
+        // back to its own path rather than rendering blank.
+        crumbs.unshift({ name: win32.basename(current) || current, path: current, hidden: false });
+        if (parent === current)
+            return crumbs;
+        current = parent;
+    }
 }
-
 /**
  * Breadcrumb rows for a level, with the WSL share head prepended for anything
  * inside a distro.
@@ -71,46 +72,57 @@ export function ancestryCrumbs(target) {
  * @returns breadcrumb rows, outermost first.
  */
 export function breadcrumbs(target, providerRoot) {
-  const crumbs = ancestryCrumbs(target);
-  const head = crumbs[0];
-  if (head === undefined) return [{ name: "WSL", path: providerRoot, hidden: false }];
-  const parsed = isWslUnc(head.path) ? uncToPosix(head.path) : undefined;
-  if (parsed !== undefined && parsed.linuxPath === "/") {
-    // `win32.dirname` reports the share root with a trailing separator
-    // (`\\wsl.localhost\ubuntu\`); rewrite the row to the canonical distro root
-    // so crumb paths match what distroRoot() and the picker produce elsewhere.
-    crumbs[0] = { name: parsed.distro, path: `${providerRoot}\\${parsed.distro}`, hidden: false };
-    crumbs.unshift({ name: "WSL", path: providerRoot, hidden: false });
-  }
-  return crumbs;
+    const crumbs = ancestryCrumbs(target);
+    const head = crumbs[0];
+    if (head === undefined)
+        return [{ name: "WSL", path: providerRoot, hidden: false }];
+    const parsed = isWslUnc(head.path) ? uncToPosix(head.path) : undefined;
+    if (parsed !== undefined && parsed.linuxPath === "/") {
+        // `win32.dirname` reports the share root with a trailing separator
+        // (`\\wsl.localhost\ubuntu\`); rewrite the row to the canonical distro root
+        // so crumb paths match what distroRoot() and the picker produce elsewhere.
+        crumbs[0] = { name: parsed.distro, path: `${providerRoot}\\${parsed.distro}`, hidden: false };
+        crumbs.unshift({ name: "WSL", path: providerRoot, hidden: false });
+    }
+    return crumbs;
 }
-
 /**
  * Insert a streamed candidate into the name-sorted bounded window, evicting the
  * name-largest candidate when the window exceeds `keep`. Keeps memory O(keep)
  * regardless of how many children a level holds, so a pathological directory
  * cannot make the picker allocate one row per entry.
  *
+ * @template {{name: string}} T
  * @param window - the name-ascending window, mutated in place.
  * @param candidate - the streamed candidate to place.
  * @param keep - the window bound.
  * @returns true when an eviction happened (the level has more candidates).
  */
 export function boundedInsert(window, candidate, keep) {
-  if (window.length === keep && candidate.name.localeCompare(window[window.length - 1].name) >= 0) return true;
-  let lo = 0;
-  let hi = window.length;
-  while (lo < hi) {
-    const mid = (lo + hi) >>> 1;
-    if (candidate.name.localeCompare(window[mid].name) < 0) hi = mid;
-    else lo = mid + 1;
-  }
-  window.splice(lo, 0, candidate);
-  if (window.length <= keep) return false;
-  window.pop();
-  return true;
+    const last = window.at(-1);
+    if (window.length === keep && last !== undefined && candidate.name.localeCompare(last.name) >= 0)
+        return true;
+    let lo = 0;
+    let hi = window.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const midRow = window[mid];
+        // mid < hi <= window.length, so the row is always defined; the check is
+        // for the checker, and it ends the search instead of throwing if that
+        // invariant were ever broken.
+        if (midRow === undefined)
+            break;
+        if (candidate.name.localeCompare(midRow.name) < 0)
+            hi = mid;
+        else
+            lo = mid + 1;
+    }
+    window.splice(lo, 0, candidate);
+    if (window.length <= keep)
+        return false;
+    window.pop();
+    return true;
 }
-
 /**
  * The distro-side argv one picker level is listed with.
  *
@@ -124,9 +136,8 @@ export function boundedInsert(window, candidate, keep) {
  * @returns the argv for the agent or a `wsl.exe --exec` launch.
  */
 export function lsListingArgv(linuxDir) {
-  return ["ls", "-1ALp", "--", linuxDir];
+    return ["ls", "-1ALp", "--", linuxDir];
 }
-
 /**
  * Parse one `ls -1ALp` listing into the picker's rows.
  *
@@ -143,17 +154,19 @@ export function lsListingArgv(linuxDir) {
  * @returns the first `maxEntries` rows and whether the level had more.
  */
 export function parseLsListing(stdout, parent, maxEntries) {
-  const rows = [];
-  let truncated = false;
-  for (const line of String(stdout).split("\n")) {
-    if (!line.endsWith("/")) continue;
-    const name = line.slice(0, -1);
-    if (name.length === 0) continue;
-    if (rows.length === maxEntries) {
-      truncated = true;
-      break;
+    const rows = [];
+    let truncated = false;
+    for (const line of String(stdout).split("\n")) {
+        if (!line.endsWith("/"))
+            continue;
+        const name = line.slice(0, -1);
+        if (name.length === 0)
+            continue;
+        if (rows.length === maxEntries) {
+            truncated = true;
+            break;
+        }
+        rows.push({ name, path: win32.join(parent, name), hidden: name.startsWith(".") });
     }
-    rows.push({ name, path: win32.join(parent, name), hidden: name.startsWith(".") });
-  }
-  return { rows, truncated };
+    return { rows, truncated };
 }

package/lib/paths.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Path translation between the three coordinate systems a WSL-backed session
+ * touches:
+ *
+ *   1. Linux/POSIX paths inside the distro   /home/andy/proj/src/a.ts
+ *   2. WSL's Windows UNC share               \\wsl.localhost\ubuntu\home\andy\proj\src\a.ts
+ *   3. The Windows filesystem itself         C:\Users\andyz\...  ->  /mnt/c/Users/andyz/...
+ *
+ * The harness host can reach (2) directly with Node's fs, which is what makes
+ * reads and ripgrep searches work without any in-distro helper. Commands must
+ * run inside the distro, so the shell executor speaks (1).
+ *
+ * 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
+ */
+/** A distro identity and the Linux path inside it, as {@link uncToPosix} returns. */
+export interface DistroPath {
+    /** The distro name the UNC named. */
+    distro: string;
+    /** An absolute POSIX path inside that distro. */
+    linuxPath: string;
+}
+/**
+ * What the two world-path translators may consult: the pinned distro and the
+ * fallback directory for relative input.
+ */
+export interface WorldPathOptions {
+    /**
+     * The pinned distro, which maps a POSIX-absolute input onto its UNC identity
+     * in {@link toWorldPath}.
+     */
+    distro?: string;
+    /** The directory relative input resolves against. */
+    cwd?: string;
+}
+/**
+ * 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 declare function isWslUnc(value: string): boolean;
+/**
+ * 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 declare function isPosixAbsolute(value: string): boolean;
+/**
+ * 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 declare function isRelativeWorldPath(value: string): boolean;
+/**
+ * Whether a world path is a granted root or lies beneath it, compared in the
+ * coordinate system the two spellings share.
+ *
+ * A grant is written in the vocabulary of the world it governs: the Windows
+ * sandbox hands out drive and UNC paths, while a distro-side grant is a Linux
+ * path such as `/tmp`. Passing the distro maps a Linux grant onto the same UNC
+ * share as the target, so `\\wsl.localhost\ubuntu\home\andy` can be compared
+ * with `/home/andy`. Mixed pairs that share no vocabulary report no containment
+ * — the conservative answer, never a textual guess.
+ *
+ * @param target - the path being tested, in any coordinate system.
+ * @param root - the granted root, in any coordinate system.
+ * @param options - the distro that maps a Linux root onto its UNC share.
+ * @returns true when target is root itself or a descendant of it.
+ */
+export declare function isWorldPathUnder(target: string, root: string, options?: WorldPathOptions): boolean;
+/**
+ * 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 declare function posixToUnc(distro: string, linuxPath: string): string;
+/**
+ * Map a WSL UNC path back onto the distro and Linux path it names.
+ *
+ * @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 declare function uncToPosix(uncPath?: string): DistroPath | undefined;
+/**
+ * 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 declare function isUnderDistro(uncPath: string, distro: string): boolean;
+/**
+ * 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 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 declare function isAnotherDistrosUnc(value: string, distro: string): boolean;
+/**
+ * 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 declare function windowsToLinuxMount(winPath: string): string | undefined;
+/**
+ * Resolve a caller-supplied workdir into a path `wsl.exe --cd` accepts.
+ *
+ * Accepts every coordinate system, because the tool layer passes whatever the
+ * session cwd is (a UNC path once the workspace is a WSL folder) while a human
+ * editing the profile is likely to write a plain Linux path.
+ *
+ * @param value - the path to translate.
+ * @param options - the pinned distro and the fallback directory for relative input.
+ * @returns an absolute Linux path, or the input unchanged when it cannot be mapped.
+ */
+export declare function toLinuxPath(value: string, options?: WorldPathOptions): string;
+/**
+ * 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
+ * Windows paths from the host all have to land somewhere real.
+ *
+ * @param value - the path to translate.
+ * @param options - the PINNED DISTRO (required: a POSIX-absolute input mints
+ *   its UNC identity) and the fallback directory for relative input.
+ * @returns an absolute host path (UNC for anything inside the distro).
+ */
+export declare function toWorldPath(value: string, options?: WorldPathOptions): string;
+/**
+ * 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.
+ * `FsTarget.targetKey` stays the UNC path (the contract treats it as opaque);
+ * only `displayPath` is rewritten.
+ *
+ * @param worldPath - an absolute host path.
+ * @param distro - the distro whose paths should be shown as Linux paths.
+ * @returns the display path.
+ */
+export declare function toDisplayPath(worldPath: string, distro: string): string;
+/** The provider root of the WSL UNC share — the level that holds one entry per distro. */
+export declare 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
+ * picker's fully-qualified check requires and what the workspace registry
+ * accepts as a project directory.
+ *
+ * @param distro - distro name.
+ * @returns e.g. `\\wsl.localhost\ubuntu`.
+ */
+export declare function distroRoot(distro: string): string;
+/**
+ * Whether a path names the WSL share's root rather than a distro inside it.
+ * Both share spellings and a trailing separator are accepted.
+ *
+ * @param value - candidate path.
+ * @returns true for `\\wsl.localhost` and `\\wsl$` in any casing.
+ */
+export declare function isProviderRoot(value: string): boolean;