@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.2

package/packages/server/src/__tests__/post-install-openspec-refresh.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Unit tests for the post-install OpenSpec + pi-resources force-refresh
+ * portion of `runPostInstallRepair`.
+ *
+ * See change: fix-openspec-buttons-after-bootstrap-install.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { runPostInstallRepair } from "../server.js";
+
+interface SpyRegistry { rescan: ReturnType<typeof vi.fn>; }
+interface SpyDirSvc {
+  knownDirectories: ReturnType<typeof vi.fn>;
+  getOpenSpecData: ReturnType<typeof vi.fn>;
+  refreshOpenSpec: ReturnType<typeof vi.fn>;
+  refreshPiResources: ReturnType<typeof vi.fn>;
+}
+interface SpyGateway { broadcastToAll: ReturnType<typeof vi.fn>; }
+
+function makeRegistry(): SpyRegistry { return { rescan: vi.fn() }; }
+function makeGateway(): SpyGateway { return { broadcastToAll: vi.fn() }; }
+
+describe("runPostInstallRepair: openspec + pi-resources refresh", () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  });
+
+  it("calls refreshOpenSpec(cwd) once for every known directory", async () => {
+    const registry = makeRegistry();
+    const cwds = ["/p1", "/p2", "/p3"];
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      getOpenSpecData: vi.fn(() => ({ initialized: false, changes: [] })),
+      refreshOpenSpec: vi.fn(async () => ({ initialized: true, changes: [{ name: "x" } as never] })),
+      refreshPiResources: vi.fn(async () => ({})),
+    };
+    const browserGateway = makeGateway();
+
+    await runPostInstallRepair({
+      registry: registry as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+
+    expect(directoryService.refreshOpenSpec).toHaveBeenCalledTimes(3);
+    expect(directoryService.refreshOpenSpec).toHaveBeenNthCalledWith(1, "/p1");
+    expect(directoryService.refreshOpenSpec).toHaveBeenNthCalledWith(2, "/p2");
+    expect(directoryService.refreshOpenSpec).toHaveBeenNthCalledWith(3, "/p3");
+  });
+
+  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),
+      // Prior was undefined for /a, empty for /b — both should broadcast.
+      getOpenSpecData: vi.fn((cwd: string) =>
+        cwd === "/a" ? undefined : { initialized: false, changes: [] }
+      ),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      refreshPiResources: vi.fn(async () => ({})),
+    };
+    const browserGateway = makeGateway();
+
+    await runPostInstallRepair({
+      registry: makeRegistry() as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+
+    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", async () => {
+    const same = { initialized: true, changes: [{ name: "stable" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/p"]),
+      getOpenSpecData: vi.fn(() => same),
+      refreshOpenSpec: vi.fn(async () => same),
+      refreshPiResources: vi.fn(async () => ({})),
+    };
+    const browserGateway = makeGateway();
+
+    await runPostInstallRepair({
+      registry: makeRegistry() as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(0);
+  });
+
+  it("isolates a per-cwd refresh failure — the other cwd still refreshes and broadcasts", async () => {
+    const cwds = ["/good", "/bad"];
+    const fresh = { initialized: true, changes: [{ name: "ok" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      getOpenSpecData: vi.fn(() => undefined),
+      refreshOpenSpec: vi.fn(async (cwd: string) => {
+        if (cwd === "/bad") throw new Error("boom");
+        return fresh;
+      }),
+      refreshPiResources: vi.fn(async () => ({})),
+    };
+    const browserGateway = makeGateway();
+
+    await runPostInstallRepair({
+      registry: makeRegistry() as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+
+    // Both cwds attempted.
+    expect(directoryService.refreshOpenSpec).toHaveBeenCalledTimes(2);
+    // Only the good one broadcasts.
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update" && m.cwd === "/good");
+    expect(broadcasts).toHaveLength(1);
+    // Failure was logged, not propagated.
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("calls refreshPiResources(cwd) once for every known directory", async () => {
+    const cwds = ["/a", "/b", "/c"];
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      getOpenSpecData: vi.fn(() => undefined),
+      refreshOpenSpec: vi.fn(async () => ({ initialized: false, changes: [] })),
+      refreshPiResources: vi.fn(async () => ({})),
+    };
+
+    await runPostInstallRepair({
+      registry: makeRegistry() as never,
+      directoryService: directoryService as never,
+      browserGateway: makeGateway() as never,
+    });
+
+    expect(directoryService.refreshPiResources).toHaveBeenCalledTimes(3);
+    expect(directoryService.refreshPiResources).toHaveBeenCalledWith("/a");
+    expect(directoryService.refreshPiResources).toHaveBeenCalledWith("/b");
+    expect(directoryService.refreshPiResources).toHaveBeenCalledWith("/c");
+  });
+
+  it("a refreshPiResources failure does not block other cwds or openspec broadcasts", async () => {
+    const cwds = ["/good", "/bad"];
+    const fresh = { initialized: true, changes: [{ name: "ok" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      getOpenSpecData: vi.fn(() => undefined),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      refreshPiResources: vi.fn(async (cwd: string) => {
+        if (cwd === "/bad") throw new Error("pi-resources blew up");
+        return {};
+      }),
+    };
+    const browserGateway = makeGateway();
+
+    await runPostInstallRepair({
+      registry: makeRegistry() as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+
+    expect(directoryService.refreshPiResources).toHaveBeenCalledTimes(2);
+    const openSpecBroadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(openSpecBroadcasts).toHaveLength(2);
+  });
+});

package/packages/server/src/__tests__/post-install-rescan.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Unit tests for the centralized post-install rescan hook.
+ *
+ * Asserts that the helper invoked from the bootstrap-state subscribe
+ * callback calls `registry.rescan()` (no arg → full registry invalidate)
+ * exactly once on `installing → ready` and never on other transitions.
+ *
+ * See change: fix-openspec-buttons-after-bootstrap-install.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { runPostInstallRepair, makeBootstrapTransitionHandler } from "../server.js";
+
+interface SpyRegistry {
+  rescan: ReturnType<typeof vi.fn>;
+}
+
+interface SpyDirSvc {
+  knownDirectories: ReturnType<typeof vi.fn>;
+  getOpenSpecData: ReturnType<typeof vi.fn>;
+  refreshOpenSpec: ReturnType<typeof vi.fn>;
+  refreshPiResources: ReturnType<typeof vi.fn>;
+}
+
+interface SpyGateway {
+  broadcastToAll: ReturnType<typeof vi.fn>;
+}
+
+function makeRegistry(): SpyRegistry {
+  return { rescan: vi.fn() };
+}
+
+function makeDirSvc(): SpyDirSvc {
+  return {
+    knownDirectories: vi.fn(() => []),
+    getOpenSpecData: vi.fn(() => undefined),
+    refreshOpenSpec: vi.fn(async () => ({ initialized: false, changes: [] })),
+    refreshPiResources: vi.fn(async () => ({ initialized: false, packages: [] })),
+  };
+}
+
+function makeGateway(): SpyGateway {
+  return { broadcastToAll: vi.fn() };
+}
+
+describe("runPostInstallRepair", () => {
+  it("calls registry.rescan() with no argument (full registry)", async () => {
+    const registry = makeRegistry();
+    const directoryService = makeDirSvc();
+    const browserGateway = makeGateway();
+    await runPostInstallRepair({
+      registry: registry as never,
+      directoryService: directoryService as never,
+      browserGateway: browserGateway as never,
+    });
+    expect(registry.rescan).toHaveBeenCalledTimes(1);
+    expect(registry.rescan).toHaveBeenCalledWith();
+  });
+});
+
+describe("makeBootstrapTransitionHandler", () => {
+  it("invokes the post-install repair exactly once on installing → ready", async () => {
+    const repair = vi.fn(async () => undefined);
+    const flushAll = vi.fn(async () => undefined);
+    const handler = makeBootstrapTransitionHandler({
+      onTransitionToReady: repair,
+      flushQueue: flushAll,
+    });
+    handler({ status: "installing" } as never);
+    handler({ status: "ready" } as never);
+    // Wait one microtask tick for the fire-and-forget to fire.
+    await Promise.resolve();
+    expect(repair).toHaveBeenCalledTimes(1);
+    expect(flushAll).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call repair on ready → ready", async () => {
+    const repair = vi.fn(async () => undefined);
+    const flushAll = vi.fn(async () => undefined);
+    const handler = makeBootstrapTransitionHandler({
+      onTransitionToReady: repair,
+      flushQueue: flushAll,
+    });
+    // Initial state defaults to ready, so first ready-snapshot is a no-op.
+    handler({ status: "ready" } as never);
+    handler({ status: "ready" } as never);
+    await Promise.resolve();
+    expect(repair).not.toHaveBeenCalled();
+    expect(flushAll).not.toHaveBeenCalled();
+  });
+
+  it("does not call repair on installing → failed", async () => {
+    const repair = vi.fn(async () => undefined);
+    const flushAll = vi.fn(async () => undefined);
+    const handler = makeBootstrapTransitionHandler({
+      onTransitionToReady: repair,
+      flushQueue: flushAll,
+    });
+    handler({ status: "installing" } as never);
+    handler({ status: "failed" } as never);
+    await Promise.resolve();
+    expect(repair).not.toHaveBeenCalled();
+    expect(flushAll).not.toHaveBeenCalled();
+  });
+
+  it("does not call repair on the very first subscribe snapshot", async () => {
+    // Bootstrap state defaults to "ready"; the first emitted snapshot
+    // (e.g. from an immediate broadcast) should NOT trigger the hook.
+    const repair = vi.fn(async () => undefined);
+    const flushAll = vi.fn(async () => undefined);
+    const handler = makeBootstrapTransitionHandler({
+      onTransitionToReady: repair,
+      flushQueue: flushAll,
+    });
+    handler({ status: "ready" } as never);
+    await Promise.resolve();
+    expect(repair).not.toHaveBeenCalled();
+  });
+
+  it("calls repair on a second installing → ready cycle (e.g. user retry)", async () => {
+    const repair = vi.fn(async () => undefined);
+    const flushAll = vi.fn(async () => undefined);
+    const handler = makeBootstrapTransitionHandler({
+      onTransitionToReady: repair,
+      flushQueue: flushAll,
+    });
+    handler({ status: "installing" } as never);
+    handler({ status: "ready" } as never);
+    handler({ status: "installing" } as never);
+    handler({ status: "ready" } as never);
+    await Promise.resolve();
+    expect(repair).toHaveBeenCalledTimes(2);
+    expect(flushAll).toHaveBeenCalledTimes(2);
+  });
+});

package/packages/server/src/__tests__/proposal-attach-naming.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure-helper tests for the idempotent attach/detach auto-rename rule.
+ * See change: fix-mobile-attach-proposal-display (design.md decision matrix).
+ */
+import { describe, it, expect } from "vitest";
+import {
+  attachRenameTarget,
+  detachShouldClearName,
+  isNameAutoSetFromAttachment,
+} from "../proposal-attach-naming.js";
+
+type S = { name?: string | null; attachedProposal?: string | null };
+
+describe("attachRenameTarget — decision matrix", () => {
+  it("(a) empty name + null attached → returns new change name", () => {
+    const s: S = { name: undefined, attachedProposal: null };
+    expect(attachRenameTarget(s as any, "bar")).toBe("bar");
+  });
+
+  it("(a) whitespace-only name → treated as empty, returns new change name", () => {
+    const s: S = { name: "   ", attachedProposal: null };
+    expect(attachRenameTarget(s as any, "bar")).toBe("bar");
+  });
+
+  it("custom name + null attached → returns undefined (preserve user name)", () => {
+    const s: S = { name: "my custom", attachedProposal: null };
+    expect(attachRenameTarget(s as any, "bar")).toBeUndefined();
+  });
+
+  it("(b) name === attached (auto-set) → returns new change name (re-track)", () => {
+    const s: S = { name: "foo", attachedProposal: "foo" };
+    expect(attachRenameTarget(s as any, "bar")).toBe("bar");
+  });
+
+  it("custom name + non-null attached (user customised after auto) → returns undefined", () => {
+    const s: S = { name: "my custom", attachedProposal: "foo" };
+    expect(attachRenameTarget(s as any, "bar")).toBeUndefined();
+  });
+
+  it("undefined session → returns undefined (defensive)", () => {
+    expect(attachRenameTarget(undefined, "bar")).toBeUndefined();
+  });
+});
+
+describe("detachShouldClearName — decision matrix", () => {
+  it("name === attached (auto-set) → true", () => {
+    expect(detachShouldClearName({ name: "foo", attachedProposal: "foo" } as any)).toBe(true);
+  });
+
+  it("custom name + non-null attached → false", () => {
+    expect(detachShouldClearName({ name: "my custom", attachedProposal: "foo" } as any)).toBe(false);
+  });
+
+  it("empty name + non-null attached → false (nothing to revert)", () => {
+    expect(detachShouldClearName({ name: undefined, attachedProposal: "foo" } as any)).toBe(false);
+    expect(detachShouldClearName({ name: "", attachedProposal: "foo" } as any)).toBe(false);
+    expect(detachShouldClearName({ name: "  ", attachedProposal: "foo" } as any)).toBe(false);
+  });
+
+  it("name set + null attached → false (defensive: not auto-set)", () => {
+    expect(detachShouldClearName({ name: "foo", attachedProposal: null } as any)).toBe(false);
+  });
+
+  it("undefined session → false", () => {
+    expect(detachShouldClearName(undefined)).toBe(false);
+  });
+});
+
+describe("isNameAutoSetFromAttachment", () => {
+  it("name === attached → true", () => {
+    expect(isNameAutoSetFromAttachment({ name: "foo", attachedProposal: "foo" } as any)).toBe(true);
+  });
+  it("name !== attached → false", () => {
+    expect(isNameAutoSetFromAttachment({ name: "foo", attachedProposal: "bar" } as any)).toBe(false);
+  });
+  it("trims whitespace before comparing", () => {
+    expect(isNameAutoSetFromAttachment({ name: "  foo  ", attachedProposal: "foo" } as any)).toBe(true);
+  });
+});

package/packages/server/src/__tests__/session-action-handler-spawn-with-attach.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Verifies that `handleSpawnSession` enqueues a pending-attach intent
+ * when the browser sends `attachProposal`, and does NOT enqueue when omitted.
+ * See change: add-folder-task-checker-and-spawn-attach.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../process-manager.js", () => ({
+  spawnPiSession: vi.fn(),
+}));
+vi.mock("../../../shared/src/config.js", () => ({
+  loadConfig: () => ({ spawnStrategy: "headless" as const }),
+}));
+vi.mock("@blackbelt-technology/pi-dashboard-shared/config.js", () => ({
+  loadConfig: () => ({ spawnStrategy: "headless" as const }),
+}));
+
+import { handleSpawnSession } from "../browser-handlers/session-action-handler.js";
+import { spawnPiSession } from "../process-manager.js";
+
+function makeCtx() {
+  const enqueue = vi.fn();
+  const ctx = {
+    ws: { readyState: 1 } as unknown as WebSocket,
+    headlessPidRegistry: { register: vi.fn() },
+    pendingDashboardSpawns: new Map<string, number>(),
+    pendingAttachRegistry: { enqueue, consume: vi.fn(), size: vi.fn() },
+    sendTo: () => {},
+  } as any;
+  return { ctx, enqueue };
+}
+
+describe("handleSpawnSession — attachProposal", () => {
+  beforeEach(() => { vi.clearAllMocks(); });
+  afterEach(() => { vi.restoreAllMocks(); });
+
+  it("enqueues exactly once when attachProposal is set", async () => {
+    (spawnPiSession as any).mockResolvedValueOnce({ success: true });
+    const { ctx, enqueue } = makeCtx();
+    await handleSpawnSession(
+      { type: "spawn_session", cwd: "/proj", attachProposal: "add-foo" } as any,
+      ctx,
+    );
+    expect(enqueue).toHaveBeenCalledTimes(1);
+    expect(enqueue).toHaveBeenCalledWith("/proj", "add-foo");
+  });
+
+  it("does NOT enqueue when attachProposal is absent", async () => {
+    (spawnPiSession as any).mockResolvedValueOnce({ success: true });
+    const { ctx, enqueue } = makeCtx();
+    await handleSpawnSession({ type: "spawn_session", cwd: "/proj" } as any, ctx);
+    expect(enqueue).not.toHaveBeenCalled();
+  });
+
+  it("does NOT enqueue when attachProposal is empty string", async () => {
+    (spawnPiSession as any).mockResolvedValueOnce({ success: true });
+    const { ctx, enqueue } = makeCtx();
+    await handleSpawnSession(
+      { type: "spawn_session", cwd: "/proj", attachProposal: "" } as any,
+      ctx,
+    );
+    expect(enqueue).not.toHaveBeenCalled();
+  });
+
+  it("enqueues BEFORE awaiting spawnPiSession (intent survives a fast register)", async () => {
+    let spawnCalled = false;
+    const { ctx, enqueue } = makeCtx();
+    enqueue.mockImplementation(() => {
+      // The spawn must not have started yet at the time we enqueue.
+      expect(spawnCalled).toBe(false);
+    });
+    (spawnPiSession as any).mockImplementation(async () => {
+      spawnCalled = true;
+      return { success: true };
+    });
+    await handleSpawnSession(
+      { type: "spawn_session", cwd: "/proj", attachProposal: "add-bar" } as any,
+      ctx,
+    );
+    expect(enqueue).toHaveBeenCalledOnce();
+  });
+
+  it("still enqueues even when spawn throws (spawn failure isn't a reason to lose intent — TTL handles it)", async () => {
+    (spawnPiSession as any).mockRejectedValueOnce(new Error("boom"));
+    const { ctx, enqueue } = makeCtx();
+    await handleSpawnSession(
+      { type: "spawn_session", cwd: "/proj", attachProposal: "add-baz" } as any,
+      ctx,
+    );
+    expect(enqueue).toHaveBeenCalledOnce();
+  });
+
+  it("works when pendingAttachRegistry is undefined (back-compat)", async () => {
+    (spawnPiSession as any).mockResolvedValueOnce({ success: true });
+    const ctx: any = {
+      ws: { readyState: 1 },
+      headlessPidRegistry: { register: vi.fn() },
+      pendingDashboardSpawns: new Map(),
+      sendTo: () => {},
+    };
+    await expect(
+      handleSpawnSession(
+        { type: "spawn_session", cwd: "/proj", attachProposal: "add-foo" } as any,
+        ctx,
+      ),
+    ).resolves.toBeUndefined();
+  });
+});

package/packages/server/src/__tests__/session-order-manager.test.ts

@@ -132,4 +132,59 @@ describe("SessionOrderManager", () => {
       expect(orders).toEqual({ "/a": ["s1"], "/b": ["s2", "s3"] });
     });
   });
+
+  describe("moveToFront", () => {
+    it("prepends id when absent (creates entry for new cwd)", () => {
+      const mgr = createSessionOrderManager(stateStore);
+      mgr.moveToFront("/project", "s1");
+      expect(mgr.getOrder("/project")).toEqual(["s1"]);
+    });
+
+    it("prepends id when absent from existing order", () => {
+      stateStore = createMockPreferencesStore({ "/project": ["s0", "s1", "s2"] });
+      const mgr = createSessionOrderManager(stateStore);
+      mgr.moveToFront("/project", "s9");
+      expect(mgr.getOrder("/project")).toEqual(["s9", "s0", "s1", "s2"]);
+    });
+
+    it("moves id from non-front position to index 0", () => {
+      stateStore = createMockPreferencesStore({ "/project": ["s0", "s1", "s2"] });
+      const mgr = createSessionOrderManager(stateStore);
+      mgr.moveToFront("/project", "s2");
+      expect(mgr.getOrder("/project")).toEqual(["s2", "s0", "s1"]);
+    });
+
+    it("is idempotent: id already at front stays at index 0", () => {
+      stateStore = createMockPreferencesStore({ "/project": ["s0", "s1", "s2"] });
+      const mgr = createSessionOrderManager(stateStore);
+      mgr.moveToFront("/project", "s0");
+      expect(mgr.getOrder("/project")).toEqual(["s0", "s1", "s2"]);
+    });
+
+    it("persists after moveToFront", () => {
+      stateStore = createMockPreferencesStore({ "/project": ["s0", "s1"] });
+      const mgr = createSessionOrderManager(stateStore);
+      mgr.moveToFront("/project", "s1");
+      expect(stateStore.setSessionOrder).toHaveBeenCalled();
+    });
+
+    it("end → resume → end → resume cycle keeps id at index 0", () => {
+      stateStore = createMockPreferencesStore({ "/project": ["s0", "s1"] });
+      const mgr = createSessionOrderManager(stateStore);
+      // First resume cycle: id is in the order list (drag-to-resume case)
+      mgr.moveToFront("/project", "s1");
+      expect(mgr.getOrder("/project")).toEqual(["s1", "s0"]);
+      // End: alive→ended branch removes the id
+      mgr.remove("/project", "s1");
+      expect(mgr.getOrder("/project")).toEqual(["s0"]);
+      // Second resume: moveToFront re-prepends
+      mgr.moveToFront("/project", "s1");
+      expect(mgr.getOrder("/project")).toEqual(["s1", "s0"]);
+      // End again
+      mgr.remove("/project", "s1");
+      // Third resume
+      mgr.moveToFront("/project", "s1");
+      expect(mgr.getOrder("/project")).toEqual(["s1", "s0"]);
+    });
+  });
 });