@hienlh/ppm 0.17.57 → 0.18.0

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

@@ -0,0 +1,171 @@
+/** Orchestrator + 60s cache for `GET /api/system/host`. Picks providers by
+ *  platform, runs them concurrently (each guarded by its own 5s timeout so
+ *  one dead network share or TCC-denied read never blocks the response),
+ *  then applies the two response-wide rules the individual providers can't
+ *  enforce themselves: only directories that still exist on disk survive
+ *  (drops Shell COM's archive-as-folder quirk and stale bookmarks), and a
+ *  known-folder path wins over a pinned duplicate at the same path.
+ *
+ *  Existence checks use `fs.promises.stat`, not `statSync` — the whole-disk
+ *  scope means a stalled UNC/mapped path must never block the event loop
+ *  (same rule `host-drives.ts` follows for the Windows letter probe). */
+import { stat as fsStat } from "node:fs/promises";
+import { hostname as osHostname, homedir as osHomedir } from "node:os";
+import type { HostInfo, PinnedFolder } from "../../types/system.ts";
+import { getDrives } from "./host-drives.ts";
+import { getKnownFolders } from "./host-known-folders.ts";
+import { getWindowsQuickAccessPinned } from "./pinned-windows-quick-access.ts";
+import { getLinuxPinned } from "./pinned-linux-bookmarks.ts";
+import { getMacosFinderFavoritesPinned } from "./pinned-macos-finder-favorites.ts";
+
+const CACHE_TTL_MS = 60_000;
+const PROVIDER_TIMEOUT_MS = 5_000;
+/** Floors how often an explicit `?refresh=true` can actually trigger a rebuild — without
+ *  this, N concurrent refresh requests (or a trigger-happy client) each spawn their own
+ *  round of PowerShell/plutil/findmnt processes. */
+const REFRESH_FLOOR_MS = 5_000;
+
+let cached: { info: HostInfo; expiresAt: number } | null = null;
+let lastBuildAt = 0;
+/** Shared by all callers while a build is running — concurrent calls (refresh or not)
+ *  await the same build instead of each starting their own. */
+let inFlight: Promise<HostInfo> | null = null;
+
+async function getPinnedByPlatform(
+  platform: NodeJS.Platform,
+  homedir: string,
+  warnings: string[],
+): Promise<PinnedFolder[]> {
+  if (platform === "win32") return getWindowsQuickAccessPinned(warnings);
+  if (platform === "linux") return getLinuxPinned(homedir, warnings);
+  if (platform === "darwin") return getMacosFinderFavoritesPinned(homedir, warnings);
+  return [];
+}
+
+export interface HostInfoDeps {
+  getDrives: typeof getDrives;
+  getKnownFolders: typeof getKnownFolders;
+  getPinned: typeof getPinnedByPlatform;
+  /** Directory-existence probe — swappable so orchestrator tests never touch the real filesystem. */
+  isDirectory: (path: string) => Promise<boolean>;
+}
+
+const defaultDeps: HostInfoDeps = {
+  getDrives,
+  getKnownFolders,
+  getPinned: getPinnedByPlatform,
+  isDirectory: async (p) => {
+    try {
+      return (await fsStat(p)).isDirectory();
+    } catch {
+      return false;
+    }
+  },
+};
+
+/** Race a provider call against its own timeout; a rejection or a timeout both
+ *  degrade to `fallback` plus a warning — the caller never sees an exception. */
+async function withTimeout<T>(label: string, promise: Promise<T>, fallback: T, warnings: string[]): Promise<T> {
+  const guarded = promise.catch((e) => {
+    warnings.push(`${label}: provider threw (${(e as Error)?.message ?? e})`);
+    return fallback;
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<T>((resolve) => {
+    timer = setTimeout(() => {
+      warnings.push(`${label}: provider timed out after ${PROVIDER_TIMEOUT_MS}ms`);
+      resolve(fallback);
+    }, PROVIDER_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([guarded, timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function existingDirectories<T extends { path: string }>(
+  items: T[],
+  isDirectory: HostInfoDeps["isDirectory"],
+): Promise<T[]> {
+  const results = await Promise.allSettled(items.map(async (item) => ((await isDirectory(item.path)) ? item : null)));
+  const out: T[] = [];
+  for (const r of results) {
+    if (r.status === "fulfilled" && r.value) out.push(r.value);
+  }
+  return out;
+}
+
+function toHostPlatform(p: NodeJS.Platform): HostInfo["platform"] {
+  if (p === "win32" || p === "darwin" || p === "linux") return p;
+  return "linux"; // unsupported host (e.g. freebsd) — closest POSIX-shaped fallback
+}
+
+/** Pure orchestration for an explicit platform/homedir/hostname (no `process.*` reads) —
+ *  lets tests exercise all three OS branches, and the cache/dedupe/existence-filter
+ *  logic in isolation, from any single host. Never throws. */
+export async function buildHostInfo(
+  platform: NodeJS.Platform,
+  homedir: string,
+  hostname: string,
+  overrides: Partial<HostInfoDeps> = {},
+): Promise<HostInfo> {
+  const deps: HostInfoDeps = { ...defaultDeps, ...overrides };
+  const warnings: string[] = [];
+
+  const [drives, rawKnownFolders, rawPinned] = await Promise.all([
+    withTimeout("drives", deps.getDrives(platform, warnings), [], warnings),
+    withTimeout("knownFolders", deps.getKnownFolders(platform, homedir, warnings), [], warnings),
+    withTimeout("pinned", deps.getPinned(platform, homedir, warnings), [], warnings),
+  ]);
+
+  const knownFolders = await existingDirectories(rawKnownFolders, deps.isDirectory);
+  const knownPaths = new Set(knownFolders.map((f) => f.path));
+  const pinned = await existingDirectories(
+    rawPinned.filter((p) => !knownPaths.has(p.path)),
+    deps.isDirectory,
+  );
+
+  return {
+    platform: toHostPlatform(platform),
+    sep: platform === "win32" ? "\\" : "/",
+    homedir,
+    hostname,
+    drives,
+    knownFolders,
+    pinned,
+    warnings,
+  };
+}
+
+/** Cached singleton entrypoint for the route. Pass `refresh: true` to bypass the 60s
+ *  cache — floored to one rebuild per `REFRESH_FLOOR_MS`, and de-duped against any
+ *  build already in flight, so concurrent/rapid-fire refreshes share one process spawn. */
+export async function getHostInfo(
+  opts: { refresh?: boolean } = {},
+  overrides: Partial<HostInfoDeps> = {},
+): Promise<HostInfo> {
+  const now = Date.now();
+  if (!opts.refresh && cached && cached.expiresAt > now) return cached.info;
+  if (opts.refresh && cached && now - lastBuildAt < REFRESH_FLOOR_MS) return cached.info;
+  if (inFlight) return inFlight;
+
+  inFlight = (async () => {
+    try {
+      const info = await buildHostInfo(process.platform, osHomedir(), osHostname(), overrides);
+      lastBuildAt = Date.now();
+      cached = { info, expiresAt: lastBuildAt + CACHE_TTL_MS };
+      return info;
+    } finally {
+      inFlight = null;
+    }
+  })();
+  return inFlight;
+}
+
+/** Test-only: force the next `getHostInfo()` call to rebuild instead of serving the cache. */
+export function _resetHostInfoCache(): void {
+  cached = null;
+  lastBuildAt = 0;
+  inFlight = null;
+}

package/src/services/host-info/host-known-folders.ts

@@ -0,0 +1,180 @@
+/** Resolved known-folder locations per OS — not the naive `~/Desktop` guess.
+ *  Windows asks `[Environment]::GetFolderPath` (handles OneDrive-redirected
+ *  folders) plus the registry for Downloads (no `SHGetKnownFolderPath` shim
+ *  in `[Environment]`). macOS prefers the iCloud "Desktop & Documents" sync
+ *  location when present (Finder silently moves the real content there).
+ *  Linux asks `xdg-user-dir` (merges locale + `/etc/xdg` defaults), falling
+ *  back to a tolerant regex parse of `user-dirs.dirs`. */
+import * as fsp from "node:fs/promises";
+import type { KnownFolder, KnownFolderKey } from "../../types/system.ts";
+import { defaultRunner, type Runner } from "./spawn-runner.ts";
+
+export interface KnownFolderDeps {
+  run: Runner;
+  pathExists: (path: string) => Promise<boolean>;
+  readFile: (path: string) => Promise<string>;
+}
+
+const defaultDeps: KnownFolderDeps = {
+  run: defaultRunner,
+  pathExists: async (p) => {
+    try {
+      return (await fsp.stat(p)).isDirectory();
+    } catch {
+      return false;
+    }
+  },
+  readFile: (p) => fsp.readFile(p, "utf-8"),
+};
+
+// ── Windows ──────────────────────────────────────────────────────────────
+
+const WIN_NAMES: Record<string, string> = {
+  desktop: "Desktop",
+  documents: "Documents",
+  pictures: "Pictures",
+  music: "Music",
+  videos: "Videos",
+  downloads: "Downloads",
+};
+
+const WIN_SCRIPT = `
+$r = [ordered]@{}
+$r.desktop = [Environment]::GetFolderPath('Desktop')
+$r.documents = [Environment]::GetFolderPath('MyDocuments')
+$r.pictures = [Environment]::GetFolderPath('MyPictures')
+$r.music = [Environment]::GetFolderPath('MyMusic')
+$r.videos = [Environment]::GetFolderPath('MyVideos')
+$reg = Get-ItemProperty 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders' -ErrorAction SilentlyContinue
+$dl = $reg.'{374DE290-123F-4565-9164-39C4925E467B}'
+if ($dl) { $r.downloads = [Environment]::ExpandEnvironmentVariables($dl) }
+$r | ConvertTo-Json -Compress
+`.trim();
+
+async function getWindowsKnownFolders(deps: KnownFolderDeps, warnings: string[]): Promise<KnownFolder[]> {
+  try {
+    const res = await deps.run(
+      ["powershell.exe", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", WIN_SCRIPT],
+      5000,
+    );
+    if (res.timedOut || res.code !== 0) {
+      warnings.push(`knownFolders: PowerShell ${res.timedOut ? "timed out" : `exited ${res.code}`}`);
+      return [];
+    }
+    const parsed = JSON.parse(res.stdout.trim() || "{}") as Record<string, string | undefined>;
+    const folders: KnownFolder[] = [];
+    for (const key of Object.keys(WIN_NAMES)) {
+      const path = parsed[key];
+      if (path) folders.push({ key: key as KnownFolderKey, name: WIN_NAMES[key]!, path });
+    }
+    return folders;
+  } catch (e) {
+    warnings.push(`knownFolders: PowerShell failed (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+}
+
+// ── macOS ────────────────────────────────────────────────────────────────
+
+const DARWIN_FOLDERS: { key: KnownFolderKey; name: string; dir: string; cloudSynced: boolean }[] = [
+  { key: "desktop", name: "Desktop", dir: "Desktop", cloudSynced: true },
+  { key: "documents", name: "Documents", dir: "Documents", cloudSynced: true },
+  { key: "downloads", name: "Downloads", dir: "Downloads", cloudSynced: false },
+  { key: "pictures", name: "Pictures", dir: "Pictures", cloudSynced: false },
+  { key: "music", name: "Music", dir: "Music", cloudSynced: false },
+  { key: "videos", name: "Movies", dir: "Movies", cloudSynced: false },
+];
+
+async function getDarwinKnownFolders(deps: KnownFolderDeps, homedir: string): Promise<KnownFolder[]> {
+  const cloudRoot = `${homedir}/Library/Mobile Documents/com~apple~CloudDocs`;
+  const cloudExists = await deps.pathExists(cloudRoot);
+  const folders: KnownFolder[] = [];
+  for (const entry of DARWIN_FOLDERS) {
+    let path = `${homedir}/${entry.dir}`;
+    if (entry.cloudSynced && cloudExists) {
+      const cloudPath = `${cloudRoot}/${entry.dir}`;
+      if (await deps.pathExists(cloudPath)) path = cloudPath;
+    }
+    folders.push({ key: entry.key, name: entry.name, path });
+  }
+  if (cloudExists) folders.push({ key: "icloud", name: "iCloud Drive", path: cloudRoot });
+  return folders;
+}
+
+// ── Linux ────────────────────────────────────────────────────────────────
+
+const LINUX_FOLDERS: { key: KnownFolderKey; name: string; xdg: string }[] = [
+  { key: "desktop", name: "Desktop", xdg: "DESKTOP" },
+  { key: "documents", name: "Documents", xdg: "DOCUMENTS" },
+  { key: "downloads", name: "Downloads", xdg: "DOWNLOAD" },
+  { key: "pictures", name: "Pictures", xdg: "PICTURES" },
+  { key: "music", name: "Music", xdg: "MUSIC" },
+  { key: "videos", name: "Videos", xdg: "VIDEOS" },
+];
+
+async function readUserDirsFallback(
+  deps: KnownFolderDeps,
+  homedir: string,
+  warnings: string[],
+): Promise<Record<string, string>> {
+  try {
+    const raw = await deps.readFile(`${homedir}/.config/user-dirs.dirs`);
+    const map: Record<string, string> = {};
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^XDG_(\w+)_DIR="(.+)"$/);
+      if (!m) continue;
+      map[m[1]!] = m[2]!.replace("$HOME", homedir);
+    }
+    return map;
+  } catch (e) {
+    warnings.push(`knownFolders: user-dirs.dirs read failed (${(e as Error)?.message ?? e})`);
+    return {};
+  }
+}
+
+async function getLinuxKnownFolders(
+  deps: KnownFolderDeps,
+  homedir: string,
+  warnings: string[],
+): Promise<KnownFolder[]> {
+  const folders: KnownFolder[] = [];
+  let fallback: Record<string, string> | null = null;
+  for (const entry of LINUX_FOLDERS) {
+    let path: string | undefined;
+    try {
+      const res = await deps.run(["xdg-user-dir", entry.xdg], 3000);
+      if (!res.timedOut && res.code === 0) {
+        const out = res.stdout.trim();
+        if (out && out !== homedir) path = out;
+      }
+    } catch {
+      // spawn itself threw (e.g. xdg-user-dir not installed) — fall through to file parse
+    }
+    if (!path) {
+      fallback ??= await readUserDirsFallback(deps, homedir, warnings);
+      path = fallback[entry.xdg];
+    }
+    if (path) folders.push({ key: entry.key, name: entry.name, path });
+  }
+  return folders;
+}
+
+/** Resolve known folders for `platform`, appending any failure to the shared `warnings` array (never throws). */
+export async function getKnownFolders(
+  platform: NodeJS.Platform,
+  homedir: string,
+  warnings: string[],
+  overrides: Partial<KnownFolderDeps> = {},
+): Promise<KnownFolder[]> {
+  const deps: KnownFolderDeps = { ...defaultDeps, ...overrides };
+  try {
+    if (platform === "win32") return await getWindowsKnownFolders(deps, warnings);
+    if (platform === "darwin") return await getDarwinKnownFolders(deps, homedir);
+    if (platform === "linux") return await getLinuxKnownFolders(deps, homedir, warnings);
+    warnings.push(`knownFolders: unsupported platform "${platform}"`);
+    return [];
+  } catch (e) {
+    warnings.push(`knownFolders: unexpected failure (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+}

package/src/services/host-info/pinned-linux-bookmarks.ts

@@ -0,0 +1,89 @@
+/** Linux pinned folders: GTK3/GTK4 bookmarks (Nautilus, `~/.config/gtk-3.0/bookmarks`,
+ *  falling back to `gtk-4.0` since some sources report GTK4-only apps write
+ *  there) and KDE Places (Dolphin, `~/.local/share/user-places.xbel`). Both
+ *  formats are plain text/XML, stable for 15+ years — no reverse-engineering
+ *  needed, so a tolerant regex parse is used instead of pulling in an XML lib. */
+import * as fsp from "node:fs/promises";
+import type { PinnedFolder } from "../../types/system.ts";
+
+export interface LinuxBookmarkDeps {
+  readFile: (path: string) => Promise<string>;
+}
+
+const defaultDeps: LinuxBookmarkDeps = { readFile: (p) => fsp.readFile(p, "utf-8") };
+
+interface RawBookmark {
+  name: string;
+  path: string;
+}
+
+function parseGtkBookmarks(raw: string): RawBookmark[] {
+  const out: RawBookmark[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const m = trimmed.match(/^file:\/\/(\S+)(?: (.*))?$/);
+    if (!m) continue; // malformed line or a non-file:// bookmark (e.g. network location) — skip, not fatal
+    const path = decodeURIComponent(m[1]!);
+    const name = m[2] ? decodeURIComponent(m[2]) : (path.split("/").filter(Boolean).pop() ?? path);
+    out.push({ name, path });
+  }
+  return out;
+}
+
+async function getGtkPinned(deps: LinuxBookmarkDeps, homedir: string, warnings: string[]): Promise<PinnedFolder[]> {
+  const candidates = [`${homedir}/.config/gtk-3.0/bookmarks`, `${homedir}/.config/gtk-4.0/bookmarks`];
+  for (const file of candidates) {
+    try {
+      const raw = await deps.readFile(file);
+      return parseGtkBookmarks(raw).map((b) => ({ ...b, source: "gtk" as const }));
+    } catch {
+      // try the next candidate path
+    }
+  }
+  warnings.push("pinned: no GTK bookmarks file found (gtk-3.0/gtk-4.0)");
+  return [];
+}
+
+function parseKdePlaces(raw: string): RawBookmark[] {
+  const out: RawBookmark[] = [];
+  const re = /<bookmark\s+href="file:\/\/(.*?)"[^>]*>[\s\S]*?<title>(.*?)<\/title>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(raw))) {
+    out.push({ path: decodeURIComponent(m[1]!), name: decodeURIComponent(m[2]!) });
+  }
+  return out;
+}
+
+async function getKdePinned(deps: LinuxBookmarkDeps, homedir: string, warnings: string[]): Promise<PinnedFolder[]> {
+  try {
+    const raw = await deps.readFile(`${homedir}/.local/share/user-places.xbel`);
+    return parseKdePlaces(raw).map((b) => ({ ...b, source: "kde" as const }));
+  } catch (e) {
+    warnings.push(`pinned: KDE user-places.xbel not found (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+}
+
+/** GTK (Nautilus) + KDE (Dolphin) pinned folders, deduped by path (GTK wins on conflict).
+ *  Appends any failure to the shared `warnings` array (never throws). */
+export async function getLinuxPinned(
+  homedir: string,
+  warnings: string[],
+  overrides: Partial<LinuxBookmarkDeps> = {},
+): Promise<PinnedFolder[]> {
+  const deps: LinuxBookmarkDeps = { ...defaultDeps, ...overrides };
+  const [gtk, kde] = await Promise.all([
+    getGtkPinned(deps, homedir, warnings),
+    getKdePinned(deps, homedir, warnings),
+  ]);
+
+  const seen = new Set<string>();
+  const result: PinnedFolder[] = [];
+  for (const item of [...gtk, ...kde]) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    result.push(item);
+  }
+  return result;
+}

package/src/services/host-info/pinned-macos-finder-favorites.ts

@@ -0,0 +1,175 @@
+/** macOS Finder sidebar Favorites. The container file
+ *  (`~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.FavoriteItems.sfl{2,3,4}`)
+ *  is an NSKeyedArchiver binary plist; `plutil -convert xml1` turns it into
+ *  readable XML without extra permissions, but the payload is still an
+ *  archived object graph (`$objects` array + `CF$UID` references), not plain
+ *  key/value pairs. Each favorite item is a dict carrying `Name` plus either
+ *  a direct `URL` (fast path) or a `Bookmark` binary blob that must be
+ *  decoded by `apple-bookmark-decoder.ts` (slow path, used when the item has
+ *  moved since it was pinned).
+ *
+ *  UNVERIFIED against a real macOS sample — field names/nesting come from
+ *  public reverse-engineering (see plans research), not Apple docs. Kept
+ *  enabled; any parse failure degrades to a `warnings[]` entry instead of
+ *  blocking the whole `/api/system/host` response. Also gated by TCC: the
+ *  sharedfilelist directory needs Full Disk Access for an unsandboxed
+ *  process, so a denied read must surface as an actionable warning, not a
+ *  silent empty list. */
+import * as fsp from "node:fs/promises";
+import type { PinnedFolder } from "../../types/system.ts";
+import { defaultRunner, type Runner } from "./spawn-runner.ts";
+import { parsePlistXml, type PlistValue } from "./apple-plist-xml-parser.ts";
+import { decodeBookmarkPath } from "./apple-bookmark-decoder.ts";
+
+export interface FinderFavoritesDeps {
+  run: Runner;
+  fileExists: (path: string) => Promise<boolean>;
+}
+
+const defaultDeps: FinderFavoritesDeps = {
+  run: defaultRunner,
+  fileExists: async (p) => {
+    try {
+      await fsp.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+const SFL_EXTENSIONS = ["sfl4", "sfl3", "sfl2"]; // newest naming first (macOS 26, 13-25, <=12)
+
+interface RawFavorite {
+  name: string;
+  path: string;
+}
+
+function isUidMarker(v: PlistValue): v is { "CF$UID": number } {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    !Buffer.isBuffer(v) &&
+    Object.keys(v).length === 1 &&
+    typeof (v as Record<string, PlistValue>)["CF$UID"] === "number"
+  );
+}
+
+function resolveUid(objects: PlistValue[], v: PlistValue): PlistValue | null {
+  return isUidMarker(v) ? (objects[v["CF$UID"]] ?? null) : v;
+}
+
+function asRecord(v: PlistValue | null): Record<string, PlistValue> | null {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && !Buffer.isBuffer(v)
+    ? (v as Record<string, PlistValue>)
+    : null;
+}
+
+/** NSDictionary is archived as parallel `NS.keys`/`NS.objects` UID-ref arrays, not plain key/value pairs. */
+function resolveNsKeyedDict(raw: PlistValue | null, objects: PlistValue[]): Record<string, PlistValue> | null {
+  const rec = asRecord(raw);
+  if (!rec) return null;
+  const nsKeys = rec["NS.keys"];
+  const nsObjects = rec["NS.objects"];
+  if (!Array.isArray(nsKeys) || !Array.isArray(nsObjects) || nsKeys.length !== nsObjects.length) return rec;
+  const out: Record<string, PlistValue> = {};
+  for (let i = 0; i < nsKeys.length; i++) {
+    const key = resolveUid(objects, nsKeys[i]!);
+    if (typeof key === "string") out[key] = nsObjects[i]!;
+  }
+  return out;
+}
+
+function extractFavorites(objects: PlistValue[], warnings: string[]): RawFavorite[] {
+  const out: RawFavorite[] = [];
+  for (const raw of objects) {
+    const item = resolveNsKeyedDict(raw, objects);
+    if (!item || item["Name"] === undefined) continue;
+    const name = resolveUid(objects, item["Name"]);
+    if (typeof name !== "string") continue;
+
+    let path: string | null = null;
+
+    // Fast path: NSURL already carries a file:// string.
+    if (item["URL"] !== undefined) {
+      const urlDict = resolveNsKeyedDict(resolveUid(objects, item["URL"]), objects);
+      const relative = urlDict?.["NS.relative"];
+      const relativeStr = relative !== undefined ? resolveUid(objects, relative) : undefined;
+      if (typeof relativeStr === "string" && relativeStr.startsWith("file://")) {
+        try {
+          path = decodeURIComponent(relativeStr.replace(/^file:\/\//, ""));
+        } catch {
+          // Malformed percent-encoding — fall through to the Bookmark blob below.
+        }
+      }
+    }
+
+    // Slow path: decode the raw Bookmark blob (used once the item has moved).
+    if (!path && item["Bookmark"] !== undefined) {
+      const bookmark = resolveUid(objects, item["Bookmark"]);
+      if (Buffer.isBuffer(bookmark)) {
+        try {
+          path = decodeBookmarkPath(bookmark);
+        } catch (e) {
+          warnings.push(`pinned: Finder Favorites bookmark decode failed for "${name}" (${(e as Error)?.message ?? e})`);
+        }
+      }
+    }
+
+    if (path) out.push({ name, path });
+  }
+  return out;
+}
+
+/** Read Finder sidebar Favorites, appending any failure to the shared `warnings` array (never throws). */
+export async function getMacosFinderFavoritesPinned(
+  homedir: string,
+  warnings: string[],
+  overrides: Partial<FinderFavoritesDeps> = {},
+): Promise<PinnedFolder[]> {
+  const deps: FinderFavoritesDeps = { ...defaultDeps, ...overrides };
+  const dir = `${homedir}/Library/Application Support/com.apple.sharedfilelist`;
+
+  let file: string | null = null;
+  for (const ext of SFL_EXTENSIONS) {
+    const candidate = `${dir}/com.apple.LSSharedFileList.FavoriteItems.${ext}`;
+    if (await deps.fileExists(candidate)) {
+      file = candidate;
+      break;
+    }
+  }
+  if (!file) {
+    warnings.push(
+      "pinned: Finder Favorites file not found (.sfl2/.sfl3/.sfl4) — grant Full Disk Access to the terminal/ppm binary if it should exist",
+    );
+    return [];
+  }
+
+  let xml: string;
+  try {
+    const res = await deps.run(["plutil", "-convert", "xml1", "-o", "-", file], 5000);
+    if (res.timedOut || res.code !== 0) {
+      warnings.push(
+        `pinned: Finder Favorites: plutil ${res.timedOut ? "timed out" : `exited ${res.code}`} — grant Full Disk Access to the terminal/ppm binary`,
+      );
+      return [];
+    }
+    xml = res.stdout;
+  } catch (e) {
+    warnings.push(`pinned: Finder Favorites plutil failed (${(e as Error)?.message ?? e})`);
+    return [];
+  }
+
+  try {
+    const plist = parsePlistXml(xml);
+    const objects = asRecord(plist)?.["$objects"];
+    if (!Array.isArray(objects)) throw new Error("no $objects array in NSKeyedArchiver container");
+    return extractFavorites(objects, warnings).map((f) => ({ ...f, source: "finder-favorites" as const }));
+  } catch (e) {
+    warnings.push(
+      `pinned: Finder Favorites parse failed (${(e as Error)?.message ?? e}) — reverse-engineered format, verify against a real macOS sample`,
+    );
+    return [];
+  }
+}