@hienlh/ppm 0.23.10 → 0.23.12

package/src/services/system-metrics/wifi-darwin.ts

@@ -0,0 +1,224 @@
+/**
+ * The Wi-Fi radio's live facts on macOS — signal, channel, transmit rate — read
+ * from CoreWLAN over `bun:ffi` and the Objective-C runtime.
+ *
+ * Not `system_profiler SPAirPortDataType`, which is where these figures are
+ * usually taken from on the command line: it SCANS for nearby networks on every
+ * run (3.8 s wall, measured) and the scan is not free for the link either — the
+ * gateway's ping maximum went from 73 to 135 ms while it ran. CoreWLAN answers the
+ * same questions from the association the radio already has, in 5–10 ms (39 ms at
+ * most, measured while a scan was running).
+ *
+ * That is still a synchronous call on PPM's one event loop, so it is taken at most
+ * once per `WIFI_MEMO_MS`. Three things keep it from taking the process down:
+ * - every object id is a `u64` (BigInt). Short `NSString`s are TAGGED POINTERS —
+ *   the value is the string, with the top bit set — and a JS number cannot hold
+ *   that bit, so passing one as a number hands the runtime a different pointer
+ *   (measured: a segfault at 0x10, then a C++ exception out of `UTF8String`);
+ * - every message is preceded by `class_respondsToSelector`, because an
+ *   Objective-C exception unwinding through an FFI frame aborts the process;
+ * - each read runs inside its own autorelease pool, or every `ssid` and
+ *   `wlanChannel` returned would leak for the life of the server.
+ *
+ * The network's name is usually absent: since macOS 14 CoreWLAN withholds the
+ * SSID from any process without Location Services permission. That is reported
+ * as unknown, not guessed from somewhere else.
+ */
+import { CString, dlopen, FFIType as T, type Pointer } from "bun:ffi";
+
+/** Signal and rate move slowly; a read is a blocking call. */
+export const WIFI_MEMO_MS = 5000;
+
+const OBJC = "/usr/lib/libobjc.A.dylib";
+const LIBSYSTEM = "/usr/lib/libSystem.B.dylib";
+const COREWLAN = "/System/Library/Frameworks/CoreWLAN.framework/CoreWLAN";
+const RTLD_LAZY = 1;
+
+/** `CWChannelBand`. */
+const BAND_2GHZ = 1;
+const BAND_5GHZ = 2;
+const BAND_6GHZ = 3;
+
+export interface DarwinWifiStatus {
+  /** "en0" — which interface these facts belong to. */
+  interfaceName: string;
+  /** dBm; 0 when the radio is not associated. */
+  rssiDbm?: number;
+  noiseDbm?: number;
+  /** The rate the radio is transmitting at, Mbit/s; 0 when not associated. */
+  transmitRateMbps?: number;
+  channel?: number;
+  /** `CWChannelBand`: 1 = 2.4 GHz, 2 = 5 GHz, 3 = 6 GHz. */
+  band?: number;
+  ssid?: string;
+}
+
+/** NetworkManager's `nm_wifi_utils_level_to_quality`, which is where the signal
+ *  percentage Mission Center shows comes from: -40 dBm and stronger is 100%,
+ *  -100 dBm and weaker is 0%, truncated as NM truncates. */
+export function signalPercent(rssiDbm: number): number {
+  const distance = Math.abs(Math.min(-40, Math.max(-100, rssiDbm)) + 40);
+  return Math.max(0, Math.min(100, 100 - Math.trunc((100 * distance) / 60)));
+}
+
+/** Centre frequency of a channel, MHz (IEEE 802.11 channel numbering). */
+export function channelFrequencyMHz(channel: number, band: number): number | undefined {
+  if (!Number.isInteger(channel) || channel <= 0) return undefined;
+  if (band === BAND_2GHZ) return channel === 14 ? 2484 : channel <= 13 ? 2407 + 5 * channel : undefined;
+  if (band === BAND_5GHZ) return 5000 + 5 * channel;
+  // Channel 2 is the one 6 GHz channel off the 5 MHz grid.
+  if (band === BAND_6GHZ) return channel === 2 ? 5935 : 5950 + 5 * channel;
+  return undefined;
+}
+
+/** The facts a NIC row carries. A radio that is off or not associated reports
+ *  zeroes, which are left out rather than shown as 0% and 0 Mbps. */
+export function wirelessFacts(status: DarwinWifiStatus): {
+  ssid?: string; signalPercent?: number; frequencyMHz?: number; linkMbps?: number;
+} {
+  const frequency = status.channel !== undefined && status.band !== undefined
+    ? channelFrequencyMHz(status.channel, status.band)
+    : undefined;
+  const rate = status.transmitRateMbps;
+  return {
+    ...(status.ssid ? { ssid: status.ssid } : {}),
+    ...(status.rssiDbm !== undefined && status.rssiDbm < 0 ? { signalPercent: signalPercent(status.rssiDbm) } : {}),
+    ...(frequency !== undefined ? { frequencyMHz: frequency } : {}),
+    ...(rate !== undefined && rate > 0 ? { linkMbps: Math.round(rate) } : {}),
+  };
+}
+
+type Id = bigint;
+
+interface ObjcRuntime {
+  getClass(name: string): Id;
+  /** `[obj sel]`, or undefined when obj is nil or does not answer sel. */
+  object(obj: Id, sel: string): Id | undefined;
+  integer(obj: Id, sel: string): number | undefined;
+  double(obj: Id, sel: string): number | undefined;
+  utf8(obj: Id): string | undefined;
+  pool<R>(body: () => R): R;
+}
+
+function openObjcRuntime(): ObjcRuntime | null {
+  const base = dlopen(OBJC, {
+    objc_getClass: { args: [T.ptr], returns: T.u64 },
+    sel_registerName: { args: [T.ptr], returns: T.ptr },
+    object_getClass: { args: [T.u64], returns: T.u64 },
+    class_respondsToSelector: { args: [T.u64, T.ptr], returns: T.bool },
+    objc_autoreleasePoolPush: { args: [], returns: T.ptr },
+    objc_autoreleasePoolPop: { args: [T.ptr], returns: T.void },
+  }).symbols;
+  // One handle per return type: `objc_msgSend` is a trampoline, and the declared
+  // signature is what decides which register the answer is read from.
+  const sendId = dlopen(OBJC, { objc_msgSend: { args: [T.u64, T.ptr], returns: T.u64 } }).symbols.objc_msgSend;
+  const sendPtr = dlopen(OBJC, { objc_msgSend: { args: [T.u64, T.ptr], returns: T.ptr } }).symbols.objc_msgSend;
+  const sendI64 = dlopen(OBJC, { objc_msgSend: { args: [T.u64, T.ptr], returns: T.i64 } }).symbols.objc_msgSend;
+  const sendF64 = dlopen(OBJC, { objc_msgSend: { args: [T.u64, T.ptr], returns: T.f64 } }).symbols.objc_msgSend;
+
+  const selectors = new Map<string, Pointer>();
+  const sel = (name: string) => {
+    let s = selectors.get(name);
+    if (!s) {
+      s = base.sel_registerName(Buffer.from(`${name}\0`)) as Pointer;
+      selectors.set(name, s);
+    }
+    return s;
+  };
+  const answers = (obj: Id, name: string) =>
+    obj !== 0n && base.class_respondsToSelector(base.object_getClass(obj), sel(name));
+
+  return {
+    getClass: (name) => base.objc_getClass(Buffer.from(`${name}\0`)) as Id,
+    object: (obj, name) => {
+      if (!answers(obj, name)) return undefined;
+      const r = sendId(obj, sel(name)) as Id;
+      return r === 0n ? undefined : r;
+    },
+    integer: (obj, name) => (answers(obj, name) ? Number(sendI64(obj, sel(name))) : undefined),
+    double: (obj, name) => (answers(obj, name) ? (sendF64(obj, sel(name)) as number) : undefined),
+    utf8: (obj) => {
+      if (!answers(obj, "UTF8String")) return undefined;
+      const p = sendPtr(obj, sel("UTF8String")) as Pointer | null;
+      return p ? new CString(p).toString() : undefined;
+    },
+    pool: (body) => {
+      const token = base.objc_autoreleasePoolPush();
+      try {
+        return body();
+      } finally {
+        base.objc_autoreleasePoolPop(token);
+      }
+    },
+  };
+}
+
+/**
+ * A reader for the default Wi-Fi interface, or undefined on every call where the
+ * runtime or the framework cannot be loaded (never on a real Mac) or there is no
+ * Wi-Fi hardware.
+ */
+export function createCoreWlanReader(): () => DarwinWifiStatus | undefined {
+  let runtime: ObjcRuntime | null | undefined;
+  return () => {
+    if (runtime === undefined) {
+      try {
+        const loader = dlopen(LIBSYSTEM, { dlopen: { args: [T.ptr, T.i32], returns: T.ptr } }).symbols;
+        runtime = loader.dlopen(Buffer.from(`${COREWLAN}\0`), RTLD_LAZY) ? openObjcRuntime() : null;
+      } catch {
+        runtime = null;
+      }
+    }
+    const rt = runtime;
+    if (!rt) return undefined;
+    try {
+      return rt.pool(() => {
+        const cls = rt.getClass("CWWiFiClient");
+        const client = cls === 0n ? undefined : rt.object(cls, "sharedWiFiClient");
+        const iface = client === undefined ? undefined : rt.object(client, "interface");
+        if (iface === undefined) return undefined;
+        const name = rt.object(iface, "interfaceName");
+        const interfaceName = name === undefined ? undefined : rt.utf8(name);
+        if (!interfaceName) return undefined;
+        const channel = rt.object(iface, "wlanChannel");
+        const ssid = rt.object(iface, "ssid");
+        const status: DarwinWifiStatus = { interfaceName };
+        const set = <K extends keyof DarwinWifiStatus>(key: K, value: DarwinWifiStatus[K] | undefined) => {
+          if (value !== undefined) status[key] = value;
+        };
+        set("rssiDbm", rt.integer(iface, "rssiValue"));
+        set("noiseDbm", rt.integer(iface, "noiseMeasurement"));
+        set("transmitRateMbps", rt.double(iface, "transmitRate"));
+        if (channel !== undefined) {
+          set("channel", rt.integer(channel, "channelNumber"));
+          set("band", rt.integer(channel, "channelBand"));
+        }
+        set("ssid", ssid === undefined ? undefined : rt.utf8(ssid));
+        return status;
+      });
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/** `read` at most once per `ttlMs`, a failure included. */
+export function memoWifiStatus(
+  read: () => DarwinWifiStatus | undefined,
+  now: () => number = Date.now,
+  ttlMs = WIFI_MEMO_MS,
+): () => DarwinWifiStatus | undefined {
+  let last: { at: number; value: DarwinWifiStatus | undefined } | null = null;
+  return () => {
+    const at = now();
+    if (!last || at - last.at >= ttlMs) last = { at, value: read() };
+    return last.value;
+  };
+}
+
+let shared: (() => DarwinWifiStatus | undefined) | null = null;
+
+export function darwinWifiStatus(): DarwinWifiStatus | undefined {
+  shared ??= memoWifiStatus(createCoreWlanReader());
+  return shared();
+}

package/src/services/system-services/app-icon-service.ts

@@ -2,30 +2,56 @@
  * App id to an icon file on disk, for the icon route.
  *
  * The security property lives here rather than in the route: the caller supplies
- * an APP ID, this looks up that id's desktop entry, and only the path that
- * entry's own Icon resolved to is ever returned. There is no request shape that
- * names a file, so the route cannot become an arbitrary file read.
+ * an APP ID, this looks up that app, and only the file that app's own metadata
+ * pointed at is ever returned. There is no request shape that names a file, so
+ * the route cannot become an arbitrary file read.
  *
+ * Linux: the id is a desktop entry, and its Icon resolves through the icon themes.
  * Both caches are lazy and built once, so a host where nobody opens the Apps page
  * pays nothing: the entry scan measured 9 ms and the icon index 100 ms here.
+ *
+ * macOS: the id is a bundle the last tick listed, and the file is a PNG converted
+ * from that bundle's own icon. An app no tick listed has no icon to ask for.
  */
+import { join } from "node:path";
 import { realLinuxFs, type LinuxFs } from "../system-metrics/linux-fs.ts";
+import { getPpmDir } from "../ppm-dir.ts";
 import { createLinuxAppCollector } from "./apps-linux.ts";
+import { darwinAppCollector, type DarwinAppCollector } from "./apps-darwin.ts";
 import { createIconResolver } from "./app-icons-linux.ts";
+import { createDarwinIconConverter, type DarwinIconConverter } from "./app-icons-darwin.ts";
 
 export interface AppIconService {
   /** Absolute path to the icon file, or null when the app or its icon is unknown. */
-  path(appId: string): string | null;
+  path(appId: string): string | null | Promise<string | null>;
 }
 
-export function createAppIconService(fs: LinuxFs = realLinuxFs): AppIconService {
+const isAppId = (id: string) => id !== "" && !id.includes("/") && !id.includes("..");
+
+export function createAppIconService(platform: NodeJS.Platform = process.platform): AppIconService {
+  return platform === "darwin" ? createDarwinAppIconService() : createLinuxAppIconService();
+}
+
+export function createLinuxAppIconService(fs: LinuxFs = realLinuxFs): AppIconService {
   const apps = createLinuxAppCollector(fs);
   const icons = createIconResolver(fs);
   return {
     path(appId: string): string | null {
-      if (!appId || appId.includes("/") || appId.includes("..")) return null;
+      if (!isAppId(appId)) return null;
       const entry = apps.entries().get(appId);
       return entry ? icons.resolve(entry.icon) : null;
     },
   };
 }
+
+export function createDarwinAppIconService(
+  apps: Pick<DarwinAppCollector, "iconSource"> = darwinAppCollector(),
+  icons: DarwinIconConverter = createDarwinIconConverter(join(getPpmDir(), "app-icons")),
+): AppIconService {
+  return {
+    async path(appId: string): Promise<string | null> {
+      const source = isAppId(appId) ? apps.iconSource(appId) : null;
+      return source ? icons.png(source.bundle, source.iconPath) : null;
+    },
+  };
+}

package/src/services/system-services/app-icons-darwin.ts

@@ -0,0 +1,88 @@
+/**
+ * A macOS app's icon as an image the browser can draw: the bundle's `.icns`
+ * converted by `sips` to a 64 px PNG (20 ms and about 5 KB for Chrome's), kept
+ * under `<ppm dir>/app-icons/` so each icon is converted once.
+ *
+ * A PNG is named after its bundle and the icon file's mtime. An update that
+ * replaces the icon therefore gets a new PNG, and the old one is removed as the
+ * new one lands. The Apps page asks for every icon at once when it opens, so two
+ * requests for one icon share a conversion instead of racing on the file.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { defaultRunner, type Runner } from "../host-info/spawn-runner.ts";
+
+export const ICON_PX = 64;
+const SIPS_TIMEOUT_MS = 10_000;
+
+/** Every file of one bundle starts with this, which is how its old PNGs are found. */
+export function bundleIconPrefix(bundle: string): string {
+  return `${createHash("sha1").update(bundle).digest("hex").slice(0, 16)}-`;
+}
+
+export function iconCacheName(bundle: string, iconMtimeMs: number): string {
+  return `${bundleIconPrefix(bundle)}${Math.trunc(iconMtimeMs)}.png`;
+}
+
+function mtimeOf(path: string): number | null {
+  try {
+    const s = statSync(path);
+    return s.isFile() ? s.mtimeMs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function createDarwinIconConverter(dir: string, run: Runner = defaultRunner) {
+  const pending = new Map<string, Promise<string | null>>();
+  /** Icons sips could not read. Converting one again on every request cannot help;
+   *  an update to the app changes its mtime, and so the file asked for. */
+  const unreadable = new Set<string>();
+  let temps = 0;
+
+  const convert = async (bundle: string, iconPath: string, target: string): Promise<string | null> => {
+    const prefix = bundleIconPrefix(bundle);
+    // Named like the bundle's PNGs, so one left behind by a crash is cleaned up
+    // with them the next time this icon is converted.
+    const temp = join(dir, `${prefix}tmp-${process.pid}-${++temps}.png`);
+    try {
+      mkdirSync(dir, { recursive: true });
+      const r = await run(["sips", "-s", "format", "png", "-Z", String(ICON_PX), iconPath, "--out", temp], SIPS_TIMEOUT_MS);
+      if (r.code !== 0 || mtimeOf(temp) === null) {
+        rmSync(temp, { force: true });
+        unreadable.add(target);
+        return null;
+      }
+      renameSync(temp, target);
+      for (const name of readdirSync(dir)) {
+        if (name.startsWith(prefix) && join(dir, name) !== target) rmSync(join(dir, name), { force: true });
+      }
+      return target;
+    } catch {
+      // The cache directory could not be written: no icon this time, and the
+      // letter tile the page falls back to.
+      return null;
+    }
+  };
+
+  return {
+    /** The PNG of one bundle's icon file, converting it on first use; null when
+     *  the icon cannot be read. */
+    async png(bundle: string, iconPath: string): Promise<string | null> {
+      const mtime = mtimeOf(iconPath);
+      if (mtime === null) return null;
+      const target = join(dir, iconCacheName(bundle, mtime));
+      if (mtimeOf(target) !== null) return target;
+      if (unreadable.has(target)) return null;
+      let conversion = pending.get(target);
+      if (!conversion) {
+        conversion = convert(bundle, iconPath, target).finally(() => pending.delete(target));
+        pending.set(target, conversion);
+      }
+      return conversion;
+    },
+  };
+}
+
+export type DarwinIconConverter = ReturnType<typeof createDarwinIconConverter>;

package/src/services/system-services/apps-darwin.ts

@@ -0,0 +1,275 @@
+/**
+ * The Apps page on macOS: which applications are running, and which pids are theirs.
+ *
+ * An app is an application bundle, which is how the Dock and Activity Monitor see
+ * one, and a process belongs to the bundle its executable runs from. `ps` already
+ * prints that path, so nothing is matched by name: an Electron app's renderers run
+ * from `<App>.app/Contents/Frameworks/<App> Helper (Renderer).app/…`, inside the
+ * app's own bundle, and fold into it.
+ *
+ * Which bundle a process belongs to, and whether that bundle is an app anyone
+ * would call running, takes five rules, each from a case on a real machine:
+ *
+ * - A bundle inside a `.framework` is part of the framework, not an app. Chrome's
+ *   helpers live in `Google Chrome Framework.framework/…/Helpers/`, and Python's
+ *   interpreter runs from `Python.framework/…/Python.app`.
+ * - The innermost REGULAR app wins (neither LSUIElement nor LSBackgroundOnly), else
+ *   the outermost. Simulator runs from inside Xcode and is an app of its own, while
+ *   an Electron app's helpers are LSUIElement bundles inside it and belong to it.
+ * - An app extension never lists an app by itself. macOS runs the widgets of
+ *   Clock, Weather and Calendar with none of them open, so an extension counts
+ *   only once its app has a process of its own.
+ * - Under /System only the application folders list, and Finder: the rest of
+ *   CoreServices is the Dock, Control Center, Spotlight and the rest of macOS.
+ * - Anything in an Applications folder lists; nothing under a Library folder does
+ *   (those are an app's agents and updaters); anywhere else, only a regular app.
+ *
+ * Info.plists are read in-process in either format and cached against their mtime,
+ * so a tick stats each running bundle once and parses one only after an update.
+ */
+import { readFileSync, statSync } from "node:fs";
+import type { AppInfo } from "../../types/system-metrics.ts";
+import { parsePlistBytes } from "../system-metrics/plist-binary.ts";
+import { isPlistDict, plistString, type PlistValue } from "../system-metrics/plist-xml.ts";
+import { primaryPids, type AppProcess } from "./apps-linux.ts";
+
+/** An Info.plist is a few KB. One this size is not worth parsing every tick. */
+export const MAX_INFO_PLIST_BYTES = 1024 * 1024;
+
+const SYSTEM_APP_DIRS = [
+  "/System/Applications/",
+  // Safari ships in a cryptex, updated apart from the OS, since macOS 13. Safari
+  // itself runs from the first path; its agents run through the symlink to it.
+  "/System/Volumes/Preboot/Cryptexes/App/System/Applications/",
+  "/System/Cryptexes/App/System/Applications/",
+  "/System/Library/CoreServices/Applications/",
+];
+const FINDER = "/System/Library/CoreServices/Finder.app";
+const APPLICATIONS_DIR = /^\/(?:Users\/[^/]+\/)?Applications\//;
+const LIBRARY_DIR = /^\/(?:Users\/[^/]+\/)?Library\//;
+
+export interface BundleFs {
+  /** A regular file's mtime and size, or null when it is missing or not a file. */
+  stat(path: string): { mtimeMs: number; size: number } | null;
+  read(path: string): Uint8Array | null;
+}
+
+export const realBundleFs: BundleFs = {
+  stat: (path) => {
+    try {
+      const s = statSync(path);
+      return s.isFile() ? { mtimeMs: s.mtimeMs, size: s.size } : null;
+    } catch {
+      return null;
+    }
+  },
+  read: (path) => {
+    try {
+      return readFileSync(path);
+    } catch {
+      return null;
+    }
+  },
+};
+
+/** The app bundles an executable runs from. */
+export interface ExecutableBundles {
+  /** Outermost first. */
+  apps: string[];
+  /** It runs from an app extension (`.appex`) inside one of them. */
+  extension: boolean;
+}
+
+/**
+ * The app bundles an absolute executable path runs from, or null when it runs from
+ * none. A bundle counts only where the path goes on into its `Contents`: a folder
+ * that is merely named `Foo.app` holds no app.
+ */
+export function bundlesOf(exePath: string): ExecutableBundles | null {
+  if (!exePath.startsWith("/")) return null;
+  const parts = exePath.split("/");
+  const apps: string[] = [];
+  let extension = false;
+  let inFramework = false;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const name = parts[i]!.toLowerCase();
+    if (name.endsWith(".framework")) {
+      inFramework = true;
+      continue;
+    }
+    if (parts[i + 1] !== "Contents") continue;
+    if (name.endsWith(".app") && !inFramework) apps.push(parts.slice(0, i + 1).join("/"));
+    else if (name.endsWith(".appex") && apps.length > 0) extension = true;
+  }
+  return apps.length > 0 ? { apps, extension } : null;
+}
+
+/** Whether a bundle at this path may be listed, given whether it is a regular app. */
+export function isListable(bundle: string, regular: boolean): boolean {
+  if (bundle === FINDER || SYSTEM_APP_DIRS.some((dir) => bundle.startsWith(dir))) return true;
+  if (bundle.startsWith("/System/")) return false;
+  if (APPLICATIONS_DIR.test(bundle)) return true;
+  if (LIBRARY_DIR.test(bundle)) return false;
+  // Downloads, a mounted disk image, an App Translocation copy: an app someone
+  // opened, as long as it is one with a window to open.
+  return regular;
+}
+
+/** What an Info.plist says about its app, as far as listing it goes. */
+export interface BundleInfo {
+  /** CFBundleIdentifier. A bundle without one is not an app LaunchServices would run. */
+  id: string;
+  name: string;
+  /** Neither menu-bar-only (LSUIElement) nor faceless (LSBackgroundOnly). */
+  regular: boolean;
+  /** The icon's file name in `Contents/Resources`, when it declares one that exists. */
+  iconFile: string | null;
+}
+
+/** An Info.plist's view of its bundle, or null when it does not describe an app. */
+export function bundleInfo(bundle: string, plist: PlistValue | undefined, fs: Pick<BundleFs, "stat">): BundleInfo | null {
+  if (!isPlistDict(plist)) return null;
+  const id = text(plist.CFBundleIdentifier);
+  if (!id) return null;
+  const folder = bundle.slice(bundle.lastIndexOf("/") + 1).replace(/\.app$/i, "");
+  return {
+    id,
+    name: text(plist.CFBundleDisplayName) ?? text(plist.CFBundleName) ?? folder,
+    regular: !flag(plist.LSUIElement) && !flag(plist.LSBackgroundOnly),
+    iconFile: iconFileOf(bundle, text(plist.CFBundleIconFile), fs),
+  };
+}
+
+function text(v: PlistValue | undefined): string | undefined {
+  const s = plistString(v)?.trim();
+  return s ? s : undefined;
+}
+
+/** Info.plists write a boolean key as `<true/>`, as `<integer>1</integer>` or as `<string>1</string>`. */
+function flag(v: PlistValue | undefined): boolean {
+  if (typeof v === "string") return /^(?:1|yes|true)$/i.test(v.trim());
+  return v === true || v === 1;
+}
+
+/**
+ * The declared icon's file, as LaunchServices finds it: the name as written, or
+ * with `.icns` added when that is how it is stored ("AppIcon" is AppIcon.icns).
+ * The name comes from the bundle, so it may not step out of its Resources folder.
+ */
+function iconFileOf(bundle: string, declared: string | undefined, fs: Pick<BundleFs, "stat">): string | null {
+  if (!declared || declared.includes("/") || declared.includes("..")) return null;
+  const names = declared.toLowerCase().endsWith(".icns") ? [declared] : [declared, `${declared}.icns`];
+  return names.find((name) => fs.stat(`${bundle}/Contents/Resources/${name}`) !== null) ?? null;
+}
+
+/** Where a listed app's icon is, for the icon route. */
+export interface AppIconSource {
+  bundle: string;
+  iconPath: string;
+}
+
+export interface DarwinAppList {
+  apps: AppInfo[];
+  /** id to icon, for the listed apps that have one. */
+  icons: Map<string, AppIconSource>;
+}
+
+/**
+ * Apps with at least one live process of their own, name-sorted. `lookup` reads a
+ * bundle's Info.plist; null means it does not describe an app.
+ *
+ * Two copies of one app (one in Applications, one in Downloads) are one app: the
+ * first copy seen gives the name and icon, and both copies' pids count.
+ */
+export function collectDarwinApps(
+  processes: readonly AppProcess[],
+  lookup: (bundle: string) => BundleInfo | null,
+): DarwinAppList {
+  const found = new Map<string, { bundle: string; info: BundleInfo; pids: number[]; ownProcess: boolean }>();
+  for (const proc of processes) {
+    const where = proc.exePath ? bundlesOf(proc.exePath) : null;
+    const app = where ? appOf(where.apps, lookup) : null;
+    if (!where || !app || !isListable(app.bundle, app.info.regular)) continue;
+    const entry = found.get(app.info.id) ?? { ...app, pids: [], ownProcess: false };
+    found.set(app.info.id, entry);
+    entry.pids.push(proc.pid);
+    if (!where.extension) entry.ownProcess = true;
+  }
+
+  const ppidOf = new Map(processes.map((p) => [p.pid, p.ppid]));
+  const apps: AppInfo[] = [];
+  const icons = new Map<string, AppIconSource>();
+  for (const [id, { bundle, info, pids, ownProcess }] of found) {
+    if (!ownProcess) continue;
+    apps.push({ id, name: info.name, icon: info.iconFile, pids: primaryPids(pids, ppidOf) });
+    if (info.iconFile) icons.set(id, { bundle, iconPath: `${bundle}/Contents/Resources/${info.iconFile}` });
+  }
+  return { apps: apps.sort((a, b) => a.name.localeCompare(b.name)), icons };
+}
+
+/** The innermost regular app of the chain, else the outermost that is an app at all. */
+function appOf(chain: readonly string[], lookup: (bundle: string) => BundleInfo | null) {
+  let outermost: { bundle: string; info: BundleInfo } | null = null;
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const info = lookup(chain[i]!);
+    if (!info) continue;
+    if (info.regular) return { bundle: chain[i]!, info };
+    outermost = { bundle: chain[i]!, info };
+  }
+  return outermost;
+}
+
+interface CachedPlist {
+  mtimeMs: number;
+  size: number;
+  info: BundleInfo | null;
+}
+
+/** Production wiring: the real filesystem, and a cache that lives as long as the server. */
+export function createDarwinAppCollector(fs: BundleFs = realBundleFs) {
+  /** Bundle to its Info.plist as last read. Only the bundles the last tick ran into
+   *  are kept, so an app that quit is not held on to. */
+  let plists = new Map<string, CachedPlist>();
+  let icons = new Map<string, AppIconSource>();
+
+  const read = (bundle: string, cached: CachedPlist | undefined): CachedPlist | null => {
+    const path = `${bundle}/Contents/Info.plist`;
+    const st = fs.stat(path);
+    if (!st) return null;
+    if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) return cached;
+    const bytes = st.size <= MAX_INFO_PLIST_BYTES ? fs.read(path) : null;
+    return { ...st, info: bytes ? bundleInfo(bundle, parsePlistBytes(bytes), fs) : null };
+  };
+
+  return {
+    collect(processes: readonly AppProcess[]): AppInfo[] {
+      const next = new Map<string, CachedPlist>();
+      /** Chrome is forty processes and one Info.plist: stat it once per tick. */
+      const seen = new Map<string, BundleInfo | null>();
+      const result = collectDarwinApps(processes, (bundle) => {
+        if (seen.has(bundle)) return seen.get(bundle)!;
+        const plist = read(bundle, plists.get(bundle));
+        if (plist) next.set(bundle, plist);
+        seen.set(bundle, plist?.info ?? null);
+        return plist?.info ?? null;
+      });
+      plists = next;
+      icons = result.icons;
+      return result.apps;
+    },
+    /** The icon of an app the last tick listed. Nothing else can be asked for. */
+    iconSource(appId: string): AppIconSource | null {
+      return icons.get(appId) ?? null;
+    },
+  };
+}
+
+export type DarwinAppCollector = ReturnType<typeof createDarwinAppCollector>;
+
+let shared: DarwinAppCollector | null = null;
+
+/** The one collector the tick and the icon route share, so the route can serve the
+ *  icon of an app the tick listed and of nothing else. */
+export function darwinAppCollector(): DarwinAppCollector {
+  return (shared ??= createDarwinAppCollector());
+}

package/src/services/system-services/apps-linux.ts

@@ -62,6 +62,9 @@ export interface AppProcess {
   pid: number;
   ppid: number;
   name: string;
+  /** The executable's absolute path, where the process collector has it. macOS finds
+   *  a process's app bundle from it (apps-darwin.ts); Linux reads cgroups instead. */
+  exePath?: string;
 }
 
 export interface CollectAppsInput {