@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/__tests__/auto-attach.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { WebSocket } from "ws";
+import { createServer, type DashboardServer } from "../server.js";
+
+/**
+ * Helper: connect a pi session via WebSocket and register it.
+ */
+async function connectSession(piPort: number, sessionId: string): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://localhost:${piPort}`);
+  await new Promise<void>((resolve) => {
+    ws.on("open", () => {
+      ws.send(JSON.stringify({
+        type: "session_register",
+        sessionId,
+        cwd: "/tmp",
+        source: "cli",
+      }));
+      setTimeout(resolve, 50);
+    });
+  });
+  return ws;
+}
+
+/**
+ * Helper: send a tool_execution_start event that triggers OpenSpec detection.
+ * Uses a Read tool on a SKILL.md path to trigger phase detection,
+ * or a Read/Write on an openspec/changes/ path for changeName detection.
+ */
+function sendToolEvent(ws: WebSocket, sessionId: string, opts: { phase?: string; changeName?: string }) {
+  if (opts.phase) {
+    // Map phase back to skill name suffix for detection
+    const phaseToSuffix: Record<string, string> = {
+      apply: "apply-change",
+      archive: "archive-change",
+      continue: "continue-change",
+      explore: "explore",
+      ff: "ff-change",
+      new: "new-change",
+      verify: "verify-change",
+    };
+    const suffix = phaseToSuffix[opts.phase] ?? opts.phase;
+    ws.send(JSON.stringify({
+      type: "event_forward",
+      sessionId,
+      event: {
+        eventType: "tool_execution_start",
+        timestamp: Date.now(),
+        data: {
+          toolName: "Read",
+          args: { path: `.pi/skills/openspec-${suffix}/SKILL.md` },
+        },
+      },
+    }));
+  }
+  if (opts.changeName) {
+    ws.send(JSON.stringify({
+      type: "event_forward",
+      sessionId,
+      event: {
+        eventType: "tool_execution_start",
+        timestamp: Date.now(),
+        data: {
+          toolName: "Read",
+          args: { path: `openspec/changes/${opts.changeName}/proposal.md` },
+        },
+      },
+    }));
+  }
+}
+
+/**
+ * Helper: send a detach_proposal via browser gateway.
+ */
+async function sendDetach(browserPort: number, sessionId: string): Promise<void> {
+  const ws = new WebSocket(`ws://localhost:${browserPort}/ws`);
+  await new Promise<void>((resolve) => {
+    ws.on("open", () => {
+      ws.send(JSON.stringify({
+        type: "detach_proposal",
+        sessionId,
+      }));
+      setTimeout(resolve, 50);
+    });
+  });
+  ws.close();
+}
+
+describe("Auto-attach from openspec activity", () => {
+  let server: DashboardServer;
+  let piPort: number;
+  let browserPort: number;
+  let ws: WebSocket;
+
+  let testPort = 18800;
+
+  beforeEach(async () => {
+    testPort += 2;
+    browserPort = testPort;
+    piPort = testPort + 1;
+    server = await createServer({
+      port: browserPort,
+      piPort,
+      dev: true,
+      autoShutdown: false,
+      shutdownIdleSeconds: 999,
+      tunnel: false,
+    editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+    });
+    await server.start();
+    ws = await connectSession(piPort, "s1");
+  });
+
+  afterEach(async () => {
+    ws.close();
+    await server.stop();
+  });
+
+  it("auto-attaches when phase and changeName arrive in separate events", async () => {
+    // Send phase only (via skill file read)
+    sendToolEvent(ws, "s1", { phase: "apply" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    let session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBeFalsy();
+
+    // Send changeName only (via change file read)
+    sendToolEvent(ws, "s1", { changeName: "add-auth" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("add-auth");
+  });
+
+  it("auto-attaches when only changeName is detected (no phase)", async () => {
+    // Only send changeName — no phase event at all
+    // This happens when a skill is loaded via prompt template (no SKILL.md read tool event)
+    sendToolEvent(ws, "s1", { changeName: "my-feature" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    const session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("my-feature");
+  });
+
+  it("auto-attaches when both arrive from a single tool event", async () => {
+    // A single tool event can only detect one thing at a time (phase OR changeName),
+    // so we send two events in quick succession
+    sendToolEvent(ws, "s1", { phase: "apply" });
+    sendToolEvent(ws, "s1", { changeName: "add-auth" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    const session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("add-auth");
+  });
+
+  it("auto-names session from changeName when name is blank", async () => {
+    sendToolEvent(ws, "s1", { changeName: "cool-feature" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    const session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("cool-feature");
+    expect(session?.name).toBe("cool-feature");
+  });
+
+  it("does not auto-attach when proposal is already attached", async () => {
+    // First, attach
+    sendToolEvent(ws, "s1", { phase: "apply" });
+    sendToolEvent(ws, "s1", { changeName: "add-auth" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    // Try to attach a different change
+    sendToolEvent(ws, "s1", { changeName: "other-change" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    const session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("add-auth");
+  });
+});
+
+describe("Detach clears openspec state", () => {
+  let server: DashboardServer;
+  let piPort: number;
+  let browserPort: number;
+  let ws: WebSocket;
+
+  let testPort = 18900;
+
+  beforeEach(async () => {
+    testPort += 2;
+    browserPort = testPort;
+    piPort = testPort + 1;
+    server = await createServer({
+      port: browserPort,
+      piPort,
+      dev: true,
+      autoShutdown: false,
+      shutdownIdleSeconds: 999,
+      tunnel: false,
+    editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+    });
+    await server.start();
+    ws = await connectSession(piPort, "s1");
+  });
+
+  afterEach(async () => {
+    ws.close();
+    await server.stop();
+  });
+
+  it("clears openspecPhase and openspecChange on detach", async () => {
+    // Attach first
+    sendToolEvent(ws, "s1", { phase: "apply" });
+    sendToolEvent(ws, "s1", { changeName: "add-auth" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    let session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("add-auth");
+
+    // Detach via browser
+    await sendDetach(browserPort, "s1");
+    await new Promise((r) => setTimeout(r, 80));
+
+    session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBeNull();
+    expect(session?.openspecPhase).toBeNull();
+    expect(session?.openspecChange).toBeNull();
+  });
+
+  it("allows re-attach after detach with new activity", async () => {
+    // Attach
+    sendToolEvent(ws, "s1", { phase: "apply" });
+    sendToolEvent(ws, "s1", { changeName: "add-auth" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    // Detach
+    await sendDetach(browserPort, "s1");
+    await new Promise((r) => setTimeout(r, 80));
+
+    // New activity
+    sendToolEvent(ws, "s1", { phase: "ff" });
+    sendToolEvent(ws, "s1", { changeName: "new-change" });
+    await new Promise((r) => setTimeout(r, 80));
+
+    const session = server.sessionManager.get("s1");
+    expect(session?.attachedProposal).toBe("new-change");
+  });
+});

package/packages/server/src/__tests__/auto-resume.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createPendingResumeRegistry } from "../pending-resume-registry.js";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+/**
+ * Tests for the auto-resume-on-prompt flow.
+ * These test the registry + orchestration logic without full server setup.
+ */
+
+function createMockSession(overrides: Partial<DashboardSession> = {}): DashboardSession {
+  return {
+    id: "session-1",
+    cwd: "/project",
+    source: "tui",
+    status: "ended",
+    startedAt: Date.now(),
+    sessionFile: "/path/to/session.jsonl",
+    ...overrides,
+  };
+}
+
+describe("Auto-resume on prompt", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("send_prompt to ended session triggers resume flow", () => {
+    it("records pending resume with prompt data", () => {
+      const registry = createPendingResumeRegistry();
+      const session = createMockSession();
+
+      registry.record(session.cwd, {
+        text: "fix the bug",
+        oldSessionId: session.id,
+        sessionFile: session.sessionFile!,
+      });
+
+      const entry = registry.consume(session.cwd);
+      expect(entry).toBeDefined();
+      expect(entry!.text).toBe("fix the bug");
+      expect(entry!.oldSessionId).toBe("session-1");
+      expect(entry!.sessionFile).toBe("/path/to/session.jsonl");
+    });
+
+    it("records pending resume with images", () => {
+      const registry = createPendingResumeRegistry();
+      const session = createMockSession();
+      const images = [{ type: "image" as const, data: "base64", mimeType: "image/png" }];
+
+      registry.record(session.cwd, {
+        text: "look at this",
+        images,
+        oldSessionId: session.id,
+        sessionFile: session.sessionFile!,
+      });
+
+      const entry = registry.consume(session.cwd);
+      expect(entry!.images).toEqual(images);
+    });
+
+    it("does not record when session has no sessionFile", () => {
+      const registry = createPendingResumeRegistry();
+      const session = createMockSession({ sessionFile: undefined });
+
+      // The browser-gateway checks sessionFile before calling record,
+      // so this tests the precondition
+      expect(session.sessionFile).toBeUndefined();
+    });
+  });
+
+  describe("session_register with pending resume flushes prompt", () => {
+    it("consumes entry for matching cwd and returns prompt data", () => {
+      const registry = createPendingResumeRegistry();
+
+      registry.record("/project", {
+        text: "fix the bug",
+        oldSessionId: "old-session",
+        sessionFile: "session.jsonl",
+      });
+
+      // Simulate new session registering with same cwd
+      const entry = registry.consume("/project");
+      expect(entry).toBeDefined();
+      expect(entry!.text).toBe("fix the bug");
+      expect(entry!.oldSessionId).toBe("old-session");
+
+      // Entry should be consumed (not available again)
+      expect(registry.consume("/project")).toBeUndefined();
+    });
+
+    it("returns undefined when no pending resume for cwd", () => {
+      const registry = createPendingResumeRegistry();
+      expect(registry.consume("/project")).toBeUndefined();
+    });
+  });
+
+  describe("spawn failure clears resuming state", () => {
+    it("consume clears entry so timeout does not fire", () => {
+      const onTimeout = vi.fn();
+      const registry = createPendingResumeRegistry({ onTimeout });
+
+      registry.record("/project", {
+        text: "fix it",
+        oldSessionId: "old-1",
+        sessionFile: "session.jsonl",
+      });
+
+      // Simulate spawn failure: consume immediately to clear
+      registry.consume("/project");
+
+      // Advance past expiry — onTimeout should NOT fire since entry was consumed
+      vi.advanceTimersByTime(31_000);
+      expect(onTimeout).not.toHaveBeenCalled();
+    });
+
+    it("timeout fires onTimeout with oldSessionId when not consumed", () => {
+      const onTimeout = vi.fn();
+      const registry = createPendingResumeRegistry({ onTimeout });
+
+      registry.record("/project", {
+        text: "fix it",
+        oldSessionId: "old-1",
+        sessionFile: "session.jsonl",
+      });
+
+      vi.advanceTimersByTime(30_001);
+      expect(onTimeout).toHaveBeenCalledWith("old-1");
+    });
+  });
+});

package/packages/server/src/__tests__/auto-shutdown.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createServer, type ServerConfig, type DashboardServer } from "../server.js";
+
+describe("Server auto-shutdown", () => {
+  let server: DashboardServer;
+  const baseConfig: ServerConfig = {
+    port: 0,
+    piPort: 0,
+    dev: true,
+    autoShutdown: true,
+    shutdownIdleSeconds: 2,
+    tunnel: false,
+    pingInterval: 0, // Disable WS ping to avoid fake/real timer conflicts
+    editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+  };
+
+  let testPort = 18700;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    testPort += 2;
+    server = await createServer({
+      ...baseConfig,
+      port: testPort,
+      piPort: testPort + 1,
+    });
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    try {
+      await server.stop();
+    } catch {
+      // may already be stopped
+    }
+  });
+
+  it("should shut down after idle timeout when no sessions connect", async () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    await server.start();
+
+    await vi.advanceTimersByTimeAsync(2000);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    exitSpy.mockRestore();
+  });
+
+  it("should not shut down when autoShutdown is false", async () => {
+    await server.stop();
+    testPort += 2;
+    server = await createServer({
+      ...baseConfig,
+      port: testPort,
+      piPort: testPort + 1,
+      autoShutdown: false,
+    });
+
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    await server.start();
+
+    await vi.advanceTimersByTimeAsync(5000);
+
+    expect(exitSpy).not.toHaveBeenCalled();
+    exitSpy.mockRestore();
+  });
+
+  it("should not shut down if session reconnects before idle timer fires", async () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    await server.start();
+
+    // Advance to just before idle timeout
+    await vi.advanceTimersByTimeAsync(1500);
+
+    // Connect a session — this cancels the idle timer and sets lastConnectionTimestamp
+    vi.useRealTimers();
+    const { WebSocket } = await import("ws");
+    const ws = new WebSocket(`ws://localhost:${testPort + 1}`);
+    await new Promise<void>((resolve) => {
+      ws.on("open", () => {
+        ws.send(JSON.stringify({
+          type: "session_register",
+          sessionId: "wake-sess",
+          cwd: "/tmp",
+          source: "cli",
+        }));
+        setTimeout(resolve, 50);
+      });
+    });
+
+    vi.useFakeTimers();
+
+    // Even if we advance way past the idle timeout, should NOT exit because session is connected
+    await vi.advanceTimersByTimeAsync(10000);
+    expect(exitSpy).not.toHaveBeenCalled();
+
+    vi.useRealTimers();
+    ws.close();
+    exitSpy.mockRestore();
+  }, 10000);
+
+  it("should cancel idle timer when a session connects", async () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    await server.start();
+
+    await vi.advanceTimersByTimeAsync(1000);
+
+    vi.useRealTimers();
+    const { WebSocket } = await import("ws");
+    const ws = new WebSocket(`ws://localhost:${testPort + 1}`);
+    await new Promise<void>((resolve) => {
+      ws.on("open", () => {
+        ws.send(JSON.stringify({
+          type: "session_register",
+          sessionId: "test-sess",
+          cwd: "/tmp",
+          source: "cli",
+        }));
+        setTimeout(resolve, 50);
+      });
+    });
+
+    vi.useFakeTimers();
+
+    await vi.advanceTimersByTimeAsync(5000);
+
+    expect(exitSpy).not.toHaveBeenCalled();
+
+    vi.useRealTimers();
+    ws.close();
+    exitSpy.mockRestore();
+  });
+});

package/packages/server/src/__tests__/browse-endpoint.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for the browse directory endpoint logic.
+ */
+import { describe, it, expect } from "vitest";
+import { listDirectories } from "../browse.js";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+
+describe("listDirectories", () => {
+  it("should return directory entries for a valid path", async () => {
+    // Use the project root — known to have subdirectories
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const result = await listDirectories(projectRoot);
+
+    expect(result.current).toBe(projectRoot);
+    expect(result.parent).toBe(path.dirname(projectRoot));
+    expect(result.entries.length).toBeGreaterThan(0);
+
+    // Should contain known subdirectories
+    const names = result.entries.map((e) => e.name);
+    expect(names).toContain("src");
+    expect(names).toContain("node_modules");
+  });
+
+  it("should default to home directory when no path given", async () => {
+    const result = await listDirectories();
+    expect(result.current).toBe(os.homedir());
+  });
+
+  it("should return entries sorted alphabetically", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const result = await listDirectories(projectRoot);
+    const names = result.entries.map((e) => e.name);
+    const sorted = [...names].sort((a, b) => a.localeCompare(b));
+    expect(names).toEqual(sorted);
+  });
+
+  it("should exclude hidden directories", async () => {
+    // Home dir typically has hidden dirs like .config, .cache
+    const result = await listDirectories(os.homedir());
+    const names = result.entries.map((e) => e.name);
+    const hidden = names.filter((n) => n.startsWith("."));
+    expect(hidden).toEqual([]);
+  });
+
+  it("should detect isGit flag for git repos", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const parentDir = path.dirname(projectRoot);
+    const result = await listDirectories(parentDir);
+
+    const projectEntry = result.entries.find(
+      (e) => e.name === path.basename(projectRoot)
+    );
+    expect(projectEntry).toBeDefined();
+    expect(projectEntry!.isGit).toBe(true);
+  });
+
+  it("should detect isPi flag for pi projects", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const parentDir = path.dirname(projectRoot);
+    const result = await listDirectories(parentDir);
+
+    const projectEntry = result.entries.find(
+      (e) => e.name === path.basename(projectRoot)
+    );
+    expect(projectEntry).toBeDefined();
+    expect(projectEntry!.isPi).toBe(true);
+  });
+
+  it("should return null parent for root directory", async () => {
+    const result = await listDirectories("/");
+    expect(result.parent).toBeNull();
+  });
+
+  it("should throw for non-existent directory", async () => {
+    await expect(
+      listDirectories("/nonexistent/path/that/does/not/exist")
+    ).rejects.toThrow();
+  });
+
+  it("should cap entries at 200", async () => {
+    // Can't easily create 200+ dirs, but test the logic path exists
+    const result = await listDirectories(os.homedir());
+    expect(result.entries.length).toBeLessThanOrEqual(200);
+  });
+
+  it("should only return directories, not files", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const result = await listDirectories(projectRoot);
+    const names = result.entries.map((e) => e.name);
+    // package.json is a file, should not appear
+    expect(names).not.toContain("package.json");
+    expect(names).not.toContain("tsconfig.json");
+  });
+
+  it("should include full path in each entry", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const result = await listDirectories(projectRoot);
+    for (const entry of result.entries) {
+      expect(entry.path).toBe(path.join(projectRoot, entry.name));
+    }
+  });
+});

package/packages/server/src/__tests__/bulk-archive-handler.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import type { OpenSpecBulkArchiveBrowserMessage, BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+
+describe("openspec_bulk_archive message type", () => {
+  it("is a valid BrowserToServerMessage", () => {
+    const msg: OpenSpecBulkArchiveBrowserMessage = {
+      type: "openspec_bulk_archive",
+      cwd: "/project/foo",
+    };
+    // Type-check: ensure it's assignable to the union
+    const _: BrowserToServerMessage = msg;
+    expect(msg.type).toBe("openspec_bulk_archive");
+    expect(msg.cwd).toBe("/project/foo");
+  });
+});