A local-first multi-agent app development platform, built on PenguinHarness
/**
* Where a machine keeps its things, as the Workspace picker's sidebar wants them: the
* platform's standard folders as THIS machine resolves them (a Desktop redirected into
* OneDrive, a `~/桌面` on a Chinese Linux desktop), and the storage locations it offers beside
* its folders — Windows drives with their labels and kinds, macOS volumes, the Linux root and
* its mounts. Also the Windows hidden attribute, which no Node API exposes and which Explorer
* uses to keep `AppData`, `NTUSER.DAT` and the legacy profile junctions out of sight.
*
* Everything that touches the platform goes through {@link PlaceEffects}, so the parsers and
* the decisions run under test on any platform; {@link systemEffects} is the real machine.
*
* Two constraints shape every shell-out here. First, a disconnected network drive makes any
* filesystem call on it block for the redirector's timeout (tens of seconds), and a blocked
* `fs` call pins one of libuv's four threadpool threads for that long — the whole server's
* file I/O queues behind it, and a probe "raced against a timeout" still pins the thread after
* its caller moved on. So nothing in this file touches a drive from this process: enumeration
* runs in a child (spawning uses no threadpool thread), the child is time-boxed and killed, and
* whatever it printed before the deadline is kept. Second, the picker's home request waits for
* this answer, so the whole discovery is cached for a short while, a failure included, and two
* concurrent requests share one run.
*/
import { spawn, type ChildProcess } from "node:child_process";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import type { DirLocation, DirStandardFolders } from "../api/types.js";
/** What the home request carries with `places=1`. */
export interface DirPlaces {
/**
* Absent when the machine could not be asked (the Windows report ended before it got to
* the folders), so the picker falls back to matching names in the home listing. Present and
* empty means the machine was asked and has none of them, and the picker shows none.
*/
standardFolders?: DirStandardFolders;
locations: DirLocation[];
}
/** One child process run to completion or to its deadline. */
export interface ExecOutcome {
/** What the child wrote before it exited or was killed — bytes, because `cmd /u` writes UTF-16LE. */
stdout: Buffer;
/** The exit code; null when the child was killed or never started. */
code: number | null;
/** True when the child outlived its budget and was killed; `stdout` is what it had printed by then. */
timedOut: boolean;
/** Set when the child could not be started at all (the command is not on the machine). */
failed?: string;
}
/** A directory entry as `readdir` records it, without a stat: the two kinds this file asks about. */
export interface PlaceDirent {
name: string;
isDirectory(): boolean;
isSymbolicLink(): boolean;
}
/** The machine as discovery sees it; tests inject one, production uses {@link systemEffects}. */
export interface PlaceEffects {
platform: string;
homedir: string;
env: Record<string, string | undefined>;
readFile(file: string): Promise<string>;
readdir(dir: string): Promise<PlaceDirent[]>;
readlink(file: string): Promise<string>;
/** False for anything that is not a directory, a missing path included. */
isDirectory(file: string): Promise<boolean>;
/**
* Runs a child without a shell and without the threadpool, killing it at `timeoutMs`.
* `verbatim` hands the arguments to Windows unquoted, for a `cmd.exe` command line whose
* quoting this file controls itself.
*/
exec(
file: string,
args: string[],
opts: { timeoutMs: number; verbatim?: boolean },
): Promise<ExecOutcome>;
}
/**
* The discovery's shelf life. Long enough that reopening the picker, or two of its requests
* landing together, never spawn PowerShell twice; short enough that a USB drive plugged in
* shows up on the next open.
*/
export const PLACES_CACHE_TTL_MS = 15_000;
/**
* PowerShell's budget. A cold `powershell.exe` takes one to three seconds on a slow laptop or
* a CI runner; a budget it routinely blew would make the fallback the normal path. The script
* prints one JSON line per fact, so a run that hits the deadline still yields everything it
* had said by then.
*/
export const POWERSHELL_TIMEOUT_MS = 5_000;
/** `cmd.exe` budgets: the drive-letter probe and the hidden-attribute listing. */
export const CMD_TIMEOUT_MS = 3_000;
/** More than any directory listing or drive report; past it the child is killed and ignored. */
const OUTPUT_CAP_BYTES = 16 * 1024 * 1024;
export function systemEffects(): PlaceEffects {
return {
platform: process.platform,
homedir: os.homedir(),
env: process.env,
readFile: (file) => fs.readFile(file, "utf8"),
readdir: (dir) => fs.readdir(dir, { withFileTypes: true }),
readlink: (file) => fs.readlink(file),
isDirectory: (file) =>
fs.stat(file).then(
(st) => st.isDirectory(),
() => false,
),
exec: runChild,
};
}
/**
* Collects a child's stdout until it exits or runs out of time. stdin and stderr are not even
* opened: nothing here reads a diagnostic (`dir`'s "File Not Found" is localized), and a pipe
* nobody drains could block the child. On the deadline the child is killed and the promise
* settles on `close`, or one second later if a grandchild inherited the pipe and keeps it open.
*/
function runChild(
file: string,
args: string[],
opts: { timeoutMs: number; verbatim?: boolean },
): Promise<ExecOutcome> {
return new Promise((resolve) => {
const chunks: Buffer[] = [];
let size = 0;
let timedOut = false;
let settled = false;
let timer: NodeJS.Timeout | undefined;
let backstop: NodeJS.Timeout | undefined;
const settle = (code: number | null, failed?: string) => {
if (settled) return;
settled = true;
if (timer !== undefined) clearTimeout(timer);
if (backstop !== undefined) clearTimeout(backstop);
resolve({
stdout: Buffer.concat(chunks),
code,
timedOut,
...(failed !== undefined ? { failed } : {}),
});
};
let child: ChildProcess;
try {
child = spawn(file, args, {
stdio: ["ignore", "pipe", "ignore"],
windowsHide: true,
windowsVerbatimArguments: opts.verbatim === true,
});
} catch (err) {
settle(null, (err as Error).message);
return;
}
const kill = () => {
try {
child.kill();
} catch {
// Already gone.
}
};
timer = setTimeout(() => {
timedOut = true;
kill();
backstop = setTimeout(() => settle(null), 1_000);
}, opts.timeoutMs);
child.stdout?.on("data", (chunk: Buffer) => {
size += chunk.length;
if (size > OUTPUT_CAP_BYTES) {
kill();
settle(null, "output too large");
return;
}
chunks.push(chunk);
});
child.on("error", (err) => settle(null, err.message));
child.on("close", (code) => settle(code));
});
}
// ---------------------------------------------------------------------------------------------
// The cached discovery
/** Place discovery with its cache; one per machine, built once for the server by {@link discoverLocalPlaces}. */
export function createPlaceDiscovery(
effects: PlaceEffects,
opts: { ttlMs?: number; now?: () => number } = {},
): { discover(): Promise<DirPlaces> } {
const ttl = opts.ttlMs ?? PLACES_CACHE_TTL_MS;
const now = opts.now ?? Date.now;
let cached: { at: number; value: DirPlaces } | null = null;
let inFlight: Promise<DirPlaces> | null = null;
return {
discover() {
if (cached !== null && now() - cached.at < ttl) return Promise.resolve(cached.value);
if (inFlight !== null) return inFlight;
inFlight = discoverPlaces(effects)
.then((value) => {
cached = { at: now(), value };
return value;
})
.finally(() => {
inFlight = null;
});
return inFlight;
},
};
}
let local: { discover(): Promise<DirPlaces> } | null = null;
/** The places of the machine this server runs on, cached. Never rejects. */
export function discoverLocalPlaces(): Promise<DirPlaces> {
local ??= createPlaceDiscovery(systemEffects());
return local.discover();
}
/**
* One uncached discovery. Never rejects: a platform whose every source failed still answers
* with the root (or the system drive), and leaves the folders unanswered for the picker to
* find by name, which is what it showed before places existed.
*/
export async function discoverPlaces(effects: PlaceEffects): Promise<DirPlaces> {
try {
if (effects.platform === "win32") return await windowsPlaces(effects);
if (effects.platform === "darwin") return await darwinPlaces(effects);
if (effects.platform === "linux") return await linuxPlaces(effects);
} catch {
// Fall through to the bare answer.
}
return {
locations:
effects.platform === "win32" ? knownWindowsDrives(effects) : [{ path: "/", kind: "root" }],
};
}
// ---------------------------------------------------------------------------------------------
// Standard folders by their English names (macOS, and the fallback everywhere)
const FIXED_FOLDERS: ReadonlyArray<[keyof DirStandardFolders, string]> = [
["desktop", "Desktop"],
["documents", "Documents"],
["downloads", "Downloads"],
["pictures", "Pictures"],
];
/** `~/Desktop` and friends, those that exist. The path flavour follows the DESCRIBED platform, not the host's. */
async function fixedStandardFolders(effects: PlaceEffects): Promise<DirStandardFolders> {
const flavour = effects.platform === "win32" ? path.win32 : path.posix;
const found: DirStandardFolders = {};
await Promise.all(
FIXED_FOLDERS.map(async ([key, name]) => {
const full = flavour.join(effects.homedir, name);
if (await effects.isDirectory(full)) found[key] = full;
}),
);
return found;
}
// ---------------------------------------------------------------------------------------------
// Linux
const NETWORK_FSTYPES = new Set([
"nfs",
"nfs4",
"cifs",
"smb3",
"smbfs",
"sshfs",
"fuse.sshfs",
"fuse.rclone",
"davfs",
"fuse.davfs2",
"afs",
"ceph",
"fuse.ceph",
"glusterfs",
"fuse.glusterfs",
"ncpfs",
"coda",
"afp",
"fuse.afpfs",
]);
/** Kernel bookkeeping that happens to be mounted under a user prefix (WSL puts a tmpfs at /mnt/wsl). */
const PSEUDO_FSTYPES = new Set([
"tmpfs",
"devtmpfs",
"proc",
"sysfs",
"cgroup",
"cgroup2",
"binfmt_misc",
"debugfs",
"tracefs",
"securityfs",
"pstore",
"bpf",
"configfs",
"fusectl",
"mqueue",
"hugetlbfs",
"devpts",
"nsfs",
"rpc_pipefs",
]);
/** The filesystems WSL mounts a Windows drive with: WSL1 `drvfs`, WSL2 `9p`, and their newer spellings. */
const WSL_DRIVE_FSTYPES = new Set(["9p", "drvfs", "v9fs", "virtiofs"]);
/** Where Linux desktops and admins mount things a person would browse to. */
const MOUNT_PREFIXES = ["/media/", "/run/media/", "/mnt/"];
/** `/proc/mounts` escapes a space as `\040`, a tab `\011`, a newline `\012` and a backslash `\134`. */
function unescapeMountField(field: string): string {
return field.replace(/\\([0-7]{3})/g, (_, oct: string) => String.fromCharCode(parseInt(oct, 8)));
}
/**
* The browsable mounts in a `/proc/self/mounts` text, in path order: those under
* {@link MOUNT_PREFIXES}, minus WSL's own plumbing (`/mnt/wsl*`, `/mnt/wslg`), pseudo
* filesystems, and a mount nested under another listed one (a bind mount inside a disk is the
* disk's business). The same mount point listed twice keeps the later row: a systemd automount
* shows its `autofs` trigger and, once mounted, the real filesystem at the same path.
*/
export function parseMounts(text: string): DirLocation[] {
const byPath = new Map<string, { fstype: string }>();
for (const line of text.split("\n")) {
const fields = line.trim().split(/\s+/);
if (fields.length < 3) continue;
const mountPoint = unescapeMountField(fields[1] ?? "");
const fstype = fields[2] ?? "";
if (!MOUNT_PREFIXES.some((prefix) => mountPoint.startsWith(prefix))) continue;
if (/^\/mnt\/wslg?(\/|$)/.test(mountPoint)) continue;
if (PSEUDO_FSTYPES.has(fstype)) continue;
byPath.set(mountPoint, { fstype });
}
// Code-unit order, so a mount point always precedes anything nested under it.
const sorted = [...byPath.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
const kept: DirLocation[] = [];
for (const [mountPoint, { fstype }] of sorted) {
if (kept.some((k) => mountPoint.startsWith(`${k.path}/`))) continue;
kept.push(mountLocation(mountPoint, fstype));
}
return kept;
}
function mountLocation(mountPoint: string, fstype: string): DirLocation {
const name = path.posix.basename(mountPoint);
if (NETWORK_FSTYPES.has(fstype)) return { path: mountPoint, kind: "network", label: name };
const wslDrive = /^\/mnt\/([A-Za-z])$/.exec(mountPoint);
if (wslDrive !== null && WSL_DRIVE_FSTYPES.has(fstype)) {
return { path: mountPoint, kind: "drive", label: `${wslDrive[1]?.toUpperCase()}:` };
}
if (mountPoint.startsWith("/media/") || mountPoint.startsWith("/run/media/")) {
return { path: mountPoint, kind: "removable", label: name };
}
return { path: mountPoint, kind: "volume", label: name };
}
const XDG_KEYS: ReadonlyArray<[keyof DirStandardFolders, string]> = [
["desktop", "XDG_DESKTOP_DIR"],
["documents", "XDG_DOCUMENTS_DIR"],
["downloads", "XDG_DOWNLOAD_DIR"],
["pictures", "XDG_PICTURES_DIR"],
];
/**
* The four folders as `user-dirs.dirs` configures them: `XDG_DESKTOP_DIR="$HOME/桌面"` lines,
* `$HOME` expanded. A value that is the home directory itself is how the spec says "this
* folder is disabled", and comes back as null; a key the file does not mention is absent.
*/
export function parseUserDirs(
text: string,
home: string,
): Partial<Record<keyof DirStandardFolders, string | null>> {
const found: Partial<Record<keyof DirStandardFolders, string | null>> = {};
const homeNorm = home.replace(/\/+$/, "") || "/";
for (const line of text.split("\n")) {
const match = /^\s*(XDG_[A-Z]+_DIR)\s*=\s*"?([^"\n]*)"?\s*$/.exec(line);
if (match === null) continue;
const key = XDG_KEYS.find(([, name]) => name === match[1])?.[0];
if (key === undefined) continue;
const value = (match[2] ?? "").replace(/^\$\{?HOME\}?/, homeNorm).replace(/\/+$/, "") || "/";
found[key] = value === homeNorm ? null : value;
}
return found;
}
/**
* Linux standard folders: what `user-dirs.dirs` names, where it exists; the English name where
* the file says nothing; nothing where the file disables the folder.
*/
async function linuxStandardFolders(effects: PlaceEffects): Promise<DirStandardFolders> {
const configHome = effects.env.XDG_CONFIG_HOME || path.posix.join(effects.homedir, ".config");
let configured: Partial<Record<keyof DirStandardFolders, string | null>> = {};
try {
configured = parseUserDirs(
await effects.readFile(path.posix.join(configHome, "user-dirs.dirs")),
effects.homedir,
);
} catch {
// No file: the English names below.
}
const found: DirStandardFolders = {};
await Promise.all(
FIXED_FOLDERS.map(async ([key, name]) => {
const chosen = key in configured ? configured[key] : path.posix.join(effects.homedir, name);
if (chosen !== null && chosen !== undefined && (await effects.isDirectory(chosen))) {
found[key] = chosen;
}
}),
);
return found;
}
async function linuxPlaces(effects: PlaceEffects): Promise<DirPlaces> {
let mounts: DirLocation[] = [];
try {
mounts = parseMounts(await effects.readFile("/proc/self/mounts"));
} catch {
// A sandbox without /proc still has a root to offer.
}
return {
standardFolders: await linuxStandardFolders(effects),
locations: [{ path: "/", kind: "root" }, ...mounts],
};
}
// ---------------------------------------------------------------------------------------------
// macOS
/**
* The volumes under `/Volumes`, the startup disk first. Since Catalina the startup disk is a
* symlink there (`/Volumes/Macintosh HD -> /`), which is how it gets its name; `/` leads even
* when no entry links to it, so the picker's root always has a target. Only the directory
* listing and the link targets are read — a network volume whose server is gone is a plain
* directory entry of `/Volumes` until something touches it. Dot-names and Time Machine's
* `com.apple.TimeMachine.localsnapshots` are not volumes a person would pick.
*/
export async function darwinLocations(effects: PlaceEffects): Promise<DirLocation[]> {
let startup: DirLocation = { path: "/", kind: "volume" };
const others: DirLocation[] = [];
let entries: PlaceDirent[] = [];
try {
entries = await effects.readdir("/Volumes");
} catch {
// No /Volumes at all: the root alone.
}
for (const entry of entries) {
if (entry.name.startsWith(".") || entry.name.startsWith("com.apple.")) continue;
const full = `/Volumes/${entry.name}`;
if (entry.isSymbolicLink()) {
let target: string;
try {
target = path.posix.resolve("/Volumes", await effects.readlink(full));
} catch {
continue;
}
if (target === "/") startup = { path: "/", kind: "volume", label: entry.name };
continue;
}
if (entry.isDirectory()) others.push({ path: full, kind: "volume", label: entry.name });
}
others.sort((a, b) => (a.label ?? "").localeCompare(b.label ?? ""));
return [startup, ...others];
}
async function darwinPlaces(effects: PlaceEffects): Promise<DirPlaces> {
const [locations, standardFolders] = await Promise.all([
darwinLocations(effects),
fixedStandardFolders(effects),
]);
return { standardFolders, locations };
}
// ---------------------------------------------------------------------------------------------
// Windows
/**
* The drive and known-folder report, one JSON object per line, written as raw UTF-8 bytes.
*
* Raw bytes because Windows PowerShell's redirected output otherwise uses the OEM code page,
* and its `ConvertTo-Json` leaves non-ASCII as is — a volume labelled 「U 盘」 would arrive
* garbled. One object per line because the parser then keeps whatever arrived before the
* deadline, and because `ConvertTo-Json` on a collection of one yields an object, not an array.
*
* Drives are enumerated with `GetLogicalDrives` (a bitmask) and `DriveInfo.DriveType` (the DOS
* device table) rather than `Win32_LogicalDisk`: WMI reads size and free space from every
* disk, which on a disconnected mapped drive is the redirector round-trip this whole file
* avoids, and a cold WMI call also starts its provider host. A label is read only from a local
* drive that says it is ready (an empty card reader throws); a network drive is named by its
* share, from the persistent mappings in the registry and then the redirector's own list, and
* never by a volume label that would have to come from the server. Constrained Language Mode
* forbids `New-Object` on .NET types, so that branch falls back to WMI without network drives.
*
* Folders come last: `Test-Path` on a Documents folder redirected to a dead share blocks, and
* put last it costs the folders alone. Downloads has no `SpecialFolder` member; its known
* folder id is read from the shell's registry key.
*/
const WINDOWS_REPORT_SCRIPT =
String.raw`
$ErrorActionPreference = 'SilentlyContinue'
$stdout = [Console]::OpenStandardOutput()
function Emit($value) {
$bytes = [Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject $value -Compress -Depth 3) + "` +
"`n" +
String.raw`")
$stdout.Write($bytes, 0, $bytes.Length)
$stdout.Flush()
}
$network = @()
try {
foreach ($root in [IO.Directory]::GetLogicalDrives()) {
try {
$drive = New-Object -TypeName IO.DriveInfo -ArgumentList $root
$type = [int]$drive.DriveType
if ($type -eq 4) { $network += $root; continue }
$label = $null
try { if ($drive.IsReady) { $label = $drive.VolumeLabel } } catch {}
Emit @{ drive = $root; type = $type; label = $label }
} catch {}
}
} catch {
try {
foreach ($disk in @(Get-CimInstance Win32_LogicalDisk -Filter 'DriveType <> 4' -ErrorAction Stop)) {
Emit @{ drive = ($disk.DeviceID + '\'); type = [int]$disk.DriveType; label = $disk.VolumeName }
}
} catch {}
try { $network = @(Get-ChildItem -LiteralPath 'HKCU:\Network' -ErrorAction Stop | ForEach-Object { $_.PSChildName + ':\' }) } catch {}
}
foreach ($root in $network) {
$letter = $root.Substring(0, 1)
$share = $null
try { $share = (Get-ItemProperty -LiteralPath "HKCU:\Network\$letter" -ErrorAction Stop).RemotePath } catch {}
if (-not $share) {
try {
$drives = (New-Object -ComObject WScript.Network).EnumNetworkDrives()
for ($i = 0; $i -lt $drives.Count; $i += 2) {
if ($drives.Item($i) -ieq ($letter + ':')) { $share = $drives.Item($i + 1) }
}
} catch {}
}
Emit @{ drive = $root; type = 4; share = $share }
}
$folders = @{}
foreach ($pair in @(@('desktop', 'Desktop'), @('documents', 'MyDocuments'), @('pictures', 'MyPictures'))) {
try {
$dir = [Environment]::GetFolderPath($pair[1])
if ($dir -and (Test-Path -LiteralPath $dir -PathType Container)) { $folders[$pair[0]] = $dir }
} catch {}
}
try {
$shell = Get-ItemProperty -LiteralPath 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders' -ErrorAction Stop
$downloads = $shell.'{374DE290-123F-4565-9164-39C4925E467B}'
if (-not $downloads) { $downloads = Join-Path $env:USERPROFILE 'Downloads' }
$downloads = [Environment]::ExpandEnvironmentVariables($downloads)
if (Test-Path -LiteralPath $downloads -PathType Container) { $folders['downloads'] = $downloads }
} catch {}
Emit @{ folders = $folders }
`;
/**
* The script travels base64-encoded (UTF-16LE, what `-EncodedCommand` takes), so no character
* in it meets the command line's quoting rules. Exported for the test that pins the arguments.
*/
export const POWERSHELL_ARGS: readonly string[] = [
"-NoProfile",
"-NonInteractive",
"-NoLogo",
"-ExecutionPolicy",
"Bypass",
"-EncodedCommand",
Buffer.from(WINDOWS_REPORT_SCRIPT, "utf16le").toString("base64"),
];
/** Resolved from the system root so the desktop app's PATH, which users do break, is not relied on. */
function powershellPath(env: PlaceEffects["env"]): string {
const root = env.SystemRoot ?? env.windir;
return root
? path.win32.join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
: "powershell.exe";
}
function cmdPath(env: PlaceEffects["env"]): string {
return env.ComSpec ?? "cmd.exe";
}
/** One drive line of the report, after normalization. */
export interface WindowsDrive {
/** `C:\` */
root: string;
/** `System.IO.DriveType` and `Win32_LogicalDisk.DriveType` share the numbering: 2 removable, 3 fixed, 4 network, 5 CD-ROM, 6 RAM. */
type: number;
label?: string;
/** A network drive's `\\server\share`. */
share?: string;
}
export interface WindowsReport {
/** Null until the report's folders line arrived: the script prints it last, after the drives. */
folders: DirStandardFolders | null;
drives: WindowsDrive[];
}
/** `C:`, `c:\`, `C:\Users` → `C:\`; null for anything that does not start with a drive letter. */
function driveRoot(value: unknown): string | null {
if (typeof value !== "string") return null;
const match = /^([A-Za-z]):/.exec(value);
return match === null ? null : `${match[1]?.toUpperCase()}:\\`;
}
function nonEmpty(value: unknown): string | undefined {
return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
}
/**
* The report's lines, each a JSON object (or an array of them), everything else skipped: a
* line PowerShell's host printed on its own, or one cut short by the deadline.
*/
export function parseWindowsReport(text: string): WindowsReport {
const report: WindowsReport = { folders: null, drives: [] };
for (const line of text.split(/\r?\n/)) {
const trimmed = line.trim();
if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) continue;
let parsed: unknown;
try {
parsed = JSON.parse(trimmed);
} catch {
continue;
}
for (const item of Array.isArray(parsed) ? parsed : [parsed]) absorbReportItem(report, item);
}
return report;
}
function absorbReportItem(report: WindowsReport, item: unknown): void {
if (typeof item !== "object" || item === null) return;
const record = item as Record<string, unknown>;
const folders = record.folders;
if (typeof folders === "object" && folders !== null) {
const found: DirStandardFolders = report.folders ?? {};
for (const [key] of FIXED_FOLDERS) {
const value = nonEmpty((folders as Record<string, unknown>)[key]);
if (value !== undefined) found[key] = value;
}
report.folders = found;
}
const root = driveRoot(record.drive);
if (root === null) return;
const type = typeof record.type === "number" ? record.type : Number(record.type);
const label = nonEmpty(record.label);
const share = nonEmpty(record.share);
report.drives.push({
root,
type: Number.isFinite(type) ? type : 0,
...(label !== undefined ? { label } : {}),
...(share !== undefined ? { share } : {}),
});
}
function driveKind(type: number): DirLocation["kind"] {
if (type === 2) return "removable";
if (type === 4) return "network";
if (type === 5) return "optical";
return "drive";
}
/**
* The drives as This PC lists them: local drives by letter, then network drives by letter. A
* drive is named by its volume label when it has one; a network drive otherwise by its share —
* Explorer shows `media (\\nas)`, and the server behind a dead mapping is never asked for a
* label, so the share is what a network drive normally carries.
*/
export function windowsLocations(drives: readonly WindowsDrive[]): DirLocation[] {
const unique = [...new Map(drives.map((d): [string, WindowsDrive] => [d.root, d])).values()];
const byLetter = (a: WindowsDrive, b: WindowsDrive) => a.root.localeCompare(b.root);
const locals = unique.filter((d) => d.type !== 4).sort(byLetter);
const networks = unique.filter((d) => d.type === 4).sort(byLetter);
return [...locals, ...networks].map((d) => {
const label = d.label ?? d.share;
return { path: d.root, kind: driveKind(d.type), ...(label !== undefined ? { label } : {}) };
});
}
/** `cmd /u` writes UTF-16LE without a BOM; a child killed mid-character leaves an odd byte to drop. */
export function decodeCmdOutput(stdout: Buffer): string {
return stdout.subarray(0, stdout.length - (stdout.length % 2)).toString("utf16le");
}
const DRIVE_LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("");
/**
* Drive letters without PowerShell: `if exist X:\` for each letter, inside a `cmd.exe` we can
* kill. A dead network mapping blocks the loop at its letter; the letters printed before the
* deadline are kept, and the probe pins a thread of the child's, not one of ours.
*/
async function probeDriveLetters(effects: PlaceEffects): Promise<DirLocation[]> {
const probe = await effects.exec(
cmdPath(effects.env),
["/d", "/u", "/c", `for %d in (${DRIVE_LETTERS.join(" ")}) do @if exist %d:\\ echo %d:`],
{ timeoutMs: CMD_TIMEOUT_MS, verbatim: true },
);
const roots = new Set<string>();
for (const line of decodeCmdOutput(probe.stdout).split(/\r?\n/)) {
const root = /^[A-Za-z]:$/.test(line.trim()) ? driveRoot(line.trim()) : null;
if (root !== null) roots.add(root);
}
return [...roots].sort().map((root): DirLocation => ({ path: root, kind: "drive" }));
}
/** What is known without asking anything: the system drive and the one holding the home directory. */
function knownWindowsDrives(effects: PlaceEffects): DirLocation[] {
const roots = new Set<string>();
for (const candidate of [effects.env.SystemDrive, effects.homedir]) {
const root = driveRoot(candidate);
if (root !== null) roots.add(root);
}
return [...roots].sort().map((root): DirLocation => ({ path: root, kind: "drive" }));
}
async function windowsPlaces(effects: PlaceEffects): Promise<DirPlaces> {
const run = await effects.exec(powershellPath(effects.env), [...POWERSHELL_ARGS], {
timeoutMs: POWERSHELL_TIMEOUT_MS,
});
const report = parseWindowsReport(run.stdout.toString("utf8"));
let locations = windowsLocations(report.drives);
if (locations.length === 0) locations = await probeDriveLetters(effects);
if (locations.length === 0) locations = knownWindowsDrives(effects);
// A report cut short before its folders line leaves the folders unanswered rather than
// guessed: the picker then finds them by name, as it did before.
return {
locations,
...(report.folders !== null ? { standardFolders: report.folders } : {}),
};
}
// ---------------------------------------------------------------------------------------------
// The Windows hidden attribute
/**
* Names Explorer hides in a profile or a drive root, for a listing whose attributes could not be
* read: the profile's own files, the legacy junctions (hidden and access-denied, so a click on
* one only fails), and the system's root-level folders.
*/
const HIDDEN_BY_CONVENTION = new Set(
[
"AppData",
"Application Data",
"Cookies",
"Local Settings",
"My Documents",
"NetHood",
"PrintHood",
"Recent",
"SendTo",
"Start Menu",
"Templates",
"ntuser.ini",
"desktop.ini",
"Thumbs.db",
"Documents and Settings",
"System Volume Information",
"pagefile.sys",
"hiberfil.sys",
"swapfile.sys",
"DumpStack.log.tmp",
"bootmgr",
"BOOTNXT",
"Config.Msi",
].map((n) => n.toLowerCase()),
);
/** The curated fallback: finding-7 names anywhere, `ntuser.dat*`, and `$`-prefixed names in a drive root. */
export function conventionallyHiddenNames(dir: string, names: readonly string[]): Set<string> {
const atRoot = /^[A-Za-z]:\\?$/.test(dir);
return new Set(
names.filter((name) => {
const lower = name.toLowerCase();
return (
HIDDEN_BY_CONVENTION.has(lower) ||
lower.startsWith("ntuser.dat") ||
(atRoot && name.startsWith("$"))
);
}),
);
}
/**
* Which of `names` in `dir` carry the hidden attribute, as `dir /a:h /b` reports them — the
* attribute Explorer's default view hides (system-only items it shows, and every item Explorer
* hides in a profile is hidden, so one attribute and one process suffice). `/u` makes the
* output UTF-16LE whatever the console code page, `/d` keeps AutoRun commands out of it.
*
* The directory is an argument rather than the child's working directory because a mapped
* drive's realpath is a UNC path, and cmd.exe started in a UNC directory warns and silently
* runs in the Windows directory instead — wrong names with a clean exit. A path can hold no
* `"`, so the quoting is safe; a segment spelled `%NAME%` after a variable that exists is the
* one shape cmd mangles, and that folder's entries come back unmarked.
*
* `dir` exits 1 when nothing matched ("File Not Found", localized, on the stderr nobody reads),
* so exit 1 with nothing printed means no hidden entries. Anything else — no cmd.exe, a
* deadline, an unexpected exit — falls back to {@link conventionallyHiddenNames}.
*/
export async function windowsHiddenNames(
dir: string,
names: readonly string[],
effects: PlaceEffects = systemEffects(),
): Promise<Set<string>> {
if (names.length === 0) return new Set();
const run = await effects.exec(
cmdPath(effects.env),
["/d", "/u", "/c", "dir", "/a:h", "/b", `"${dir}"`],
{ timeoutMs: CMD_TIMEOUT_MS, verbatim: true },
);
const usable =
run.failed === undefined &&
!run.timedOut &&
(run.code === 0 || (run.code === 1 && run.stdout.length === 0));
if (!usable) return conventionallyHiddenNames(dir, names);
const listed = new Set(
decodeCmdOutput(run.stdout)
.split(/\r?\n/)
.map((line) => line.replace(/^\uFEFF/, ""))
.filter((line) => line !== ""),
);
return new Set(names.filter((name) => listed.has(name)));
}