@hienlh/ppm 0.23.6 → 0.23.7

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

@@ -0,0 +1,124 @@
+/**
+ * Resolving a desktop entry's Icon to a file PPM can serve.
+ *
+ * An Icon is either an absolute path or a theme icon NAME, and the name is the
+ * common case: on this host `code.desktop` says `Icon=vscode`, which exists only
+ * under /usr/share/pixmaps, while `org.kde.dolphin` is an SVG under hicolor and
+ * `claude-desktop` is a PNG under hicolor's sized directories. A resolver that
+ * searches only the current theme finds none of the three.
+ *
+ * So the whole search path is indexed once, name to path: measured here, 22022
+ * names in 29 ms. That is far cheaper than walking per lookup and it is built
+ * lazily, on the first icon anyone actually asks for.
+ *
+ * The index is also the security boundary. The HTTP route never takes a path - it
+ * takes an app id, looks the entry up, and serves only what this module resolved,
+ * so there is no request shape that can name an arbitrary file.
+ */
+import type { LinuxFs } from "../system-metrics/linux-fs.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+
+/** Preference order: a vector icon scales to any row height the UI uses. */
+export const ICON_EXTENSIONS: readonly string[] = [".svg", ".png", ".xpm"];
+
+/** How deep a theme nests: theme / context / size / name, plus a little slack. */
+const MAX_DEPTH = 5;
+
+export const ICON_MIME: Record<string, string> = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".xpm": "image/x-xpixmap",
+};
+
+export function iconRoots(env: Record<string, string | undefined>, home: string): string[] {
+  const dataHome = env.XDG_DATA_HOME || `${home}/.local/share`;
+  const dataDirs = (env.XDG_DATA_DIRS || "/usr/local/share:/usr/share").split(":").filter(Boolean);
+  const roots: string[] = [`${home}/.icons`, `${dataHome}/icons`];
+  for (const base of dataDirs) roots.push(`${base}/icons`);
+  // pixmaps is not a theme and is easy to forget; it is also the ONLY place some
+  // very common icons exist, so leaving it out loses them entirely.
+  for (const base of dataDirs) roots.push(`${base}/pixmaps`);
+  return [...new Set(roots)];
+}
+
+/**
+ * name to path. An earlier root wins over a later one, and within a root a better
+ * extension replaces a worse one - so a theme's SVG beats the same theme's PNG
+ * without needing the walk to be ordered by size.
+ */
+export function buildIconIndex(roots: readonly string[], fs: LinuxFs): Map<string, string> {
+  const index = new Map<string, string>();
+  const rank = new Map<string, number>();
+  const walk = (dir: string, depth: number, rootOrder: number): void => {
+    if (depth > MAX_DEPTH) return;
+    const entries = fs.list(dir);
+    if (!entries) return;
+    for (const name of entries) {
+      const path = `${dir}/${name}`;
+      const dot = name.lastIndexOf(".");
+      const ext = dot > 0 ? name.slice(dot) : "";
+      const extRank = ICON_EXTENSIONS.indexOf(ext);
+      if (extRank < 0) {
+        // No known extension: treat it as a directory and descend. A plain file
+        // simply lists as nothing and costs one failed readdir.
+        walk(path, depth + 1, rootOrder);
+        continue;
+      }
+      const base = name.slice(0, dot);
+      const score = rootOrder * 10 + extRank;
+      const previous = rank.get(base);
+      if (previous === undefined || score < previous) {
+        rank.set(base, score);
+        index.set(base, path);
+      }
+    }
+  };
+  roots.forEach((root, order) => walk(root, 0, order));
+  return index;
+}
+
+/**
+ * The file for one Icon value, or null when nothing resolves.
+ *
+ * An absolute path is taken from the entry itself, which is host-owned content -
+ * but it is still required to be an image extension, so a malformed entry cannot
+ * turn the icon route into a reader of arbitrary files.
+ */
+export function resolveIconPath(
+  icon: string | null,
+  index: Map<string, string>,
+  fs: LinuxFs,
+): string | null {
+  if (!icon) return null;
+  if (icon.startsWith("/")) {
+    return hasImageExtension(icon) && fs.exists(icon) ? icon : null;
+  }
+  // Some entries write the file name rather than the icon name ("foo.png").
+  const dot = icon.lastIndexOf(".");
+  const stem = dot > 0 && ICON_EXTENSIONS.includes(icon.slice(dot)) ? icon.slice(0, dot) : icon;
+  return index.get(stem) ?? index.get(icon) ?? null;
+}
+
+export function hasImageExtension(path: string): boolean {
+  const dot = path.lastIndexOf(".");
+  return dot > 0 && ICON_EXTENSIONS.includes(path.slice(dot).toLowerCase());
+}
+
+export function iconMimeType(path: string): string {
+  const dot = path.lastIndexOf(".");
+  return ICON_MIME[dot > 0 ? path.slice(dot).toLowerCase() : ""] ?? "application/octet-stream";
+}
+
+/** Production wiring: one lazily-built index for the process's lifetime. */
+export function createIconResolver(fs: LinuxFs = realLinuxFs) {
+  const roots = iconRoots(process.env, process.env.HOME ?? "/root");
+  let index: Map<string, string> | null = null;
+  return {
+    resolve(icon: string | null): string | null {
+      index ??= buildIconIndex(roots, fs);
+      return resolveIconPath(icon, index, fs);
+    },
+  };
+}
+
+export type IconResolver = ReturnType<typeof createIconResolver>;

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

