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

package/packages/server/src/__tests__/build-auth-status.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Tests for `_buildAuthStatus` — server-side pure derivation that merges
+ * the bridge-pushed catalogue, auth.json data, and the local OAuth handler set.
+ * See change: replace-hardcoded-provider-lists.
+ */
+import { describe, it, expect } from "vitest";
+import { _buildAuthStatus, type AuthData } from "../provider-auth-storage.js";
+import type { ProviderHandler } from "../provider-auth-handlers.js";
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+function makeOAuthHandler(providerId: string, displayName: string, flowType: "auth_code" | "device_code" = "auth_code"): ProviderHandler {
+  return {
+    flowType,
+    providerId,
+    displayName,
+    callbackPort: 0,
+    callbackPath: "/cb",
+    buildAuthUrl: () => "",
+    exchangeCode: async () => ({ type: "oauth", refresh: "", access: "", expires: 0 }),
+  } as ProviderHandler;
+}
+
+const ANTHROPIC_HANDLER = makeOAuthHandler("anthropic", "Anthropic (Claude Pro/Max)");
+
+describe("_buildAuthStatus", () => {
+  it("returns OAuth handler rows with authenticated:false when no catalogue or auth", () => {
+    const result = _buildAuthStatus([], {}, [ANTHROPIC_HANDLER]);
+    expect(result).toEqual([
+      {
+        id: "anthropic",
+        name: "Anthropic (Claude Pro/Max)",
+        flowType: "auth_code",
+        authenticated: false,
+      },
+    ]);
+  });
+
+  it("OAuth row authenticated:true with expires when auth.json has oauth credential", () => {
+    const auth: AuthData = {
+      anthropic: { type: "oauth", refresh: "r", access: "a", expires: 999 },
+    };
+    const result = _buildAuthStatus([], auth, [ANTHROPIC_HANDLER]);
+    expect(result[0]).toMatchObject({
+      id: "anthropic",
+      authenticated: true,
+      expires: 999,
+    });
+  });
+
+  it("emits both anthropic (OAuth) and anthropic-api (API key) rows when catalogue has anthropic", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [ANTHROPIC_HANDLER]);
+    expect(result).toHaveLength(2);
+    expect(result[0].id).toBe("anthropic");
+    expect(result[0].flowType).toBe("auth_code");
+    expect(result[1].id).toBe("anthropic-api");
+    expect(result[1].name).toBe("Anthropic (API Key)");
+    expect(result[1].flowType).toBe("api_key");
+  });
+
+  it("non-collision catalogue ids use bare id and bare display name", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0]).toEqual({
+      id: "deepseek",
+      name: "DeepSeek",
+      flowType: "api_key",
+      authenticated: false,
+    });
+  });
+
+  it("masks stored API key (>=12 chars) showing first 5 + ... + last 3", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: true },
+    ];
+    const auth: AuthData = { deepseek: { type: "api_key", key: "sk-abcdef123456789" } };
+    const result = _buildAuthStatus(catalogue, auth, []);
+    expect(result[0].authenticated).toBe(true);
+    expect(result[0].maskedKey).toBe("sk-ab...789");
+  });
+
+  it("masks short stored API key as ****", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "groq", displayName: "Groq", hasOAuth: false, configured: true },
+    ];
+    const auth: AuthData = { groq: { type: "api_key", key: "short" } };
+    const result = _buildAuthStatus(catalogue, auth, []);
+    expect(result[0].maskedKey).toBe("****");
+  });
+
+  it("ambient catalogue entry forces authenticated:true and maskedKey:'(ambient)' even with no auth.json entry", () => {
+    const catalogue: ProviderInfo[] = [
+      {
+        id: "google-vertex",
+        displayName: "Google Vertex AI",
+        hasOAuth: false,
+        configured: false,
+        ambient: true,
+      },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0]).toMatchObject({
+      id: "google-vertex",
+      authenticated: true,
+      ambient: true,
+      maskedKey: "(ambient)",
+    });
+  });
+
+  it("envVar from catalogue propagates to status row", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "openai", displayName: "OpenAI", hasOAuth: false, configured: false, envVar: "OPENAI_API_KEY" },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0].envVar).toBe("OPENAI_API_KEY");
+    expect(result[0].authenticated).toBe(false);
+  });
+
+  it("OAuth credential under anthropic does NOT mark anthropic-api authenticated", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: true },
+    ];
+    const auth: AuthData = {
+      anthropic: { type: "oauth", refresh: "r", access: "a", expires: 999 },
+    };
+    const result = _buildAuthStatus(catalogue, auth, [ANTHROPIC_HANDLER]);
+    const oauthRow = result.find((r) => r.id === "anthropic");
+    const apiRow = result.find((r) => r.id === "anthropic-api");
+    expect(oauthRow?.authenticated).toBe(true);
+    expect(apiRow?.authenticated).toBe(false);
+    expect(apiRow?.maskedKey).toBeUndefined();
+  });
+
+  it("api_key credential at auth.json[anthropic] marks anthropic-api authenticated", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: true },
+    ];
+    const auth: AuthData = {
+      anthropic: { type: "api_key", key: "sk-anthropic-key-1234" },
+    };
+    const result = _buildAuthStatus(catalogue, auth, [ANTHROPIC_HANDLER]);
+    const oauthRow = result.find((r) => r.id === "anthropic");
+    const apiRow = result.find((r) => r.id === "anthropic-api");
+    expect(oauthRow?.authenticated).toBe(false);
+    expect(apiRow?.authenticated).toBe(true);
+    expect(apiRow?.maskedKey).toBe("sk-an...234");
+  });
+
+  it("skips API-key rows for catalogue entries marked custom:true", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+      { id: "proxy", displayName: "proxy", hasOAuth: false, configured: false, custom: true },
+      { id: "your-llmproxy", displayName: "your-llmproxy", hasOAuth: false, configured: true, custom: true },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    const ids = result.map((r) => r.id);
+    expect(ids).toContain("deepseek");
+    expect(ids).not.toContain("proxy");
+    expect(ids).not.toContain("your-llmproxy");
+  });
+
+  it("OAuth row IS still emitted for a custom provider with an OAuth handler", () => {
+    // A custom provider whose id matches a registered OAuth handler
+    // should still surface its OAuth row — only the API-key row is
+    // suppressed for custom providers.
+    const corporateHandler = makeOAuthHandler("corporate-sso", "Corporate SSO");
+    const catalogue: ProviderInfo[] = [
+      { id: "corporate-sso", displayName: "Corporate SSO", hasOAuth: true, configured: false, custom: true },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [corporateHandler]);
+    const oauthRow = result.find((r) => r.id === "corporate-sso");
+    const apiKeyRow = result.find((r) => r.id === "corporate-sso-api");
+    expect(oauthRow).toBeDefined();
+    expect(oauthRow?.flowType).toBe("auth_code");
+    expect(apiKeyRow).toBeUndefined();
+  });
+
+  it("preserves OAuth handler order then catalogue order", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+      { id: "groq", displayName: "Groq", hasOAuth: false, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [ANTHROPIC_HANDLER]);
+    expect(result.map((r) => r.id)).toEqual(["anthropic", "deepseek", "groq"]);
+  });
+});

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__/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);
+  });
+});

