@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/shared/src/__tests__/protocol.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from "vitest";
+import type {
+  ExtensionToServerMessage,
+  ServerToExtensionMessage,
+} from "../protocol.js";
+import type {
+  ServerToBrowserMessage,
+  BrowserToServerMessage,
+} from "../browser-protocol.js";
+import type {
+  DashboardSession,
+  DashboardEvent,
+  SessionSource,
+  SessionStatus,
+  CommandInfo,
+  ApiResponse,
+} from "../types.js";
+
+describe("Protocol message serialization round-trip", () => {
+  it("should serialize/deserialize extension→server messages", () => {
+    const messages: ExtensionToServerMessage[] = [
+      {
+        type: "session_register",
+        sessionId: "s1",
+        cwd: "/home/user/project",
+        source: "tui",
+        model: "claude-sonnet-4-20250514",
+        thinkingLevel: "medium",
+      },
+      {
+        type: "session_unregister",
+        sessionId: "s1",
+      },
+      {
+        type: "session_heartbeat",
+        sessionId: "s1",
+      },
+      {
+        type: "event_forward",
+        sessionId: "s1",
+        event: {
+          eventType: "message_update",
+          timestamp: Date.now(),
+          data: { text: "Hello" },
+        },
+      },
+      {
+        type: "commands_list",
+        sessionId: "s1",
+        commands: [
+          { name: "test", description: "Run tests", source: "extension" },
+        ],
+      },
+      {
+        type: "extension_ui_request",
+        sessionId: "s1",
+        requestId: "req-1",
+        method: "confirm",
+        params: { title: "Allow?", message: "Delete files?" },
+      },
+
+    ];
+
+    for (const msg of messages) {
+      const json = JSON.stringify(msg);
+      const parsed = JSON.parse(json) as ExtensionToServerMessage;
+      expect(parsed).toEqual(msg);
+      expect(parsed.type).toBe(msg.type);
+    }
+  });
+
+  it("should serialize/deserialize server→extension messages", () => {
+    const messages: ServerToExtensionMessage[] = [
+      {
+        type: "send_prompt",
+        sessionId: "s1",
+        text: "Hello agent",
+      },
+      {
+        type: "abort",
+        sessionId: "s1",
+      },
+      {
+        type: "request_commands",
+        sessionId: "s1",
+      },
+      {
+        type: "request_state_sync",
+        sessionId: "s1",
+      },
+      {
+        type: "extension_ui_response",
+        sessionId: "s1",
+        requestId: "req-1",
+        result: { confirmed: true },
+      },
+      {
+        type: "extension_ui_response",
+        sessionId: "s1",
+        requestId: "req-2",
+        cancelled: true,
+      },
+    ];
+
+    for (const msg of messages) {
+      const json = JSON.stringify(msg);
+      const parsed = JSON.parse(json) as ServerToExtensionMessage;
+      expect(parsed).toEqual(msg);
+      expect(parsed.type).toBe(msg.type);
+    }
+  });
+
+  it("should serialize/deserialize server→browser messages", () => {
+    const messages: ServerToBrowserMessage[] = [
+      {
+        type: "session_added",
+        session: {
+          id: "s1",
+          cwd: "/project",
+          source: "tui",
+          status: "active",
+          model: "claude-sonnet-4-20250514",
+          thinkingLevel: "medium",
+          startedAt: Date.now(),
+        },
+      },
+      {
+        type: "session_updated",
+        sessionId: "s1",
+        updates: { status: "streaming" },
+      },
+      {
+        type: "session_removed",
+        sessionId: "s1",
+      },
+      {
+        type: "event",
+        sessionId: "s1",
+        seq: 42,
+        event: {
+          eventType: "message_update",
+          timestamp: Date.now(),
+          data: { text: "hi" },
+        },
+      },
+      {
+        type: "event_replay",
+        sessionId: "s1",
+        events: [],
+        isLast: true,
+      },
+      {
+        type: "commands_list",
+        sessionId: "s1",
+        commands: [],
+      },
+      {
+        type: "extension_ui_request",
+        sessionId: "s1",
+        requestId: "req-2",
+        method: "notify",
+        params: { message: "done", level: "info" },
+      },
+    ];
+
+    for (const msg of messages) {
+      const json = JSON.stringify(msg);
+      const parsed = JSON.parse(json) as ServerToBrowserMessage;
+      expect(parsed).toEqual(msg);
+      expect(parsed.type).toBe(msg.type);
+    }
+  });
+
+  it("should serialize/deserialize browser→server messages", () => {
+    const messages: BrowserToServerMessage[] = [
+      {
+        type: "subscribe",
+        sessionId: "s1",
+        lastSeq: 0,
+      },
+      {
+        type: "unsubscribe",
+        sessionId: "s1",
+      },
+      {
+        type: "send_prompt",
+        sessionId: "s1",
+        text: "Hello",
+      },
+      {
+        type: "abort",
+        sessionId: "s1",
+      },
+      {
+        type: "request_commands",
+        sessionId: "s1",
+      },
+      {
+        type: "fetch_content",
+        sessionId: "s1",
+        seq: 42,
+      },
+      {
+        type: "extension_ui_response",
+        sessionId: "s1",
+        requestId: "req-1",
+        result: { value: "Option A" },
+      },
+    ];
+
+    for (const msg of messages) {
+      const json = JSON.stringify(msg);
+      const parsed = JSON.parse(json) as BrowserToServerMessage;
+      expect(parsed).toEqual(msg);
+      expect(parsed.type).toBe(msg.type);
+    }
+  });
+});
+
+describe("Shared data model types", () => {
+  it("should have correct SessionSource values", () => {
+    const sources: SessionSource[] = ["tui", "zed", "tmux", "dashboard", "unknown"];
+    expect(sources).toHaveLength(5);
+  });
+
+  it("should have correct SessionStatus values", () => {
+    const statuses: SessionStatus[] = ["active", "streaming", "ended"];
+    expect(statuses).toHaveLength(3);
+  });
+
+  it("should construct valid ApiResponse", () => {
+    const success: ApiResponse<{ id: string }> = {
+      success: true,
+      data: { id: "123" },
+    };
+    const error: ApiResponse = {
+      success: false,
+      error: "Not found",
+    };
+    expect(success.success).toBe(true);
+    expect(error.success).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/resolve-jiti.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+
+describe("resolveJitiImport", () => {
+  it("throws with clear error when pi-coding-agent is not resolvable", async () => {
+    // In test context (vitest, not inside pi's jiti loader),
+    // peer deps are not resolvable — should throw
+    const { resolveJitiImport } = await import("../resolve-jiti.js");
+
+    expect(() => resolveJitiImport()).toThrow("Cannot find pi's TypeScript loader");
+  });
+
+  it("error message mentions pi-coding-agent", async () => {
+    const { resolveJitiImport } = await import("../resolve-jiti.js");
+
+    expect(() => resolveJitiImport()).toThrow("pi-coding-agent");
+  });
+});

package/packages/shared/src/__tests__/server-identity.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { isDashboardRunning } from "../server-identity.js";
+
+describe("isDashboardRunning", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns running: true with pid when health endpoint responds correctly", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ ok: true, pid: 12345, uptime: 60 }),
+    });
+
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: true, pid: 12345 });
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "http://localhost:8000/api/health",
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+  });
+
+  it("returns portConflict when port returns non-ok HTTP status", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+    });
+
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: false, portConflict: true });
+  });
+
+  it("returns portConflict when response is HTTP 200 but not dashboard format", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ status: "ok", service: "nginx" }),
+    });
+
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: false, portConflict: true });
+  });
+
+  it("returns running: false when connection refused (nothing running)", async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: false });
+  });
+
+  it("returns running: false when request times out", async () => {
+    const abortError = new Error("aborted");
+    abortError.name = "AbortError";
+    globalThis.fetch = vi.fn().mockRejectedValue(abortError);
+
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: false });
+  });
+
+  it("uses custom host when provided", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ ok: true, pid: 999 }),
+    });
+
+    await isDashboardRunning(8000, "192.168.1.10");
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "http://192.168.1.10:8000/api/health",
+      expect.any(Object),
+    );
+  });
+});

