@hienlh/ppm 0.17.56 → 0.18.0

package/src/services/fs-path-guard.service.ts

@@ -0,0 +1,196 @@
+import { resolve, sep } from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { getPpmDir } from "./ppm-dir.ts";
+import { realPathOrSelf, realPathOrSelfSync } from "./fs-ops/fs-real-path.ts";
+
+// Re-exported so callers reach both the guards and the resolver they build on
+// through one import.
+export { realPathOrSelf, realPathOrSelfSync };
+
+/**
+ * Central guard for every filesystem route that works outside project scope.
+ * The whole disk is browsable behind PPM auth, so the remaining defences are:
+ * a normalized resolve, a platform allowlist that still rejects UNC shares,
+ * a refusal for the PPM directory (holds the credentials DB) and a protected
+ * root list so a stray rename cannot take out `$HOME` or a drive root.
+ */
+
+/** Structured mapping of an FS failure to an HTTP answer. */
+export interface FsErrorInfo {
+  status: number;
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+/**
+ * Resolve a path, expanding a leading `~` to the home directory. Only a bare
+ * `~` or `~/`…`~\` expands: `~foo` is a user-home shorthand this code does not
+ * implement, and slicing it blindly would silently resolve to `$HOME/oo`.
+ */
+export function resolvePath(input: string): string {
+  if (input === "~") return homedir();
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return resolve(homedir(), input.slice(2));
+  }
+  return resolve(input);
+}
+
+/** Case-insensitive prefix test on Windows/macOS-style paths. */
+function isInside(child: string, parent: string): boolean {
+  const norm = (p: string) => (process.platform === "win32" ? p.toLowerCase() : p);
+  const c = norm(child);
+  const p = norm(parent);
+  return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+
+/**
+ * Whitelist for system-level access. POSIX exposes the whole tree; Windows
+ * requires a drive letter, which keeps UNC shares (`\\server\share`) out —
+ * they are unsupported in this version because they can block indefinitely.
+ */
+export function isAllowedPath(resolved: string): boolean {
+  // The platform shape is decided first: a UNC path must stay rejected even
+  // when it also matches the exception below, or an attacker-named share
+  // (\\host\claude\x\tasks\y.output) would turn a read into an outbound SMB
+  // fetch to their server.
+  const shapeAllowed =
+    process.platform === "win32" ? /^[A-Za-z]:\\/.test(resolved) : resolved.startsWith("/");
+  if (shapeAllowed) return true;
+
+  // SDK background-command output lives under the OS temp dir; the chat output
+  // panel reads those files directly. Matched by structure so it survives the
+  // per-platform claude dir naming ("claude" vs "claude-<uid>"), but never for
+  // a UNC path.
+  if (isUncPath(resolved)) return false;
+  return /[\\/]claude[^\\/]*[\\/].+[\\/]tasks[\\/][^\\/]+\.output$/.test(resolved);
+}
+
+/** `\\server\share\…` (or the forward-slash spelling). */
+function isUncPath(candidate: string): boolean {
+  return /^[\\/]{2}[^\\/]/.test(candidate);
+}
+
+/** Throw a 403 when a path is outside the allowlist. */
+export function assertAllowed(resolved: string): void {
+  if (!isAllowedPath(resolved)) {
+    throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
+  }
+}
+
+/** True when the path is the PPM directory or anything inside it. */
+export function isPpmDirPath(resolved: string): boolean {
+  return isInside(resolved, getPpmDir());
+}
+
+/**
+ * Refuse the PPM directory subtree on read-style doors. It stores the config
+ * database with provider credentials and auth tokens, which must never be
+ * downloadable through a generic file route.
+ */
+export function assertNotPpmDir(resolved: string): void {
+  if (isPpmDirPath(resolved)) {
+    throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
+  }
+}
+
+/**
+ * Refuse operations that would take the PPM directory's contents anywhere
+ * else. Reading that subtree is already blocked, so without this a copy to a
+ * public path followed by an ordinary read would still hand out the
+ * credentials database.
+ */
+export function assertNotPpmSubtree(candidate: string): void {
+  if (isPpmDirPath(candidate)) {
+    throw Object.assign(new Error(`Refusing to operate on the PPM directory: ${candidate}`), {
+      status: 403,
+      code: "EPROTECTED",
+    });
+  }
+}
+
+/**
+ * Same refusal, applied to the real path as well. A path that does not exist
+ * yet is still resolved through its parents, so a symlinked directory cannot
+ * be used to reach — or create something inside — the PPM directory.
+ */
+export async function assertNotPpmSubtreeDeep(candidate: string): Promise<void> {
+  assertNotPpmSubtree(candidate);
+  assertNotPpmSubtree(await realPathOrSelf(candidate));
+}
+
+/** Paths whose removal or rename would break the host or PPM itself. */
+export function isProtectedRoot(candidate: string): boolean {
+  const p = resolve(candidate);
+  if (p === "/" ) return true;
+  if (/^[A-Za-z]:\\?$/.test(p)) return true;
+  const norm = (v: string) => (process.platform === "win32" ? v.toLowerCase() : v);
+  return norm(p) === norm(homedir()) || norm(p) === norm(getPpmDir());
+}
+
+/**
+ * Reject destructive operations on protected roots. For a real entry the
+ * realpath is checked too, so a symlinked *directory* cannot be used as a
+ * proxy for `$HOME`. A symlink is exempt from that second check: every
+ * operation here acts on the link itself, and deleting a shortcut that points
+ * at the home directory removes the shortcut, not the home directory.
+ */
+export async function assertNotProtected(candidate: string): Promise<void> {
+  const deny = () => {
+    throw Object.assign(new Error(`Refusing to modify a protected path: ${candidate}`), {
+      status: 403,
+      code: "EPROTECTED",
+    });
+  };
+  if (isProtectedRoot(candidate)) deny();
+  try {
+    if ((await lstat(candidate)).isSymbolicLink()) return;
+    if (isProtectedRoot(await realpath(candidate))) deny();
+  } catch (e) {
+    if ((e as { status?: number }).status === 403) throw e;
+    // Unresolvable path (missing or broken link) — the plain check already ran.
+  }
+}
+
+const HINT_EPERM =
+  process.platform === "darwin"
+    ? "grant Full Disk Access to the process running ppm"
+    : "the process running ppm lacks permission for this path";
+
+/** Map a Node FS error (or a guard error carrying `status`) to an HTTP answer. */
+export function mapFsError(e: unknown): FsErrorInfo {
+  const err = e as { status?: number; code?: string; message?: string };
+  const message = err?.message || "Filesystem error";
+  if (typeof err?.status === "number") {
+    // A refusal we decided ourselves is not a permission problem the user can
+    // fix, so the OS-permission hint only rides along on real EPERM/EACCES.
+    const osDenied = err.code === "EPERM" || err.code === "EACCES";
+    return {
+      status: err.status,
+      code: err.code || "EFAIL",
+      message,
+      hint: osDenied ? HINT_EPERM : undefined,
+    };
+  }
+  switch (err?.code) {
+    case "ENOENT":
+      return { status: 404, code: "ENOENT", message };
+    case "EEXIST":
+    case "ERR_FS_CP_EEXIST":
+      return { status: 409, code: "EEXIST", message };
+    case "ENOTEMPTY":
+      return { status: 409, code: "ENOTEMPTY", message };
+    case "EPERM":
+    case "EACCES":
+      return { status: 403, code: err.code, message, hint: HINT_EPERM };
+    case "ENOTDIR":
+    case "EISDIR":
+    case "EINVAL":
+      return { status: 400, code: err.code, message };
+    case "EBUSY":
+      return { status: 409, code: "EBUSY", message };
+    default:
+      return { status: 500, code: err?.code || "EFAIL", message };
+  }
+}

package/src/services/host-info/apple-bookmark-decoder.ts

@@ -0,0 +1,97 @@
+/** Pure buffer parser for the Apple Bookmark binary record (the `Bookmark`
+ *  blob stored per-item in a Finder sidebar `.sfl2`/`.sfl3`/`.sfl4` file).
+ *  Format is Apple-undocumented and reverse-engineered — see the mac-alias
+ *  bookmark-format writeup this follows: 48-byte header (magic `book`,
+ *  total-size, version, header-size-constant, 32 reserved bytes), a 4-byte
+ *  TOC offset at byte 48, a TOC of `(key, dataOffset, reserved)` triples, and
+ *  self-describing data records (`length` + `type` + payload). All offsets
+ *  in this implementation are absolute from the start of the buffer.
+ *  UNVERIFIED against a real macOS sample — field constants come from public
+ *  reverse-engineering writeups, not Apple docs; re-validate before shipping. */
+
+export class BookmarkDecodeError extends Error {}
+
+const MAGIC = "book";
+const TOC_MAGIC = 0xfffffffe;
+
+/** Data record type codes (low 16 bits distinguish the payload shape). */
+const TYPE_STRING = 0x0101; // UTF-8 bytes
+const TYPE_ARRAY = 0x0201; // payload = concatenated 4-byte LE offsets into other data records
+
+/** TOC key for the path-components array (`kBookmarkPath`). */
+const KEY_PATH = 0x1004;
+/** TOC keys that may carry a cross-volume prefix (external drives) — try both. */
+const KEY_VOLUME_PATH_CANDIDATES = [0x1005, 0x2002];
+
+interface TocEntry {
+  key: number;
+  dataOffset: number;
+}
+
+function readToc(buf: Buffer, tocOffset: number): TocEntry[] {
+  if (tocOffset + 20 > buf.length) throw new BookmarkDecodeError("TOC offset out of range");
+  const magic = buf.readUInt32LE(tocOffset + 4);
+  if (magic !== TOC_MAGIC) throw new BookmarkDecodeError(`bad TOC magic 0x${magic.toString(16)}`);
+  const entryCount = buf.readUInt32LE(tocOffset + 16);
+  const entries: TocEntry[] = [];
+  let cursor = tocOffset + 20;
+  for (let i = 0; i < entryCount; i++) {
+    if (cursor + 12 > buf.length) throw new BookmarkDecodeError("TOC entry out of range");
+    entries.push({ key: buf.readUInt32LE(cursor), dataOffset: buf.readUInt32LE(cursor + 4) });
+    cursor += 12;
+  }
+  return entries;
+}
+
+function readDataRecord(buf: Buffer, offset: number): { type: number; payload: Buffer } {
+  if (offset + 8 > buf.length) throw new BookmarkDecodeError("data record offset out of range");
+  const length = buf.readUInt32LE(offset);
+  const type = buf.readUInt32LE(offset + 4);
+  const payloadStart = offset + 8;
+  const payloadEnd = payloadStart + length;
+  if (payloadEnd > buf.length) throw new BookmarkDecodeError("data record payload out of range");
+  return { type, payload: buf.subarray(payloadStart, payloadEnd) };
+}
+
+function readString(buf: Buffer, offset: number): string {
+  const { type, payload } = readDataRecord(buf, offset);
+  if (type !== TYPE_STRING) throw new BookmarkDecodeError(`expected string record, got type 0x${type.toString(16)}`);
+  return payload.toString("utf-8");
+}
+
+function readArrayOfStrings(buf: Buffer, offset: number): string[] {
+  const { type, payload } = readDataRecord(buf, offset);
+  if (type !== TYPE_ARRAY) throw new BookmarkDecodeError(`expected array record, got type 0x${type.toString(16)}`);
+  if (payload.length % 4 !== 0) throw new BookmarkDecodeError("array payload not a multiple of 4 bytes");
+  const items: string[] = [];
+  for (let i = 0; i < payload.length; i += 4) {
+    items.push(readString(buf, payload.readUInt32LE(i)));
+  }
+  return items;
+}
+
+/** Decode an Apple Bookmark record into an absolute POSIX path.
+ *  Throws `BookmarkDecodeError` on any structural mismatch — callers must
+ *  catch and turn it into a `warnings[]` entry, never let it reach the HTTP layer. */
+export function decodeBookmarkPath(buf: Buffer): string {
+  if (buf.length < 52 || buf.subarray(0, 4).toString("ascii") !== MAGIC) {
+    throw new BookmarkDecodeError("missing 'book' magic header");
+  }
+  const tocOffset = buf.readUInt32LE(48);
+  const toc = readToc(buf, tocOffset);
+
+  const pathEntry = toc.find((e) => e.key === KEY_PATH);
+  if (!pathEntry) throw new BookmarkDecodeError("no kBookmarkPath (0x1004) entry in TOC");
+  const components = readArrayOfStrings(buf, pathEntry.dataOffset);
+
+  let volumePath = "";
+  const volumeEntry = toc.find((e) => KEY_VOLUME_PATH_CANDIDATES.includes(e.key));
+  if (volumeEntry) {
+    try {
+      volumePath = readString(buf, volumeEntry.dataOffset);
+    } catch {
+      // Volume key present but not a plain string (e.g. a UUID data record) — assume boot volume.
+    }
+  }
+  return `${volumePath}/${components.join("/")}`;
+}

package/src/services/host-info/apple-plist-xml-parser.ts

@@ -0,0 +1,107 @@
+/** Minimal parser for `plutil -convert xml1 -o -` output — not a general XML
+ *  parser, just enough of Apple's plist DTD (`dict`/`array`/`string`/
+ *  `integer`/`real`/`true`/`false`/`data`) to walk an NSKeyedArchiver
+ *  container. Avoids pulling in an XML dependency for a fixed, well-known
+ *  tag set, same rationale as the Linux GTK/KDE bookmark regex parsers. */
+
+export type PlistValue =
+  | string
+  | number
+  | boolean
+  | Buffer
+  | PlistValue[]
+  | { [key: string]: PlistValue };
+
+interface Frame {
+  type: "array" | "dict";
+  items: PlistValue[];
+  keys: string[];
+  /** The dict's own "awaiting a value" key — scoped per-frame, not global, because a
+   *  `<key>k</key><array>...<dict>...<key>other</key>...</dict>...</array>` sequence
+   *  nests another dict (with its own key/value turns) before the outer key is consumed. */
+  pendingKey: string | null;
+}
+
+const TAG_RE = /<(\/)?([a-zA-Z][\w.-]*)([^>]*?)(\/)?>/g;
+
+export class PlistParseError extends Error {}
+
+/** Parse plist XML text into a plain JS value tree (dict → object, array → array, data → Buffer). */
+export function parsePlistXml(xml: string): PlistValue {
+  TAG_RE.lastIndex = 0;
+  const stack: Frame[] = [];
+  let root: PlistValue | undefined;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  function place(value: PlistValue): void {
+    const top = stack[stack.length - 1];
+    if (!top) {
+      root = value;
+      return;
+    }
+    if (top.type === "array") {
+      top.items.push(value);
+      return;
+    }
+    if (top.pendingKey === null) throw new PlistParseError("dict value without a preceding <key>");
+    top.keys.push(top.pendingKey);
+    top.items.push(value);
+    top.pendingKey = null;
+  }
+
+  while ((match = TAG_RE.exec(xml))) {
+    const closing = !!match[1];
+    const name = match[2]!;
+    const selfClose = !!match[4];
+    const between = xml.slice(lastIndex, match.index);
+    lastIndex = TAG_RE.lastIndex;
+
+    if (name === "?xml" || name === "plist" || name === "!DOCTYPE") continue;
+
+    if (selfClose) {
+      if (name === "true") place(true);
+      else if (name === "false") place(false);
+      else if (name === "dict") place({});
+      else if (name === "array") place([]);
+      continue;
+    }
+    if (!closing) {
+      if (name === "dict" || name === "array") stack.push({ type: name, items: [], keys: [], pendingKey: null });
+      continue; // other opening tags (string/integer/...) are handled on their closing tag below
+    }
+
+    // closing tag
+    if (name === "key") {
+      const top = stack[stack.length - 1];
+      if (!top || top.type !== "dict") throw new PlistParseError("<key> outside of a <dict>");
+      top.pendingKey = between;
+    } else if (name === "dict") {
+      const frame = stack.pop();
+      if (!frame) throw new PlistParseError("unbalanced </dict>");
+      const obj: Record<string, PlistValue> = {};
+      frame.keys.forEach((k, i) => {
+        obj[k] = frame.items[i]!;
+      });
+      place(obj);
+    } else if (name === "array") {
+      const frame = stack.pop();
+      if (!frame) throw new PlistParseError("unbalanced </array>");
+      place(frame.items);
+    } else if (name === "string") {
+      place(between);
+    } else if (name === "integer") {
+      place(parseInt(between, 10));
+    } else if (name === "real") {
+      place(parseFloat(between));
+    } else if (name === "data") {
+      place(Buffer.from(between.replace(/\s+/g, ""), "base64"));
+    } else if (name === "date") {
+      place(between);
+    }
+    // Unrecognized closing tags are ignored — tolerant of plist dialects we don't need.
+  }
+
+  if (root === undefined) throw new PlistParseError("empty or unparsable plist document");
+  return root;
+}

package/src/services/host-info/concurrency-limit.ts

@@ -0,0 +1,20 @@
+/** Runs `fn` over `items` with at most `limit` in flight at once — a minimal
+ *  worker-pool, not a dependency. Used to bound fs probes (e.g. Windows drive
+ *  letters) so a handful of hung mapped/network paths can't park libuv's
+ *  whole threadpool and stall unrelated fs work in the process. */
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let cursor = 0;
+  async function worker(): Promise<void> {
+    while (cursor < items.length) {
+      const i = cursor++;
+      results[i] = await fn(items[i]!);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}

package/src/services/host-info/host-drives.ts

@@ -0,0 +1,190 @@
+/** Drive/volume enumeration per OS. Windows probes A:-Z: async (never
+ *  `existsSync` — a disconnected mapped drive blocks the event loop) and
+ *  merges `Get-CimInstance Win32_LogicalDisk` for kind/label only, so a dead
+ *  network share never empties the whole list. macOS reads `/Volumes` minus
+ *  the boot-volume symlink-to-root. Linux prefers `findmnt`, falls back to
+ *  `/proc/mounts`, and always ships root `/`. */
+import * as fsp from "node:fs/promises";
+import type { Drive, DriveKind } from "../../types/system.ts";
+import { defaultRunner, type Runner } from "./spawn-runner.ts";
+import { mapWithConcurrency } from "./concurrency-limit.ts";
+
+export interface DriveDeps {
+  run: Runner;
+  stat: (path: string) => Promise<unknown>;
+  readdir: (path: string) => Promise<string[]>;
+  lstat: (path: string) => Promise<{ isSymbolicLink: () => boolean }>;
+  readlink: (path: string) => Promise<string>;
+  readFile: (path: string) => Promise<string>;
+}
+
+const defaultDeps: DriveDeps = {
+  run: defaultRunner,
+  stat: (p) => fsp.stat(p),
+  readdir: (p) => fsp.readdir(p),
+  lstat: (p) => fsp.lstat(p),
+  readlink: (p) => fsp.readlink(p),
+  readFile: (p) => fsp.readFile(p, "utf-8"),
+};
+
+const WIN_LETTER_TIMEOUT_MS = 1500;
+const WIN_PROBE_CONCURRENCY = 4; // bounds fs.stat fan-out so hung drives can't park the threadpool
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("");
+const CIM_SCRIPT =
+  "Get-CimInstance Win32_LogicalDisk | Select-Object DeviceID,DriveType,VolumeName | ConvertTo-Json -Compress";
+
+interface CimRow {
+  DeviceID: string;
+  DriveType: number;
+  VolumeName?: string;
+}
+
+function driveKindFromCimType(t: number): DriveKind {
+  if (t === 2) return "removable";
+  if (t === 3) return "fixed";
+  if (t === 4) return "network";
+  return "unknown";
+}
+
+async function probeWindowsLetter(deps: DriveDeps, letter: string): Promise<string | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error("timeout")), WIN_LETTER_TIMEOUT_MS);
+  });
+  try {
+    await Promise.race([deps.stat(`${letter}:\\`), timeout]);
+    return letter;
+  } catch {
+    return null; // no drive at this letter, or the mapped drive is unreachable (timed out)
+  } finally {
+    clearTimeout(timer); // avoid leaving a pending timer alive per scan
+  }
+}
+
+// CIM runs first: when it succeeds it's authoritative for which letters exist, so those
+// letters skip the fs.stat probe (avoids redundantly re-checking a hung mapped drive).
+async function getWindowsDrives(deps: DriveDeps, warnings: string[]): Promise<Drive[]> {
+  let cimRows: CimRow[] = [];
+  let cimOk = false;
+  try {
+    const res = await deps.run(
+      ["powershell.exe", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", CIM_SCRIPT],
+      5000,
+    );
+    if (res.timedOut || res.code !== 0) {
+      warnings.push(`drives: Get-CimInstance Win32_LogicalDisk ${res.timedOut ? "timed out" : `exited ${res.code}`}, drive kind unknown`);
+    } else {
+      const parsed = JSON.parse(res.stdout.trim() || "[]");
+      cimRows = Array.isArray(parsed) ? parsed : [parsed];
+      cimOk = true;
+    }
+  } catch (e) {
+    warnings.push(`drives: Get-CimInstance Win32_LogicalDisk failed (${(e as Error)?.message ?? e}), drive kind unknown`);
+  }
+
+  const cimByLetter = new Map(cimRows.map((r) => [r.DeviceID, r]));
+  const cimDrives: Drive[] = cimRows.map((r) => ({
+    name: r.DeviceID,
+    path: `${r.DeviceID}\\`,
+    kind: driveKindFromCimType(r.DriveType),
+    ...(r.VolumeName ? { label: r.VolumeName } : {}),
+  }));
+
+  // Only probe letters CIM didn't already confirm (all 26, when CIM failed/timed out).
+  const lettersToProbe = LETTERS.filter((l) => !cimOk || !cimByLetter.has(`${l}:`));
+  const probed = await mapWithConcurrency(lettersToProbe, WIN_PROBE_CONCURRENCY, (letter) =>
+    probeWindowsLetter(deps, letter),
+  );
+  const probedDrives: Drive[] = probed
+    .filter((l): l is string => l !== null)
+    .map((l) => ({ name: `${l}:`, path: `${l}:\\`, kind: "unknown" as const }));
+
+  return [...cimDrives, ...probedDrives];
+}
+
+async function getDarwinDrives(deps: DriveDeps, warnings: string[]): Promise<Drive[]> {
+  let entries: string[] = [];
+  try {
+    entries = await deps.readdir("/Volumes");
+  } catch (e) {
+    warnings.push(`drives: readdir(/Volumes) failed (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+
+  const drives: Drive[] = [];
+  for (const name of entries) {
+    const path = `/Volumes/${name}`;
+    try {
+      const st = await deps.lstat(path);
+      if (st.isSymbolicLink()) {
+        const target = await deps.readlink(path);
+        if (target === "/" || target === "") continue; // boot volume alias, not a distinct browsable drive
+      }
+      drives.push({ name, path, kind: "unknown" });
+    } catch {
+      // Vanished between readdir and lstat (unmounted mid-scan) — skip, not fatal.
+    }
+  }
+  return drives;
+}
+
+interface FindmntEntry {
+  target: string;
+  source: string;
+}
+
+const LINUX_MOUNT_PREFIXES = ["/media/", "/run/media/", "/mnt/"];
+
+async function getLinuxDrives(deps: DriveDeps, warnings: string[]): Promise<Drive[]> {
+  const drives: Drive[] = [{ name: "/", path: "/", kind: "fixed" }];
+  let entries: FindmntEntry[] = [];
+
+  try {
+    const res = await deps.run(["findmnt", "-J", "--real", "-o", "TARGET,SOURCE,FSTYPE"], 5000);
+    if (res.timedOut || res.code !== 0) throw new Error(res.timedOut ? "timed out" : `exited ${res.code}`);
+    const parsed = JSON.parse(res.stdout);
+    entries = (parsed?.filesystems ?? []).map((f: any) => ({ target: String(f.target ?? ""), source: String(f.source ?? "") }));
+  } catch (e) {
+    warnings.push(`drives: findmnt failed (${(e as Error)?.message ?? e}), falling back to /proc/mounts`);
+    try {
+      const raw = await deps.readFile("/proc/mounts");
+      entries = raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+          const parts = line.split(" ");
+          return { source: parts[0] ?? "", target: parts[1] ?? "" };
+        });
+    } catch (e2) {
+      warnings.push(`drives: /proc/mounts read failed (${(e2 as Error)?.message ?? e2})`);
+      return drives;
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.target || entry.target === "/") continue;
+    if (!LINUX_MOUNT_PREFIXES.some((p) => entry.target.startsWith(p))) continue;
+    const name = entry.target.split("/").filter(Boolean).pop() ?? entry.target;
+    drives.push({ name, path: entry.target, kind: "unknown" });
+  }
+  return drives;
+}
+
+/** Enumerate drives for `platform`, appending any failure to the shared `warnings` array (never throws). */
+export async function getDrives(
+  platform: NodeJS.Platform,
+  warnings: string[],
+  overrides: Partial<DriveDeps> = {},
+): Promise<Drive[]> {
+  const deps: DriveDeps = { ...defaultDeps, ...overrides };
+  try {
+    if (platform === "win32") return await getWindowsDrives(deps, warnings);
+    if (platform === "darwin") return await getDarwinDrives(deps, warnings);
+    if (platform === "linux") return await getLinuxDrives(deps, warnings);
+    warnings.push(`drives: unsupported platform "${platform}"`);
+    return [];
+  } catch (e) {
+    warnings.push(`drives: unexpected failure (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+}