@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.0

package/packages/shared/src/__tests__/no-direct-platform-branch.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Repo-level invariant: `process.platform === "<os>"` branches (and the
+ * inverse `!==` form) MUST NOT appear outside the canonical platform
+ * primitive locations. All OS-specific behaviour lives under
+ * `packages/shared/src/platform/**` (and `packages/electron/src/platform/**`
+ * for Electron-specific primitives) plus a small documented allowlist.
+ *
+ * If this test fails, either:
+ *   (a) Move the platform-aware logic into a platform/* primitive that
+ *       takes an optional `platform: NodeJS.Platform` parameter, OR
+ *   (b) Add an opt-out marker `// platform-branch-ok` on the same line
+ *       for a genuine, localised OS probe (e.g. a top-level env fingerprint).
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/**
+ * Files / directory-prefixes where platform branches are allowed.
+ *
+ * Each entry is a repo-relative path using forward slashes. Entries
+ * ending in `/` match any file under that directory (prefix match);
+ * entries without a trailing slash must match exactly.
+ *
+ * Every entry has a one-line reason and a follow-up owner.
+ */
+const ALLOWLIST: readonly string[] = [
+  // Canonical platform primitives — the whole POINT is platform branching.
+  "packages/shared/src/platform/",
+  // Electron-specific platform primitives.
+  "packages/electron/src/platform/",
+
+  // ── Seed allowlist (documented follow-ups, out of scope for this change)
+
+  // Extension's pgid/ps scanner — platform-aware but uses `_platform` test
+  // hooks rather than shared primitives; consolidating into
+  // shared/platform/process-scan.ts is a separate change.
+  "packages/extension/src/process-scanner.ts",
+
+  // Electron dependency detection predates the tool-registry; migration
+  // to ToolRegistry.resolve is a separate change.
+  "packages/electron/src/lib/dependency-detector.ts",
+
+  // Electron top-level bootstrap: process.platform printed in log output,
+  // legitimate observability use.
+  "packages/electron/src/main.ts",
+
+  // Electron doctor: reports process.platform to the user.
+  "packages/electron/src/lib/doctor.ts",
+
+  // Electron forge config: build-time darwin special-case.
+  "packages/electron/forge.config.ts",
+
+  // Server process-manager: one domain branch in spawnHeadless picking
+  // Unix "sh -c tail -f" wrapper vs Windows direct node.exe spawn.
+  // The wrapper is genuinely Unix-only (sh+tail); splitting the headless
+  // mechanism into two is tracked as a follow-up.
+  "packages/server/src/process-manager.ts",
+
+  // Server editor registry: selects per-OS process patterns from a data
+  // table. Genuine data-lookup branching, benign.
+  "packages/server/src/editor-registry.ts",
+
+  // Server tunnel: surfaces process.platform in a response body.
+  "packages/server/src/tunnel.ts",
+
+  // Server browse: returns process.platform in BrowseResult for the
+  // client path-picker (protocol surface).
+  "packages/server/src/browse.ts",
+
+  // Client session-grouping: reads process.platform in a comment-only
+  // doc reference and uses inferPlatform heuristic; no actual branch.
+  "packages/client/src/lib/session-grouping.ts",
+
+  // ── Follow-up: migrate to electron/src/platform/ per deferred
+  // consolidate-platform-handlers (18→13 file refactor).
+
+  // App menu: darwin detection for role:appMenu (Electron convention).
+  "packages/electron/src/lib/app-menu.ts",
+  // Bundled node: win32 binary name suffix; data-lookup branch.
+  "packages/electron/src/lib/bundled-node.ts",
+  // Server lifecycle: win32 managed-tsx.cmd + which/where probes.
+  "packages/electron/src/lib/server-lifecycle.ts",
+  // Tray icon: platform-specific asset selection; will move to
+  // electron/src/platform/tray-icon.ts in deferred consolidation.
+  "packages/electron/src/lib/tray.ts",
+
+  // Server editor PID registry: per-OS process pattern matching for
+  // orphan detection on boot. Genuine data-table branching.
+  "packages/server/src/editor-pid-registry.ts",
+  // Electron dependency installer: Windows npm is npm.cmd (batch wrapper);
+  // spawn('npm') without .cmd extension fails ENOENT on Windows. The branch
+  // routes around this by preferring bundled node+npm-cli.js on Windows.
+  // Follow-up: migrate to a platform/exec npm-resolver primitive.
+  "packages/electron/src/lib/dependency-installer.ts",
+  // fix-pty-permissions: Windows short-circuit (no chmod needed).
+  "packages/server/src/fix-pty-permissions.ts",
+  // package-manager-wrapper: comment-only reference; no runtime branch.
+  "packages/server/src/package-manager-wrapper.ts",
+  // terminal-manager: win32 branch for node-pty spawnOptions; will move
+  // to platform/terminal in deferred consolidation.
+  "packages/server/src/terminal-manager.ts",
+];
+
+const PLATFORM_BRANCH_RE = /process\.platform\s*(===|!==)\s*["'](win32|linux|darwin)["']/;
+
+const OPT_OUT_MARKER = "platform-branch-ok";
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "__tests__") continue;
+      yield* walk(full);
+    } else if (entry.isFile() && /\.(ts|tsx|mts|cts)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+/** Check if a repo-relative normalised path is covered by the allowlist. */
+function isAllowed(relPath: string, allow: readonly string[]): boolean {
+  for (const entry of allow) {
+    if (entry.endsWith("/")) {
+      if (relPath.startsWith(entry)) return true;
+    } else {
+      if (relPath === entry) return true;
+    }
+  }
+  return false;
+}
+
+describe("no direct process.platform branches outside platform/**", () => {
+  it("only allowlisted files contain process.platform === \"<os>\" branches", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+
+    for (const pkg of await fs.readdir(packagesDir, { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue;
+      const srcDir = path.join(packagesDir, pkg.name, "src");
+      try { await fs.access(srcDir); } catch { continue; }
+
+      for await (const file of walk(srcDir)) {
+        const relPath = path.relative(repoRoot, file).replace(/\\/g, "/");
+        if (isAllowed(relPath, ALLOWLIST)) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!PLATFORM_BRANCH_RE.test(line)) return;
+          if (line.includes(OPT_OUT_MARKER)) return;
+          violations.push({ file: relPath, line: idx + 1, text: line.trim() });
+        });
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Direct process.platform branches found outside the allowlist.\n` +
+        `Move the logic into a platform/* primitive or add a ` +
+        `\`// ${OPT_OUT_MARKER}\` comment on the line with a justification.\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations.map((v) => `  ${v.file}:${v.line}  ${v.text}`).join("\n");
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

package/packages/shared/src/__tests__/no-direct-process-kill.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Repo-level invariant: `process.kill(...)` MUST NOT be called directly
+ * outside `packages/shared/src/platform/`. All termination / liveness must
+ * go through the platform helpers (`isProcessAlive`, `killProcess`,
+ * `killPidWithGroup`) so that Windows tree-kill (taskkill /F /T /PID) and
+ * POSIX process-group semantics are applied uniformly.
+ *
+ * If this test fails, migrate the offending file's call to:
+ *   import { isProcessAlive, killProcess, killPidWithGroup }
+ *     from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+ *
+ * See change: route-kill-paths-through-platform.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/** Files or directories allowed to call `process.kill(...)` directly. */
+const ALLOWLIST_DIRS: readonly string[] = [
+  "packages/shared/src/platform",
+];
+
+/**
+ * Regex catches any textual reference to `process.kill(...)`. We match on
+ * whole-word `process` to avoid flagging `childProcess.kill(...)`, which
+ * is the `ChildProcess#kill()` instance method, not the global
+ * `process.kill`. Calls on `ChildProcess` instances are banned separately
+ * via code review / type-guided refactors, not this lint.
+ */
+const PROCESS_KILL_RE = /(?:^|[^.\w])process\.kill\s*\(/;
+
+/**
+ * Per-line opt-out marker. Use for embedded scripts that run in a
+ * separate Node process (e.g. the `node -e` orchestrator string in
+ * restart-helper.ts):
+ *   const orchestrator = `process.kill(pid, 0);` // ban:process-kill-ok
+ */
+const OPT_OUT_MARKER = "ban:process-kill-ok";
+
+/** Recursively walk a directory, yielding all .ts / .tsx files. */
+async function* walk(dir: string): AsyncGenerator<string> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "__tests__") continue;
+      yield* walk(full);
+    } else if (entry.isFile() && /\.(ts|tsx|mts|cts)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+describe("no direct process.kill outside packages/shared/src/platform/", () => {
+  it("only allowlisted paths call process.kill directly", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+    const allowPrefixes = ALLOWLIST_DIRS.map((p) =>
+      path.resolve(repoRoot, p).replace(/\\/g, "/") + "/",
+    );
+
+    for (const pkg of await fs.readdir(packagesDir, { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue;
+      const srcDir = path.join(packagesDir, pkg.name, "src");
+      try {
+        await fs.access(srcDir);
+      } catch {
+        continue;
+      }
+      for await (const file of walk(srcDir)) {
+        const normalized = file.replace(/\\/g, "/");
+        if (allowPrefixes.some((prefix) => normalized.startsWith(prefix))) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!PROCESS_KILL_RE.test(line)) return;
+          if (line.includes(OPT_OUT_MARKER)) return;
+          violations.push({
+            file: path.relative(repoRoot, file),
+            line: idx + 1,
+            text: line.trim(),
+          });
+        });
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Direct process.kill(...) calls found outside packages/shared/src/platform/.\n` +
+        `Migrate each to a platform helper:\n` +
+        `  import { isProcessAlive, killProcess, killPidWithGroup }\n` +
+        `    from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map((v) => `  ${v.file}:${v.line}  ${v.text}`)
+          .join("\n");
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

package/packages/shared/src/__tests__/platform-commands.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for packages/shared/src/platform/commands.ts.
+ * Platform behavior exercised via injected `platform` + `exec` / `asyncExec`.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { openBrowser, isVirtualMachine } from "../platform/commands.js";
+
+describe("openBrowser", () => {
+  it("uses `open` on macOS", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "darwin", asyncExec });
+    expect(asyncExec).toHaveBeenCalledOnce();
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^open\s+"https:\/\/example\.com"$/);
+  });
+
+  it("uses `start` on Windows", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "win32", asyncExec });
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^start\s+""\s+"https:\/\/example\.com"$/);
+  });
+
+  it("uses `xdg-open` on Linux", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser("https://example.com", { platform: "linux", asyncExec });
+    expect(asyncExec.mock.calls[0][0]).toMatch(/^xdg-open\s+"https:\/\/example\.com"$/);
+  });
+
+  it("escapes URLs via JSON.stringify (quotes, newlines, backslashes)", () => {
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(null));
+    openBrowser('https://example.com/?q="escaped"', { platform: "linux", asyncExec });
+    // JSON.stringify converts " → \"
+    expect(asyncExec.mock.calls[0][0]).toContain('\\"escaped\\"');
+  });
+
+  it("invokes onError callback when async exec fails", () => {
+    const err = new Error("nope");
+    const onError = vi.fn();
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(err));
+    openBrowser("https://example.com", { platform: "linux", asyncExec, onError });
+    expect(onError).toHaveBeenCalledWith(err);
+  });
+
+  it("does not throw when onError is absent", () => {
+    const err = new Error("nope");
+    const asyncExec = vi.fn((_cmd, cb: (e: Error | null) => void) => cb(err));
+    expect(() =>
+      openBrowser("https://example.com", { platform: "linux", asyncExec }),
+    ).not.toThrow();
+  });
+});
+
+describe("isVirtualMachine", () => {
+  it("detects VMware via sysctl on macOS", () => {
+    const exec = vi.fn().mockReturnValue("VMware7,1\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(true);
+  });
+
+  it("detects VirtualBox via sysctl on macOS", () => {
+    const exec = vi.fn().mockReturnValue("VirtualBox6,0\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(true);
+  });
+
+  it("returns false on physical macOS hardware", () => {
+    const exec = vi.fn().mockReturnValue("MacBookPro18,3\n");
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(false);
+  });
+
+  it("detects VM via systemd-detect-virt on Linux", () => {
+    const exec = vi.fn().mockReturnValue("kvm\n");
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(true);
+  });
+
+  it("returns false on bare-metal Linux", () => {
+    const exec = vi.fn().mockReturnValue("none\n");
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(false);
+  });
+
+  it("detects VMware via wmic on Windows", () => {
+    const exec = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd.includes("bios")) return "SerialNumber\nVMware-42 AA BB\n";
+      return "";
+    });
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(true);
+  });
+
+  it("detects Hyper-V via wmic computersystem on Windows", () => {
+    const exec = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd.includes("bios")) throw new Error("no serial");
+      if (cmd.includes("computersystem")) return "Manufacturer  Model\nMicrosoft Corporation  Virtual Machine\n";
+      return "";
+    });
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(true);
+  });
+
+  it("returns false on physical Windows when no VM markers found", () => {
+    const exec = vi.fn().mockReturnValue("SerialNumber\nR90ABCDE\n");
+    expect(isVirtualMachine({ platform: "win32", exec })).toBe(false);
+  });
+
+  it("returns false when exec throws unexpectedly", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(isVirtualMachine({ platform: "darwin", exec })).toBe(false);
+    expect(isVirtualMachine({ platform: "linux", exec })).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/platform-exec.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Tests for packages/shared/src/platform/exec.ts — the thin wrapper over
+ * node:child_process that sets `windowsHide: true` by default.
+ *
+ * These tests assert the *option passthrough* contract; they do not spawn
+ * real subprocesses. The wrapper is a few lines per function — its only
+ * job is to forward arguments with `windowsHide: true` layered on top.
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import { execSync, spawn, spawnSync, exec, execFile } from "../platform/exec.js";
+
+describe("platform/exec wrappers", () => {
+  // ── execSync ────────────────────────────────────────────────────────────
+  // Real invocation: we pick commands that exit 0 on every OS (node itself).
+
+  it("execSync exits 0 for `node --version`", () => {
+    const out = execSync(`"${process.execPath}" --version`, { encoding: "utf-8" });
+    expect(String(out).trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  // ── spawnSync ───────────────────────────────────────────────────────────
+
+  it("spawnSync runs `node --version` and captures stdout", () => {
+    const result = spawnSync(process.execPath, ["--version"], { encoding: "utf-8" });
+    expect(result.status).toBe(0);
+    expect(String(result.stdout).trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  it("spawnSync accepts undefined args and defaults to []", () => {
+    // Should not throw — wrapper must coerce undefined args to []
+    const result = spawnSync(process.execPath, undefined, {
+      encoding: "utf-8",
+      input: "process.stdout.write('ok')",
+    });
+    // May or may not work depending on shell, but the call itself must not throw.
+    expect(typeof result).toBe("object");
+  });
+
+  // ── windowsHide default ─────────────────────────────────────────────────
+
+  // The key invariant: wrappers set windowsHide: true when caller omits it.
+  // We verify this by inspecting the spawn metadata (spawnargs / opts).
+  // Node doesn't expose the final options object, so we check by spawning
+  // with a non-overridden call and verifying it completes successfully
+  // (a misconfigured windowsHide would not change functional behavior,
+  // so the real assertion is in D10 below via source inspection).
+
+  it("spawn returns a ChildProcess object", async () => {
+    const child = spawn(process.execPath, ["--version"]);
+    expect(child.pid).toBeGreaterThan(0);
+    await new Promise<void>((resolve) => {
+      child.on("exit", () => resolve());
+    });
+  });
+
+  // ── exec (callback form) ────────────────────────────────────────────────
+
+  it("exec(cmd, cb) invokes callback with stdout", async () => {
+    const out = await new Promise<string>((resolve, reject) => {
+      exec(`"${process.execPath}" --version`, (err, stdout) => {
+        if (err) reject(err);
+        else resolve(String(stdout));
+      });
+    });
+    expect(out.trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+
+  // ── execFile ────────────────────────────────────────────────────────────
+
+  it("execFile(file, args, cb) works", async () => {
+    const out = await new Promise<string>((resolve, reject) => {
+      execFile(process.execPath, ["--version"], (err, stdout) => {
+        if (err) reject(err);
+        else resolve(String(stdout));
+      });
+    });
+    expect(out.trim()).toMatch(/^v\d+\.\d+\.\d+/);
+  });
+});
+
+describe("platform/exec — windowsHide default (source-level assertion)", () => {
+  // Since Node doesn't expose the spawn options after the call, we verify
+  // the windowsHide default by reading the wrapper source and asserting
+  // that every public export merges `windowsHide: true` into its options.
+  //
+  // This catches refactors that accidentally drop the default.
+
+  it("exec.ts source sets windowsHide: true by default", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const url = await import("node:url");
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const src = await fs.readFile(path.resolve(here, "../platform/exec.ts"), "utf-8");
+
+    // Must define a withHide helper and apply it uniformly.
+    expect(src).toMatch(/windowsHide\??:\s*boolean/);
+    expect(src).toMatch(/windowsHide:\s*hide/);
+    // Default must be true (not false) when caller omits it.
+    expect(src).toMatch(/opts\?\.windowsHide\s*\?\?\s*true/);
+  });
+});