@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.0

package/packages/extension/src/server-launcher.ts

@@ -3,13 +3,18 @@
  * The spawned server runs in foreground mode (no subcommand) and writes
  * its own PID file at ~/.pi/dashboard/server.pid.
  */
-import { spawn } from "node:child_process";
+import { spawnDetached, waitForReady } from "@blackbelt-technology/pi-dashboard-shared/platform/detached-spawn.js";
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import type { DashboardConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { resolveJitiImport } from "@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js";
+import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
 
 export interface LaunchResult {
   success: boolean;
@@ -17,11 +22,26 @@ export interface LaunchResult {
 }
 
 /**
- * Resolve the dashboard server CLI script path relative to this extension file.
- * From packages/extension/src/server-launcher.ts → packages/server/src/cli.ts
+ * Resolve the dashboard server CLI script path.
+ *
+ * Handles two layouts:
+ *   1. Monorepo dev: `<repo>/packages/extension/src/` → `<repo>/packages/server/src/cli.ts`
+ *   2. Installed  : `<x>/node_modules/@blackbelt-technology/pi-dashboard-extension/src/`
+ *                → `<x>/node_modules/@blackbelt-technology/pi-dashboard-server/src/cli.ts`
+ *
+ * Uses Node's module resolver (`require.resolve`) to find the server package
+ * and joins `src/cli.ts`. Falls back to the monorepo-relative path so existing
+ * dev workflows keep working even if the server package isn't resolvable (e.g.
+ * a pristine checkout with no node_modules yet).
  */
 export function resolveServerCliPath(): string {
-  return path.resolve(__dirname, "..", "..", "server", "src", "cli.ts");
+  try {
+    const serverPkgJson = require.resolve("@blackbelt-technology/pi-dashboard-server/package.json");
+    return path.resolve(path.dirname(serverPkgJson), "src", "cli.ts");
+  } catch {
+    // Dev-repo fallback: <extension>/src/../../server/src/cli.ts
+    return path.resolve(__dirname, "..", "..", "server", "src", "cli.ts");
+  }
 }
 
 /**
@@ -43,36 +63,60 @@ export async function launchServer(config: DashboardConfig): Promise<LaunchResul
   const args = buildSpawnArgs(config);
 
   try {
-    // Spawn server using pi's jiti TypeScript loader (resolved to absolute path).
-    // The server writes its own PID file on startup, so
-    // `pi-dashboard status` can detect it.
-    const child = spawn(process.execPath, ["--import", resolveJitiImport(), cliPath, ...args], {
-      detached: true,
-      stdio: "ignore",
+    // Open the server.log in append mode so any startup error is visible.
+    // Matches the log location used by `pi-dashboard start`.
+    let logFd: number | undefined;
+    try {
+      const logDir = path.join(os.homedir(), ".pi", "dashboard");
+      fs.mkdirSync(logDir, { recursive: true });
+      const logPath = path.join(logDir, "server.log");
+      logFd = fs.openSync(logPath, "a");
+      fs.writeSync(
+        logFd,
+        `\n[${new Date().toISOString()}] bridge auto-start (parent pid ${process.pid}, port ${config.port})\n`,
+      );
+    } catch { /* if we can't open the log, spawn still works */ }
+
+    // Spawn server via the detached-spawn primitive. resolveJitiImport()
+    // returns a file:// URL (required on Windows for node --import).
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["--import", resolveJitiImport(), cliPath, ...args],
       env: { ...process.env },
+      logFd,
     });
 
