dsh-plugin-wsl-env 0.6.0 → 0.7.3

package/lib/file-reference-wsl.js

@@ -0,0 +1,284 @@
+/**
+ * The distro-side traversal strategy for `@` completion — the plugin's
+ * ready answer to RFC addendum ① (docs/upstream/rfc-wsl-workspaces.md).
+ *
+ * ## The seam this consumes
+ *
+ * `@deepseek-ai/dsh-file-reference-local` funnels every workspace traversal
+ * through three module-internal functions: `readWorkspaceRoot` and
+ * `readDirectory` (both `node:fs/promises` readdir with `withFileTypes`) and
+ * `resolveDisplayDirectory` (a lexical resolve plus a per-segment `lstat`
+ * walk that refuses symlink and non-directory components). Everything else —
+ * the fuzzy ranking, the bounded index, the generation/invalidation dance,
+ * the excluded-directory list — is pure logic over the entries those three
+ * return. Addendum ① proposes exposing the three as an injectable strategy
+ * with the current implementations as defaults; this module is the consumer
+ * side, built and tested against that interface so the takeover lands the
+ * day the seam does.
+ *
+ * It is deliberately NOT wired into cordis.patch.yml yet: with the seam
+ * absent, reaching the funnels would mean subclassing past module-internal
+ * functions or re-implementing the ranking engine — the behavior-regression
+ * path the RFC rules out. The module ships, tested, until upstream speaks.
+ *
+ * ## Semantics, held faithful where the seam allows
+ *
+ * - Entries keep upstream's Dirent shape: `{name, isDirectory(), isFile()}`.
+ *   The distro listing uses `find -printf '%y\t%f'` rather than `ls -1ALp`
+ *   precisely for this: `%y` reports `l` for symlinks, which the parse skips
+ *   the way a readdir Dirent is neither file nor directory. `ls -1ALp` would
+ *   resolve links through and change which candidates exist.
+ * - `resolveDisplayDirectory` refuses a symlink or non-directory component
+ *   with one agent exec that walks the (lexically normalized) segments —
+ *   the same verdict upstream reaches with N sequential lstats, and unlike
+ *   `realpath`, refusing is the point, not resolving.
+ * - A directory the traversal cannot read yields `[]` (upstream's readdir
+ *   catch); an aborted caller propagates the abort instead.
+ * - The returned absolutes stay in the root's own coordinate system (UNC for
+ *   a distro workspace), because upstream joins children with the host
+ *   `node:path` — a POSIX path from this layer would be mangled by it.
+ *
+ * @module dsh-plugin-wsl/file-reference-wsl
+ */
+
+import { isWslUnc, posixToUnc, uncToPosix } from "./paths.js";
+
+/** Upstream's default cap on one workspace index; the per-directory listing
+ * rides the same bound, since one level can't usefully exceed the budget. */
+const DEFAULT_MAX_ENTRIES = 50000;
+
+/**
+ * Lexically normalize a `/`-separated display directory against its root.
+ * Upstream resolves `resolve(root, displayDirectory)` and refuses a result
+ * outside the root, so `a/../b` lands on `b` while `..` past the root is
+ * refused outright — the walk below never sees a `..` segment.
+ *
+ * @param {string} displayDirectory - the query text before the fragment, possibly "".
+ * @returns {string[] | undefined} the normalized segments, or undefined when
+ *   the display directory escapes the root.
+ */
+export function normalizeDisplaySegments(displayDirectory) {
+  const segments = [];
+  for (const segment of String(displayDirectory).split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return undefined;
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments;
+}
+
+/**
+ * The distro argv for one directory listing: `find -printf '%y\t%f'` over the
+ * contained directory. The containment guard is the same shape the picker and
+ * workspace-files use — `realpath` the requested directory, refuse anything
+ * the root does not contain — and the `%y` type char is what keeps symlink
+ * semantics identical to a readdir Dirent (skipped, not followed).
+ *
+ * @param {string} linuxRoot - the workspace root, POSIX spelling.
+ * @param {string} linuxDir - the directory to list, POSIX spelling.
+ * @param {number} maxEntries - the listing cap (head -n bound).
+ * @returns {string[]} the agent exec argv.
+ */
+export function traversalArgv(linuxRoot, linuxDir, maxEntries) {
+  const script = [
+    "root=$1 dir=$2 max=$3",
+    'real=$(realpath -L -- "$dir") || exit 2',
+    'case "$real" in "$root") ;; "$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac',
+    '[ -d "$real" ] || { echo "NOTDIR:$real" >&2; exit 4; }',
+    'find "$real" -mindepth 1 -maxdepth 1 -printf \'%y\\t%f\\n\' | head -n "$max"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", linuxRoot, linuxDir, maxEntries];
+}
+
+/**
+ * Parse one `%y\t%f` listing into upstream's Dirent-like entries.
+ * `d` is a directory and `f` a file; every other type char — `l` for
+ * symlinks, devices, sockets — is skipped, matching a readdir Dirent.
+ *
+ * @param {string} stdout - the raw listing.
+ * @returns {{name: string, isDirectory: () => boolean, isFile: () => boolean}[]}
+ */
+export function parseTraversalListing(stdout) {
+  const entries = [];
+  for (const line of String(stdout).split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab <= 0) continue;
+    const kind = line.slice(0, tab);
+    const name = line.slice(tab + 1);
+    if (name.length === 0) continue;
+    if (kind !== "d" && kind !== "f") continue;
+    entries.push({
+      name,
+      isDirectory: () => kind === "d",
+      isFile: () => kind === "f",
+    });
+  }
+  return entries;
+}
+
+/**
+ * The argv for the per-segment walk behind `resolveDisplayDirectory`: each
+ * segment must exist, be a directory, and not be a symlink — upstream's
+ * lstat verdicts, checked in one exec. Segments ride as argv elements, never
+ * interpolated into the script.
+ *
+ * @param {string} linuxRoot - the workspace root, POSIX spelling.
+ * @param {string[]} segments - the normalized display segments below the root.
+ * @returns {string[]} the agent exec argv.
+ */
+export function resolveDirectoryArgv(linuxRoot, segments) {
+  const script = [
+    "root=$1",
+    'cur="$root"',
+    'for seg in "${@:2}"; do',
+    '  cur="$cur/$seg"',
+    '  if [ -L "$cur" ]; then echo "SYMLINK:$cur" >&2; exit 5; fi',
+    '  [ -d "$cur" ] || { echo "NOTDIR:$cur" >&2; exit 4; }',
+    "done",
+    'printf \'%s\\n\' "$cur"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", linuxRoot, ...segments];
+}
+
+/**
+ * The host-default traversal — the node:fs implementations the seam keeps
+ * as upstream's defaults, replicated here so the prototype answers host
+ * workspaces without the seam and so tests can inject substitutes for it.
+ * (Upstream owns the real defaults; this copy exists only until the takeover.)
+ *
+ * @param {object} deps - the node:fs/promises functions, injectable for tests.
+ * @returns the strategy object with the upstream default semantics.
+ */
+export function hostFileReferenceTraversal(deps) {
+  const read = async (absolute, signal) => {
+    signal.throwIfAborted();
+    try {
+      const entries = await deps.readdir(absolute, { withFileTypes: true });
+      signal.throwIfAborted();
+      return entries;
+    } catch (error) {
+      signal.throwIfAborted();
+      throw error;
+    }
+  };
+  return {
+    readWorkspaceRoot: read,
+    readDirectory: async (absolute, signal) => {
+      signal.throwIfAborted();
+      try {
+        const entries = await deps.readdir(absolute, { withFileTypes: true });
+        signal.throwIfAborted();
+        return entries;
+      } catch {
+        signal.throwIfAborted();
+        return [];
+      }
+    },
+    resolveDisplayDirectory: async (root, displayDirectory, signal) => {
+      const segments = normalizeDisplaySegments(displayDirectory);
+      if (segments === undefined) return undefined;
+      let current = root;
+      for (const segment of segments) {
+        signal.throwIfAborted();
+        current = `${current}${current.endsWith("/") ? "" : "/"}${segment}`;
+        try {
+          const status = await deps.lstat(current);
+          signal.throwIfAborted();
+          if (status.isSymbolicLink() || !status.isDirectory()) return undefined;
+        } catch (error) {
+          signal.throwIfAborted();
+          return undefined;
+        }
+      }
+      return current;
+    },
+  };
+}
+
+/**
+ * The distro-routed traversal strategy. Each method routes by coordinate:
+ * a `\\wsl.localhost\<distro>` UNC rides the resident agent (the search
+ * root and every absolute upstream passes stay in the UNC form it joined
+ * them with); anything else defers to the default traversal. The search
+ * root doubles as the containment root for the distro listings' guard, so
+ * the seam wires one strategy per `WorkspaceFileSearch` — exactly where
+ * `WorkspaceFileSearch(root, config, traversal)` would take it.
+ *
+ * @param {object} options
+ * @param {string} options.root - the search root, the UNC form upstream passes.
+ * @param {(distro: string) => object} options.runnerFor - the agent runner
+ *   for one distro; tests substitute a fake (a real wiring passes sharedAgent).
+ * @param {object} options.defaultTraversal - the host-default strategy.
+ * @param {number} [options.maxEntries] - the listing cap, upstream's index budget.
+ * @returns the strategy object the seam's `WorkspaceFileSearch` would take.
+ */
+export function wslFileReferenceTraversal({ root, runnerFor, defaultTraversal, maxEntries = DEFAULT_MAX_ENTRIES }) {
+  if (!isWslUnc(root)) return defaultTraversal;
+  const rootCoords = uncToPosix(root);
+  const rootLinux = rootCoords.linuxPath;
+
+  const listDistro = async (absolute, signal, onRefusal) => {
+    signal.throwIfAborted();
+    const { linuxPath } = uncToPosix(absolute);
+    try {
+      const result = await runnerFor(rootCoords.distro).exec({
+        cwd: "/",
+        argv: traversalArgv(rootLinux, linuxPath, maxEntries),
+        maxOutputBytes: 4_000_000,
+        timeoutMs: 30_000,
+        signal,
+      });
+      signal.throwIfAborted();
+      if (result.exitCode !== 0) {
+        return onRefusal(new Error(`listing "${linuxPath}" failed: ${String(result.stderr).trim() || `exit ${result.exitCode}`}`));
+      }
+      return parseTraversalListing(result.stdout);
+    } catch (error) {
+      signal.throwIfAborted();
+      return onRefusal(error);
+    }
+  };
+
+  return {
+    readWorkspaceRoot(absolute, signal) {
+      if (!isWslUnc(absolute)) return defaultTraversal.readWorkspaceRoot(absolute, signal);
+      return listDistro(absolute, signal, (error) => {
+        throw error;
+      });
+    },
+
+    readDirectory(absolute, signal) {
+      if (!isWslUnc(absolute)) return defaultTraversal.readDirectory(absolute, signal);
+      return listDistro(absolute, signal, () => []);
+    },
+
+    async resolveDisplayDirectory(rootOf, displayDirectory, signal) {
+      signal.throwIfAborted();
+      if (!isWslUnc(rootOf)) return defaultTraversal.resolveDisplayDirectory(rootOf, displayDirectory, signal);
+      const segments = normalizeDisplaySegments(displayDirectory);
+      if (segments === undefined) return undefined;
+      if (segments.length === 0) return root;
+      try {
+        const result = await runnerFor(rootCoords.distro).exec({
+          cwd: "/",
+          argv: resolveDirectoryArgv(rootLinux, segments),
+          maxOutputBytes: 4_000_000,
+          timeoutMs: 30_000,
+          signal,
+        });
+        signal.throwIfAborted();
+        if (result.exitCode !== 0) return undefined;
+        return posixToUnc(rootCoords.distro, result.stdout.trim());
+      } catch {
+        signal.throwIfAborted();
+        return undefined;
+      }
+    },
+  };
+}
+
+export default wslFileReferenceTraversal;

package/lib/fs-decisions.js

@@ -79,37 +79,33 @@ export function workspaceWriteDenial(displayPath) {
 }
 
 /**
- * The write/edit guard: compare the intent (`expected`) with what is on disk
- * NOW (`existing`, a stat row or `undefined`) and refuse the stale or
- * unobserved intent. The peer's dialect, byte for byte.
- * @param {object|undefined} expected - the write intent (`replaceIfVersion`
- *   with a `version`, or `createIfAbsent`), or `undefined` for an unguarded write.
- * @param {{version: string}|undefined} existing - what stat found, or undefined.
- * @param {string} displayPath - the caller-facing path for the message.
- * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ * The substrate configuration decision: the Windows-side share no longer
+ * serves the file tools. Every distro read and write runs on the resident
+ * agent, so no model-facing I/O crosses the 9p share at all — the share
+ * backend it replaces was the one path that still could. The provider throws
+ * this at construction time, before any session forms, so a profile carrying
+ * the old value fails loudly with the migration instead of silently serving
+ * I/O the configuration did not mean to allow.
+ * @param {string} substrate - the configured substrate value.
+ * @returns {{message: string}|null} the refusal, or null to proceed.
  */
-export function guardRefusal(expected, existing, displayPath) {
-  if (expected === undefined) return null;
-  if (expected.kind === "replaceIfVersion") {
-    if (existing === undefined) return refusal(`cannot write "${displayPath}": file no longer exists`, "FS_STALE_VERSION");
-    if (existing.version !== expected.version) {
-      return refusal(`cannot write "${displayPath}": file changed since it was read`, "FS_STALE_VERSION");
-    }
-    return null;
-  }
-  if (expected.kind === "createIfAbsent" && existing !== undefined) {
-    return refusal(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED");
-  }
-  return null;
+export function shareSubstrateRefusal(substrate) {
+  if (substrate !== "share") return null;
+  return {
+    message:
+      'wsl-fs: substrate "share" is no longer available — the resident agent serves every ' +
+      "distro read and write, and no file tool crosses the 9p share. Delete the substrate " +
+      'line from the provider config, or set it to "agent".',
+  };
 }
 
 /**
  * The substrate failure mapping: what the tool layer should surface for an
  * error that crossed the `ctx.fs` seam. A coded refusal keeps its code and
  * message byte-for-byte; anything else is the substrate being UNAVAILABLE —
- * the share backend's "distro is gone" case wearing the agent substrate's
- * wording — and the message names the documented opt-out, so an operator hit
- * by the fail-closed posture can reach the old behaviour without a doc trip.
+ * the resident agent that serves every distro read and write is out — and the
+ * message names the recovery path, because there is no fallback I/O for it to
+ * point at.
  * @param {unknown} error - what the substrate raised.
  * @returns {{message: string, code: string, cause: unknown}} the refusal the
  *   provider wraps in `FsError`.
@@ -120,7 +116,8 @@ export function substrateFailure(error) {
   return {
     message:
       `the distro file substrate is unavailable: ${message}. ` +
-      `Set "substrate: \\"share\\"" in the provider config to work on the Windows-side share while the agent is out.`,
+      `The resident agent serves every distro read and write; check the distro is running ` +
+      `("wsl.exe -l -v") and restart the session if it stays out.`,
     code: "FS_IO_ERROR",
     cause: error instanceof Error ? error : undefined,
   };

package/lib/fs-routing.js

@@ -0,0 +1,176 @@
+/**
+ * The root-plane filesystem with coordinate routing: targets under a
+ * `\\wsl.localhost\<distro>` identity are served by the distro substrate
+ * (the resident agent, on ext4); every other target — drive-letter paths,
+ * the deployment cwd — is served by the host `LocalFileSystem` this class
+ * extends, unchanged.
+ *
+ * ## Why a router, and why here
+ *
+ * The root `ctx.fs` is session-less: it cannot be switched per session the
+ * way a preset's isolated `fs` can, so the two workspace kinds share one
+ * backend — and the stock backend serves the distro workspace across the 9p
+ * share, in its slow direction, with no usable change notifications. Routing
+ * by coordinate makes every root consumer (the workspace-files change feed
+ * among them) correct on both workspace kinds without per-consumer patches.
+ *
+ * The design note is `docs/root-fs-routing.md` (the operation routing table,
+ * the intended behavior differences, and the dormant-root-fence rationale).
+ *
+ * ## What is intentionally not here
+ *
+ * No write fence: the root plane has no write consumers (the model's writes
+ * ride the per-session preset filesystems, which enforce their own
+ * containment — the distro side kernel-enforced). If a root-plane write
+ * consumer appears, its fence rides with that consumer.
+ *
+ * @module dsh-plugin-wsl/fs-routing
+ */
+
+import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { linuxJoin } from "./workspace-files-route.js";
+import { WslFileSystem } from "./index.js";
+
+/**
+ * Whether a resolved target identity belongs to the distro.
+ *
+ * @param targetKey - the target's identity (a UNC for distro paths).
+ * @returns true when the target lives inside a WSL distro.
+ */
+export function targetIsDistro(targetKey) {
+  return isWslUnc(targetKey);
+}
+
+/**
+ * Whether a raw path-or-cwd input names the distro (used by the operations
+ * that take paths before a target exists: resolve, lstat).
+ *
+ * @param value - a path in any coordinate system, or undefined.
+ * @returns true when the input names a distro UNC.
+ */
+export function inputIsDistro(value) {
+  return value !== undefined && isWslUnc(value);
+}
+
+/**
+ * The Linux working path for one request: UNC absolutes map onto their Linux
+ * paths, POSIX absolutes and relative paths join onto the root.
+ *
+ * @param linuxRoot - the workspace root in Linux form.
+ * @param path - the requested path, any coordinate system.
+ * @returns the absolute Linux path.
+ */
+/**
+ * The root-plane filesystem with coordinate routing.
+ *
+ * The distro backend is built lazily on the first routed target, sharing this
+ * context (the root `sandboxPolicy` service provides the deployment default
+ * mode the distro side reports through `sandboxMode`).
+ */
+export class WslRoutingFileSystem extends LocalFileSystem {
+  static Config = LocalFileSystem.Config;
+
+  /** The lazy distro backend, built on first routed use. */
+  #distro;
+  /** The distro knobs, verbatim from the row config. */
+  #distroConfig;
+
+  constructor(ctx, config) {
+    super(ctx, config);
+    this.#distroConfig = {
+      distro: config.distro ?? "",
+      wslPath: config.wslPath ?? "wsl.exe",
+      cwd: config.distroCwd ?? "",
+      diffBasisMaxBytes: config.diffBasisMaxBytes,
+      sandbox: config.sandbox ?? true,
+      maskWindowsDrive: config.maskWindowsDrive ?? false,
+      restrictToDistro: config.restrictToDistro ?? true,
+      watchMaxDepth: config.watchMaxDepth ?? 0,
+    };
+  }
+
+  /** The distro backend for routed targets, built on first use. */
+  distro() {
+    return (this.#distro ??= new WslFileSystem(this.ctx, this.#distroConfig));
+  }
+
+  async resolve(path, opts) {
+    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).resolve(path, opts);
+    return super.resolve(path, opts);
+  }
+
+  async lstat(path, opts, signal) {
+    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).lstat(path, opts, signal);
+    return super.lstat(path, opts, signal);
+  }
+
+  async stat(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).stat(target, signal);
+    return super.stat(target, signal);
+  }
+
+  async readText(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readText(target, signal);
+    return super.readText(target, signal);
+  }
+
+  async streamText(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).streamText(target, signal);
+    return super.streamText(target, signal);
+  }
+
+  async readBytes(target, signal, maxBytes) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readBytes(target, signal, maxBytes);
+    return super.readBytes(target, signal, maxBytes);
+  }
+
+  async readByteRange(target, range, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readByteRange(target, range, signal);
+    return super.readByteRange(target, range, signal);
+  }
+
+  async listDir(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).listDir(target, signal);
+    return super.listDir(target, signal);
+  }
+
+  async writeText(target, content, expected, signal, sandboxPolicy) {
+    if (targetIsDistro(target.targetKey)) {
+      return (await this.distro()).writeText(target, content, expected, signal, sandboxPolicy);
+    }
+    return super.writeText(target, content, expected, signal, sandboxPolicy);
+  }
+
+  async editText(target, edit, expected, signal, sandboxPolicy) {
+    if (targetIsDistro(target.targetKey)) {
+      return (await this.distro()).editText(target, edit, expected, signal, sandboxPolicy);
+    }
+    return super.editText(target, edit, expected, signal, sandboxPolicy);
+  }
+
+  async watch(target, changed, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).watch(target, changed, signal);
+    return super.watch(target, changed, signal);
+  }
+
+  contains(parent, child) {
+    if (targetIsDistro(parent.targetKey)) {
+      // Both targets came from this router's distro resolve, so the plain
+      // POSIX containment over their process paths is the same check the
+      // distro substrate performs for its own guarded writes.
+      const base = this.processPath(parent);
+      const full = this.processPath(child);
+      return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
+    }
+    return super.contains(parent, child);
+  }
+
+  processPath(target) {
+    const parsed = uncToPosix(target.targetKey);
+    if (parsed !== undefined) return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    return super.processPath(target);
+  }
+}
+
+export default WslRoutingFileSystem;

