@hienlh/ppm 0.17.49 → 0.17.51

package/src/services/file-watcher/recreated-dir-poller.ts

@@ -0,0 +1,149 @@
+/**
+ * Polling fallback for directories `fs.watch` can no longer report on.
+ *
+ * Bun (verified on 1.3.13, Linux) keys its `fs.watch` registry by the literal
+ * path string, so once a directory has been watched, deleted and recreated, a
+ * new watcher on that same path reuses the dead inotify watch and is silent
+ * forever. Closing the old handle first or waiting does not help, and there is
+ * no usable alternative spelling: a trailing separator is a distinct key that
+ * works exactly once, while `//` and `///` normalise back to the same one.
+ *
+ * The poisoning is per-path and permanent, but it does NOT spread: a directory
+ * Bun has never watched works normally even when it sits inside a recreated
+ * parent. So this poller only ever covers the handful of paths that were
+ * actually re-attached, one directory level each, and real watchers keep
+ * covering everything else.
+ *
+ * Reproducers: `spike-bun-recursive-watch-probe.mjs` (the defect, and that
+ * Windows is unaffected) and `spike-bun-watch-poison-scope-probe.mjs` (that it
+ * is confined to previously-watched paths, which is what bounds this poller).
+ *
+ * Windows and macOS re-watch such directories correctly, so nothing here runs
+ * there.
+ */
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Slow enough to be invisible next to inotify, fast enough for a save-and-see loop. */
+const POLL_INTERVAL_MS = 1000;
+/**
+ * Hard cap on polled directories. Churn is bounded in practice (a `git checkout`
+ * recreates a few directories), and refusing to grow without limit matters more
+ * than perfect coverage in a watcher that has already caused a watch-count
+ * blowup once.
+ */
+const MAX_POLLED_DIRS = 64;
+
+export interface RecreatedDirPollerOptions {
+  /** Absolute path of every entry that appeared, vanished or changed. */
+  onChange: (absPath: string) => void;
+  intervalMs?: number;
+  maxDirs?: number;
+}
+
+/** name → mtimeMs for the direct entries of one directory. */
+type DirSnapshot = Map<string, number>;
+
+export class RecreatedDirPoller {
+  private readonly snapshots = new Map<string, DirSnapshot>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly intervalMs: number;
+  private readonly maxDirs: number;
+  private droppedForBudget = false;
+
+  constructor(private readonly options: RecreatedDirPollerOptions) {
+    this.intervalMs = options.intervalMs ?? POLL_INTERVAL_MS;
+    this.maxDirs = options.maxDirs ?? MAX_POLLED_DIRS;
+  }
+
+  get size(): number {
+    return this.snapshots.size;
+  }
+
+  /** True when a directory had to be refused because the cap was reached. */
+  get truncated(): boolean {
+    return this.droppedForBudget;
+  }
+
+  /**
+   * Start polling `absDir`'s direct entries. The current contents become the
+   * baseline, so pre-existing files are not reported as new.
+   */
+  add(absDir: string): void {
+    if (this.snapshots.has(absDir)) return;
+    if (this.snapshots.size >= this.maxDirs) {
+      this.droppedForBudget = true;
+      return;
+    }
+    this.snapshots.set(absDir, this.readDir(absDir));
+    if (!this.timer) {
+      this.timer = setInterval(() => this.tick(), this.intervalMs);
+      // Never hold the process open just to poll.
+      this.timer.unref?.();
+    }
+  }
+
+  /** Stop polling `absDir` and anything beneath it. */
+  remove(absDir: string): void {
+    const prefix = absDir + "/";
+    for (const dir of this.snapshots.keys()) {
+      // Compare on both separators: callers pass native paths.
+      if (dir === absDir || dir.startsWith(prefix) || dir.startsWith(absDir + "\\")) {
+        this.snapshots.delete(dir);
+      }
+    }
+    if (this.snapshots.size === 0) this.stopTimer();
+  }
+
+  close(): void {
+    this.snapshots.clear();
+    this.droppedForBudget = false;
+    this.stopTimer();
+  }
+
+  private stopTimer(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private tick(): void {
+    for (const [dir, previous] of this.snapshots) {
+      const current = this.readDir(dir);
+
+      for (const [name, mtime] of current) {
+        const before = previous.get(name);
+        if (before === undefined || before !== mtime) {
+          this.options.onChange(join(dir, name));
+        }
+      }
+      for (const name of previous.keys()) {
+        if (!current.has(name)) this.options.onChange(join(dir, name));
+      }
+
+      this.snapshots.set(dir, current);
+    }
+  }
+
+  /** Direct entries of `absDir` with their mtimes. Empty when it is unreadable. */
+  private readDir(absDir: string): DirSnapshot {
+    const snapshot: DirSnapshot = new Map();
+    let names: string[];
+    try {
+      names = readdirSync(absDir);
+    } catch {
+      return snapshot; // deleted again, or permissions — treat as empty
+    }
+    for (const name of names) {
+      try {
+        // lstat, not stat: a symlink's own mtime, never its target's, matching
+        // the scan that decides coverage.
+        snapshot.set(name, lstatSync(join(absDir, name)).mtimeMs);
+      } catch {
+        // Vanished between readdir and lstat; the next tick reports it.
+      }
+    }
+    return snapshot;
+  }
+}

package/src/services/file-watcher/watch-tree.ts

@@ -1,6 +1,7 @@
 import { lstatSync, readdirSync, watch, type FSWatcher } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { hasIgnoredDirSegment, isIgnoredDirName, isIgnoredPath } from "./ignore-rules.ts";
+import { RecreatedDirPoller } from "./recreated-dir-poller.ts";
 
 /**
  * Watches a project directory while keeping the number of watched directories
@@ -54,18 +55,36 @@ export interface WatchTreeStats {
   dirs: number;
   /** `fs.watch` handles held. */
   watchers: number;
-  /** Coverage was cut short by `maxDirs`, so part of the tree is unwatched. */
+  /** Coverage was cut short by a budget, so part of the tree is unwatched. */
   truncated: boolean;
+  /**
+   * Directories covered by the polling fallback instead of a watcher, because
+   * the runtime cannot re-watch a recreated path. Linux only; 0 elsewhere.
+   */
+  polledDirs: number;
 }
 
 export class WatchTree {
   private readonly attached = new Map<string, AttachedWatcher>();
   private readonly rebuildTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /**
+   * Every path we have ever handed to `fs.watch`. On Bun + Linux a second watch
+   * on the same path after a delete/recreate is silent forever, so this set is
+   * what tells us a watcher cannot be trusted and the poller has to stand in.
+   */
+  private readonly everAttached = new Set<string>();
+  private readonly poller: RecreatedDirPoller | null;
   private covered = 0;
   private truncated = false;
   private closed = false;
 
-  constructor(private readonly options: WatchTreeOptions) {}
+  constructor(private readonly options: WatchTreeOptions) {
+    // Only Bun on Linux has the stale-watch defect; elsewhere re-watching works
+    // and paying for polling would be pure waste.
+    this.poller = process.platform === "linux"
+      ? new RecreatedDirPoller({ onChange: (abs) => this.reportAbs(abs) })
+      : null;
+  }
 
   start(): void {
     this.cover(this.options.root);
@@ -79,12 +98,19 @@ export class WatchTree {
       try { watcher.close(); } catch { /* already gone */ }
     }
     this.attached.clear();
+    this.everAttached.clear();
+    this.poller?.close();
     this.covered = 0;
     this.truncated = false;
   }
 
   stats(): WatchTreeStats {
-    return { dirs: this.covered, watchers: this.attached.size, truncated: this.truncated };
+    return {
+      dirs: this.covered,
+      watchers: this.attached.size,
+      truncated: this.truncated || (this.poller?.truncated ?? false),
+      polledDirs: this.poller?.size ?? 0,
+    };
   }
 
   /** Walk `absDir` and attach the fewest watchers that cover it without touching ignored dirs. */
@@ -134,6 +160,22 @@ export class WatchTree {
 
   private attach(node: ScanNode): void {
     const fitsWholeSubtree = this.covered + node.size <= this.options.maxDirs;
+
+    // A path we have watched before is being re-attached, so this directory was
+    // deleted and recreated. On Bun + Linux its watcher will never fire again:
+    // poll its own entries, and cover the subtree non-recursively so each child
+    // gets a watcher on a path the runtime still honours.
+    if (this.poller && this.everAttached.has(node.path)) {
+      this.poller.add(node.path);
+      if (this.covered + 1 > this.options.maxDirs) {
+        this.truncated = true;
+        return;
+      }
+      this.addWatcher(node.path, false, 1);
+      for (const child of node.dirs) this.attach(child);
+      return;
+    }
+
     // One recursive watch for a subtree the runtime can safely expand on its own.
     if (!node.hasIgnored && fitsWholeSubtree && this.addWatcher(node.path, true, node.size)) return;
 
@@ -158,6 +200,7 @@ export class WatchTree {
       // server down; drop the handle instead and record the lost coverage.
       watcher.on("error", () => this.dropWatcher(absDir));
       this.attached.set(absDir, { watcher, covers, recursive });
+      this.everAttached.add(absDir);
       this.covered += covers;
       return true;
     } catch {
@@ -203,6 +246,17 @@ export class WatchTree {
     if (!isIgnoredPath(relPath)) this.options.onChange(relPath);
   }
 
+  /**
+   * Report an absolute path the poller noticed, applying the same root-scoping
+   * and ignore rules a watcher event goes through.
+   */
+  private reportAbs(abs: string): void {
+    if (this.closed) return;
+    const relPath = relative(this.options.root, abs).replaceAll("\\", "/");
+    if (!relPath || relPath === ".." || relPath.startsWith("../")) return;
+    if (!isIgnoredPath(relPath)) this.options.onChange(relPath);
+  }
+
   /** Extend or release coverage after a directory under a non-recursive watch appeared or vanished. */
   private syncChildDir(abs: string): void {
     let isDir = false;
@@ -233,6 +287,7 @@ export class WatchTree {
   }
 
   private closeSubtree(absPath: string): void {
+    this.poller?.remove(absPath);
     const prefix = absPath + sep;
     for (const [dir, entry] of this.attached) {
       if (dir !== absPath && !dir.startsWith(prefix)) continue;

package/src/services/proc-table-linux.ts

@@ -0,0 +1,183 @@
+/**
+ * Process table straight from `/proc` — Linux only, no subprocess.
+ *
+ * Every caller in PPM used to shell out to `ps`, which lives in `procps` and is
+ * simply absent from slim Debian images (including the one PPM's own test suite
+ * runs in). Each call site swallowed the spawn error and carried on with empty
+ * data, so a missing binary silently disabled orphan reaping, resource graphs
+ * and cloudflared discovery instead of failing loudly.
+ *
+ * Callers keep `ps` as the macOS path; there is no `/proc` there.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+
+export const PROC_AVAILABLE = process.platform === "linux";
+
+/**
+ * Kernel clock ticks per second. `sysconf(_SC_CLK_TCK)` is not reachable from
+ * JS; 100 is the value Linux has shipped on every mainstream configuration for
+ * decades, and it only scales CPU-time maths, so a wrong guess would skew a
+ * percentage rather than break anything.
+ */
+const CLOCK_TICKS_PER_SEC = 100;
+/** `/proc/<pid>/stat` reports RSS in pages. */
+const PAGE_SIZE_KB = 4;
+
+export interface ProcEntry {
+  pid: number;
+  ppid: number;
+  /** Average CPU% over the process lifetime — the same figure `ps %cpu` prints. */
+  cpuPercent: number;
+  rssKB: number;
+  /** Seconds since the process started. */
+  elapsedSec: number;
+  /** Wall-clock start time, epoch ms. Stable identity for PID-reuse checks. */
+  startedAtMs: number;
+  /** Executable name from `comm` (truncated to 15 chars by the kernel). */
+  comm: string;
+  /** Full argv joined by spaces. Empty for kernel threads. */
+  args: string;
+}
+
+/** Lowercased argv of `pid`, or null when /proc is unavailable/unreadable. */
+export function readProcCmdline(pid: number): string | null {
+  if (!PROC_AVAILABLE) return null;
+  try {
+    // NUL-separated argv; join with spaces so substring checks behave like `ps`.
+    return readFileSync(`/proc/${pid}/cmdline`, "utf-8").split("\0").join(" ").toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/** Kernel `comm` for `pid`, or null when /proc is unavailable/unreadable. */
+export function readProcComm(pid: number): string | null {
+  if (!PROC_AVAILABLE) return null;
+  try {
+    return readFileSync(`/proc/${pid}/comm`, "utf-8").trim();
+  } catch {
+    return null;
+  }
+}
+
+/** pid → ppid for every visible process, or null when /proc is unavailable. */
+export function readProcPpidMap(): Map<number, number> | null {
+  if (!PROC_AVAILABLE) return null;
+  let names: string[];
+  try {
+    names = readdirSync("/proc");
+  } catch {
+    return null;
+  }
+  const ppidOf = new Map<number, number>();
+  for (const name of names) {
+    if (!isPidDir(name)) continue;
+    const fields = readStatFields(Number(name));
+    if (fields) ppidOf.set(Number(name), fields.ppid);
+  }
+  return ppidOf.size > 0 ? ppidOf : null;
+}
+
+/**
+ * Full process table, or null when /proc is unavailable. Reads `/proc/uptime`
+ * and `/proc/stat` once and reuses them for every process, so a table of a few
+ * hundred processes costs a few hundred small reads and no process spawns.
+ */
+export function readProcTable(): ProcEntry[] | null {
+  if (!PROC_AVAILABLE) return null;
+
+  let names: string[];
+  let uptimeSec: number;
+  let bootTimeMs: number;
+  try {
+    names = readdirSync("/proc");
+    uptimeSec = parseFloat(readFileSync("/proc/uptime", "utf-8").split(/\s+/)[0] ?? "");
+    const btime = readFileSync("/proc/stat", "utf-8").match(/^btime\s+(\d+)/m);
+    bootTimeMs = btime ? Number(btime[1]) * 1000 : Date.now() - uptimeSec * 1000;
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(uptimeSec)) return null;
+
+  const out: ProcEntry[] = [];
+  for (const name of names) {
+    if (!isPidDir(name)) continue;
+    const pid = Number(name);
+    const f = readStatFields(pid);
+    if (!f) continue;
+
+    const startSec = f.startTicks / CLOCK_TICKS_PER_SEC;
+    // Clamp: a process started in the same tick as the uptime read can compute
+    // a tiny negative elapsed, which would produce an absurd CPU percentage.
+    const elapsedSec = Math.max(uptimeSec - startSec, 0.001);
+    const cpuSec = (f.utime + f.stime) / CLOCK_TICKS_PER_SEC;
+
+    let args = "";
+    try {
+      args = readFileSync(`/proc/${pid}/cmdline`, "utf-8").split("\0").filter(Boolean).join(" ");
+    } catch { /* exited between readdir and read */ }
+
+    out.push({
+      pid,
+      ppid: f.ppid,
+      cpuPercent: Math.round((cpuSec / elapsedSec) * 1000) / 10,
+      rssKB: f.rssPages * PAGE_SIZE_KB,
+      elapsedSec,
+      startedAtMs: bootTimeMs + startSec * 1000,
+      comm: f.comm,
+      args,
+    });
+  }
+  return out.length > 0 ? out : null;
+}
+
+const isPidDir = (name: string): boolean => /^\d+$/.test(name);
+
+interface StatFields {
+  comm: string;
+  ppid: number;
+  utime: number;
+  stime: number;
+  startTicks: number;
+  rssPages: number;
+}
+
+/**
+ * Parse the fields we need out of `/proc/<pid>/stat`.
+ *
+ * The format is `pid (comm) state ppid …` and `comm` may contain spaces AND
+ * parentheses, so the split has to anchor on the LAST ')' — a naive
+ * whitespace split silently shifts every field for any process whose name
+ * contains a space.
+ */
+function readStatFields(pid: number): StatFields | null {
+  let stat: string;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+  } catch {
+    return null; // process exited, or not permitted
+  }
+  const close = stat.lastIndexOf(")");
+  const open = stat.indexOf("(");
+  if (close < 0 || open < 0 || close < open) return null;
+
+  const comm = stat.slice(open + 1, close);
+  // After the last ')' the fields are: state ppid pgrp … i.e. proc(5) field N
+  // sits at index N-3.
+  const f = stat.slice(close + 1).trim().split(/\s+/);
+  const num = (i: number): number => {
+    const v = parseInt(f[i] ?? "", 10);
+    return isNaN(v) ? 0 : v;
+  };
+  const ppid = parseInt(f[1] ?? "", 10);
+  if (isNaN(ppid)) return null;
+
+  return {
+    comm,
+    ppid,
+    utime: num(11),      // field 14
+    stime: num(12),      // field 15
+    startTicks: num(19), // field 22
+    rssPages: num(21),   // field 24
+  };
+}

package/src/services/resource-monitor.service.ts

@@ -5,6 +5,7 @@
  */
 
 import { parseProcessList, buildTree, groupProcesses } from "./resource-monitor-utils.ts";
+import { readProcTable } from "./proc-table-linux.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -76,17 +77,40 @@ class ResourceMonitorService {
     }
   }
 
+  /**
+   * Prefer `/proc` and fall back to `ps`. `ps` is not installed on slim Linux
+   * images, and the old code let the failed spawn surface as an empty process
+   * list — the resource panel just showed zeros with no hint why.
+   */
+  private async listProcesses(): Promise<ProcessEntry[]> {
+    const table = readProcTable();
+    if (table) {
+      const now = Date.now();
+      return table
+        .filter((p) => p.pid !== 0 && p.args)
+        .map((p) => ({
+          pid: p.pid,
+          ppid: p.ppid,
+          cpu: Math.round(p.cpuPercent * 10) / 10,
+          ramMB: Math.round((p.rssKB / 1024) * 10) / 10,
+          startedAt: Math.min(p.startedAtMs, now),
+          command: p.args,
+        }));
+    }
+
+    const proc = Bun.spawn({
+      cmd: ["ps", "-e", "-o", "pid,ppid,%cpu,rss,etimes,args"],
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const stdout = await new Response(proc.stdout).text();
+    await proc.exited;
+    return parseProcessList(stdout);
+  }
+
   private async poll() {
     try {
-      const proc = Bun.spawn({
-        cmd: ["ps", "-e", "-o", "pid,ppid,%cpu,rss,etimes,args"],
-        stdout: "pipe",
-        stderr: "ignore",
-      });
-      const stdout = await new Response(proc.stdout).text();
-      await proc.exited;
-
-      const entries = parseProcessList(stdout);
+      const entries = await this.listProcesses();
       const rootPid = process.pid;
       const serverEntry = entries.find((e) => e.pid === rootPid);
       const children = buildTree(entries, rootPid);

package/src/services/supervisor-stopped-page.ts

@@ -1,10 +1,16 @@
 /**
  * Minimal HTTP server that serves a "stopped" page when the PPM server child is down.
- * Binds to the same port so the tunnel URL still works.
+ *
+ * It stands in for the server, so it binds an OS-assigned loopback port and
+ * publishes it to `.server-port` exactly as the real server does. The edge
+ * forwarder then routes the public port here and the tunnel URL keeps working —
+ * which is the whole point of the page. Binding the public port directly would
+ * collide with the edge, which owns it.
  */
-import { appendFileSync } from "node:fs";
+import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { getPpmDir } from "./ppm-dir.ts";
+import { SERVER_PORT_FILE } from "./edge-target-resolver.ts";
 
 function log(level: string, msg: string) {
   const ts = new Date().toISOString();
@@ -36,6 +42,11 @@ const STOPPED_HTML = `<!DOCTYPE html>
 
 let stoppedServer: ReturnType<typeof Bun.serve> | null = null;
 
+/**
+ * @param port  0 in normal operation — the edge finds this page via
+ *              `.server-port`, so it needs no fixed port of its own.
+ * @param host  loopback; the edge is the only public listener.
+ */
 export function startStoppedPage(port: number, host: string) {
   if (stoppedServer) return;
 
@@ -56,7 +67,13 @@ export function startStoppedPage(port: number, host: string) {
         });
       },
     });
-    log("INFO", `Stopped page serving on port ${port}`);
+    // Take over as the edge's target so the public URL shows this page.
+    try {
+      writeFileSync(SERVER_PORT_FILE(), String(stoppedServer.port));
+    } catch (e) {
+      log("WARN", `Failed to publish stopped-page port: ${e}`);
+    }
+    log("INFO", `Stopped page serving on ${host}:${stoppedServer.port}`);
   } catch (e) {
     log("WARN", `Failed to start stopped page: ${e}`);
   }