-    child.unref();
-
-    // Monitor for early exit (within 2s)
-    const earlyExit = await new Promise<boolean>((resolve) => {
-      const timer = setTimeout(() => {
-        resolve(false); // No early exit — server is running
-      }, 2000);
+    // Close the parent's copy of the log fd — the child has its own.
+    if (logFd !== undefined) {
+      try { fs.closeSync(logFd); } catch { /* ignore */ }
+    }
 
-      child.on("exit", () => {
-        clearTimeout(timer);
-        resolve(true); // Exited early — failure
-      });
+    if (!r.ok || !r.process) {
+      return { success: false, message: `Server process failed to spawn: ${r.error ?? "unknown"}` };
+    }
 
-      child.on("error", () => {
-        clearTimeout(timer);
-        resolve(true);
-      });
+    // Wait for the server to actually become available via positive
+    // HTTP probe. NO deadline — we rely on child-exit for failure
+    // detection. A timeout here only catches the pathological case
+    // "process alive but never ready", which is rarer than the
+    // false-positive case "slow cold-start mistakenly flagged as
+    // failure" (Fastify + jiti compile + session scan can take 15–30s
+    // on Windows). If the child crashes, `waitForReady` returns
+    // { ok: false, error: "child exited with code N" } via its
+    // `child` listener. If the child hangs alive-but-broken, the user
+    // can kill it manually — timers don't help that case anyway.
+    const ready = await waitForReady({
+      probe: async () => (await isDashboardRunning(config.port)).running,
+      pollIntervalMs: 300,
+      child: r.process,
+      // deadlineMs intentionally omitted — wait indefinitely.
     });
 
-    if (earlyExit) {
-      return { success: false, message: "Server process exited immediately" };
+    if (!ready.ok) {
+      return {
+        success: false,
+        message: `Server process failed: ${ready.error ?? "unknown"}. See ~/.pi/dashboard/server.log`,
+      };
     }
 
     return { success: true, message: "Server started" };

package/packages/server/package.json

@@ -1,8 +1,19 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "piCompatibility": {
+    "minimum": "0.6.7",
+    "recommended": "0.6.7",
+    "maximum": null
+  },
   "main": "src/cli.ts",
   "bin": {
     "pi-dashboard": "src/cli.ts"
@@ -15,7 +26,8 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-shared": "*",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.4.0",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.4.0",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",
@@ -28,11 +40,13 @@
     "fastify": "^5.0.0",
     "jsonwebtoken": "^9.0.3",
     "node-pty": "^1.1.0",
+    "proper-lockfile": "^4.1.2",
     "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/diff": "^7.0.0",
     "@types/jsonwebtoken": "^9.0.9",
+    "@types/proper-lockfile": "^4.1.4",
     "@types/ws": "^8.18.1"
   }
 }

package/packages/server/src/__tests__/bootstrap-queue.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Unit tests for the in-memory bootstrap ticket queue.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import { describe, it, expect } from "vitest";
+import { createBootstrapQueue } from "../bootstrap-queue.js";
+
+describe("bootstrap-queue", () => {
+  it("enqueue returns a unique ticketId + pending result", () => {
+    const q = createBootstrapQueue();
+    const a = q.enqueue(async () => "A");
+    const b = q.enqueue(async () => "B");
+    expect(a.ticketId).not.toBe(b.ticketId);
+    expect(q.size()).toBe(2);
+  });
+
+  it("flushAll runs handlers in enqueue order and resolves results", async () => {
+    const q = createBootstrapQueue();
+    const order: string[] = [];
+    const a = q.enqueue(async () => {
+      order.push("a");
+      return "A";
+    });
+    const b = q.enqueue(async () => {
+      order.push("b");
+      return "B";
+    });
+    await q.flushAll();
+    expect(order).toEqual(["a", "b"]);
+    await expect(a.result).resolves.toBe("A");
+    await expect(b.result).resolves.toBe("B");
+    expect(q.size()).toBe(0);
+  });
+
+  it("handler exceptions reject the ticket promise", async () => {
+    const q = createBootstrapQueue();
+    const t = q.enqueue(async () => {
+      throw new Error("boom");
+    });
+    await q.flushAll();
+    await expect(t.result).rejects.toThrow("boom");
+  });
+
+  it("onTicketComplete fires success=true for resolved handlers", async () => {
+    const q = createBootstrapQueue();
+    const events: Array<{ ticketId: string; success: boolean; error?: string }> = [];
+    q.onTicketComplete((e) => events.push(e));
+    const t = q.enqueue(async () => 42);
+    await q.flushAll();
+    await t.result;
+    expect(events).toEqual([{ ticketId: t.ticketId, success: true }]);
+  });
+
+  it("onTicketComplete fires success=false with error message on rejection", async () => {
+    const q = createBootstrapQueue();
+    const events: Array<{ ticketId: string; success: boolean; error?: string }> = [];
+    q.onTicketComplete((e) => events.push(e));
+    const t = q.enqueue(async () => {
+      throw new Error("oh no");
+    });
+    await q.flushAll();
+    await t.result.catch(() => undefined);
+    expect(events).toEqual([
+      { ticketId: t.ticketId, success: false, error: "oh no" },
+    ]);
+  });
+
+  it("onTicketComplete returns an unsubscribe function", async () => {
+    const q = createBootstrapQueue();
+    const events: unknown[] = [];
+    const off = q.onTicketComplete((e) => events.push(e));
+    off();
+    q.enqueue(async () => "x");
+    await q.flushAll();
+    expect(events).toEqual([]);
+  });
+
+  it("clear drops pending tickets with an error result and broadcasts completion", async () => {
+    const q = createBootstrapQueue();
+    const events: Array<{ ticketId: string; success: boolean; error?: string }> = [];
+    q.onTicketComplete((e) => events.push(e));
+    const t = q.enqueue(async () => "never runs");
+    q.clear("server shutting down");
+    await t.result.catch(() => undefined);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      ticketId: t.ticketId,
+      success: false,
+      error: "server shutting down",
+    });
+    expect(q.size()).toBe(0);
+  });
+
+  it("multiple listeners all receive the completion event", async () => {
+    const q = createBootstrapQueue();
+    const a: unknown[] = [];
+    const b: unknown[] = [];
+    q.onTicketComplete((e) => a.push(e));
+    q.onTicketComplete((e) => b.push(e));
+    const t = q.enqueue(async () => "ok");
+    await q.flushAll();
+    await t.result;
+    expect(a).toHaveLength(1);
+    expect(b).toHaveLength(1);
+  });
+
+  it("a listener that throws does not block other listeners", async () => {
+    const q = createBootstrapQueue();
+    const seen: unknown[] = [];
+    q.onTicketComplete(() => {
+      throw new Error("listener crash");
+    });
+    q.onTicketComplete((e) => seen.push(e));
+    const t = q.enqueue(async () => "ok");
+    await q.flushAll();
+    await t.result;
+    expect(seen).toHaveLength(1);
+  });
+});

