@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/__tests__/cli-parse.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Tests for CLI argument parsing.
+ */
+import { describe, it, expect } from "vitest";
+import { parseArgs } from "../cli.js";
+
+describe("parseArgs", () => {
+  it("returns null subcommand with no args", () => {
+    const result = parseArgs([]);
+    expect(result.subcommand).toBeNull();
+    expect(result.flags).toEqual({});
+  });
+
+  it("parses start subcommand", () => {
+    const result = parseArgs(["start"]);
+    expect(result.subcommand).toBe("start");
+  });
+
+  it("parses stop subcommand", () => {
+    const result = parseArgs(["stop"]);
+    expect(result.subcommand).toBe("stop");
+  });
+
+  it("parses restart subcommand", () => {
+    const result = parseArgs(["restart"]);
+    expect(result.subcommand).toBe("restart");
+  });
+
+  it("parses status subcommand", () => {
+    const result = parseArgs(["status"]);
+    expect(result.subcommand).toBe("status");
+  });
+
+  it("parses subcommand with flags", () => {
+    const result = parseArgs(["start", "--port", "3000", "--pi-port", "4000"]);
+    expect(result.subcommand).toBe("start");
+    expect(result.flags.port).toBe(3000);
+    expect(result.flags.piPort).toBe(4000);
+  });
+
+  it("parses flags without subcommand (foreground mode)", () => {
+    const result = parseArgs(["--port", "3000", "--dev"]);
+    expect(result.subcommand).toBeNull();
+    expect(result.flags.port).toBe(3000);
+    expect(result.flags.dev).toBe(true);
+  });
+
+  it("parses --no-tunnel flag", () => {
+    const result = parseArgs(["start", "--no-tunnel"]);
+    expect(result.subcommand).toBe("start");
+    expect(result.flags.tunnel).toBe(false);
+  });
+
+  it("ignores unknown args", () => {
+    const result = parseArgs(["start", "--unknown", "value"]);
+    expect(result.subcommand).toBe("start");
+    expect(result.flags).toEqual({});
+  });
+
+  it("does not treat flag values as subcommands", () => {
+    const result = parseArgs(["--port", "3000"]);
+    expect(result.subcommand).toBeNull();
+    expect(result.flags.port).toBe(3000);
+  });
+});
+
+describe("daemon spawn jiti resolution", () => {
+  it("resolveJitiImport throws outside of pi context", async () => {
+    // In test context (no pi/jiti loader), peer deps aren't resolvable
+    const { resolveJitiImport } = await import("@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js");
+    expect(() => resolveJitiImport()).toThrow("Cannot find pi's TypeScript loader");
+  });
+});

package/packages/server/src/__tests__/client-discovery.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * Tests the client static file discovery order.
+ * Replicates the search logic from server.ts.
+ */
+function findClientDir(serverDir: string): string {
+  const searchPaths = [
+    path.join(serverDir, "../../node_modules/@blackbelt-technology/pi-dashboard-web/dist"),
+    path.join(serverDir, "../../client/dist"),
+    path.join(serverDir, "../../dist/client"),
+  ];
+  return searchPaths.find(p => existsSync(path.join(p, "index.html"))) ?? "";
+}
+
+describe("client static file discovery", () => {
+  it("returns empty string when no client build exists", () => {
+    // Use a path that definitely doesn't have client builds
+    expect(findClientDir("/tmp/nonexistent-server-dir")).toBe("");
+  });
+
+  it("searches npm package path first", () => {
+    // This is a structural test — verifies search order
+    const serverDir = "/fake/packages/server/src";
+    const searchPaths = [
+      path.join(serverDir, "../../node_modules/@blackbelt-technology/pi-dashboard-web/dist"),
+      path.join(serverDir, "../../client/dist"),
+      path.join(serverDir, "../../dist/client"),
+    ];
+    // npm package path should be first
+    expect(searchPaths[0]).toContain("pi-dashboard-web/dist");
+    // workspace sibling second
+    expect(searchPaths[1]).toContain("client/dist");
+    // legacy third
+    expect(searchPaths[2]).toContain("dist/client");
+  });
+});

