@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/server/src/__tests__/changelog-remote.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for `changelog-remote.ts`.
+ *
+ * All tests use mocked fetch — never hit live raw.githubusercontent.com.
+ *
+ * See change: read-changelog-from-github.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  deriveChangelogRawUrl,
+  fetchRemoteChangelog,
+} from "../changelog-remote.js";
+
+describe("deriveChangelogRawUrl", () => {
+  it("derives raw URL from string repository", () => {
+    expect(deriveChangelogRawUrl("https://github.com/badlogic/pi-mono.git")).toBe(
+      "https://raw.githubusercontent.com/badlogic/pi-mono/main/CHANGELOG.md",
+    );
+  });
+
+  it("honours monorepo `directory` subfield", () => {
+    expect(
+      deriveChangelogRawUrl({
+        type: "git",
+        url: "git+https://github.com/badlogic/pi-mono.git",
+        directory: "packages/coding-agent",
+      }),
+    ).toBe(
+      "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/CHANGELOG.md",
+    );
+  });
+
+  it("strips leading/trailing slashes from directory", () => {
+    expect(
+      deriveChangelogRawUrl({
+        url: "https://github.com/org/repo.git",
+        directory: "/packages/foo/",
+      }),
+    ).toBe("https://raw.githubusercontent.com/org/repo/main/packages/foo/CHANGELOG.md");
+  });
+
+  it("supports github:org/repo shorthand", () => {
+    expect(deriveChangelogRawUrl("github:org/repo")).toBe(
+      "https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md",
+    );
+  });
+
+  it("supports ssh form git@github.com:org/repo.git", () => {
+    expect(deriveChangelogRawUrl("git@github.com:org/repo.git")).toBe(
+      "https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md",
+    );
+  });
+
+  it("returns null for non-GitHub repos", () => {
+    expect(deriveChangelogRawUrl("https://gitlab.com/org/repo.git")).toBeNull();
+    expect(deriveChangelogRawUrl({ url: "https://bitbucket.org/x/y" })).toBeNull();
+  });
+
+  it("returns null for missing/malformed input", () => {
+    expect(deriveChangelogRawUrl(undefined)).toBeNull();
+    expect(deriveChangelogRawUrl(null)).toBeNull();
+    expect(deriveChangelogRawUrl({})).toBeNull();
+    expect(deriveChangelogRawUrl({ url: "" })).toBeNull();
+    expect(deriveChangelogRawUrl(42)).toBeNull();
+  });
+});
+
+describe("fetchRemoteChangelog", () => {
+  let originalOffline: string | undefined;
+
+  beforeEach(() => {
+    originalOffline = process.env.PI_OFFLINE;
+    delete process.env.PI_OFFLINE;
+  });
+  afterEach(() => {
+    if (originalOffline !== undefined) process.env.PI_OFFLINE = originalOffline;
+    else delete process.env.PI_OFFLINE;
+    vi.restoreAllMocks();
+  });
+
+  it("returns ok with text + etag on 200", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers({ etag: '"abc123"' }),
+      text: async () => "# Changelog\n\n## [1.0.0] - 2026-01-01\n",
+    });
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl },
+    );
+    expect(out).toEqual({
+      status: "ok",
+      text: expect.stringContaining("[1.0.0]"),
+      etag: '"abc123"',
+    });
+  });
+
+  it("returns not-modified on 304", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 304,
+      headers: new Headers(),
+      text: async () => "",
+    });
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl, etag: '"abc123"' },
+    );
+    expect(out).toEqual({ status: "not-modified" });
+  });
+
+  it("sends If-None-Match when etag provided", async () => {
+    let captured: Record<string, string> | undefined;
+    const fetchImpl = vi.fn().mockImplementation((_url: string, init: any) => {
+      captured = init.headers as Record<string, string>;
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        headers: new Headers(),
+        text: async () => "ok",
+      });
+    });
+    await fetchRemoteChangelog("https://raw.githubusercontent.com/x/y/main/CHANGELOG.md", {
+      fetchImpl,
+      etag: '"abc123"',
+    });
+    expect(captured?.["If-None-Match"]).toBe('"abc123"');
+  });
+
+  it("returns null on non-2xx (excluding 304)", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      headers: new Headers(),
+      text: async () => "Not Found",
+    });
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl },
+    );
+    expect(out).toBeNull();
+  });
+
+  it("returns null on network error", async () => {
+    const fetchImpl = vi.fn().mockRejectedValue(new Error("ECONNRESET"));
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl },
+    );
+    expect(out).toBeNull();
+  });
+
+  it("returns null on empty text body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers(),
+      text: async () => "",
+    });
+    expect(
+      await fetchRemoteChangelog(
+        "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+        { fetchImpl },
+      ),
+    ).toBeNull();
+  });
+
+  it("skips fetch entirely when PI_OFFLINE is set", async () => {
+    process.env.PI_OFFLINE = "1";
+    const fetchImpl = vi.fn();
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl },
+    );
+    expect(out).toBeNull();
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("propagates etag null when response has no ETag header", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers(),
+      text: async () => "ok",
+    });
+    const out = await fetchRemoteChangelog(
+      "https://raw.githubusercontent.com/x/y/main/CHANGELOG.md",
+      { fetchImpl },
+    );
+    expect(out).toEqual({ status: "ok", text: "ok", etag: null });
+  });
+});

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