package/packages/server/src/__tests__/bootstrap-routes.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Route tests for `/api/bootstrap/*`.
+ *
+ * Spins up a minimal Fastify instance with the bootstrap routes wired
+ * to a fresh state store and a pair of spy triggers. No real network
+ * access, no real subprocesses.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import { createBootstrapState, type BootstrapStateStore } from "../bootstrap-state.js";
+import { registerBootstrapRoutes } from "../routes/bootstrap-routes.js";
+
+const noopGuard = async () => {
+  /* allow all requests in tests */
+};
+
+interface Harness {
+  app: FastifyInstance;
+  state: BootstrapStateStore;
+  upgradeCalls: string[];
+  retryCalls: string[];
+}
+
+async function makeHarness(): Promise<Harness> {
+  const app = Fastify({ logger: false });
+  const state = createBootstrapState();
+  const upgradeCalls: string[] = [];
+  const retryCalls: string[] = [];
+
+  registerBootstrapRoutes(app, {
+    bootstrapState: state,
+    networkGuard: noopGuard,
+    triggerUpgradePi: async (ticketId) => {
+      upgradeCalls.push(ticketId);
+    },
+    triggerRetry: async (ticketId) => {
+      retryCalls.push(ticketId);
+    },
+  });
+
+  await app.ready();
+  return { app, state, upgradeCalls, retryCalls };
+}
+
+describe("bootstrap-routes", () => {
+  let h: Harness;
+
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+
+  afterEach(async () => {
+    await h.app.close();
+  });
+
+  describe("GET /api/bootstrap/status", () => {
+    it("returns the current state (default ready)", async () => {
+      const res = await h.app.inject({ method: "GET", url: "/api/bootstrap/status" });
+      expect(res.statusCode).toBe(200);
+      expect(res.json()).toEqual({ status: "ready" });
+    });
+
+    it("reflects subsequent state changes", async () => {
+      h.state.set({ status: "installing", progress: { step: "pi" } });
+      const res = await h.app.inject({ method: "GET", url: "/api/bootstrap/status" });
+      expect(res.json()).toMatchObject({
+        status: "installing",
+        progress: { step: "pi" },
+      });
+    });
+  });
+
+  describe("POST /api/bootstrap/upgrade-pi", () => {
+    it("returns 202 with a ticketId and invokes the trigger", async () => {
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/upgrade-pi" });
+      expect(res.statusCode).toBe(202);
+      const body = res.json() as { ticketId: string; status: string };
+      expect(body.status).toBe("accepted");
+      expect(typeof body.ticketId).toBe("string");
+      expect(body.ticketId.length).toBeGreaterThan(0);
+      // Trigger runs async — await a microtask.
+      await new Promise((r) => setImmediate(r));
+      expect(h.upgradeCalls).toEqual([body.ticketId]);
+    });
+
+    it("returns 409 when an install is already in progress", async () => {
+      h.state.set({ status: "installing" });
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/upgrade-pi" });
+      expect(res.statusCode).toBe(409);
+      expect(h.upgradeCalls).toEqual([]);
+    });
+
+    it("is allowed when status is failed (to upgrade after a previous failure)", async () => {
+      h.state.set({ status: "failed", error: { message: "network" } });
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/upgrade-pi" });
+      expect(res.statusCode).toBe(202);
+    });
+  });
+
+  describe("POST /api/bootstrap/retry", () => {
+    it("returns 409 when status is ready", async () => {
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/retry" });
+      expect(res.statusCode).toBe(409);
+      expect(h.retryCalls).toEqual([]);
+    });
+
+    it("returns 409 when status is installing", async () => {
+      h.state.set({ status: "installing" });
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/retry" });
+      expect(res.statusCode).toBe(409);
+      expect(h.retryCalls).toEqual([]);
+    });
+
+    it("returns 202 when status is failed and invokes the trigger", async () => {
+      h.state.set({ status: "failed", error: { message: "network" } });
+      const res = await h.app.inject({ method: "POST", url: "/api/bootstrap/retry" });
+      expect(res.statusCode).toBe(202);
+      const body = res.json() as { ticketId: string };
+      await new Promise((r) => setImmediate(r));
+      expect(h.retryCalls).toEqual([body.ticketId]);
+    });
+  });
+});