@@ -0,0 +1,174 @@
+/**
+ * The Apps page: which desktop applications are running, and which pids are
+ * theirs - Mission Center's app list.
+ *
+ * Matching is primary-source rather than heuristic. A systemd graphical session
+ * puts every launched app in its own app scope whose unit name states the desktop
+ * entry id, so a pid names its app outright (see app-cgroup-linux.ts). The exec
+ * fallback below exists only for a session that is not systemd-managed, where
+ * there is no scope to read.
+ *
+ * Injectable filesystem throughout, so the whole thing is fixture-tested.
+ */
+import type { AppInfo } from "../../types/system-metrics.ts";
+import type { LinuxFs } from "../system-metrics/linux-fs.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+import { appIdFromCgroup } from "./app-cgroup-linux.ts";
+import { execBinary, parseDesktopEntry, type DesktopEntry } from "./desktop-entry.ts";
+
+const DESKTOP_SUFFIX = ".desktop";
+
+/**
+ * The XDG search path, most specific first. Precedence is what decides which copy
+ * of a duplicated id wins: a user's own entry must beat the system one, which is
+ * how an override in the home directory works at all.
+ */
+export function desktopDirs(env: Record<string, string | undefined>, home: string): string[] {
+  const dataHome = env.XDG_DATA_HOME || `${home}/.local/share`;
+  const dataDirs = (env.XDG_DATA_DIRS || "/usr/local/share:/usr/share").split(":").filter(Boolean);
+  const seen = new Set<string>();
+  const dirs: string[] = [];
+  for (const base of [dataHome, ...dataDirs]) {
+    const dir = `${base}/applications`;
+    if (!seen.has(dir)) {
+      seen.add(dir);
+      dirs.push(dir);
+    }
+  }
+  return dirs;
+}
+
+/** id to entry. The FIRST directory to define an id wins, per XDG precedence. */
+export function loadDesktopEntries(dirs: readonly string[], fs: LinuxFs): Map<string, DesktopEntry> {
+  const entries = new Map<string, DesktopEntry>();
+  for (const dir of dirs) {
+    for (const file of fs.list(dir) ?? []) {
+      if (!file.endsWith(DESKTOP_SUFFIX)) continue;
+      const id = file.slice(0, -DESKTOP_SUFFIX.length);
+      if (entries.has(id)) continue;
+      const text = fs.read(`${dir}/${file}`);
+      const entry = text === null ? null : parseDesktopEntry(id, text);
+      if (entry) entries.set(id, entry);
+    }
+  }
+  return entries;
+}
+
+/** What the tick calls once per full snapshot. */
+export type AppCollector = (processes: readonly AppProcess[]) => AppInfo[];
+
+/** A process as this module needs it - the subset the tick already has in hand. */
+export interface AppProcess {
+  pid: number;
+  ppid: number;
+  name: string;
+}
+
+export interface CollectAppsInput {
+  processes: readonly AppProcess[];
+  entries: Map<string, DesktopEntry>;
+  /** `/proc/<pid>/cgroup` for one pid, or null when it is gone. */
+  readCgroup: (pid: number) => string | null;
+}
+
+/**
+ * Apps with at least one live process, name-sorted.
+ *
+ * A NoDisplay entry is skipped: its author asked for it not to appear in menus,
+ * and including them would list every url-handler and console helper shipped
+ * beside a real app.
+ */
+export function collectApps(input: CollectAppsInput): AppInfo[] {
+  const { processes, entries, readCgroup } = input;
+  const byBinary = execBinaryIndex(entries);
+  const pidsByApp = new Map<string, number[]>();
+
+  for (const proc of processes) {
+    const id = matchApp(proc, entries, byBinary, readCgroup);
+    if (!id) continue;
+    const list = pidsByApp.get(id);
+    if (list) list.push(proc.pid);
+    else pidsByApp.set(id, [proc.pid]);
+  }
+
+  const ppidOf = new Map(processes.map((p) => [p.pid, p.ppid]));
+  const apps: AppInfo[] = [];
+  for (const [id, pids] of pidsByApp) {
+    const entry = entries.get(id);
+    if (!entry) continue;
+    apps.push({ id, name: entry.name, icon: entry.icon, pids: primaryPids(pids, ppidOf) });
+  }
+  return apps.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The pids that stand for the app: those whose parent is not also one of its own.
+ * Each is the root of a subtree, which is what an app row's figures sum over -
+ * counting every member would count a helper's CPU once per level of nesting.
+ */
+export function primaryPids(pids: readonly number[], ppidOf: Map<number, number>): number[] {
+  const own = new Set(pids);
+  return pids.filter((pid) => !own.has(ppidOf.get(pid) ?? -1)).sort((a, b) => a - b);
+}
+
+/**
+ * Exec binary to id, for the fallback match. Ambiguous binaries are dropped
+ * entirely rather than resolved arbitrarily: two entries launching `sh` must not
+ * make every shell on the machine look like one of them.
+ */
+export function execBinaryIndex(entries: Map<string, DesktopEntry>): Map<string, string> {
+  const index = new Map<string, string>();
+  const ambiguous = new Set<string>();
+  for (const entry of entries.values()) {
+    if (entry.noDisplay) continue;
+    const binary = execBinary(entry.exec);
+    if (!binary) continue;
+    if (index.has(binary)) ambiguous.add(binary);
+    else index.set(binary, entry.id);
+  }
+  for (const binary of ambiguous) index.delete(binary);
+  return index;
+}
+
+function matchApp(
+  proc: AppProcess,
+  entries: Map<string, DesktopEntry>,
+  byBinary: Map<string, string>,
+  readCgroup: (pid: number) => string | null,
+): string | null {
+  const cgroup = readCgroup(proc.pid);
+  const scoped = cgroup ? appIdFromCgroup(cgroup) : null;
+  if (scoped) {
+    const entry = entries.get(scoped);
+    // A scope naming an id no entry defines is still not an app PPM can show:
+    // it has no name and no icon to draw.
+    if (entry && !entry.noDisplay) return scoped;
+    return null;
+  }
+  // Not in an app scope. Only an exact executable-name match counts, so a shell
+  // or an editor started by something else is not attributed to an app.
+  const id = byBinary.get(proc.name);
+  return id && !entries.get(id)?.noDisplay ? id : null;
+}
+
+/** Production wiring: the real XDG dirs and the real /proc. */
+export function createLinuxAppCollector(fs: LinuxFs = realLinuxFs) {
+  const dirs = desktopDirs(process.env, process.env.HOME ?? "/root");
+  let entries: Map<string, DesktopEntry> | null = null;
+  return {
+    /** Desktop entries change only when a package is installed; read once. */
+    entries(): Map<string, DesktopEntry> {
+      entries ??= loadDesktopEntries(dirs, fs);
+      return entries;
+    },
+    collect(processes: readonly AppProcess[]): AppInfo[] {
+      return collectApps({
+        processes,
+        entries: this.entries(),
+        readCgroup: (pid) => fs.read(`/proc/${pid}/cgroup`),
+      });
+    },
+  };
+}
+
+export type LinuxAppCollector = ReturnType<typeof createLinuxAppCollector>;

package/src/services/system-services/desktop-entry.ts

@@ -0,0 +1,103 @@
+/**
+ * freedesktop `.desktop` parsing for the Apps page - Mission Center's app list.
+ *
+ * MC delegates this to its own `app-rummage` crate; PPM parses the entries
+ * directly because it only needs four fields, and the matching is done from
+ * systemd's app cgroups (see `app-cgroup-linux.ts`), which name the desktop id
+ * outright rather than guessing it from an executable path.
+ *
+ * Pure: every function takes the file's text. Nothing here touches the disk.
+ */
+
+export interface DesktopEntry {
+  /** File name without the suffix - the id systemd's app cgroups carry. */
+  id: string;
+  name: string;
+  /** A theme icon name or an absolute path. Null when the entry has none. */
+  icon: string | null;
+  /** Exec with the field codes removed. Null when the entry has none. */
+  exec: string | null;
+  /** The author asked for this entry not to appear in menus. */
+  noDisplay: boolean;
+}
+
+/**
+ * The percent-codes an Exec may carry. The launcher substitutes files and URLs
+ * for them, so one left in the string would be shown to the user and would break
+ * any comparison against a real command line.
+ */
+const FIELD_CODES = /%[fFuUdDnNickvm]/g;
+/** A doubled percent is a literal one; parking it keeps the round trip lossless. */
+const PERCENT_SENTINEL = " PPM_PCT ";
+
+export function stripFieldCodes(exec: string): string {
+  return exec
+    .replaceAll("%%", PERCENT_SENTINEL)
+    .replace(FIELD_CODES, " ")
+    .replaceAll(PERCENT_SENTINEL, "%")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Reads the `[Desktop Entry]` group only. An entry's actions live in their own
+ * `[Desktop Action ...]` groups with their own Name, Icon and Exec, so a parser
+ * that scans the whole file takes the LAST action's name as the app's.
+ *
+ * Returns null for anything that is not a launchable application: a Link entry,
+ * `Hidden=true` (the spec says treat it as deleted) and an entry with no Name.
+ */
+export function parseDesktopEntry(id: string, text: string): DesktopEntry | null {
+  const fields: Record<string, string> = {};
+  let inGroup = false;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("[")) {
+      inGroup = line === "[Desktop Entry]";
+      continue;
+    }
+    if (!inGroup || !line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    // A bracketed key is a translation. PPM shows the unlocalised value so the
+    // id, the list and any log line all name the app the same way.
+    if (key.includes("[")) continue;
+    if (fields[key] === undefined) fields[key] = line.slice(eq + 1).trim();
+  }
+
+  if (fields.Type !== "Application") return null;
+  if (fields.Hidden === "true") return null;
+  const name = fields.Name?.trim();
+  if (!name) return null;
+
+  const exec = fields.Exec ? stripFieldCodes(fields.Exec) : "";
+  return {
+    id,
+    name,
+    icon: fields.Icon?.trim() || null,
+    exec: exec || null,
+    noDisplay: fields.NoDisplay === "true",
+  };
+}
+
+/**
+ * The program an Exec actually runs, as a bare file name - the fallback match for
+ * an app started outside a systemd app scope (from a terminal, say), where there
+ * is no cgroup to read the id from.
+ *
+ * Leading assignments and an `env` wrapper are skipped: an Exec of
+ * `env GDK_BACKEND=x11 /usr/bin/foo` runs foo, not env.
+ */
+export function execBinary(exec: string | null): string | null {
+  if (!exec) return null;
+  const tokens = exec.match(/"[^"]*"|\S+/g) ?? [];
+  for (const token of tokens) {
+    const t = token.replace(/^"|"$/g, "");
+    if (!t || t === "env" || t.includes("=")) continue;
+    const slash = t.lastIndexOf("/");
+    const base = slash >= 0 ? t.slice(slash + 1) : t;
+    return base || null;
+  }
+  return null;
+}

package/src/services/system-services/service-guard.ts

@@ -0,0 +1,124 @@
+/**
+ * Which service actions PPM refuses, and why.
+ *
+ * Mission Center refuses nothing — it asks systemd and lets polkit decide. PPM
+ * cannot: it is *inside* one of the units it lists, so "stop ppm.service" would
+ * end the request mid-flight and leave the user with no way back in. The refusal
+ * is derived from PPM's own cgroup rather than a hardcoded unit name, so it is
+ * still right when the unit is renamed, run system-wide, or run under a
+ * different user manager.
+ *
+ * One function produces both the per-row `refused` map and the route's verdict,
+ * so a disabled button and a 403 can never disagree.
+ */
+import type { ServiceAction, ServiceScope } from "../../types/system-services.ts";
+import { SERVICE_ACTIONS } from "../../types/system-services.ts";
+import { systemdHierarchy } from "./app-cgroup-linux.ts";
+
+/** Actions that take a running unit away. `start` and `enable` never do. */
+const DISRUPTIVE: readonly ServiceAction[] = ["stop", "restart", "disable"];
+
+/**
+ * Units whose loss takes the session or the machine with it. Stopping journald
+ * or the message bus is not recoverable from a web UI, and `-.mount` is the root
+ * filesystem.
+ */
+export const CRITICAL_UNITS: readonly string[] = [
+  "-.mount",
+  "dbus.service",
+  "dbus.socket",
+  "dbus-broker.service",
+  "systemd-journald.service",
+  "systemd-journald.socket",
+  "systemd-logind.service",
+  "systemd-udevd.service",
+  "init.scope",
+];
+
+export interface ServiceGuardContext {
+  /** `/proc/self/cgroup`'s path for PPM itself. Null → only the static list applies. */
+  selfCgroup: string | null;
+}
+
+/**
+ * The unit names on PPM's own cgroup path, innermost last:
+ * `/user.slice/user-1000.slice/user@1000.service/app.slice/ppm.service`
+ * → `["user@1000.service", "ppm.service"]`.
+ *
+ * Slices are not returned: they are not one of the three unit types the page
+ * lists, so they can never be the target of an action anyway.
+ *
+ * The file is parsed by `systemdHierarchy` rather than split directly. Two
+ * reasons, and both are the difference between refusing PPM's own unit and
+ * offering a Stop button for it. The kernel terminates the line, so a direct
+ * split ends on `"ppm.service\n"`, which no suffix test matches. And under
+ * cgroup v1 the file is one line per controller, whose hierarchies need not
+ * agree — only the `name=systemd` line describes the unit tree.
+ */
+export function selfUnitChain(cgroup: string | null): string[] {
+  if (!cgroup) return [];
+  const path = systemdHierarchy(cgroup);
+  if (!path) return [];
+  return path
+    .split("/")
+    .filter((part) => part.endsWith(".service") || part.endsWith(".scope") || part.endsWith(".socket"));
+}
+
+/** Every action this unit refuses, with the reason shown to the user. */
+export function serviceRefusals(
+  unit: string,
+  scope: ServiceScope,
+  ctx: ServiceGuardContext,
+): Partial<Record<ServiceAction, string>> {
+  const refusals: Partial<Record<ServiceAction, string>> = {};
+  const chain = selfUnitChain(ctx.selfCgroup);
+
+  if (chain.includes(unit)) {
+    const reason = unit === chain[chain.length - 1]
+      ? `${unit} is PPM itself — stopping it would end this session`
+      : `${unit} is the manager PPM runs under — stopping it would end this session`;
+    for (const action of DISRUPTIVE) refusals[action] = reason;
+    return refusals;
+  }
+
+  if (CRITICAL_UNITS.includes(unit)) {
+    const reason = `${unit} is required by the system — PPM will not stop it`;
+    for (const action of DISRUPTIVE) refusals[action] = reason;
+    return refusals;
+  }
+
+  // A user-scope unit named like the system manager cannot exist, so the scope
+  // is only carried for the message. Kept in the signature because the route
+  // passes it and a future scope-specific rule must not change every call site.
+  void scope;
+  return refusals;
+}
+
+export interface ServiceActionVerdict {
+  allowed: boolean;
+  reason?: string;
+}
+
+export function checkServiceActionAllowed(
+  unit: string,
+  scope: ServiceScope,
+  action: ServiceAction,
+  ctx: ServiceGuardContext,
+): ServiceActionVerdict {
+  if (!SERVICE_ACTIONS.includes(action)) return { allowed: false, reason: `Unknown action "${action}"` };
+  // A unit name reaches `systemctl` as one argv element, never a shell string,
+  // but it is still bounded here: anything with a slash or whitespace in it is
+  // not a unit name and has no business being passed on.
+  if (!isPlausibleUnitName(unit)) return { allowed: false, reason: "Not a unit name" };
+  const reason = serviceRefusals(unit, scope, ctx)[action];
+  return reason ? { allowed: false, reason } : { allowed: true };
+}
+
+/** systemd unit names: no slash, no whitespace, bounded length. */
+export function isPlausibleUnitName(unit: string): boolean {
+  return typeof unit === "string"
+    && unit.length > 0
+    && unit.length <= 256
+    && !/[\s/]/.test(unit)
+    && /\.[a-z]+$/.test(unit);
+}