dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/scripts/profile-preset.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Print or write the complete `- id: preset-wsl` block (P0.3 / WSL-103).
+ *
+ * `wsl-shell` and `wsl-fs` live inside the `preset-wsl` row's `config.plugins`,
+ * so a patch that targets them by id changes nothing — the loader logs
+ * `patch: entry "wsl-shell" not found` and boots the shipped values. The only
+ * route that works is replacing the whole `preset-wsl` row, which must carry
+ * every nested plugin verbatim. This helper extracts that row from the shipped
+ * `cordis.patch.yml`, applies the common edits, and can validate or write a
+ * profile layer.
+ *
+ *   node scripts/profile-preset.mjs [--distro Debian] [--session-sandbox false|auto]
+ *        [--sandbox false] [--mask-windows-drive true] [--agent-backend native]
+ *        [--out <profile/cordis.patch.yml>] [--check <file>] [--force]
+ *
+ * With no `--out`/`--check`, the block (with the edits) goes to stdout.
+ * `--check` fails loudly on a nested id patch and prints the block to paste.
+ * `--out` refuses to overwrite a patch that has no `preset-wsl` row unless
+ * `--force`, so it cannot silently drop another override.
+ *
+ * @module dsh-plugin-wsl/scripts/profile-preset
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = join(ROOT, "cordis.patch.yml");
+/** The shipped row's first line: four spaces deep inside the second `insert:` list. */
+const ROW_START = /^ {4}- id: preset-wsl\s*$/m;
+
+/**
+ * Extract the shipped `preset-wsl` row, dedented to a top-level patch entry.
+ * @param {string} source - the `cordis.patch.yml` text.
+ * @returns {string} the block, without a trailing newline.
+ */
+export function presetBlock(source) {
+  const match = ROW_START.exec(source);
+  if (match === null) throw new Error("profile-preset: cordis.patch.yml carries no `- id: preset-wsl` row");
+  return source.slice(match.index).replace(/^ {4}/gm, "").replace(/\s+$/u, "");
+}
+
+/**
+ * The top-level nested-row ids a profile layer wrongly targets.
+ * @param {string} text - a profile patch file.
+ * @returns {string[]} the offending ids, in file order.
+ */
+export function nestedRowIds(text) {
+  /** @type {string[]} */
+  const found = [];
+  for (const line of text.split("\n")) {
+    const match = /^ {0,4}-\s*id:\s*(wsl-shell|wsl-fs)\s*$/u.exec(line);
+    if (match?.[1] !== undefined && !found.includes(match[1])) found.push(match[1]);
+  }
+  return found;
+}
+
+/**
+ * The line range of one nested row inside the block.
+ * @param {string[]} lines - the block's lines.
+ * @param {string} id - `wsl-shell` or `wsl-fs`.
+ * @returns {{ start: number, end: number }} the range, end exclusive.
+ */
+function rowRange(lines, id) {
+  const start = lines.findIndex((line) => line.trim() === `- id: ${id}`);
+  if (start < 0) throw new Error(`profile-preset: the preset block carries no "${id}" row`);
+  const indent = /^\s*/u.exec(lines[start] ?? "")?.[0].length ?? 0;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const head = /^(\s*)- id: /u.exec(lines[i] ?? "");
+    if (head !== null && head[1]?.length === indent) {
+      end = i;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+/**
+ * Set one config key inside one nested row, keeping every other line byte-for-byte.
+ * @param {string[]} lines - the block's lines.
+ * @param {string} id - the nested row.
+ * @param {string} key - the config key.
+ * @param {string} value - the rendered YAML value.
+ */
+function setKey(lines, id, key, value) {
+  const { start, end } = rowRange(lines, id);
+  const keyLine = new RegExp(`^(\\s*)${key}:\\s`, "u");
+  for (let i = start; i < end; i += 1) {
+    const match = keyLine.exec(lines[i] ?? "");
+    if (match !== null) {
+      lines[i] = `${match[1]}${key}: ${value}`;
+      return;
+    }
+  }
+  // Absent keys go under `distro:` (or `config:`), at the same depth as the
+  // keys around them.
+  const anchor = lines.slice(start, end).findIndex((line) => /^\s*distro:/u.test(line));
+  const config = lines.slice(start, end).findIndex((line) => /^\s*config:\s*$/u.test(line));
+  const offset = anchor >= 0 ? start + anchor : start + config;
+  const base = /^\s*/u.exec(lines[offset] ?? "")?.[0] ?? "";
+  // Alongside `distro:` the new key takes the same depth; under a bare
+  // `config:` it takes the next level.
+  const indent = anchor >= 0 ? base : `${base}  `;
+  lines.splice(offset + 1, 0, `${indent}${key}: ${value}`);
+}
+
+/**
+ * Apply the supported edits to a preset block.
+ * @param {string} block - the block from {@link presetBlock}.
+ * @param {{ distro?: string, sessionSandbox?: boolean | "auto", sandbox?: boolean, maskWindowsDrive?: boolean, agentBackend?: string }} edits - the edits.
+ * @returns {string} the edited block.
+ */
+export function applyEdits(block, edits) {
+  const lines = block.split("\n");
+  const both = /** @type {Array<[string, string | undefined]>} */ ([
+    ["distro", edits.distro],
+    ["sessionSandbox", edits.sessionSandbox === undefined ? undefined : String(edits.sessionSandbox)],
+    ["sandbox", edits.sandbox === undefined ? undefined : String(edits.sandbox)],
+    ["maskWindowsDrive", edits.maskWindowsDrive === undefined ? undefined : String(edits.maskWindowsDrive)],
+  ]);
+  for (const [key, value] of both) {
+    if (value === undefined) continue;
+    setKey(lines, "wsl-shell", key, value);
+    setKey(lines, "wsl-fs", key, value);
+  }
+  if (edits.agentBackend !== undefined) setKey(lines, "wsl-shell", "agentBackend", edits.agentBackend);
+  return lines.join("\n");
+}
+
+/**
+ * Parse the helper's arguments.
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @returns {{ edits: Record<string, string | boolean>, out?: string, check?: string, force: boolean }} the options.
+ */
+function parseArgs(argv) {
+  /** @type {Record<string, string | boolean>} */
+  const edits = {};
+  /** @type {{ edits: Record<string, string | boolean>, out?: string, check?: string, force: boolean }} */
+  const options = { edits, force: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i] ?? "";
+    const [flag, inline] = arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+    const value = inline ?? argv[++i] ?? "";
+    if (flag === "--distro") {
+      if (value.length === 0) throw new Error("profile-preset: --distro needs a name");
+      edits.distro = value;
+    } else if (flag === "--session-sandbox") edits.sessionSandbox = parseSandboxMode(flag, value);
+    else if (flag === "--sandbox") edits.sandbox = parseBoolean(flag, value);
+    else if (flag === "--mask-windows-drive") edits.maskWindowsDrive = parseBoolean(flag, value);
+    else if (flag === "--agent-backend") {
+      if (!["auto", "native", "shell"].includes(value)) throw new Error(`profile-preset: --agent-backend must be auto, native or shell (got "${value}")`);
+      edits.agentBackend = value;
+    } else if (flag === "--out") options.out = value;
+    else if (flag === "--check") options.check = value;
+    else if (flag === "--force") {
+      options.force = true;
+      i -= 1;
+    } else if (flag === "--help" || flag === "-h") {
+      console.log("node scripts/profile-preset.mjs [--distro NAME] [--session-sandbox true|false|auto] [--sandbox true|false] [--mask-windows-drive true|false] [--agent-backend auto|native|shell] [--out FILE] [--check FILE] [--force]");
+      process.exit(0);
+    } else throw new Error(`profile-preset: unknown option "${arg}"`);
+  }
+  return options;
+}
+
+/**
+ * Parse one boolean flag value.
+ * @param {string} flag - the flag, for the error.
+ * @param {string} value - the value.
+ * @returns {boolean} the boolean.
+ */
+function parseBoolean(flag, value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`profile-preset: ${flag} takes true or false (got "${value}")`);
+}
+
+/**
+ * Parse the `--session-sandbox` value: the boolean modes plus `auto`.
+ * @param {string} flag - the flag, for the error.
+ * @param {string} value - the value.
+ * @returns {boolean | "auto"} the mode.
+ */
+function parseSandboxMode(flag, value) {
+  if (value === "auto") return "auto";
+  return parseBoolean(flag, value);
+}
+
+/**
+ * Report a nested id patch with the exact block to paste.
+ * @param {string} file - the profile patch.
+ * @param {string[]} ids - the offending ids.
+ * @param {string} block - the corrected block.
+ * @returns {number} the exit status.
+ */
+function nestedFailure(file, ids, block) {
+  console.error(`profile-preset: ${file} patches ${ids.map((id) => `"${id}"`).join(" and ")} by id.`);
+  console.error("Those rows live inside preset-wsl's config.plugins; the loader ignores the");
+  console.error("entry and boots the shipped values. Replace that entry with this complete");
+  console.error("preset-wsl block (it also carries the edits you asked for):");
+  console.error("");
+  console.error(block);
+  return 1;
+}
+
+/**
+ * Run the helper.
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @returns {number} the exit status.
+ */
+function main(argv) {
+  const options = parseArgs(argv);
+  const block = applyEdits(presetBlock(readFileSync(SOURCE, "utf8")), options.edits);
+
+  if (options.check !== undefined) {
+    if (!existsSync(options.check)) throw new Error(`profile-preset: no such patch: ${options.check}`);
+    const ids = nestedRowIds(readFileSync(options.check, "utf8"));
+    if (ids.length > 0) return nestedFailure(options.check, ids, block);
+    console.log(`ok: ${options.check} has no nested wsl-shell/wsl-fs id patch`);
+  }
+
+  if (options.out !== undefined) {
+    if (existsSync(options.out)) {
+      const existing = readFileSync(options.out, "utf8");
+      const ids = nestedRowIds(existing);
+      if (ids.length > 0) return nestedFailure(options.out, ids, block);
+      if (!existing.includes("- id: preset-wsl") && !options.force) {
+        console.error(`profile-preset: ${options.out} exists and has no preset-wsl row; refusing to replace its other overrides (pass --force to overwrite)`);
+        return 1;
+      }
+    }
+    mkdirSync(dirname(options.out), { recursive: true });
+    const temporary = join(tmpdir(), `dsh-preset-${process.pid}.yml`);
+    writeFileSync(temporary, `${block}\n`);
+    renameSync(temporary, options.out);
+    console.log(`wrote ${options.out}`);
+    return 0;
+  }
+
+  if (options.check === undefined) process.stdout.write(`${block}\n`);
+  return 0;
+}
+
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    console.error(/** @type {Error} */ (error).message);
+    process.exitCode = 1;
+  }
+}