package/packages/server/src/__tests__/bootstrap-state.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Unit tests for the in-memory bootstrap state store.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import { describe, it, expect } from "vitest";
+import { createBootstrapState } from "../bootstrap-state.js";
+
+describe("bootstrap-state", () => {
+  it("defaults to status=ready", () => {
+    const s = createBootstrapState();
+    expect(s.get()).toEqual({ status: "ready" });
+  });
+
+  it("applies initial overrides", () => {
+    const s = createBootstrapState({
+      status: "installing",
+      progress: { step: "pi", output: "starting" },
+    });
+    const state = s.get();
+    expect(state.status).toBe("installing");
+    expect(state.progress).toEqual({ step: "pi", output: "starting" });
+  });
+
+  it("set merges partial into state", () => {
+    const s = createBootstrapState();
+    s.set({ status: "installing", progress: { step: "pi" } });
+    expect(s.get().status).toBe("installing");
+    s.set({ progress: { step: "openspec" } });
+    expect(s.get().progress).toEqual({ step: "openspec" });
+    expect(s.get().status).toBe("installing");
+  });
+
+  it("set with undefined explicitly clears a key", () => {
+    const s = createBootstrapState({ progress: { step: "pi" } });
+    expect(s.get().progress).toBeDefined();
+    s.set({ progress: undefined });
+    expect(s.get().progress).toBeUndefined();
+  });
+
+  it("notifies subscribers on set", () => {
+    const s = createBootstrapState();
+    const calls: string[] = [];
+    s.subscribe((st) => calls.push(st.status));
+    s.set({ status: "installing" });
+    s.set({ status: "ready" });
+    expect(calls).toEqual(["installing", "ready"]);
+  });
+
+  it("subscribe returns an unsubscribe function", () => {
+    const s = createBootstrapState();
+    const calls: string[] = [];
+    const off = s.subscribe((st) => calls.push(st.status));
+    s.set({ status: "installing" });
+    off();
+    s.set({ status: "ready" });
+    expect(calls).toEqual(["installing"]);
+  });
+
+  it("listener errors do not stop other listeners", () => {
+    const s = createBootstrapState();
+    const calls: string[] = [];
+    s.subscribe(() => {
+      throw new Error("boom");
+    });
+    s.subscribe((st) => calls.push(st.status));
+    s.set({ status: "installing" });
+    expect(calls).toEqual(["installing"]);
+  });
+
+  it("dispose clears all listeners", () => {
+    const s = createBootstrapState();
+    const calls: string[] = [];
+    s.subscribe((st) => calls.push(st.status));
+    s.dispose();
+    s.set({ status: "installing" });
+    expect(calls).toEqual([]);
+  });
+
+  it("get returns a fresh snapshot (external mutation does not affect store)", () => {
+    const s = createBootstrapState({ progress: { step: "pi" } });
+    const snap = s.get();
+    snap.status = "failed";
+    expect(s.get().status).toBe("ready");
+  });
+
+  describe("lastInstallPackages", () => {
+    it("defaults to an empty array", () => {
+      const s = createBootstrapState();
+      expect(s.getLastInstallPackages()).toEqual([]);
+    });
+
+    it("records and returns a fresh copy", () => {
+      const s = createBootstrapState();
+      s.setLastInstallPackages(["pi", "openspec"]);
+      const got = s.getLastInstallPackages();
+      expect(got).toEqual(["pi", "openspec"]);
+      // External mutation does not affect the stored value.
+      got.push("tsx");
+      expect(s.getLastInstallPackages()).toEqual(["pi", "openspec"]);
+    });
+
+    it("accepts a readonly input without type error", () => {
+      const s = createBootstrapState();
+      const readonlyInput: readonly string[] = ["a", "b"];
+      s.setLastInstallPackages(readonlyInput);
+      expect(s.getLastInstallPackages()).toEqual(["a", "b"]);
+    });
+
+    it("is independent of status broadcast (not part of snapshot)", () => {
+      const s = createBootstrapState();
+      const seen: string[] = [];
+      s.subscribe((st) => seen.push(st.status));
+      s.setLastInstallPackages(["pi"]);
+      // setLastInstallPackages MUST NOT trigger a listener.
+      expect(seen).toEqual([]);
+    });
+  });
+});

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

