paseo-plugin-machine-status 0.1.1

package/server/docker.ts

@@ -0,0 +1,260 @@
+import type { z } from "zod";
+import { describeError, run, runStreams, tryRun } from "./exec";
+import type {
+  controlContainer,
+  controlEngine,
+  pruneDocker,
+  readContainerLogs,
+  readDocker,
+  removeImage,
+  DockerContainer,
+  DockerEngine,
+  DockerImage,
+  DockerUsageRow,
+} from "../shared/docker";
+
+type ReadOutput = z.output<typeof readDocker.output>;
+type ControlInput = z.output<typeof controlContainer.input>;
+type PruneInput = z.output<typeof pruneDocker.input>;
+type EngineInput = z.output<typeof controlEngine.input>;
+type LogsInput = z.output<typeof readContainerLogs.input>;
+type ImageInput = z.output<typeof removeImage.input>;
+
+const DOCKER = "/usr/local/bin/docker";
+const PS_FORMAT = "{{.ID}}\t{{.Names}}\t{{.Image}}\t{{.State}}\t{{.Status}}\t{{.Ports}}";
+
+/**
+ * Docker reports sizes in SI units in `system df` (`5.874GB`) and binary units in
+ * `stats` (`31.39MiB`). Both appear, so both are read.
+ */
+const UNITS: Record<string, number> = {
+  B: 1,
+  KB: 1000,
+  MB: 1000 ** 2,
+  GB: 1000 ** 3,
+  TB: 1000 ** 4,
+  KIB: 1024,
+  MIB: 1024 ** 2,
+  GIB: 1024 ** 3,
+  TIB: 1024 ** 4,
+};
+
+export function parseDockerSize(value: string): number {
+  const match = /^\s*([\d.]+)\s*([A-Za-z]*)\s*$/.exec(value);
+  if (!match) return 0;
+  return Number(match[1]) * (UNITS[match[2].toUpperCase()] ?? 1);
+}
+
+export function parseContainers(raw: string): DockerContainer[] {
+  const containers: DockerContainer[] = [];
+  for (const line of raw.split("\n")) {
+    const [id, name, image, state, status, ports] = line.split("\t");
+    if (!id || !name) continue;
+    const published = new Set<number>();
+    // "0.0.0.0:5653->5432/tcp, [::]:5653->5432/tcp" — the published side is what
+    // is reachable from this machine.
+    for (const match of (ports ?? "").matchAll(/:(\d+)->/g)) published.add(Number(match[1]));
+    containers.push({
+      id,
+      name,
+      image: image ?? "",
+      state: state ?? "",
+      status: status ?? "",
+      ports: [...published].sort((left, right) => left - right),
+      running: state === "running",
+    });
+  }
+  return containers;
+}
+
+const VOLUME_LABEL = "Local Volumes";
+
+/**
+ * Reads `docker system df`. Volumes are marked unsafe to reclaim: they are where
+ * container data lives, and the biggest reclaimable number on a dev machine is
+ * usually a database someone still wants.
+ */
+export function parseSystemDf(raw: string): DockerUsageRow[] {
+  const rows: DockerUsageRow[] = [];
+  for (const line of raw.split("\n").slice(1)) {
+    const match = /^(\S+(?: \S+)?)\s+(\d+)\s+(\d+)\s+([\d.]+\s*\w+)\s+([\d.]+\s*\w+)/.exec(line.trim());
+    if (!match) continue;
+    const label = match[1];
+    rows.push({
+      label,
+      total: Number(match[2]),
+      active: Number(match[3]),
+      sizeBytes: parseDockerSize(match[4]),
+      reclaimableBytes: parseDockerSize(match[5]),
+      safeToReclaim: label !== VOLUME_LABEL,
+    });
+  }
+  return rows;
+}
+
+export function parseImages(raw: string): DockerImage[] {
+  const images: DockerImage[] = [];
+  for (const line of raw.split("\n")) {
+    const [id, reference, size, created] = line.split("\t");
+    if (!id || !reference) continue;
+    images.push({
+      id,
+      reference,
+      sizeBytes: parseDockerSize(size ?? "0B"),
+      created: created ?? "",
+      // An untagged image is a leftover layer set, which is what prune targets.
+      dangling: reference.startsWith("<none>"),
+    });
+  }
+  return images;
+}
+
+/** The desktop apps this panel knows how to launch, in the order it prefers them. */
+const ENGINE_APPS = ["Docker", "OrbStack", "Rancher Desktop"];
+
+async function installedApp(): Promise<string | null> {
+  for (const app of ENGINE_APPS) {
+    if (await tryRun("/bin/test", ["-d", `/Applications/${app}.app`], 2_000).then((r) => r !== null)) {
+      return app;
+    }
+  }
+  return null;
+}
+
+/**
+ * Distinguishes "no engine installed" from "installed but not running". Only the
+ * second one is worth offering a Start button for.
+ */
+export async function readEngine(): Promise<DockerEngine> {
+  const version = await tryRun(DOCKER, ["version", "--format", "{{.Server.Version}}"], 5_000);
+  const app = await installedApp();
+  if (version !== null && version.trim().length > 0) {
+    return { state: "running", version: version.trim(), app };
+  }
+  const cli = await tryRun("/bin/test", ["-x", DOCKER], 2_000);
+  if (app === null && cli === null) return { state: "missing", version: null, app: null };
+  return { state: "stopped", version: null, app };
+}
+
+export async function readDockerHandler(): Promise<ReadOutput> {
+  const collectedAt = new Date().toISOString();
+  const engine = await readEngine();
+
+  if (engine.state !== "running") {
+    return {
+      engine,
+      available: false,
+      reason:
+        engine.state === "missing"
+          ? "No container engine is installed on this machine."
+          : `${engine.app ?? "The container engine"} is installed but not running.`,
+      collectedAt,
+      containers: [],
+      images: [],
+      usage: [],
+      notes: [],
+    };
+  }
+
+  const [psRaw, dfRaw, imagesRaw] = await Promise.all([
+    tryRun(DOCKER, ["ps", "-a", "--format", PS_FORMAT], 10_000),
+    tryRun(DOCKER, ["system", "df"], 15_000),
+    tryRun(DOCKER, ["images", "--format", "{{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}"], 10_000),
+  ]);
+
+  const containers = parseContainers(psRaw ?? "");
+  const usage = parseSystemDf(dfRaw ?? "");
+  const notes: string[] = [];
+
+  const volumes = usage.find((row) => row.label === VOLUME_LABEL);
+  if (volumes && volumes.reclaimableBytes > 0) {
+    notes.push(
+      "Unused volumes are counted as reclaimable by Docker, but they hold container data — this panel never offers to remove them.",
+    );
+  }
+  if (dfRaw === null) notes.push("Disk usage was not readable.");
+
+  return {
+    engine,
+    available: true,
+    reason: null,
+    collectedAt,
+    containers,
+    images: parseImages(imagesRaw ?? ""),
+    usage,
+    notes,
+  };
+}
+
+/**
+ * Starting the engine is a launch, not a daemon command: Docker Desktop owns its
+ * own VM and comes up over tens of seconds, so this returns as soon as the app
+ * has been asked and the panel polls until the daemon answers.
+ */
+export async function controlEngineHandler({ action }: EngineInput) {
+  const app = (await installedApp()) ?? "Docker";
+  try {
+    if (action === "start") {
+      await run("/usr/bin/open", ["-a", app], 15_000);
+    } else {
+      await run("/usr/bin/osascript", ["-e", `quit app "${app}"`], 20_000);
+    }
+    return { ok: true, error: null };
+  } catch (error) {
+    console.error(`[machine-status] docker engine ${action} failed`, error);
+    return { ok: false, error: describeError(error) };
+  }
+}
+
+export async function readContainerLogsHandler({ id, lines }: LogsInput) {
+  try {
+    const { stdout, stderr } = await runStreams(
+      DOCKER,
+      ["logs", "--tail", String(lines), "--timestamps", id],
+      20_000,
+    );
+    return { ok: true, text: `${stdout}${stderr}`.trimEnd(), error: null };
+  } catch (error) {
+    return { ok: false, text: "", error: describeError(error) };
+  }
+}
+
+export async function removeImageHandler({ id }: ImageInput) {
+  try {
+    await run(DOCKER, ["rmi", id], 60_000);
+    return { ok: true, error: null };
+  } catch (error) {
+    console.error(`[machine-status] docker rmi failed for ${id}`, error);
+    return { ok: false, error: describeError(error) };
+  }
+}
+
+export async function controlContainerHandler({ id, action }: ControlInput) {
+  try {
+    // `remove` is only ever reached through the confirmation menu in the panel.
+    const args = action === "remove" ? ["rm", id] : [action, id];
+    await run(DOCKER, args, 60_000);
+    return { ok: true, error: null };
+  } catch (error) {
+    console.error(`[machine-status] docker ${action} failed for ${id}`, error);
+    return { ok: false, error: describeError(error) };
+  }
+}
+
+/** Matches the "Total reclaimed space: 1.234GB" line Docker prints after a prune. */
+export function parseReclaimed(raw: string): number {
+  const match = /Total reclaimed space:\s*([\d.]+\s*\w+)/i.exec(raw);
+  return match ? parseDockerSize(match[1]) : 0;
+}
+
+export async function pruneDockerHandler({ target }: PruneInput) {
+  // Images are pruned dangling-only. `-a` would delete every image not currently
+  // in use by a container, which on a dev machine means re-pulling gigabytes.
+  const args = target === "containers" ? ["container", "prune", "-f"] : ["image", "prune", "-f"];
+  try {
+    return { ok: true, reclaimedBytes: parseReclaimed(await run(DOCKER, args, 120_000)), error: null };
+  } catch (error) {
+    console.error(`[machine-status] docker prune ${target} failed`, error);
+    return { ok: false, reclaimedBytes: 0, error: describeError(error) };
+  }
+}