package/packages/server/src/__tests__/config-api.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { readConfigRedacted, writeConfigPartial } from "../config-api.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+describe("config-api", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-config-api-${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;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  describe("readConfigRedacted", () => {
+    it("should redact auth.secret and provider clientSecrets", () => {
+      fs.writeFileSync(configFile, JSON.stringify({
+        port: 8000,
+        auth: {
+          secret: "real-secret",
+          providers: {
+            github: { clientId: "id1", clientSecret: "real-client-secret" },
+          },
+        },
+      }));
+      const config = readConfigRedacted();
+      expect(config.auth!.secret).toBe("***");
+      expect(config.auth!.providers.github.clientSecret).toBe("***");
+      expect(config.auth!.providers.github.clientId).toBe("id1");
+    });
+
+    it("should return config without auth when not configured", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ port: 3000 }));
+      const config = readConfigRedacted();
+      expect(config.auth).toBeUndefined();
+      expect(config.port).toBe(3000);
+    });
+  });
+
+  describe("writeConfigPartial", () => {
+    it("should merge partial config and write to disk", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ port: 8000, autoShutdown: true }));
+      const result = writeConfigPartial({ autoShutdown: false });
+      expect(result.success).toBe(true);
+      expect(result.restartRequired).toBe(false);
+      const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      expect(written.autoShutdown).toBe(false);
+      expect(written.port).toBe(8000); // preserved
+    });
+
+    it("should flag restartRequired when port changes", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+      const result = writeConfigPartial({ port: 9000 });
+      expect(result.success).toBe(true);
+      expect(result.restartRequired).toBe(true);
+    });
+
+    it("should flag restartRequired when piPort changes", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ piPort: 9999 }));
+      const result = writeConfigPartial({ piPort: 8888 });
+      expect(result.restartRequired).toBe(true);
+    });
+
+    it("should not flag restartRequired for non-port changes", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ port: 8000, autoShutdown: true }));
+      const result = writeConfigPartial({ autoShutdown: false, shutdownIdleSeconds: 60 });
+      expect(result.restartRequired).toBe(false);
+    });
+
+    it("should preserve redacted auth.secret", () => {
+      fs.writeFileSync(configFile, JSON.stringify({
+        auth: { secret: "real-secret", providers: { github: { clientId: "id", clientSecret: "real-cs" } } },
+      }));
+      const result = writeConfigPartial({
+        auth: { secret: "***", providers: { github: { clientId: "new-id", clientSecret: "***" } } },
+      });
+      expect(result.success).toBe(true);
+      const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      expect(written.auth.secret).toBe("real-secret");
+      expect(written.auth.providers.github.clientSecret).toBe("real-cs");
+      expect(written.auth.providers.github.clientId).toBe("new-id");
+    });
+
+    it("should update allowedUsers", () => {
+      fs.writeFileSync(configFile, JSON.stringify({ auth: { providers: { github: { clientId: "x", clientSecret: "y" } } } }));
+      const result = writeConfigPartial({ auth: { allowedUsers: ["octocat", "*@company.com"] } });
+      expect(result.success).toBe(true);
+      const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      expect(written.auth.allowedUsers).toEqual(["octocat", "*@company.com"]);
+      // providers preserved
+      expect(written.auth.providers.github.clientId).toBe("x");
+    });
+  });
+});

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

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+/**
+ * Unit tests for CORS origin validation logic.
+ * Tests the same logic used in server.ts CORS callback.
+ */
+
+function isAllowedOrigin(origin: string | undefined, configuredOrigins: string[]): boolean {
+  if (!origin) return true;
+  try {
+    const u = new URL(origin);
+    const host = u.hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1") {
+      return true;
+    }
+  } catch { /* ignore */ }
+  return configuredOrigins.includes(origin);
+}
+
+describe("CORS origin validation", () => {
+  it("allows requests with no origin (same-origin)", () => {
+    expect(isAllowedOrigin(undefined, [])).toBe(true);
+  });
+
+  it("allows localhost on any port", () => {
+    expect(isAllowedOrigin("http://localhost:3000", [])).toBe(true);
+    expect(isAllowedOrigin("http://localhost:5173", [])).toBe(true);
+    expect(isAllowedOrigin("https://localhost:8443", [])).toBe(true);
+  });
+
+  it("allows 127.0.0.1 on any port", () => {
+    expect(isAllowedOrigin("http://127.0.0.1:3000", [])).toBe(true);
+  });
+
+  it("allows configured origins", () => {
+    const configured = ["https://dashboard.example.com"];
+    expect(isAllowedOrigin("https://dashboard.example.com", configured)).toBe(true);
+  });
+
+  it("rejects unknown origins", () => {
+    expect(isAllowedOrigin("https://evil.example.com", [])).toBe(false);
+    expect(isAllowedOrigin("https://evil.example.com", ["https://good.example.com"])).toBe(false);
+  });
+
+  it("rejects non-localhost remote origins without config", () => {
+    expect(isAllowedOrigin("http://192.168.1.100:3000", [])).toBe(false);
+  });
+});

