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

package/packages/shared/src/__tests__/detached-spawn.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Tests for platform/detached-spawn.ts primitives.
+ *
+ * Uses real `node -e` subprocess fixtures (no mocking) so we can exercise
+ * the actual Node spawn path with libuv's detached semantics on whatever
+ * OS the test runs on.
+ *
+ * All platform-dependent helpers take an explicit `platform` argument so
+ * tests can exercise both branches. We never mutate `process.platform`
+ * and never `vi.mock`.
+ */
+import { describe, it, expect } from "vitest";
+import { openSync, closeSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnDetached, waitForNoCrash, waitForReady } from "../platform/detached-spawn.js";
+
+function tmpLog(): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "dspawn-"));
+  return path.join(dir, "out.log");
+}
+
+describe("spawnDetached", () => {
+  it("spawns a real detached child with correct defaults", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 300)"],
+    });
+    expect(r.ok).toBe(true);
+    expect(r.pid).toBeTypeOf("number");
+    expect(r.process).toBeDefined();
+    // clean up
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("returns ok:false with error when cmd does not exist", async () => {
+    const r = await spawnDetached({
+      cmd: "/definitely/not/a/real/binary/nope.exe",
+      args: [],
+    });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBeTruthy();
+  });
+
+  it("redirects stderr to logFd when provided", async () => {
+    const logPath = tmpLog();
+    const fd = openSync(logPath, "a");
+    try {
+      const r = await spawnDetached({
+        cmd: process.execPath,
+        args: ["-e", "process.stderr.write('BOOM'); setTimeout(() => process.exit(0), 100)"],
+        logFd: fd,
+      });
+      expect(r.ok).toBe(true);
+      await new Promise((res) => r.process!.once("exit", res));
+    } finally {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+    const content = readFileSync(logPath, "utf-8");
+    expect(content).toContain("BOOM");
+    rmSync(path.dirname(logPath), { recursive: true, force: true });
+  });
+
+  it("does not keep parent event loop alive (unref)", async () => {
+    // Can only check behaviour indirectly: the returned pid/process exist
+    // and the child is running detached. Lifecycle survival is covered by
+    // Node's own libuv tests; we assert we didn't throw.
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  // ── detach option ────────────────────────────────────────────────────────
+  //
+  // Behaviour of `detach` can't be directly observed at the Node level
+  // (libuv's UV_PROCESS_DETACHED flag + setpgid/JobObject are internal).
+  // These tests verify the OPTION is accepted and does not break spawn;
+  // lifecycle semantics are exercised in the integration smoke tests
+  // (phase 2.10 manual Windows check).
+
+  it("accepts detach: true (default behaviour, unchanged)", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      detach: true,
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("accepts detach: false without breaking spawn", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      detach: false,
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("accepts detach: undefined (implicit default)", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      // detach is deliberately omitted
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+});
+
+describe("waitForNoCrash", () => {
+  it("returns ok:true when child outlives the window", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 1000)"],
+    });
+    expect(r.ok).toBe(true);
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 150 });
+    expect(gate.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("returns ok:false with exitCode when child exits early", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "process.exit(7)"],
+    });
+    expect(r.ok).toBe(true);
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 1000 });
+    expect(gate.ok).toBe(false);
+    expect(gate.exitCode).toBe(7);
+  });
+
+  it("respects a small windowMs and does not hang on live children", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 5000)"],
+    });
+    expect(r.ok).toBe(true);
+    const start = Date.now();
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 100 });
+    const elapsed = Date.now() - start;
+    expect(gate.ok).toBe(true);
+    expect(elapsed).toBeLessThan(500);
+    r.process!.kill();
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+});
+
+describe("waitForReady", () => {
+  it("returns ok:true when probe succeeds", async () => {
+    const r = await waitForReady({
+      probe: async () => true,
+      deadlineMs: 1000,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  it("returns ok:false with 'timeout' when probe never succeeds", async () => {
+    const r = await waitForReady({
+      probe: async () => false,
+      deadlineMs: 200,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("timeout");
+  });
+
+  it("short-circuits on child error event", async () => {
+    // Spawn a nonexistent path via spawnDetached — triggers error event.
+    const bad = await spawnDetached({
+      cmd: "/does/not/exist/XYZQQ",
+      args: [],
+    });
+    // bad.process may or may not exist depending on how Node surfaced the
+    // error. If it does, we can observe the short-circuit; if not, skip
+    // this specific assertion. Either way, waitForReady must not hang.
+    if (bad.process) {
+      const start = Date.now();
+      const r = await waitForReady({
+        probe: async () => false,
+        deadlineMs: 5000,
+        pollIntervalMs: 500,
+        child: bad.process,
+      });
+      const elapsed = Date.now() - start;
+      expect(r.ok).toBe(false);
+      expect(elapsed).toBeLessThan(5000);
+    }
+  });
+
+  it("waits indefinitely when deadlineMs is undefined (succeeds eventually)", async () => {
+    let calls = 0;
+    const start = Date.now();
+    const r = await waitForReady({
+      probe: async () => ++calls >= 5,
+      // deadlineMs intentionally omitted
+      pollIntervalMs: 30,
+    });
+    const elapsed = Date.now() - start;
+    expect(r.ok).toBe(true);
+    expect(calls).toBeGreaterThanOrEqual(5);
+    // ~5 polls at 30ms interval ≈ 120–180ms. Just ensure we're not
+    // short-circuiting suspiciously fast or hanging absurdly long.
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  it("waits indefinitely until child crashes (no deadline, child-exit wins)", async () => {
+    // Spawn a short-lived child that exits non-zero after ~200ms.
+    const bad = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(1), 200)"],
+    });
+    expect(bad.ok).toBe(true);
+    const start = Date.now();
+    const r = await waitForReady({
+      probe: async () => false, // never ready
+      // deadlineMs intentionally omitted — relies on child-exit
+      pollIntervalMs: 50,
+      child: bad.process!,
+    });
+    const elapsed = Date.now() - start;
+    expect(r.ok).toBe(false);
+    expect(r.error).toMatch(/child exited/);
+    expect(elapsed).toBeLessThan(2000); // short-circuited, not stuck
+  });
+
+  it("polls at pollIntervalMs until probe flips", async () => {
+    let calls = 0;
+    const r = await waitForReady({
+      probe: async () => ++calls >= 3,
+      deadlineMs: 2000,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(true);
+    expect(calls).toBeGreaterThanOrEqual(3);
+  });
+});

package/packages/shared/src/__tests__/managed-paths.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for `managed-paths.ts` getters.
+ *
+ * The constants (MANAGED_DIR, MANAGED_BIN, PI_SETTINGS_PATH) reflect
+ * the live environment at module-load time — those are covered by
+ * implicit use throughout the codebase. These tests pin the
+ * getter-with-override path used by the bootstrap harness and by
+ * future tests/proposals that need HOME injection.
+ */
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  MANAGED_BIN,
+  MANAGED_DIR,
+  PI_SETTINGS_PATH,
+  getManagedBin,
+  getManagedDir,
+  getPiSettingsPath,
+} from "../managed-paths.js";
+
+describe("managed-paths getters", () => {
+  it("getManagedDir() with no arg matches live MANAGED_DIR", () => {
+    expect(getManagedDir()).toBe(MANAGED_DIR);
+    expect(getManagedDir()).toBe(path.join(os.homedir(), ".pi-dashboard"));
+  });
+
+  it("getManagedBin() with no arg matches live MANAGED_BIN", () => {
+    expect(getManagedBin()).toBe(MANAGED_BIN);
+  });
+
+  it("getPiSettingsPath() with no arg matches live PI_SETTINGS_PATH", () => {
+    expect(getPiSettingsPath()).toBe(PI_SETTINGS_PATH);
+  });
+
+  it("getManagedDir({ homedir }) uses the override", () => {
+    expect(getManagedDir({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi-dashboard"),
+    );
+  });
+
+  it("getManagedBin({ homedir }) composes from override", () => {
+    expect(getManagedBin({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node_modules", ".bin"),
+    );
+  });
+
+  it("getPiSettingsPath({ homedir }) uses the override", () => {
+    expect(getPiSettingsPath({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi", "agent", "settings.json"),
+    );
+  });
+
+  it("override-less getManagedDir and live MANAGED_DIR constant are in sync", () => {
+    // Sanity: if someone accidentally drifts the constant from the
+    // getter default, this catches it.
+    expect(getManagedDir()).toEqual(MANAGED_DIR);
+    expect(getManagedBin()).toEqual(MANAGED_BIN);
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Repo-level invariant: `node:child_process` MUST NOT be imported directly
+ * outside `packages/shared/src/platform/exec.ts` (and, once added,
+ * `packages/shared/src/platform/runner.ts`). All subprocess execution goes
+ * through the safe wrappers so `windowsHide: true` and other defaults are
+ * uniform.
+ *
+ * If this test fails, migrate the offending file's import to:
+ *   import { ... } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/** Files allowed to import from node:child_process directly. */
+const ALLOWLIST: readonly string[] = [
+  "packages/shared/src/platform/exec.ts",
+  "packages/shared/src/platform/runner.ts",
+  // Platform primitives that legitimately own the raw child_process
+  // APIs (Windows detached-spawn + cross-platform subprocess adapter).
+  // See change: consolidate-windows-spawn-and-platform-handlers.
+  "packages/shared/src/platform/detached-spawn.ts",
+  "packages/shared/src/platform/subprocess-adapter.ts",
+];
+
+/**
+ * Regex catches any textual reference to the `node:child_process` module:
+ *   - import X from "node:child_process"
+ *   - import { X } from 'node:child_process'
+ *   - require("node:child_process")
+ *   - const X = await import("node:child_process")
+ *
+ * We intentionally match the `node:` prefix strictly — this codebase uses
+ * ESM node-protocol imports everywhere, and the bare `child_process`
+ * alias is already absent.
+ */
+const CHILD_PROCESS_IMPORT_RE = /(?:from\s+|require\s*\(\s*|import\s*\(\s*)["']node:child_process["']/;
+
+/**
+ * Per-line opt-out marker. Use for embedded scripts (e.g. `node -e` orchestrators
+ * or Electron renderer bootstrap strings) where the `require("node:child_process")`
+ * is source text that runs in a separate Node process, not an import by the
+ * host module. Add this comment on the same line as the allowed usage:
+ *   const { spawn } = require("node:child_process"); // ban:child_process-ok
+ */
+const OPT_OUT_MARKER = "ban:child_process-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()) {
+      // Skip nested node_modules, dist, and test directories
+      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 node:child_process imports outside platform/exec.ts", () => {
+  it("only allowlisted files import node:child_process", 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 allowSet = new Set(
+      ALLOWLIST.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; // package has no src/
+      }
+      for await (const file of walk(srcDir)) {
+        const normalized = file.replace(/\\/g, "/");
+        if (allowSet.has(normalized)) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!CHILD_PROCESS_IMPORT_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 node:child_process imports found outside the allowlist.\n` +
+        `Migrate each to:\n` +
+        `  import { ... } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map((v) => `  ${v.file}:${v.line}  ${v.text}`)
+          .join("\n");
+      // Use a plain expect to surface the full diff in the test output.
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

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([]);
+    }
+  });
+});