package/packages/server/src/__tests__/event-wiring-providers-list.test.ts

@@ -0,0 +1,87 @@
+/**
+ * End-to-end test: `providers_list` arriving from a (fake) bridge updates
+ * the provider-catalogue cache, and `getAuthStatus()` reflects it.
+ * See change: replace-hardcoded-provider-lists.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { WebSocket } from "ws";
+import { createServer, type DashboardServer } from "../server.js";
+import { _resetForTests, getLatestCatalogue } from "../provider-catalogue-cache.js";
+import { getAuthStatus } from "../provider-auth-storage.js";
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+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",
+      }));
+      ws.send(JSON.stringify({ type: "replay_complete", sessionId }));
+      setTimeout(resolve, 60);
+    });
+  });
+  return ws;
+}
+
+describe("providers_list — server wiring", () => {
+  let server: DashboardServer;
+  let piPort: number;
+  let browserPort: number;
+  let testPort = 19500;
+
+  beforeEach(async () => {
+    _resetForTests();
+    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();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+    _resetForTests();
+  });
+
+  it("incoming providers_list updates the cache and is visible via getAuthStatus", async () => {
+    const piWs = await connectSession(piPort, "p1");
+    expect(getLatestCatalogue()).toEqual([]);
+
+    piWs.send(JSON.stringify({
+      type: "providers_list",
+      sessionId: "p1",
+      providers: [
+        { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+        { id: "fireworks", displayName: "Fireworks", hasOAuth: false, configured: false, envVar: "FIREWORKS_API_KEY" },
+      ],
+    }));
+
+    await wait(80);
+
+    const cached = getLatestCatalogue();
+    expect(cached).toHaveLength(2);
+    expect(cached.map((p) => p.id).sort()).toEqual(["deepseek", "fireworks"]);
+
+    const status = getAuthStatus();
+    const deepseekRow = status.find((r) => r.id === "deepseek");
+    const fireworksRow = status.find((r) => r.id === "fireworks");
+    expect(deepseekRow).toBeDefined();
+    expect(deepseekRow?.flowType).toBe("api_key");
+    expect(fireworksRow?.envVar).toBe("FIREWORKS_API_KEY");
+
+    piWs.close();
+  });
+});

package/packages/server/src/__tests__/has-openspec-dir.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for `hasOpenSpecDir` — synchronous spawn-free probe used by
+ * the WS on-connect snapshot to disambiguate "no openspec here" from
+ * "openspec here, polling pending".
+ *
+ * See change: fix-cold-boot-openspec-protocol.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { hasOpenSpecDir } from "../directory-service.js";
+
+describe("hasOpenSpecDir", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "has-openspec-dir-"));
+  });
+
+  afterEach(() => {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it("returns true when <cwd>/openspec/changes exists as a directory", () => {
+    fs.mkdirSync(path.join(tmp, "openspec", "changes"), { recursive: true });
+    expect(hasOpenSpecDir(tmp)).toBe(true);
+  });
+
+  it("returns false when openspec dir is absent (ENOENT)", () => {
+    expect(hasOpenSpecDir(tmp)).toBe(false);
+  });
+
+  it("returns false when openspec exists but openspec/changes does not", () => {
+    fs.mkdirSync(path.join(tmp, "openspec"));
+    expect(hasOpenSpecDir(tmp)).toBe(false);
+  });
+
+  it("returns false when openspec/changes is a regular file, not a directory", () => {
+    fs.mkdirSync(path.join(tmp, "openspec"));
+    fs.writeFileSync(path.join(tmp, "openspec", "changes"), "not a dir");
+    expect(hasOpenSpecDir(tmp)).toBe(false);
+  });
+
+  it("returns false when openspec/changes is a symlink to a non-directory", () => {
+    fs.mkdirSync(path.join(tmp, "openspec"));
+    const target = path.join(tmp, "target.txt");
+    fs.writeFileSync(target, "x");
+    fs.symlinkSync(target, path.join(tmp, "openspec", "changes"));
+    expect(hasOpenSpecDir(tmp)).toBe(false);
+  });
+
+  it("returns true when openspec/changes is a symlink to a directory", () => {
+    fs.mkdirSync(path.join(tmp, "openspec"));
+    const target = path.join(tmp, "target-dir");
+    fs.mkdirSync(target);
+    fs.symlinkSync(target, path.join(tmp, "openspec", "changes"));
+    expect(hasOpenSpecDir(tmp)).toBe(true);
+  });
+
+  it("returns false for a non-existent cwd", () => {
+    expect(hasOpenSpecDir("/this/path/does/not/exist/__nope__")).toBe(false);
+  });
+});

package/packages/server/src/__tests__/health-shape.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Tests for /api/health response shape after Phase A additions.
+ *
+ * Asserts:
+ *  - `pid` field is present (regression pin).
+ *  - `starter` field is present, defaults to "Standalone".
+ *
+ * Note: the "Standalone default for missing DASHBOARD_STARTER" case is
+ * also covered exhaustively in packages/shared/src/__tests__/dashboard-starter.test.ts.
+ * This test pins the contract at the HTTP layer so a refactor cannot silently
+ * drop either field from the health response.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createTestServer, type TestServerHandle } from "../test-support/test-server.js";
+
+let handle: TestServerHandle | undefined;
+
+describe("GET /api/health — Phase A shape", () => {
+  afterEach(async () => {
+    if (handle) {
+      try { await handle.stop(); } catch { /* already stopped */ }
+      handle = undefined;
+    }
+  });
+
+  it("includes pid field (regression pin)", async () => {
+    handle = await createTestServer();
+    const res = await fetch(`http://localhost:${handle.httpPort}/api/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(typeof body.pid).toBe("number");
+    expect(body.pid).toBe(process.pid);
+  });
+
+  it("includes starter field defaulting to Standalone", async () => {
+    handle = await createTestServer();
+    const res = await fetch(`http://localhost:${handle.httpPort}/api/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    // When bootstrapState has no starter set, defaults to "Standalone".
+    expect(body.starter).toBe("Standalone");
+  });
+});