package/packages/server/src/__tests__/directory-service.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Tests for DirectoryService - server-side directory-scoped operations.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createDirectoryService, type DirectoryService } from "../directory-service.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+// Mock the shared openspec poller
+vi.mock("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js", () => ({
+  pollOpenSpecAsync: vi.fn(async () => ({ initialized: false, changes: [] })),
+}));
+
+// Mock the shared state replay
+vi.mock("@blackbelt-technology/pi-dashboard-shared/state-replay.js", () => ({
+  replayEntriesAsEvents: vi.fn(() => []),
+}));
+
+// Mock session-discovery
+vi.mock("../session-discovery.js", () => ({
+  discoverSessionsForCwd: vi.fn(() => []),
+}));
+
+// Mock session-file-reader
+vi.mock("../session-file-reader.js", () => ({
+  loadSessionEntries: vi.fn(() => []),
+}));
+
+// Mock the pi-coding-agent SessionManager (legacy, kept for compatibility)
+vi.mock("@mariozechner/pi-coding-agent", () => ({
+  SessionManager: {
+    list: vi.fn(async () => []),
+    open: vi.fn(() => ({
+      getBranch: vi.fn(() => []),
+    })),
+  },
+}));
+
+function createMockPreferencesStore(pinnedDirs: string[] = []): PreferencesStore {
+  return {
+    getPinnedDirectories: () => pinnedDirs,
+    getSessionOrder: () => ({}),
+    setSessionOrder: vi.fn(),
+    setPinnedDirectories: vi.fn(),
+    pinDirectory: vi.fn(),
+    unpinDirectory: vi.fn(),
+    reorderPinnedDirs: vi.fn(),
+    flush: vi.fn(),
+    dispose: vi.fn(),
+  };
+}
+
+function createMockSessionManager(sessions: DashboardSession[] = []): SessionManager {
+  const map = new Map<string, DashboardSession>();
+  for (const s of sessions) map.set(s.id, s);
+  return {
+    register: vi.fn((params) => {
+      const session = { ...params, status: "active", startedAt: Date.now() } as DashboardSession;
+      map.set(params.id, session);
+      return session;
+    }),
+    restore: vi.fn(),
+    unregister: vi.fn((id) => {
+      const s = map.get(id);
+      if (s) { s.status = "ended"; s.endedAt = Date.now(); }
+    }),
+    update: vi.fn(),
+    get: (id) => map.get(id),
+    listActive: () => Array.from(map.values()).filter((s) => s.status !== "ended"),
+    listAll: () => Array.from(map.values()),
+  };
+}
+
+describe("DirectoryService", () => {
+  let service: DirectoryService;
+
+  afterEach(() => {
+    service?.stopPolling();
+  });
+
+  describe("knownDirectories", () => {
+    it("returns union of pinned dirs and session cwds", () => {
+      const stateStore = createMockPreferencesStore(["/pinned/a", "/pinned/b"]);
+      const sessionManager = createMockSessionManager([
+        { id: "s1", cwd: "/pinned/a", source: "tui", status: "active", startedAt: 1 } as DashboardSession,
+        { id: "s2", cwd: "/project/c", source: "tui", status: "active", startedAt: 2 } as DashboardSession,
+      ]);
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const dirs = service.knownDirectories();
+      expect(dirs).toContain("/pinned/a");
+      expect(dirs).toContain("/pinned/b");
+      expect(dirs).toContain("/project/c");
+      expect(dirs.length).toBe(3);
+    });
+
+    it("deduplicates directories", () => {
+      const stateStore = createMockPreferencesStore(["/same/dir"]);
+      const sessionManager = createMockSessionManager([
+        { id: "s1", cwd: "/same/dir", source: "tui", status: "active", startedAt: 1 } as DashboardSession,
+      ]);
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const dirs = service.knownDirectories();
+      expect(dirs.filter((d) => d === "/same/dir").length).toBe(1);
+    });
+  });
+
+  describe("discoverSessions", () => {
+    it("calls discoverSessionsForCwd and returns metadata", async () => {
+      const { discoverSessionsForCwd } = await import("../session-discovery.js");
+      (discoverSessionsForCwd as any).mockReturnValueOnce([
+        {
+          id: "hist-1",
+          cwd: "/project",
+          name: "old session",
+          startedAt: Date.now(),
+          modifiedAt: Date.now(),
+          firstMessage: "hello",
+          sessionFile: "/project/.pi/sessions/hist-1.jsonl",
+          sessionDir: "/project/.pi/sessions",
+        },
+      ]);
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const sessions = service.discoverSessions("/project");
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0].id).toBe("hist-1");
+      expect(sessions[0].cwd).toBe("/project");
+      expect(sessions[0].sessionFile).toBe("/project/.pi/sessions/hist-1.jsonl");
+    });
+
+    it("returns empty array when no sessions found", async () => {
+      const { discoverSessionsForCwd } = await import("../session-discovery.js");
+      (discoverSessionsForCwd as any).mockReturnValueOnce([]);
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const sessions = service.discoverSessions("/nonexistent");
+      expect(sessions).toEqual([]);
+    });
+  });
+
+  describe("loadSessionEvents", () => {
+    it("loads and converts session entries", async () => {
+      const { loadSessionEntries } = await import("../session-file-reader.js");
+      const { replayEntriesAsEvents } = await import("@blackbelt-technology/pi-dashboard-shared/state-replay.js");
+      
+      const mockEntries = [{ type: "message", message: { role: "user", content: "hi" } }];
+      (loadSessionEntries as any).mockReturnValueOnce(mockEntries);
+      (replayEntriesAsEvents as any).mockReturnValueOnce([
+        { type: "event_forward", sessionId: "s1", event: { eventType: "message_start", timestamp: 1, data: {} } },
+      ]);
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const result = await service.loadSessionEvents("s1", "/path/to/session.jsonl");
+      expect(result.success).toBe(true);
+      expect(result.events).toHaveLength(1);
+      expect(loadSessionEntries).toHaveBeenCalledWith("/path/to/session.jsonl");
+    });
+
+    it("returns error on missing file", async () => {
+      const { loadSessionEntries } = await import("../session-file-reader.js");
+      (loadSessionEntries as any).mockImplementationOnce(() => { throw Object.assign(new Error("not found"), { code: "ENOENT" }); });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const result = await service.loadSessionEvents("s1", "/missing.jsonl");
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("file_not_found");
+    });
+  });
+
+  describe("getOpenSpecData / refreshOpenSpec", () => {
+    it("returns cached data after polling", async () => {
+      const { pollOpenSpecAsync } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (pollOpenSpecAsync as any).mockResolvedValue({ initialized: true, changes: [{ name: "change-1" }] });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const data = await service.refreshOpenSpec("/project");
+      expect(data.initialized).toBe(true);
+      expect(data.changes[0].name).toBe("change-1");
+
+      // getOpenSpecData returns cached value
+      const cached = service.getOpenSpecData("/project");
+      expect(cached).toEqual(data);
+    });
+  });
+
+  describe("onDirectoryAdded", () => {
+    it("discovers sessions and polls openspec immediately", async () => {
+      const { discoverSessionsForCwd } = await import("../session-discovery.js");
+      const { pollOpenSpecAsync } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      
+      (discoverSessionsForCwd as any).mockReturnValueOnce([]);
+      (pollOpenSpecAsync as any).mockResolvedValue({ initialized: false, changes: [] });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const result = await service.onDirectoryAdded("/new/dir");
+      expect(discoverSessionsForCwd).toHaveBeenCalledWith("/new/dir");
+      expect(result.sessions).toEqual([]);
+      expect(result.openspecData).toBeDefined();
+    });
+  });
+
+  describe("polling", () => {
+    it("startPolling and stopPolling control the timer", () => {
+      vi.useFakeTimers();
+      const stateStore = createMockPreferencesStore(["/project"]);
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const onChange = vi.fn();
+      service.startPolling(onChange);
+      
+      // Should not have fired yet
+      expect(onChange).not.toHaveBeenCalled();
+
+      service.stopPolling();
+      vi.useRealTimers();
+    });
+  });
+});

