@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/__tests__/terminal-manager.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createTerminalManager, detectShell, type TerminalManager } from "../terminal-manager.js";
+
+// Mock node-pty
+const mockPtyWrite = vi.fn();
+const mockPtyResize = vi.fn();
+const mockPtyKill = vi.fn();
+let mockOnData: ((data: string) => void) | null = null;
+let mockOnExit: ((e: { exitCode: number; signal?: number }) => void) | null = null;
+
+vi.mock("node-pty", () => ({
+  spawn: vi.fn(() => ({
+    write: mockPtyWrite,
+    resize: mockPtyResize,
+    kill: mockPtyKill,
+    onData: (cb: (data: string) => void) => {
+      mockOnData = cb;
+      return { dispose: vi.fn() };
+    },
+    onExit: (cb: (e: { exitCode: number; signal?: number }) => void) => {
+      mockOnExit = cb;
+      return { dispose: vi.fn() };
+    },
+    pid: 12345,
+  })),
+}));
+
+describe("TerminalManager", () => {
+  let manager: TerminalManager;
+  let exitCallbacks: Array<(termId: string) => void>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockOnData = null;
+    mockOnExit = null;
+    exitCallbacks = [];
+    manager = createTerminalManager({
+      onExit: (termId) => exitCallbacks.forEach((cb) => cb(termId)),
+    });
+  });
+
+  afterEach(() => {
+    // Kill all terminals to clean up
+    for (const t of manager.list()) {
+      try { manager.kill(t.id); } catch {}
+    }
+  });
+
+  describe("spawn", () => {
+    it("creates a terminal with term- prefix ID", () => {
+      const session = manager.spawn("/tmp");
+      expect(session.id).toMatch(/^term-/);
+      expect(session.cwd).toBe("/tmp");
+      expect(session.status).toBe("active");
+      expect(session.shell).toBeDefined();
+    });
+
+    it("detects shell from env", () => {
+      const original = process.env.SHELL;
+      process.env.SHELL = "/bin/zsh";
+      const session = manager.spawn("/tmp");
+      expect(session.shell).toBe("/bin/zsh");
+      process.env.SHELL = original;
+    });
+
+    it("falls back to /bin/bash when SHELL not set", () => {
+      const original = process.env.SHELL;
+      delete process.env.SHELL;
+      const session = manager.spawn("/tmp");
+      expect(session.shell).toBe("/bin/bash");
+      process.env.SHELL = original;
+    });
+
+    it("spawns node-pty with correct args", async () => {
+      const pty = await import("node-pty");
+      manager.spawn("/home/user");
+      expect(pty.spawn).toHaveBeenCalledWith(
+        expect.any(String),
+        [],
+        expect.objectContaining({
+          cwd: "/home/user",
+          cols: 80,
+          rows: 24,
+        }),
+      );
+    });
+  });
+
+  describe("list and get", () => {
+    it("lists all active terminals", () => {
+      manager.spawn("/tmp/a");
+      manager.spawn("/tmp/b");
+      expect(manager.list()).toHaveLength(2);
+    });
+
+    it("gets a terminal by ID", () => {
+      const session = manager.spawn("/tmp");
+      expect(manager.get(session.id)).toEqual(session);
+    });
+
+    it("returns undefined for unknown ID", () => {
+      expect(manager.get("term-nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("updateTitle", () => {
+    it("updates the title", () => {
+      const session = manager.spawn("/tmp");
+      manager.updateTitle(session.id, "my title");
+      expect(manager.get(session.id)?.title).toBe("my title");
+    });
+  });
+
+  describe("kill", () => {
+    it("sends SIGHUP to PTY (bash on Linux ignores SIGTERM)", () => {
+      const session = manager.spawn("/tmp");
+      manager.kill(session.id);
+      expect(mockPtyKill).toHaveBeenCalledWith("SIGHUP");
+    });
+
+    it("throws for unknown ID", () => {
+      expect(() => manager.kill("term-unknown")).toThrow();
+    });
+  });
+
+  describe("attach", () => {
+    it("replays buffer contents on attach", () => {
+      const session = manager.spawn("/tmp");
+      // Simulate PTY output
+      mockOnData?.("hello world");
+
+      const mockWs = {
+        send: vi.fn(),
+        on: vi.fn(),
+        readyState: 1,
+        OPEN: 1,
+      } as any;
+
+      manager.attach(session.id, mockWs);
+
+      // First call should be the replay
+      expect(mockWs.send).toHaveBeenCalledWith(
+        expect.any(Buffer),
+      );
+      const sentData = mockWs.send.mock.calls[0][0];
+      expect(sentData.toString()).toBe("hello world");
+    });
+
+    it("routes binary frames to pty.write", () => {
+      const session = manager.spawn("/tmp");
+      const handlers: Record<string, Function> = {};
+
+      const mockWs = {
+        send: vi.fn(),
+        on: vi.fn((event: string, cb: any) => { handlers[event] = cb; }),
+        readyState: 1,
+        OPEN: 1,
+      } as any;
+
+      manager.attach(session.id, mockWs);
+
+      // Simulate binary input from browser
+      const input = Buffer.from("ls\n");
+      handlers.message(input, true);
+      expect(mockPtyWrite).toHaveBeenCalledWith(input.toString());
+    });
+
+    it("routes non-JSON text frames to pty.write (AttachAddon sends text)", () => {
+      const session = manager.spawn("/tmp");
+      const handlers: Record<string, Function> = {};
+
+      const mockWs = {
+        send: vi.fn(),
+        on: vi.fn((event: string, cb: any) => { handlers[event] = cb; }),
+        readyState: 1,
+        OPEN: 1,
+      } as any;
+
+      manager.attach(session.id, mockWs);
+
+      // AttachAddon sends keystrokes as text frames
+      const input = Buffer.from("ls\n");
+      handlers.message(input, false);
+      expect(mockPtyWrite).toHaveBeenCalledWith("ls\n");
+    });
+
+    it("handles resize control message", () => {
+      const session = manager.spawn("/tmp");
+      const handlers: Record<string, Function> = {};
+
+      const mockWs = {
+        send: vi.fn(),
+        on: vi.fn((event: string, cb: any) => { handlers[event] = cb; }),
+        readyState: 1,
+        OPEN: 1,
+      } as any;
+
+      manager.attach(session.id, mockWs);
+
+      // Simulate resize control message (text frame)
+      const resizeMsg = Buffer.from(JSON.stringify({ type: "resize", cols: 120, rows: 40 }));
+      handlers.message(resizeMsg, false);
+      expect(mockPtyResize).toHaveBeenCalledWith(120, 40);
+    });
+  });
+
+  describe("PTY exit", () => {
+    it("calls onExit callback and removes terminal", () => {
+      const cb = vi.fn();
+      exitCallbacks.push(cb);
+
+      const session = manager.spawn("/tmp");
+      // Simulate PTY exit
+      mockOnExit?.({ exitCode: 0 });
+
+      expect(cb).toHaveBeenCalledWith(session.id);
+      expect(manager.get(session.id)).toBeUndefined();
+    });
+  });
+});
+
+describe("detectShell", () => {
+  const origShell = process.env.SHELL;
+  const origComspec = process.env.COMSPEC;
+
+  afterEach(() => {
+    if (origShell !== undefined) process.env.SHELL = origShell;
+    else delete process.env.SHELL;
+    if (origComspec !== undefined) process.env.COMSPEC = origComspec;
+    else delete process.env.COMSPEC;
+  });
+
+  it("should use SHELL on macOS", () => {
+    process.env.SHELL = "/bin/zsh";
+    expect(detectShell("darwin")).toBe("/bin/zsh");
+  });
+
+  it("should use SHELL on Linux", () => {
+    process.env.SHELL = "/usr/bin/fish";
+    expect(detectShell("linux")).toBe("/usr/bin/fish");
+  });
+
+  it("should fall back to /bin/bash on Unix when SHELL unset", () => {
+    delete process.env.SHELL;
+    expect(detectShell("linux")).toBe("/bin/bash");
+  });
+
+  it("should use COMSPEC on Windows", () => {
+    process.env.COMSPEC = "C:\\Windows\\system32\\cmd.exe";
+    expect(detectShell("win32")).toBe("C:\\Windows\\system32\\cmd.exe");
+  });
+
+  it("should fall back to powershell.exe on Windows when COMSPEC unset", () => {
+    delete process.env.COMSPEC;
+    expect(detectShell("win32")).toBe("powershell.exe");
+  });
+});

package/packages/server/src/__tests__/trusted-networks-config.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+describe("trustedNetworks config", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-trusted-nets-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("should default to empty arrays when not configured", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+    const config = loadConfig();
+    expect(config.trustedNetworks).toEqual([]);
+    expect(config.resolvedTrustedNetworks).toEqual([]);
+  });
+
+  it("should parse trustedNetworks", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24", "10.0.0.*"],
+    }));
+    const config = loadConfig();
+    expect(config.trustedNetworks).toEqual(["192.168.1.0/24", "10.0.0.*"]);
+    expect(config.resolvedTrustedNetworks).toEqual(["192.168.1.0/24", "10.0.0.*"]);
+  });
+
+  it("should merge trustedNetworks with auth.bypassHosts", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: {
+        secret: "s",
+        providers: { github: { clientId: "a", clientSecret: "b" } },
+        bypassHosts: ["10.0.0.0/8"],
+      },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
+  it("should deduplicate entries", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: {
+        secret: "s",
+        providers: { github: { clientId: "a", clientSecret: "b" } },
+        bypassHosts: ["192.168.1.0/24"],
+      },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toEqual(["192.168.1.0/24"]);
+  });
+
+  it("should filter non-string entries", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24", 123, null, ""],
+    }));
+    const config = loadConfig();
+    expect(config.trustedNetworks).toEqual(["192.168.1.0/24"]);
+  });
+
+  it("should handle trustedNetworks without auth", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["10.0.0.0/8"],
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toEqual(["10.0.0.0/8"]);
+    expect(config.auth).toBeUndefined();
+  });
+});