package/server/exec.ts

@@ -0,0 +1,62 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Runs a binary directly, never through a shell. Paths and PIDs flow into these
+ * calls, and argv-style invocation removes any chance of shell interpretation.
+ */
+export async function run(file: string, args: string[], timeoutMs = 5_000): Promise<string> {
+  const { stdout } = await execFileAsync(file, args, {
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024,
+    encoding: "utf8",
+  });
+  return stdout;
+}
+
+/** Same as `run`, but a missing binary or non-zero exit resolves to null instead of throwing. */
+export async function tryRun(file: string, args: string[], timeoutMs = 5_000): Promise<string | null> {
+  try {
+    return await run(file, args, timeoutMs);
+  } catch {
+    return null;
+  }
+}
+
+export function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/**
+ * Returns stdout even when the command exits non-zero. `du` walks unreadable
+ * subdirectories, warns on stderr, exits 1, and still prints a usable total.
+ */
+export async function runTolerant(file: string, args: string[], timeoutMs = 5_000): Promise<string> {
+  try {
+    return await run(file, args, timeoutMs);
+  } catch (error) {
+    const stdout = (error as { stdout?: unknown }).stdout;
+    return typeof stdout === "string" ? stdout : "";
+  }
+}
+
+/**
+ * Returns both streams. `docker logs` writes container stdout and stderr to the
+ * matching stream of its own process, so reading only stdout loses the output of
+ * every container that logs to stderr — which most of them do.
+ */
+export async function runStreams(
+  file: string,
+  args: string[],
+  timeoutMs = 5_000,
+): Promise<{ stdout: string; stderr: string }> {
+  const { stdout, stderr } = await execFileAsync(file, args, {
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024,
+    encoding: "utf8",
+  });
+  return { stdout, stderr };
+}