package/lib/git-route.js

@@ -0,0 +1,142 @@
+/**
+ * Which git spawns belong inside the distro, and the `wsl.exe` argv they
+ * become there.
+ *
+ * `workspace-changes` snapshots a workspace's git state by spawning the host
+ * git through `ctx.subprocess` with the workspace as the working directory.
+ * On a distro workspace that spawn runs Windows git against the 9P share —
+ * the same slow direction as the search path, and the snapshot's
+ * `git add --all` is a full work-tree scan, the most metadata-heavy operation
+ * there is. The interception point is the same `spawn` override; the decision
+ * lives here, pure and unit-testable, mirroring `search-route.js`.
+ *
+ * ## What is routed, and what deliberately is not
+ *
+ * A spawn is routed only when the working directory names the distro (a
+ * `\\wsl.localhost\<distro>` UNC) and the argv carries none of the discovery
+ * flags (`--show-toplevel`, `--absolute-git-dir`, `--git-path`). Those three
+ * print **absolute paths**, which `workspace-changes` resolves against the
+ * UNC workspace (`git.ts` `resolve(cwd, line)`) — a distro git would answer
+ * in Linux paths and corrupt that resolution. Host git answers in UNC form,
+ * which is exactly what the caller wants, and the discovery call is one
+ * cheap command rather than a work-tree scan. Everything else — `add`,
+ * `write-tree`, `ls-tree`, `cat-file`, `diff-tree`, `ls-files`,
+ * `check-ignore` — is safe to route: snapshot calls run in an environment
+ * fully isolated from the user's git state (`GIT_INDEX_FILE` /
+ * `GIT_OBJECT_DIRECTORY` / `GIT_ALTERNATE_OBJECT_DIRECTORIES` pointing at the
+ * tool's private scratch), so the distro git mutates scratch, never the
+ * repository.
+ *
+ * ## Environment translation
+ *
+ * The routed spawn must forward the caller's `GIT_*` environment into the
+ * distro, and its values are paths in Windows form (`\\wsl.localhost\...`
+ * identities and drive-letter scratch dirs). `translateGitEnv` rewrites those
+ * two shapes into distro paths with the same pure translations the fs seam
+ * uses, forwards every other value verbatim (`GIT_CONFIG_COUNT=0` and
+ * friends), and returns the names that must ride `WSLENV`. One documented
+ * limit: a colon-separated multi-directory value (none of the current
+ * callers set one) passes through untranslated.
+ *
+ * @module dsh-plugin-wsl/git-route
+ */
+
+import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+
+/** The one program this rewrite passes through to the distro. */
+const GIT_PROGRAM = "git";
+
+/** Discovery flags print absolute paths — host git keeps that contract. */
+const DISCOVERY_FLAGS = ["--show-toplevel", "--absolute-git-dir", "--git-path"];
+
+/**
+ * Whether a spawn's program is git.
+ * @param unknown - the spawn's `argv[0]`.
+ * @returns true when the spawn is a git launch.
+ */
+export function isGitProgram(program) {
+  if (typeof program !== "string" || program.length === 0) return false;
+  const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
+  return base.toLowerCase().replace(/\.exe$/u, "") === GIT_PROGRAM;
+}
+
+/**
+ * Whether a git argv carries the discovery flags whose absolute output the
+ * caller resolves against the UNC world.
+ * @param {unknown[]} argv - the spawn's argv; `argv[0]` is the program.
+ * @returns true when the spawn must stay on host git.
+ */
+function namesDiscoveryPaths(argv) {
+  return argv.some((arg) => typeof arg === "string" && DISCOVERY_FLAGS.includes(arg));
+}
+
+/**
+ * Translate one `GIT_*` value into the distro's coordinate system.
+ *
+ * UNC identities (`\\wsl.localhost\<distro>\...`) map onto their Linux paths;
+ * drive-letter paths map onto their `/mnt/<drive>` mounts; anything else is
+ * not a path we can name and passes through verbatim.
+ *
+ * @param value - the env value.
+ * @returns the distro-side spelling of the value.
+ */
+export function translateGitEnvValue(value) {
+  if (typeof value !== "string") return value;
+  if (isWslUnc(value)) {
+    const parsed = uncToPosix(value);
+    return parsed === undefined ? value : parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+  }
+  const mounted = windowsToLinuxMount(value);
+  return mounted === undefined ? value : mounted;
+}
+
+/**
+ * Translate a git spawn's environment for the distro and name the keys that
+ * must ride `WSLENV`.
+ *
+ * @param env - the spawn's environment, or undefined.
+ * @returns the environment to forward (every key, path-shaped values
+ *   translated) and the `WSLENV` names.
+ */
+export function translateGitEnv(env) {
+  const translated = {};
+  const names = [];
+  for (const [name, value] of Object.entries(env ?? {})) {
+    translated[name] = name.startsWith("GIT_") ? translateGitEnvValue(value) : value;
+    names.push(name);
+  }
+  return { env: translated, wslenv: names };
+}
+
+/**
+ * The distro-side rewrite of one git spawn, when it belongs in the distro.
+ *
+ * `gitArgv` is the distro command itself; `wslArgv` is the same command
+ * wrapped for a one-shot `wsl.exe --exec` launch — git snapshot operations
+ * are not latency-sensitive, so the routing stays on the simple transport
+ * and does not need the resident agent. `wsl.exe` itself must start in a
+ * Windows directory, so the caller supplies its own host cwd.
+ *
+ * @param object - the spawn's inputs.
+ * @param {unknown[]} object.argv - the spawn's argv; `argv[0]` is the program.
+ * @param {unknown} object.cwd - the spawn's working directory, any coordinate system.
+ * @param {string} object.wslPath - path to `wsl.exe`.
+ * @returns {{distro: string, linuxCwd: string, gitArgv: string[], wslArgv: string[]}|undefined} the
+ *   rewrite, or undefined when the spawn is not a routable distro git launch
+ *   (non-git programs, host directories, and the absolute-output discovery
+ *   flags all keep the shipped spawn).
+ */
+export function gitSpawnRewrite({ argv, cwd, wslPath }) {
+  if (!Array.isArray(argv) || !isGitProgram(argv[0])) return undefined;
+  if (namesDiscoveryPaths(argv)) return undefined;
+  const named = uncToPosix(cwd);
+  if (named === undefined) return undefined;
+  const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
+  const gitArgv = [GIT_PROGRAM, ...argv.slice(1)];
+  return {
+    distro: named.distro,
+    linuxCwd,
+    gitArgv,
+    wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...gitArgv],
+  };
+}