package/packages/server/src/__tests__/tunnel.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    default: {
+      ...actual.default,
+      existsSync: vi.fn(),
+      readFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      mkdirSync: vi.fn(),
+      unlinkSync: vi.fn(),
+    },
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    mkdirSync: vi.fn(),
+    unlinkSync: vi.fn(),
+  };
+});
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return {
+    ...actual,
+    default: { ...actual.default, homedir: vi.fn(() => "/home/testuser") },
+    homedir: vi.fn(() => "/home/testuser"),
+  };
+});
+
+import {
+  loadZrokEnv,
+  detectZrokBinary,
+  writeZrokPid,
+  readZrokPid,
+  removeZrokPid,
+  cleanupStaleZrok,
+  getTunnelStatus,
+  _resetBinaryCache,
+  _setBinaryAvailable,
+} from "../tunnel.js";
+
+beforeEach(() => {
+  vi.mocked(os.homedir).mockReturnValue("/home/testuser");
+  _resetBinaryCache();
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+  _resetBinaryCache();
+});
+
+describe("loadZrokEnv", () => {
+  it("should return zrok env when enrolled", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        zrok_token: "tok_secret",
+        ziti_identity: "env-abc123",
+        api_endpoint: "https://api.zrok.io",
+      })
+    );
+
+    const env = loadZrokEnv();
+    expect(env).not.toBeNull();
+    expect(env!.apiEndpoint).toBe("https://api.zrok.io");
+    expect(env!.envZId).toBe("env-abc123");
+    expect(env!.token).toBe("tok_secret");
+  });
+
+  it("should return null when not enrolled", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(loadZrokEnv()).toBeNull();
+  });
+
+  it("should return null on malformed JSON", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue("not valid json{{{");
+    expect(loadZrokEnv()).toBeNull();
+  });
+
+  it("should return null when required fields are missing", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ ziti_identity: "test" })
+    );
+    expect(loadZrokEnv()).toBeNull();
+  });
+});
+
+describe("detectZrokBinary", () => {
+  it("should return true when set available", () => {
+    _setBinaryAvailable(true);
+    expect(detectZrokBinary()).toBe(true);
+  });
+
+  it("should return false when set unavailable", () => {
+    _setBinaryAvailable(false);
+    expect(detectZrokBinary()).toBe(false);
+  });
+
+  it("should cache the result across calls", () => {
+    _setBinaryAvailable(true);
+    expect(detectZrokBinary()).toBe(true);
+    // Value is cached — stays true
+    expect(detectZrokBinary()).toBe(true);
+  });
+});
+
+describe("PID file helpers", () => {
+  it("writeZrokPid should write PID to file", () => {
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+
+    writeZrokPid(12345);
+
+    expect(fs.mkdirSync).toHaveBeenCalled();
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      expect.stringContaining("zrok.pid"),
+      "12345\n"
+    );
+  });
+
+  it("readZrokPid should return PID from file", () => {
+    vi.mocked(fs.readFileSync).mockReturnValue("12345\n");
+    expect(readZrokPid()).toBe(12345);
+  });
+
+  it("readZrokPid should return null when file does not exist", () => {
+    vi.mocked(fs.readFileSync).mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("readZrokPid should return null for invalid content", () => {
+    vi.mocked(fs.readFileSync).mockReturnValue("not-a-number\n");
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("removeZrokPid should not throw if file does not exist", () => {
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+    expect(() => removeZrokPid()).not.toThrow();
+  });
+});
+
+describe("cleanupStaleZrok", () => {
+  it("should do nothing when no PID file exists", () => {
+    vi.mocked(fs.readFileSync).mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+    const killSpy = vi.spyOn(process, "kill");
+
+    cleanupStaleZrok();
+
+    expect(killSpy).not.toHaveBeenCalled();
+  });
+
+  it("should kill running stale process and remove PID file", () => {
+    vi.mocked(fs.readFileSync).mockReturnValue("99999\n");
+    const killSpy = vi.spyOn(process, "kill").mockReturnValue(true);
+    vi.mocked(fs.unlinkSync).mockReturnValue(undefined);
+
+    cleanupStaleZrok();
+
+    expect(killSpy).toHaveBeenCalledWith(99999, 0);
+    expect(killSpy).toHaveBeenCalledWith(99999, "SIGTERM");
+    expect(fs.unlinkSync).toHaveBeenCalled();
+  });
+
+  it("should just remove PID file if process is not running", () => {
+    vi.mocked(fs.readFileSync).mockReturnValue("99999\n");
+    const killSpy = vi.spyOn(process, "kill").mockImplementation((_pid: number, signal?: string | number) => {
+      if (signal === 0) throw new Error("ESRCH");
+      return true;
+    });
+    vi.mocked(fs.unlinkSync).mockReturnValue(undefined);
+
+    cleanupStaleZrok();
+
+    expect(killSpy).toHaveBeenCalledTimes(1);
+    expect(fs.unlinkSync).toHaveBeenCalled();
+  });
+});
+
+describe("getTunnelStatus", () => {
+  it("should return unavailable when binary not available", () => {
+    _setBinaryAvailable(false);
+
+    const status = getTunnelStatus();
+    expect(status.status).toBe("unavailable");
+    expect(status.serverOs).toBe(process.platform);
+  });
+
+  it("should return inactive when binary available but no tunnel", () => {
+    _setBinaryAvailable(true);
+
+    const status = getTunnelStatus();
+    expect(status.status).toBe("inactive");
+    expect(status.serverOs).toBe(process.platform);
+  });
+});

package/packages/server/src/__tests__/ws-ping-pong.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Tests for WS-level ping/pong dead connection detection in pi-gateway.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createPiGateway } from "../pi-gateway.js";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+import { WebSocket } from "ws";
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+function waitForOpen(ws: WebSocket): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (ws.readyState === WebSocket.OPEN) return resolve();
+    ws.on("open", resolve);
+    ws.on("error", reject);
+    setTimeout(() => reject(new Error("open timeout")), 3000);
+  });
+}
+
+// Short intervals for fast tests
+const SHORT_PING = 200; // 200ms ping interval
+const SHORT_HB = 5000; // long heartbeat so it doesn't interfere
+let portCounter = 19500;
+
+describe("WS ping/pong", () => {
+  let gateway: ReturnType<typeof createPiGateway>;
+
+  afterEach(() => {
+    gateway?.stop();
+  });
+
+  it("should keep session alive when client responds to pings", async () => {
+    const sessionManager = createMemorySessionManager();
+    gateway = createPiGateway(sessionManager, {
+      heartbeatTimeout: SHORT_HB,
+      pingInterval: SHORT_PING,
+    });
+    const port = portCounter++;
+    gateway.start(port);
+
+    // ws library auto-responds to pings with pong
+    const ws = new WebSocket(`ws://localhost:${port}`);
+    await waitForOpen(ws);
+    ws.send(JSON.stringify({
+      type: "session_register", sessionId: "ping-alive", cwd: "/tmp", source: "tui",
+    }));
+    await delay(100);
+
+    // Wait for several ping cycles — session should stay alive
+    await delay(SHORT_PING * 4);
+
+    expect(sessionManager.get("ping-alive")!.status).toBe("active");
+    ws.close();
+  }, 10000);
+
+  it("should terminate connection when client stops responding to pings", async () => {
+    const sessionManager = createMemorySessionManager();
+    gateway = createPiGateway(sessionManager, {
+      heartbeatTimeout: SHORT_HB,
+      pingInterval: SHORT_PING,
+    });
+    const port = portCounter++;
+    gateway.start(port);
+
+    const ws = new WebSocket(`ws://localhost:${port}`);
+    await waitForOpen(ws);
+    ws.send(JSON.stringify({
+      type: "session_register", sessionId: "ping-dead", cwd: "/tmp", source: "tui",
+    }));
+    await delay(100);
+    expect(sessionManager.get("ping-dead")!.status).toBe("active");
+
+    // Disable pong responses by removing the pong handler and overriding
+    // The ws library auto-responds at the protocol level, so we need to
+    // break the connection at a lower level — pause the socket
+    (ws as any)._socket?.pause();
+
+    // Wait for ping cycle to detect the dead connection
+    // First ping sets isAlive=false, second ping sees isAlive=false → terminate
+    await delay(SHORT_PING * 3);
+
+    expect(sessionManager.get("ping-dead")!.status).toBe("ended");
+  }, 10000);
+
+  it("should call onEmpty after ping timeout terminates last connection", async () => {
+    const sessionManager = createMemorySessionManager();
+    gateway = createPiGateway(sessionManager, {
+      heartbeatTimeout: SHORT_HB,
+      pingInterval: SHORT_PING,
+    });
+    const port = portCounter++;
+    gateway.start(port);
+
+    let emptyCalled = false;
+    gateway.onEmpty = () => { emptyCalled = true; };
+
+    const ws = new WebSocket(`ws://localhost:${port}`);
+    await waitForOpen(ws);
+    ws.send(JSON.stringify({
+      type: "session_register", sessionId: "ping-empty", cwd: "/tmp", source: "tui",
+    }));
+    await delay(100);
+
+    // Pause socket to prevent pong responses
+    (ws as any)._socket?.pause();
+
+    // Wait for ping timeout
+    await delay(SHORT_PING * 3);
+
+    expect(emptyCalled).toBe(true);
+  }, 10000);
+});