@@ -102,6 +102,23 @@ describe("listDirectories", () => {
       expect(entry.path).toBe(path.join(projectRoot, entry.name));
     }
   });
+
+  it("should return the server's platform", async () => {
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
+    const result = await listDirectories(projectRoot);
+    expect(result.platform).toBe(process.platform);
+  });
+
+  it("returns parent=null at the filesystem root", async () => {
+    // Use whichever root is appropriate for the host: "/" on Unix, the
+    // process's drive root on Windows. Previously this test only
+    // exercised Unix; `isFilesystemRoot` covers both branches now.
+    const root = process.platform === "win32"
+      ? path.parse(process.cwd()).root    // e.g., "C:\\" or "B:\\"
+      : "/";
+    const result = await listDirectories(root);
+    expect(result.parent).toBeNull();
+  });
 });
 
 describe("listDirectories with q filter", () => {

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

@@ -31,6 +31,17 @@ describe("parseArgs", () => {
     expect(result.subcommand).toBe("status");
   });
 
+  it("parses upgrade-pi subcommand (unified-bootstrap-install §8)", () => {
+    const result = parseArgs(["upgrade-pi"]);
+    expect(result.subcommand).toBe("upgrade-pi");
+  });
+
+  it("parses upgrade-pi with --port flag", () => {
+    const result = parseArgs(["upgrade-pi", "--port", "9090"]);
+    expect(result.subcommand).toBe("upgrade-pi");
+    expect(result.flags.port).toBe(9090);
+  });
+
   it("parses subcommand with flags", () => {
     const result = parseArgs(["start", "--port", "3000", "--pi-port", "4000"]);
     expect(result.subcommand).toBe("start");