@@ -76,9 +76,27 @@ describe("parseArgs", () => {
 });
 
 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");
+  it("resolveJitiImport either returns a file:// URL or throws the documented error", async () => {
+    // After change `support-upstream-jiti-resolution`, the resolver
+    // also looks for upstream `jiti` (bare name). Vitest itself depends
+    // transitively on `jiti`, so when the test runner is the anchor,
+    // resolution may succeed. Either outcome is valid — we just assert
+    // the contract: success returns a `file://` URL, failure throws the
+    // documented error.
+    const { resolveJitiImport } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js"
+    );
+    let url: string | undefined;
+    let err: Error | undefined;
+    try {
+      url = resolveJitiImport();
+    } catch (e) {
+      err = e as Error;
+    }
+    if (url !== undefined) {
+      expect(url.startsWith("file://")).toBe(true);
+    } else {
+      expect(err?.message).toContain("Cannot find pi's TypeScript loader");
+    }
   });
 });

package/packages/server/src/__tests__/cold-boot-openspec-broadcast.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Cold-boot OpenSpec broadcast — bootstrap initial poll must broadcast
+ * `openspec_update` to connected browsers when the prior cache was
+ * empty/undefined or the polled data differs from prior.
+ *
+ * Mirrors `post-install-openspec-refresh.test.ts` contract for the
+ * bootstrap path. See change: fix-cold-boot-openspec-protocol.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { discoverAndBroadcastSessions } from "../session-bootstrap.js";
+
+interface SpyDirSvc {
+  knownDirectories: ReturnType<typeof vi.fn>;
+  discoverSessions: ReturnType<typeof vi.fn>;
+  getOpenSpecData: ReturnType<typeof vi.fn>;
+  refreshOpenSpec: ReturnType<typeof vi.fn>;
+  startPolling: ReturnType<typeof vi.fn>;
+}
+
+function stubPolling(): { startPolling: ReturnType<typeof vi.fn> } {
+  return { startPolling: vi.fn() };
+}
+interface SpySessionMgr {
+  get: ReturnType<typeof vi.fn>;
+  restore: ReturnType<typeof vi.fn>;
+}
+interface SpyGateway {
+  broadcastToAll: ReturnType<typeof vi.fn>;
+  broadcastSessionAdded: ReturnType<typeof vi.fn>;
+}
+
+function makeSessionMgr(): SpySessionMgr {
+  return { get: vi.fn(() => undefined), restore: vi.fn() };
+}
+function makeGateway(): SpyGateway {
+  return { broadcastToAll: vi.fn(), broadcastSessionAdded: vi.fn() };
+}
+
+/**
+ * `discoverAndBroadcastSessions` fires the openspec poll fire-and-forget
+ * (`void Promise.all(...)`). We need to await the microtask queue to let
+ * those promises resolve before asserting on broadcasts. A few
+ * `setImmediate` cycles is enough since the test mocks resolve synchronously.
+ */
+async function flush() {
+  await new Promise((resolve) => setImmediate(resolve));
+  await new Promise((resolve) => setImmediate(resolve));
+}
+
+describe("discoverAndBroadcastSessions: cold-boot openspec broadcast", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+  });
+
+  it("broadcasts openspec_update for each cwd whose prior cache was empty/undefined", async () => {
+    const cwds = ["/a", "/b"];
+    const fresh = { initialized: true, changes: [{ name: "c1" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn((cwd: string) =>
+        cwd === "/a" ? undefined : { initialized: false, changes: [] },
+      ),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(2);
+    expect(broadcasts).toContainEqual({ type: "openspec_update", cwd: "/a", data: fresh });
+    expect(broadcasts).toContainEqual({ type: "openspec_update", cwd: "/b", data: fresh });
+  });
+
+  it("does not broadcast openspec_update when refreshed data equals prior data (warm-restart idempotency)", async () => {
+    const same = { initialized: true, changes: [{ name: "stable" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/p"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => same),
+      refreshOpenSpec: vi.fn(async () => same),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(0);
+  });
+
+  it("broadcasts when prior is populated and fresh differs", async () => {
+    const prior = { initialized: true, changes: [{ name: "old" } as never] };
+    const fresh = { initialized: true, changes: [{ name: "new" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/p"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => prior),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({ type: "openspec_update", cwd: "/p", data: fresh });
+  });
+
+  it("does not block on refreshOpenSpec failure; logs error and skips broadcast for that cwd", async () => {
+    const fresh = { initialized: true, changes: [{ name: "ok" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/bad", "/good"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => undefined),
+      refreshOpenSpec: vi.fn(async (cwd: string) => {
+        if (cwd === "/bad") throw new Error("boom");
+        return fresh;
+      }),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({ type: "openspec_update", cwd: "/good", data: fresh });
+  });
+});

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

@@ -39,7 +39,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

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

@@ -47,7 +47,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

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

@@ -46,7 +46,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

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

@@ -42,7 +42,7 @@ vi.mock("../session-file-reader.js", () => ({
 }));
 
 // Mock the pi-coding-agent SessionManager (legacy, kept for compatibility)
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({

package/packages/server/src/__tests__/doctor-route.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Route tests for `GET /api/doctor`.
+ *
+ * Asserts:
+ *   - JSON shape contract (every check has `section`; non-ok has message+detail+suggestion)
+ *   - summary counts match
+ *   - fault-tolerance arm: a deps function that throws → 200 with fallback row
+ *   - no Electron-only rows (4.5)
+ *
+ * See change: doctor-rich-output (tasks 4.4–4.5).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import { registerDoctorRoutes } from "../routes/doctor-routes.js";
+import type {
+  DoctorReport,
+  SharedChecksDeps,
+} from "@blackbelt-technology/pi-dashboard-shared/doctor-core.js";
+
+const ELECTRON_ONLY_NAMES = new Set([
+  "Electron",
+  "Bundled Node.js",
+  "Bundled npm",
+  "Offline packages bundle",
+  "Dashboard server code",
+  "Server launch test",
+]);
+
+async function makeApp(buildDeps?: () => SharedChecksDeps): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  registerDoctorRoutes(app, buildDeps ? { buildDeps } : {});
+  await app.ready();
+  return app;
+}
+
+function fakeDeps(overrides: Partial<SharedChecksDeps> = {}): SharedChecksDeps {
+  return {
+    managedDir: "/tmp/doctor-route-test-managed",
+    detectSystemNode: () => ({ found: true, path: "/usr/bin/node" }),
+    detectPi: () => ({ found: true, path: "/usr/local/bin/pi", source: "system" }),
+    detectOpenSpec: () => ({ found: false }),
+    isApiKeyConfigured: () => true,
+    probeServer: async () => ({ running: true, version: "0.4.6", mode: "production" }),
+    ...overrides,
+  };
+}
+
+describe("/api/doctor", () => {
+  let app: FastifyInstance;
+  afterEach(async () => {
+    await app?.close();
+  });
+
+  it("returns 200 with a DoctorReport envelope", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as DoctorReport;
+    expect(Array.isArray(body.checks)).toBe(true);
+    expect(body.summary).toBeDefined();
+    expect(typeof body.generatedAt).toBe("number");
+  });
+
+  it("every check has a section", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    for (const c of body.checks) {
+      expect(c.section).toBeDefined();
+      expect(["runtime", "pi-tooling", "server", "setup", "diagnostics"]).toContain(c.section);
+    }
+  });
+
+  it("every non-ok row carries non-empty message + detail + suggestion (Decision 8 lint)", async () => {
+    app = await makeApp(() =>
+      fakeDeps({
+        detectPi: () => ({ found: false }),
+        detectOpenSpec: () => ({ found: false }),
+        probeServer: async () => ({ running: false }),
+      }),
+    );
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    const nonOk = body.checks.filter((c) => c.status !== "ok");
+    expect(nonOk.length).toBeGreaterThan(0);
+    for (const c of nonOk) {
+      expect(c.message.length).toBeGreaterThan(0);
+      expect((c.detail ?? "").length).toBeGreaterThan(0);
+      expect((c.suggestion ?? "").length).toBeGreaterThan(0);
+    }
+  });
+
+  it("summary counts match the rows", async () => {
+    app = await makeApp(() =>
+      fakeDeps({
+        detectPi: () => ({ found: false }),
+      }),
+    );
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    const ok = body.checks.filter((c) => c.status === "ok").length;
+    const warn = body.checks.filter((c) => c.status === "warning").length;
+    const err = body.checks.filter((c) => c.status === "error").length;
+    expect(body.summary.ok).toBe(ok);
+    expect(body.summary.warnings).toBe(warn);
+    expect(body.summary.errors).toBe(err);
+  });
+
+  it("never returns Electron-only rows (4.5)", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    for (const c of body.checks) {
+      expect(ELECTRON_ONLY_NAMES.has(c.name)).toBe(false);
+    }
+  });
+
+  it("returns 200 with a single fallback row when buildDeps throws", async () => {
+    app = await makeApp(() => {
+      throw new Error("boom — deps unavailable");
+    });
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    // Per task 4.3, the route returns 200 even on internal failure so the
+    // client always has something to render.
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as DoctorReport;
+    expect(body.checks.length).toBe(1);
+    expect(body.checks[0].status).toBe("error");
+    expect(body.checks[0].name).toMatch(/Doctor failed/i);
+    expect(body.summary.errors).toBe(1);
+  });
+});