package/packages/shared/src/__tests__/session-meta.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { metaPath, readSessionMeta, writeSessionMeta, mergeSessionMeta } from "../session-meta.js";
+
+describe("session-meta", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "session-meta-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("metaPath", () => {
+    it("should derive .meta.json from .jsonl path", () => {
+      const sessionFile = "/home/user/.pi/sessions/cwd/2026-01-01T00-00-00-000Z_abc123.jsonl";
+      expect(metaPath(sessionFile)).toBe(
+        "/home/user/.pi/sessions/cwd/2026-01-01T00-00-00-000Z_abc123.meta.json"
+      );
+    });
+  });
+
+  describe("writeSessionMeta / readSessionMeta", () => {
+    it("should write and read meta", () => {
+      const sessionFile = path.join(tmpDir, "test-session.jsonl");
+      writeSessionMeta(sessionFile, { source: "dashboard" });
+      const meta = readSessionMeta(sessionFile);
+      expect(meta).toEqual({ source: "dashboard" });
+    });
+
+    it("should return undefined for missing meta file", () => {
+      const sessionFile = path.join(tmpDir, "nonexistent.jsonl");
+      expect(readSessionMeta(sessionFile)).toBeUndefined();
+    });
+
+    it("should return undefined for invalid JSON", () => {
+      const sessionFile = path.join(tmpDir, "bad.jsonl");
+      fs.writeFileSync(path.join(tmpDir, "bad.meta.json"), "not json");
+      expect(readSessionMeta(sessionFile)).toBeUndefined();
+    });
+
+    it("should write and read expanded fields", () => {
+      const sessionFile = path.join(tmpDir, "expanded.jsonl");
+      writeSessionMeta(sessionFile, {
+        source: "dashboard",
+        name: "General",
+        attachedProposal: "my-change",
+        hidden: false,
+        cwd: "/Users/test/project",
+        status: "ended",
+        startedAt: 1000,
+        endedAt: 2000,
+        model: "anthropic/claude-sonnet-4-20250514",
+        thinkingLevel: "medium",
+        tokensIn: 100,
+        tokensOut: 200,
+        cacheRead: 300,
+        cacheWrite: 400,
+        cost: 1.5,
+        contextTokens: 5000,
+        contextWindow: 200000,
+        firstMessage: "Hello",
+        cachedAt: 3000,
+      });
+      const meta = readSessionMeta(sessionFile);
+      expect(meta?.name).toBe("General");
+      expect(meta?.cost).toBe(1.5);
+      expect(meta?.cachedAt).toBe(3000);
+      expect(meta?.hidden).toBe(false);
+    });
+
+    it("should read minimal meta (backward compat)", () => {
+      const sessionFile = path.join(tmpDir, "minimal.jsonl");
+      writeSessionMeta(sessionFile, { source: "dashboard" });
+      const meta = readSessionMeta(sessionFile);
+      expect(meta).toEqual({ source: "dashboard" });
+      expect(meta?.name).toBeUndefined();
+      expect(meta?.cost).toBeUndefined();
+    });
+
+    it("should use atomic write (tmp + rename)", () => {
+      const sessionFile = path.join(tmpDir, "atomic.jsonl");
+      writeSessionMeta(sessionFile, { source: "dashboard" });
+      // tmp file should not remain
+      const tmpFile = metaPath(sessionFile) + ".tmp";
+      expect(fs.existsSync(tmpFile)).toBe(false);
+      expect(fs.existsSync(metaPath(sessionFile))).toBe(true);
+    });
+  });
+
+  describe("mergeSessionMeta", () => {
+    it("should merge new fields into existing meta", () => {
+      const sessionFile = path.join(tmpDir, "merge.jsonl");
+      writeSessionMeta(sessionFile, { source: "dashboard", name: "Old" });
+      mergeSessionMeta(sessionFile, { name: "New", cost: 5.0 });
+      const meta = readSessionMeta(sessionFile);
+      expect(meta?.source).toBe("dashboard");
+      expect(meta?.name).toBe("New");
+      expect(meta?.cost).toBe(5.0);
+    });
+
+    it("should create file if it does not exist", () => {
+      const sessionFile = path.join(tmpDir, "new-merge.jsonl");
+      mergeSessionMeta(sessionFile, { hidden: true, cost: 1.0 });
+      const meta = readSessionMeta(sessionFile);
+      expect(meta?.hidden).toBe(true);
+      expect(meta?.cost).toBe(1.0);
+    });
+
+    it("should preserve unknown fields", () => {
+      const sessionFile = path.join(tmpDir, "unknown.jsonl");
+      // Write a file with an unknown field
+      const p = metaPath(sessionFile);
+      fs.writeFileSync(p, JSON.stringify({ source: "dashboard", customField: 42 }) + "\n");
+      mergeSessionMeta(sessionFile, { name: "Test" });
+      const raw = JSON.parse(fs.readFileSync(p, "utf-8"));
+      expect(raw.customField).toBe(42);
+      expect(raw.name).toBe("Test");
+    });
+  });
+});

package/packages/shared/src/archive-types.ts

@@ -0,0 +1,11 @@
+/**
+ * Type for OpenSpec archive entries. Shared between server and client.
+ */
+export interface ArchiveEntry {
+  /** Full directory name, e.g. "2026-03-27-openspec-artifact-reader" */
+  name: string;
+  /** Date extracted from the prefix, e.g. "2026-03-27" */
+  date: string;
+  /** Detected artifacts with status "done" */
+  artifacts: { id: string; status: "done" }[];
+}