package/server/explain-rules.ts

@@ -0,0 +1,188 @@
+import type { Explanation } from "../shared/explain";
+
+/**
+ * Turns gathered evidence into a verdict.
+ *
+ * Runtime-neutral and pure: every rule here is a statement about evidence the
+ * panel already measured, so all of it is testable without a machine. Nothing in
+ * this file guesses from a name alone — the name only ever adds description to a
+ * conclusion that structure and timing already reached.
+ */
+
+export interface ProcessEvidence {
+  name: string;
+  pid: number;
+  command: string;
+  cpuPercent: number;
+  memoryBytes: number;
+  elapsedSeconds: number | null;
+  elapsed: string | null;
+  cwd: string | null;
+  parents: { pid: number; name: string }[];
+  children: { pid: number; name: string; cpuPercent: number }[];
+  ports: { port: number; protocol: string; scope: string }[];
+  isAppleSystemBinary: boolean;
+  machine: {
+    cores: number;
+    loadPercent: number;
+    pressurePercent: number | null;
+    swapUsedBytes: number;
+    swapTotalBytes: number;
+  };
+}
+
+const GB = 1024 ** 3;
+const MB = 1024 * 1024;
+
+const size = (bytes: number): string =>
+  bytes >= GB ? `${(bytes / GB).toFixed(1)} GB` : `${Math.round(bytes / MB)} MB`;
+
+/** Documented behaviour of macOS components people actually see at the top of a CPU list. */
+const KNOWN: Record<string, { what: string; trigger?: string }> = {
+  mds_stores: { what: "Spotlight's index store", trigger: "indexing after a lot of files changed" },
+  mds: { what: "the Spotlight metadata server", trigger: "indexing work" },
+  mdworker_shared: { what: "a Spotlight indexing worker", trigger: "indexing work" },
+  mdsync: { what: "a Spotlight index sync worker", trigger: "indexing work" },
+  kernel_task: { what: "the kernel's own task, which also absorbs CPU deliberately to cool the machine" },
+  WindowServer: { what: "the compositor every window on screen draws through" },
+  loginwindow: { what: "the manager of your login session" },
+  backupd: { what: "Time Machine", trigger: "a scheduled or manual backup" },
+  photoanalysisd: { what: "Photos' library analysis", trigger: "new photos to scan for faces and scenes" },
+  bird: { what: "iCloud Drive's file sync" },
+  cloudd: { what: "iCloud sync" },
+  syspolicyd: { what: "Gatekeeper's policy service", trigger: "first launch of a newly downloaded app" },
+  trustd: { what: "certificate validation" },
+  coreaudiod: { what: "the system audio server" },
+  XprotectService: { what: "XProtect's scanning service", trigger: "a scheduled malware check" },
+  "com.apple.Virtualization.VirtualMachine": { what: "a virtual machine, usually the one Docker runs Linux in" },
+};
+
+const DEV_RUNTIMES = new Set([
+  "node", "bun", "deno", "esbuild", "vite", "next-server", "turbo", "tsx", "webpack",
+  "python", "python3", "ruby", "java", "go", "cargo", "php",
+]);
+
+/** Recognises the per-family remediator binaries without pretending to know each family. */
+export function describeKnown(name: string): { what: string; trigger?: string } | null {
+  const remediator = /^XProtectRemediator(.+)$/.exec(name);
+  if (remediator) {
+    return {
+      what: `XProtect Remediator, Apple's built-in malware remediation, running its ${remediator[1]} check`,
+      trigger: "a scheduled scan, or one queued after a definition update",
+    };
+  }
+  return KNOWN[name] ?? null;
+}
+
+function kindOf(evidence: ProcessEvidence): Explanation["kind"] {
+  // Structural first: anything under the Paseo daemon was started by an agent,
+  // whatever it happens to be called.
+  if (evidence.parents.some((parent) => parent.name === "Paseo Daemon")) return "agent-spawned";
+  if (evidence.isAppleSystemBinary) return "apple-system";
+  if (/^com\.docker/.test(evidence.name)) return "container";
+  if (DEV_RUNTIMES.has(evidence.name) || evidence.ports.some((port) => port.scope === "local")) {
+    return "dev-runtime";
+  }
+  if (evidence.command.startsWith("/Applications/")) return "user-app";
+  return "unknown";
+}
+
+function stateOf(evidence: ProcessEvidence): Explanation["state"] {
+  const young = evidence.elapsedSeconds !== null && evidence.elapsedSeconds < 180;
+  if (young && evidence.cpuPercent > 40) return "just-started";
+  if (evidence.cpuPercent > 50 && !young) return "sustained-load";
+  if (evidence.memoryBytes > GB && evidence.cpuPercent < 5) return "memory-heavy";
+  return "steady";
+}
+
+export function classify(evidence: ProcessEvidence): Explanation {
+  const kind = kindOf(evidence);
+  const state = stateOf(evidence);
+  const known = describeKnown(evidence.name);
+  const findings: string[] = [];
+  const advice: string[] = [];
+
+  if (known) {
+    findings.push(`${evidence.name} is ${known.what}.${known.trigger ? ` It runs on ${known.trigger}.` : ""}`);
+  } else if (kind === "apple-system") {
+    findings.push(`It ships with macOS — the binary lives under a system path — but this panel has no description for it.`);
+  }
+
+  if (evidence.elapsed) {
+    findings.push(
+      state === "just-started"
+        ? `It started ${evidence.elapsed} ago, so this burst is it starting up or working through a task, not a process that has hung.`
+        : `It has been running for ${evidence.elapsed}.`,
+    );
+  }
+
+  if (evidence.parents.length > 0) {
+    findings.push(`It was started by ${evidence.parents[0].name}.`);
+  }
+  if (evidence.children.length > 0) {
+    findings.push(
+      `It has ${evidence.children.length} child process${evidence.children.length === 1 ? "" : "es"}, so quitting it takes them too.`,
+    );
+  }
+  if (evidence.ports.length > 0) {
+    findings.push(`It is serving ${evidence.ports.map((port) => `:${port.port}`).join(", ")}.`);
+  }
+
+  findings.push(`Right now: ${evidence.cpuPercent.toFixed(1)}% CPU and ${size(evidence.memoryBytes)} of memory.`);
+
+  let headline: string;
+  let concern: Explanation["concern"] = "none";
+
+  if (state === "just-started" && kind === "apple-system") {
+    headline = `${evidence.name} is doing scheduled system work and will finish on its own.`;
+    advice.push("Wait. It is seconds old, and killing it only makes macOS start it again later.");
+  } else if (state === "just-started") {
+    headline = `${evidence.name} has only just started — this is startup work, not a stuck process.`;
+    advice.push("Give it a minute and look again before doing anything.");
+  } else if (state === "sustained-load" && kind === "apple-system") {
+    headline = `${evidence.name} has been busy for a while; it is a macOS component, not something to kill.`;
+    concern = "watch";
+    advice.push(
+      known?.trigger
+        ? `Look for what triggered it — usually ${known.trigger}.`
+        : "Look for what triggered it; system components work when something asked them to.",
+      "If it is Spotlight, excluding large build directories from indexing stops the recurrence.",
+    );
+  } else if (state === "sustained-load") {
+    headline = `${evidence.name} has held ${evidence.cpuPercent.toFixed(0)}% CPU well past startup.`;
+    concern = evidence.cpuPercent > 80 ? "act" : "watch";
+    if (kind === "agent-spawned") {
+      advice.push("It belongs to one of your coding agents — closing that session releases it.");
+    }
+    if (evidence.ports.length > 0) {
+      advice.push(`It is serving ${evidence.ports.map((port) => `:${port.port}`).join(", ")}; stop that dev server if you are not using it.`);
+    }
+    advice.push("Quit it the normal way first; terminate it from this list only if that does not work.");
+  } else if (state === "memory-heavy") {
+    headline = `${evidence.name} is idle but holding ${size(evidence.memoryBytes)}.`;
+    concern = evidence.memoryBytes > 2 * GB ? "watch" : "none";
+    advice.push(`Quitting it frees ${size(evidence.memoryBytes)}.`);
+    if (kind === "container") advice.push("Stopping Docker releases the whole VM, not just one container.");
+  } else {
+    headline = `${evidence.name} is behaving normally.`;
+    advice.push("Nothing to do.");
+  }
+
+  // Machine-level context changes what the advice is worth.
+  const swapPercent =
+    evidence.machine.swapTotalBytes > 0
+      ? (evidence.machine.swapUsedBytes / evidence.machine.swapTotalBytes) * 100
+      : 0;
+  if (swapPercent > 50 && state !== "just-started") {
+    findings.push(
+      `The machine is swapping (${size(evidence.machine.swapUsedBytes)} in use), so memory is the tighter constraint right now, not CPU.`,
+    );
+  }
+  if (evidence.machine.loadPercent < 60 && state === "sustained-load") {
+    findings.push(
+      `The machine overall is not saturated (${evidence.machine.loadPercent.toFixed(0)}% of ${evidence.machine.cores} cores), so this one process is the outlier rather than a general overload.`,
+    );
+  }
+
+  return { headline, kind, state, concern, findings, advice };
+}