package/lib/workspace-files-route.d.ts

@@ -1,136 +0,0 @@
-/**
- * Pure builders and parsers for the distro-routed `workspace-files` service —
- * the GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace,
- * served from inside the distro instead of Windows-side 9P walks.
- *
- * Peer-free by construction (no DSH imports): the service subclass imports
- * this alongside the shipped `dsh-api-workspace-files` base class, and the
- * unit tests import it standalone.
- *
- * This is a TypeScript source built to `lib/workspace-files-route.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/workspace-files-route
- */
-/**
- * Translate one path-shaped value into distro coordinates: UNC identities map
- * onto their Linux paths, drive-letter paths onto their `/mnt/<drive>` mounts,
- * everything else passes through verbatim.
- *
- * @param value - the value to translate.
- * @returns the distro-side spelling.
- */
-export declare function distroPath(value: string): string;
-/**
- * Whether a workspace root belongs to a distro (and therefore routes
- * distro-side).
- *
- * @param workspaceRoot - the scope's workspace root, any coordinate system.
- * @returns true for a `\\wsl.localhost\<distro>` UNC root.
- */
-export declare function isDistroWorkspace(workspaceRoot: string): boolean;
-/**
- * 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.
- */
-export declare function linuxJoin(linuxRoot: string, path: string): string;
-/**
- * The record invocation for one path: line 1 is the no-follow kind (the
- * upstream lstat gate), line 2 the follow-stat fields (the upstream final
- * stat), tab-joined. The path is resolved and contained first — the GUI's
- * workspace is a boundary for every read, not just for listings.
- *
- * @param file - absolute Linux path.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export declare function statRecordArgv(file: string, root: string): string[];
-/**
- * Parse one stat record (kind + follow fields, tab-joined).
- *
- * @param line - the record line.
- * @returns the upstream kind spelling, the byte size, and the synthesized
- *   opaque version.
- */
-export declare function parseStatRecord(line: string | Buffer): {
-    kind: string;
-    type: string;
-    size: number;
-    version: string;
-};
-/**
- * Map a `stat` kind onto the wire's kind token.
- *
- * @param kind - the `stat -c %F` spelling.
- * @returns the wire kind token.
- */
-export declare function wireKind(kind: string): string;
-/**
- * The read invocation for one line-paged text read: the stat record rides
- * stderr (the caller builds the stat half of the response), the page rides
- * stdout — one line beyond the page, so EOF is decidable from the yield.
- * `$1` is the file, `$2` the 1-based first line, `$3` the line count.
- *
- * @param file - absolute Linux path.
- * @param offset - first line to return (1-based).
- * @param limit - maximum lines to return.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export declare function pageArgv(file: string, offset: number, limit: number, root: string): string[];
-/**
- * The byte-window invocation: the stat record rides stderr, the window rides
- * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
- *
- * @param file - absolute Linux path.
- * @param offset - byte offset (0-based).
- * @param length - byte count.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export declare function bytesArgv(file: string, offset: number, length: number, root: string): string[];
-/**
- * Parse the stat record a read or byte-window relayed on stderr.
- *
- * @param stderr - the relay's raw stderr.
- * @returns the parsed stat record, or undefined when stderr carries none.
- */
-export declare function parseStatRecordFromStderr(stderr: string | Buffer): {
-    kind: string;
-    type: string;
-    size: number;
-    version: string;
-} | undefined;
-/**
- * The listing invocation for one directory: resolve the final component
- * through symlinks, refuse paths outside the root and non-directories, then
- * list one more entry than the cap so truncation is decidable from the yield.
- * `-L` matches the upstream child semantics (a symlink to a directory lists
- * as a directory, a broken link drops out); `-p` marks directories with the
- * trailing `/` the parser keys on.
- *
- * @param linuxRoot - the workspace root in Linux form (containment boundary).
- * @param linuxDir - the directory to list.
- * @param maxEntries - the caller's entry cap.
- * @returns the agent argv.
- */
-export declare function listDistroArgv(linuxRoot: string, linuxDir: string, maxEntries: number): string[];
-/**
- * Parse one capped `ls -1ALp` listing into wire entries.
- *
- * @param stdout - the listing's raw stdout.
- * @param maxEntries - the entry cap the caller configured.
- * @returns at most `maxEntries` entries and whether the level had more.
- */
-export declare function parseDirListing(stdout: string | Buffer, maxEntries: number): {
-    entries: Array<{
-        name: string;
-        type: "file" | "directory";
-    }>;
-    truncated: boolean;
-};