package/packages/server/src/__tests__/editor-detection.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { detectCodeServerBinary, resetDetectionCache } from "../editor-detection.js";
+import type { EditorConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+const DEFAULT_CONFIG: EditorConfig = { idleTimeoutMinutes: 10, maxInstances: 3 };
+
+describe("detectCodeServerBinary", () => {
+  beforeEach(() => {
+    resetDetectionCache();
+  });
+
+  it("returns config override when binary is set", () => {
+    const whichFn = vi.fn();
+    const result = detectCodeServerBinary({ ...DEFAULT_CONFIG, binary: "/opt/code-server" }, whichFn);
+    expect(result).toEqual({ available: true, binary: "/opt/code-server" });
+    expect(whichFn).not.toHaveBeenCalled();
+  });
+
+  it("detects code-server on PATH", () => {
+    const whichFn = vi.fn().mockReturnValueOnce("/usr/local/bin/code-server");
+    const result = detectCodeServerBinary(DEFAULT_CONFIG, whichFn);
+    expect(result).toEqual({ available: true, binary: "/usr/local/bin/code-server" });
+    expect(whichFn).toHaveBeenCalledWith("code-server");
+  });
+
+  it("falls back to openvscode-server", () => {
+    const whichFn = vi.fn()
+      .mockReturnValueOnce(null)
+      .mockReturnValueOnce("/usr/bin/openvscode-server");
+    const result = detectCodeServerBinary(DEFAULT_CONFIG, whichFn);
+    expect(result).toEqual({ available: true, binary: "/usr/bin/openvscode-server" });
+    expect(whichFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns not available when nothing found", () => {
+    const whichFn = vi.fn().mockReturnValue(null);
+    const result = detectCodeServerBinary(DEFAULT_CONFIG, whichFn);
+    expect(result).toEqual({ available: false });
+  });
+
+  it("caches result across calls", () => {
+    const whichFn = vi.fn().mockReturnValue("/usr/local/bin/code-server");
+    detectCodeServerBinary(DEFAULT_CONFIG, whichFn);
+    detectCodeServerBinary(DEFAULT_CONFIG, whichFn);
+    // Only called once due to caching
+    expect(whichFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-detects after cache reset", () => {
+    const whichFn1 = vi.fn().mockReturnValue("/usr/local/bin/code-server");
+    const first = detectCodeServerBinary(DEFAULT_CONFIG, whichFn1);
+    expect(first.available).toBe(true);
+
+    resetDetectionCache();
+
+    const whichFn2 = vi.fn().mockReturnValue(null);
+    const second = detectCodeServerBinary(DEFAULT_CONFIG, whichFn2);
+    expect(second).toEqual({ available: false });
+  });
+});

package/packages/server/src/__tests__/editor-endpoints.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from "vitest";
+import { isLoopback } from "../localhost-guard.js";
+
+// Unit tests for localhost guard
+describe("isLoopback", () => {
+  it("should accept 127.0.0.1", () => {
+    expect(isLoopback("127.0.0.1")).toBe(true);
+  });
+
+  it("should accept ::1", () => {
+    expect(isLoopback("::1")).toBe(true);
+  });
+
+  it("should accept ::ffff:127.0.0.1", () => {
+    expect(isLoopback("::ffff:127.0.0.1")).toBe(true);
+  });
+
+  it("should reject remote IPs", () => {
+    expect(isLoopback("192.168.1.1")).toBe(false);
+    expect(isLoopback("10.0.0.1")).toBe(false);
+  });
+});
+
+// Unit tests for detectEditors are in editor-registry.test.ts
+// Integration tests for the full endpoints would require spinning up the server,
+// which is covered by manual testing. Here we test the core logic units.

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

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createEditorManager, allocatePort } from "../editor-manager.js";
+import type { EditorConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import type { EditorDetectionResult } from "@blackbelt-technology/pi-dashboard-shared/editor-types.js";
+
+const DEFAULT_CONFIG: EditorConfig = { idleTimeoutMinutes: 10, maxInstances: 3 };
+const DETECTED: EditorDetectionResult = { available: true, binary: "/usr/local/bin/code-server" };
+const NOT_DETECTED: EditorDetectionResult = { available: false };
+
+describe("allocatePort", () => {
+  it("returns a positive port number", async () => {
+    const port = await allocatePort();
+    expect(port).toBeGreaterThan(0);
+    expect(port).toBeLessThan(65536);
+  });
+});
+
+describe("createEditorManager", () => {
+  it("creates a manager with empty instance list", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(mgr.list()).toEqual([]);
+  });
+
+  it("start throws when binary not found", async () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: NOT_DETECTED, allowRedetection: false });
+    await expect(mgr.start("/tmp/test")).rejects.toThrow("binary_not_found");
+  });
+
+  it("get returns undefined for unknown id", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(mgr.get("nonexistent")).toBeUndefined();
+  });
+
+  it("getByFolder returns undefined for unknown folder", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(mgr.getByFolder("/unknown")).toBeUndefined();
+  });
+
+  it("stop on unknown id does not throw", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(() => mgr.stop("nonexistent")).not.toThrow();
+  });
+
+  it("stopAll on empty manager does not throw", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(() => mgr.stopAll()).not.toThrow();
+  });
+
+  it("heartbeat on unknown id does not throw", () => {
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED });
+    expect(() => mgr.heartbeat("nonexistent")).not.toThrow();
+  });
+
+  it("enforces max instances when all would exceed cap", async () => {
+    const config: EditorConfig = { idleTimeoutMinutes: 10, maxInstances: 0 };
+    const mgr = createEditorManager({ config, detection: DETECTED });
+    // maxInstances=0 means no instances allowed, but eviction has nothing to evict
+    await expect(mgr.start("/tmp/test")).rejects.toThrow("max_instances_reached");
+  });
+
+  it("calls onStatusChange callback", async () => {
+    const statusChanges: Array<{ cwd: string; id: string; status: string }> = [];
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: NOT_DETECTED,
+      allowRedetection: false,
+      onStatusChange: (cwd, id, status) => statusChanges.push({ cwd, id, status }),
+    });
+    // binary_not_found throws before any status change
+    await expect(mgr.start("/tmp")).rejects.toThrow("binary_not_found");
+    expect(statusChanges).toEqual([]);
+  });
+});