package/server/explain.ts

@@ -0,0 +1,95 @@
+import os from "node:os";
+import path from "node:path";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { z } from "zod";
+import { describeError, run, tryRun } from "./exec";
+import type { explainProcess } from "../shared/explain";
+import { classify, type ProcessEvidence } from "./explain-rules";
+import { readMetricsHandler } from "./metrics";
+import { ancestorsOf, parseElapsedSeconds, parsePsTable, processName, type RawProcess } from "./processes";
+import { readServicesHandler } from "./services";
+
+type Output = z.output<typeof explainProcess.output>;
+
+const MB = 1024 * 1024;
+const GB = 1024 ** 3;
+
+async function cwdOf(pid: number): Promise<string | null> {
+  const raw = await tryRun("/usr/sbin/lsof", ["-a", "-d", "cwd", "-p", String(pid), "-Fn"], 4_000);
+  return raw?.split("\n").find((line) => line.startsWith("n"))?.slice(1) ?? null;
+}
+
+function childrenOf(pid: number, table: readonly RawProcess[]): RawProcess[] {
+  return table.filter((entry) => entry.ppid === pid);
+}
+
+export async function explainProcessHandler(
+  { pid }: { pid: number },
+  context: PluginHandlerContext,
+): Promise<Output> {
+  const table = parsePsTable(await run("/bin/ps", ["-Ao", "pid=,ppid=,pcpu=,rss=,comm="], 10_000));
+  const self = table.find((entry) => entry.pid === pid);
+
+  if (!self) {
+    return {
+      found: false,
+      name: `PID ${pid}`,
+      pid,
+      explanation: {
+        headline: "This process no longer exists — it exited while you were looking at it.",
+        kind: "unknown",
+        state: "steady",
+        concern: "none",
+        findings: ["A process that short-lived is almost always scheduled work rather than a fault."],
+        advice: ["Nothing to do. Refresh the list to see what is running now."],
+      },
+    };
+  }
+
+  const [elapsedRaw, cwd, metrics, services] = await Promise.all([
+    tryRun("/bin/ps", ["-o", "etime=", "-p", String(pid)], 3_000),
+    cwdOf(pid),
+    readMetricsHandler(),
+    readServicesHandler({}, context),
+  ]);
+
+  const children = childrenOf(pid, table);
+  const childPids = new Set([pid, ...children.map((child) => child.pid)]);
+
+  const evidence: ProcessEvidence = {
+    name: processName(self.command),
+    pid,
+    command: self.command,
+    cpuPercent: self.cpuPercent,
+    memoryBytes: self.memoryBytes,
+    elapsed: elapsedRaw?.trim() ?? null,
+    elapsedSeconds: elapsedRaw ? parseElapsedSeconds(elapsedRaw) : null,
+    cwd,
+    parents: [...ancestorsOf(pid, table)]
+      .filter((entry) => entry !== pid)
+      .map((entry) => ({ pid: entry, name: processName(table.find((row) => row.pid === entry)?.command ?? "") })),
+    children: children.map((child) => ({
+      pid: child.pid,
+      name: processName(child.command),
+      cpuPercent: child.cpuPercent,
+    })),
+    ports: services.ports
+      .filter((port) => port.pid !== null && childPids.has(port.pid))
+      .map((port) => ({ port: port.port, protocol: port.protocol, scope: port.scope })),
+    isAppleSystemBinary: /^\/(System|usr\/libexec|usr\/sbin|Library\/Apple)\//.test(self.command),
+    machine: {
+      cores: metrics.cpu.cores,
+      loadPercent: metrics.cpu.loadPercent,
+      pressurePercent: metrics.memory.pressurePercent,
+      swapUsedBytes: metrics.swap.usedBytes,
+      swapTotalBytes: metrics.swap.totalBytes,
+    },
+  };
+
+  return {
+    found: true,
+    name: evidence.name,
+    pid,
+    explanation: classify(evidence),
+  };
+}