package/lib/workspace-files-route.js

@@ -1,225 +0,0 @@
-/**
- * Pure builders and parsers for the distro-routed `workspace-files` service —
- * the GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace,
- * served from inside the distro instead of Windows-side 9P walks.
- *
- * Peer-free by construction (no DSH imports): the service subclass imports
- * this alongside the shipped `dsh-api-workspace-files` base class, and the
- * unit tests import it standalone.
- *
- * This is a TypeScript source built to `lib/workspace-files-route.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/workspace-files-route
- */
-import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
-/**
- * Translate one path-shaped value into distro coordinates: UNC identities map
- * onto their Linux paths, drive-letter paths onto their `/mnt/<drive>` mounts,
- * everything else passes through verbatim.
- *
- * @param value - the value to translate.
- * @returns the distro-side spelling.
- */
-export function distroPath(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;
-}
-/**
- * Whether a workspace root belongs to a distro (and therefore routes
- * distro-side).
- *
- * @param workspaceRoot - the scope's workspace root, any coordinate system.
- * @returns true for a `\\wsl.localhost\<distro>` UNC root.
- */
-export function isDistroWorkspace(workspaceRoot) {
-    return isWslUnc(workspaceRoot);
-}
-/**
- * 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.
- */
-export function linuxJoin(linuxRoot, path) {
-    // The UNC check runs on the RAW spelling: the backslash-to-slash rewrite
-    // below would leave `//wsl.localhost/...`, which the identity regex cannot
-    // see.
-    const parsed = uncToPosix(path);
-    if (parsed !== undefined)
-        return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
-    const text = String(path).replaceAll("\\", "/");
-    if (text.startsWith("/"))
-        return text.length > 1 ? text.replace(/\/+$/, "") : "/";
-    const base = linuxRoot === "/" ? "" : linuxRoot;
-    const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
-    return joined.length === 0 ? "/" : joined;
-}
-/**
- * The containment guard every distro-side workspace read shares. `$1` is the
- * requested file, `$2` the workspace root; both are canonicalized with
- * `realpath -L`, and a target that is neither the root itself nor below it is
- * refused with exit 3 (the `workspace-file/outside-workspace` refusal). The
- * resolved file is left in `real` for the rest of the script.
- *
- * A root of `/` admits every absolute path: the workspace IS the distro. The
- * `-L` spelling matches the listing guard's, so symlinked workspace roots and
- * `..` segments resolve the same way on both sides.
- */
-const CONTAIN_FN = [
-    'contain() {',
-    '  real=$(realpath -L -- "$1") || exit 2',
-    '  root=$(realpath -L -- "$2") || exit 2',
-    '  case "$root" in /) ;; *) case "$real" in "$root"|"$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac;; esac',
-    '}',
-].join("\n");
-/**
- * The record invocation for one path: line 1 is the no-follow kind (the
- * upstream lstat gate), line 2 the follow-stat fields (the upstream final
- * stat), tab-joined. The path is resolved and contained first — the GUI's
- * workspace is a boundary for every read, not just for listings.
- *
- * @param file - absolute Linux path.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export function statRecordArgv(file, root) {
-    const script = [
-        CONTAIN_FN,
-        'contain "$1" "$2"',
-        'k=$(stat -c %F -- "$real") || exit 2',
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
-        "printf '%s\\t%s\\n' \"$k\" \"$s\"",
-    ].join("\n");
-    return ["sh", "-c", script, "sh", file, root];
-}
-/**
- * Parse one stat record (kind + follow fields, tab-joined).
- *
- * @param line - the record line.
- * @returns the upstream kind spelling, the byte size, and the synthesized
- *   opaque version.
- */
-export function parseStatRecord(line) {
-    const [kind, size, dev, ino, mtime, ctime] = String(line).trim().split("\t");
-    return {
-        kind,
-        type: wireKind(kind),
-        size: Number(size),
-        version: `${dev}:${ino}:${size}:${mtime}:${ctime}`,
-    };
-}
-/**
- * Map a `stat` kind onto the wire's kind token.
- *
- * @param kind - the `stat -c %F` spelling.
- * @returns the wire kind token.
- */
-export function wireKind(kind) {
-    const mapped = { "regular file": "file", directory: "directory", "symbolic link": "symlink" };
-    return mapped[kind] ?? kind;
-}
-/**
- * The read invocation for one line-paged text read: the stat record rides
- * stderr (the caller builds the stat half of the response), the page rides
- * stdout — one line beyond the page, so EOF is decidable from the yield.
- * `$1` is the file, `$2` the 1-based first line, `$3` the line count.
- *
- * @param file - absolute Linux path.
- * @param offset - first line to return (1-based).
- * @param limit - maximum lines to return.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export function pageArgv(file, offset, limit, root) {
-    const script = [
-        CONTAIN_FN,
-        'contain "$1" "$4"',
-        'k=$(stat -c %F -- "$real") || exit 2',
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
-        "printf '%s\\t%s\\n' \"$k\" \"$s\" >&2",
-        'sed -n "${2},$(( $2 + $3 ))p" -- "$real"',
-    ].join("\n");
-    return ["sh", "-c", script, "sh", file, String(offset), String(limit), root];
-}
-/**
- * The byte-window invocation: the stat record rides stderr, the window rides
- * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
- *
- * @param file - absolute Linux path.
- * @param offset - byte offset (0-based).
- * @param length - byte count.
- * @param root - the workspace root in Linux form (containment boundary).
- * @returns the agent argv.
- */
-export function bytesArgv(file, offset, length, root) {
-    const script = [
-        CONTAIN_FN,
-        'contain "$1" "$4"',
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
-        "printf '%s\\n' \"$s\" >&2",
-        'tail -c "+$(( $2 + 1 ))" -- "$real" | head -c "$3"',
-    ].join("\n");
-    return ["sh", "-c", script, "sh", file, String(offset), String(length), root];
-}
-/**
- * Parse the stat record a read or byte-window relayed on stderr.
- *
- * @param stderr - the relay's raw stderr.
- * @returns the parsed stat record, or undefined when stderr carries none.
- */
-export function parseStatRecordFromStderr(stderr) {
-    const line = String(stderr)
-        .split("\n")
-        .find((candidate) => candidate.includes("\t"));
-    return line === undefined ? undefined : parseStatRecord(line);
-}
-/**
- * The listing invocation for one directory: resolve the final component
- * through symlinks, refuse paths outside the root and non-directories, then
- * list one more entry than the cap so truncation is decidable from the yield.
- * `-L` matches the upstream child semantics (a symlink to a directory lists
- * as a directory, a broken link drops out); `-p` marks directories with the
- * trailing `/` the parser keys on.
- *
- * @param linuxRoot - the workspace root in Linux form (containment boundary).
- * @param linuxDir - the directory to list.
- * @param maxEntries - the caller's entry cap.
- * @returns the agent argv.
- */
-export function listDistroArgv(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; }',
-        'ls -1ALp -- "$real" | head -n "$max"',
-    ].join("\n");
-    return ["sh", "-c", script, "sh", linuxRoot, linuxDir, String(maxEntries + 1)];
-}
-/**
- * Parse one capped `ls -1ALp` listing into wire entries.
- *
- * @param stdout - the listing's raw stdout.
- * @param maxEntries - the entry cap the caller configured.
- * @returns at most `maxEntries` entries and whether the level had more.
- */
-export function parseDirListing(stdout, maxEntries) {
-    const lines = String(stdout).split("\n").filter((line) => line.length > 0);
-    const truncated = lines.length > maxEntries;
-    const entries = lines.slice(0, maxEntries).map((line) => {
-        const directory = line.endsWith("/");
-        const name = directory ? line.slice(0, -1) : line;
-        return { name, type: directory ? "directory" : "file" };
-    });
-    return { entries, truncated };
-}