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

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

@@ -0,0 +1,130 @@
+/**
+ * In-memory queue for pi-dependent operations deferred during bootstrap
+ * install. When `bootstrapState.status === "installing"`, callers should
+ * enqueue their handler and return a 202 Accepted with the ticketId.
+ * When status transitions to "ready", `flushAll()` runs every queued
+ * handler sequentially in enqueue order.
+ *
+ * Queue is process-local and NOT persisted. If the dashboard crashes
+ * mid-install, queued requests are lost — documented as a known
+ * limitation in design.md §16.2.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import { randomUUID } from "node:crypto";
+
+export interface QueuedTicket<T> {
+  ticketId: string;
+  /**
+   * Resolves when the queued handler runs (or rejects if it throws).
+   * Call sites can await this when they want to synchronously return
+   * the eventual result — but 202-Accepted flows MUST NOT await, they
+   * return the ticketId to the client immediately.
+   */
+  result: Promise<T>;
+}
+
+export interface BootstrapQueue {
+  enqueue<T>(handler: () => Promise<T>): QueuedTicket<T>;
+  flushAll(): Promise<void>;
+  /** Number of currently pending tickets. */
+  size(): number;
+  /** Drop all pending tickets without running them (used at shutdown). */
+  clear(reason?: string): void;
+  /**
+   * Register a listener invoked after each ticket runs (success or
+   * failure). The server wires this to a `bootstrap_ticket_complete`
+   * WS broadcast so browser clients can correlate the outcome of a
+   * 202-accepted request via their stored ticketId.
+   * See change: unified-bootstrap-install.
+   */
+  onTicketComplete(
+    listener: (evt: { ticketId: string; success: boolean; error?: string }) => void,
+  ): () => void;
+}
+
+interface PendingEntry {
+  ticketId: string;
+  run: () => Promise<void>;
+  /** Reject the caller's `result` promise. Called by `clear()` to
+   *  drain tickets at shutdown. */
+  reject: (err: unknown) => void;
+}
+
+export function createBootstrapQueue(): BootstrapQueue {
+  const pending: PendingEntry[] = [];
+  const listeners = new Set<
+    (evt: { ticketId: string; success: boolean; error?: string }) => void
+  >();
+
+  function notify(evt: { ticketId: string; success: boolean; error?: string }): void {
+    for (const l of listeners) {
+      try {
+        l(evt);
+      } catch (err) {
+        console.error("[bootstrap-queue] ticket-complete listener threw:", err);
+      }
+    }
+  }
+
+  return {
+    enqueue<T>(handler: () => Promise<T>): QueuedTicket<T> {
+      const ticketId = randomUUID();
+      let resolve!: (value: T) => void;
+      let reject!: (err: unknown) => void;
+      const result = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      pending.push({
+        ticketId,
+        reject,
+        run: async () => {
+          try {
+            const value = await handler();
+            resolve(value);
+            notify({ ticketId, success: true });
+          } catch (err) {
+            reject(err);
+            const message = err instanceof Error ? err.message : String(err);
+            notify({ ticketId, success: false, error: message });
+          }
+        },
+      });
+      return { ticketId, result };
+    },
+
+    async flushAll(): Promise<void> {
+      while (pending.length > 0) {
+        const entry = pending.shift();
+        if (!entry) break;
+        try {
+          await entry.run();
+        } catch (err) {
+          // Handler errors propagate via the ticket's `result` promise;
+          // they should never reach here unless there's a bug in `run`.
+          console.error(`[bootstrap-queue] ticket ${entry.ticketId} run threw:`, err);
+        }
+      }
+    },
+
+    size() {
+      return pending.length;
+    },
+
+    clear(reason = "queue cleared") {
+      const drained = pending.splice(0, pending.length);
+      for (const entry of drained) {
+        // Reject the caller's `result` promise directly and broadcast the
+        // completion so any browser holding the ticketId learns the
+        // outcome.
+        entry.reject(new Error(reason));
+        notify({ ticketId: entry.ticketId, success: false, error: reason });
+      }
+    },
+    onTicketComplete(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

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

@@ -0,0 +1,131 @@
+/**
+ * In-memory bootstrap state store for the dashboard server.
+ *
+ * Tracks the degraded-mode status during first-run pi install, upgrade
+ * operations, and version-skew detection. Subscribers (browser gateway,
+ * CLI progress printer) receive a snapshot on every `set()` call.
+ *
+ * See change: unified-bootstrap-install.
+ */
+
+export type BootstrapStatus = "ready" | "installing" | "failed";
+
+export interface BootstrapProgress {
+  /** Package / phase being processed (e.g. "pi-coding-agent", "bridge-register"). */
+  step: string;
+  /** Optional completion percentage (0..100). */
+  pct?: number;
+  /** Last line of npm output or other streaming context. */
+  output?: string;
+}
+
+export interface BootstrapError {
+  message: string;
+  stack?: string;
+}
+
+export interface BootstrapVersions {
+  pi?: string;
+  openspec?: string;
+  tsx?: string;
+}
+
+export interface BootstrapCompatibility {
+  minimum: string;
+  recommended: string;
+  /** null = no upper bound enforced yet. */
+  maximum: string | null;
+  /** Current resolved pi version, or undefined when pi is unresolved. */
+  current?: string;
+  /** Hint that the user should upgrade pi (below recommended). */
+  upgradeRecommended?: boolean;
+  /** Hint that the user should upgrade the dashboard itself (above maximum). */
+  upgradeDashboard?: boolean;
+}
+
+export interface BootstrapState {
+  status: BootstrapStatus;
+  progress?: BootstrapProgress;
+  error?: BootstrapError;
+  version?: BootstrapVersions;
+  compatibility?: BootstrapCompatibility;
+  /** Set when `registerBridgeExtension` fails after a successful install. */
+  bridgeRegistrationError?: string;
+}
+
+export type BootstrapListener = (state: BootstrapState) => void;
+
+export interface BootstrapStateStore {
+  get(): BootstrapState;
+  /**
+   * Merge `partial` into the current state. Passing `undefined` for a
+   * key explicitly clears it (e.g. `set({ progress: undefined })` removes
+   * the progress line after completion). Broadcasts to all subscribers.
+   */
+  set(partial: Partial<BootstrapState>): void;
+  subscribe(listener: BootstrapListener): () => void;
+  /** Clear all listeners (used in tests + server shutdown). */
+  dispose(): void;
+  /**
+   * Record the package list used by the most recent `bootstrapInstall`
+   * call. Used by `POST /api/bootstrap/retry` to re-run the exact failed
+   * set rather than a hard-coded default. Not part of the WS-broadcast
+   * snapshot — it's purely side-channel metadata for the server.
+   * See change: unified-bootstrap-install (verification follow-up).
+   */
+  setLastInstallPackages(packages: readonly string[]): void;
+  /** Read the last install set. Returns a fresh copy. */
+  getLastInstallPackages(): string[];
+}
+
+/**
+ * Create a fresh bootstrap state store. `initial` is merged over the
+ * default `{ status: "ready" }`.
+ */
+export function createBootstrapState(
+  initial?: Partial<BootstrapState>,
+): BootstrapStateStore {
+  let state: BootstrapState = { status: "ready", ...initial };
+  let lastInstallPackages: string[] = [];
+  const listeners = new Set<BootstrapListener>();
+
+  function notify(): void {
+    const snapshot = { ...state };
+    for (const l of listeners) {
+      try {
+        l(snapshot);
+      } catch (err) {
+        // Listener errors are non-fatal — log but continue.
+        console.error("[bootstrap-state] listener threw:", err);
+      }
+    }
+  }
+
+  return {
+    get() {
+      return { ...state };
+    },
+    set(partial) {
+      // Merge: explicit `undefined` in partial clears the field.
+      state = { ...state, ...partial } as BootstrapState;
+      // Strip keys whose value is undefined to keep the snapshot tidy.
+      for (const key of Object.keys(partial) as (keyof BootstrapState)[]) {
+        if (partial[key] === undefined) delete state[key];
+      }
+      notify();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    dispose() {
+      listeners.clear();
+    },
+    setLastInstallPackages(packages) {
+      lastInstallPackages = [...packages];
+    },
+    getLastInstallPackages() {
+      return [...lastInstallPackages];
+    },
+  };
+}

package/packages/server/src/browse.ts

@@ -5,6 +5,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import type { BrowseEntry, BrowseResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { isFilesystemRoot } from "@blackbelt-technology/pi-dashboard-shared/platform/paths.js";
 
 const MAX_ENTRIES = 200;
 const WORD_BOUNDARY_CHARS = new Set(["-", "_", ".", " ", "/"]);
@@ -85,10 +86,14 @@ export async function listDirectories(dirPath?: string, q?: string): Promise<Bro
     })
   );
 
-  // Parent: null for root
-  const parent = resolved === "/" ? null : path.dirname(resolved);
+  // Parent: null for any filesystem root (`/`, `C:\`, `\\server\share\`).
+  // Previously this was `resolved === "/"`, which only recognized the Unix
+  // root — on Windows `path.dirname("B:\\")` returns `"B:\\"`, so the
+  // picker showed a useless `..` entry at drive roots.
+  // See change: platform-path-normalization.
+  const parent = isFilesystemRoot(resolved) ? null : path.dirname(resolved);
 
-  return { entries, parent, current: resolved };
+  return { entries, parent, current: resolved, platform: process.platform };
 }
 
 /**

package/packages/server/src/browser-handlers/directory-handler.ts

@@ -4,10 +4,19 @@
 import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { BrowserHandlerContext } from "./handler-context.js";
 import { safeRealpathSync } from "../resolve-path.js";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { archiveCompleted as openspecArchiveCompleted } from "@blackbelt-technology/pi-dashboard-shared/platform/openspec.js";
+import { normalizePath } from "@blackbelt-technology/pi-dashboard-shared/platform/paths.js";
 
-const execFileAsync = promisify(execFile);
+/**
+ * Canonicalize a user-supplied path before storage: normalize separator /
+ * trailing-sep / case variants first, then resolve symlinks. Order matters
+ * — `realpath` can fail for not-yet-existing paths, so we keep its
+ * best-effort fallback but ensure we first have a sane string.
+ * See change: platform-path-normalization.
+ */
+function canonicalizePath(input: string): string {
+  return safeRealpathSync(normalizePath(input));
+}
 
 export function handlePinDirectory(
   msg: Extract<BrowserToServerMessage, { type: "pin_directory" }>,
@@ -15,7 +24,7 @@ export function handlePinDirectory(
 ): void {
   const { preferencesStore, directoryService, sessionManager, broadcast } = ctx;
   if (!preferencesStore) return;
-  const resolved = safeRealpathSync(msg.path);
+  const resolved = canonicalizePath(msg.path);
   preferencesStore.pinDirectory(resolved);
   broadcast({ type: "pinned_dirs_updated", paths: preferencesStore.getPinnedDirectories() });
   if (directoryService) {
@@ -48,7 +57,7 @@ export function handleUnpinDirectory(
   ctx: BrowserHandlerContext,
 ): void {
   if (ctx.preferencesStore) {
-    ctx.preferencesStore.unpinDirectory(safeRealpathSync(msg.path));
+    ctx.preferencesStore.unpinDirectory(canonicalizePath(msg.path));
     ctx.broadcast({ type: "pinned_dirs_updated", paths: ctx.preferencesStore.getPinnedDirectories() });
   }
 }
@@ -58,7 +67,10 @@ export function handleReorderPinnedDirs(
   ctx: BrowserHandlerContext,
 ): void {
   if (ctx.preferencesStore) {
-    ctx.preferencesStore.reorderPinnedDirs(msg.paths.map(safeRealpathSync));
+    // Wrap in arrow fn: map's (elem, index, array) callback would pass
+    // the array index as canonicalizePath's 2nd arg, silently breaking
+    // platform detection. See platform-path-normalization.
+    ctx.preferencesStore.reorderPinnedDirs(msg.paths.map((p) => canonicalizePath(p)));
     ctx.broadcast({ type: "pinned_dirs_updated", paths: ctx.preferencesStore.getPinnedDirectories() });
   }
 }
@@ -89,8 +101,11 @@ export function handleOpenSpecBulkArchive(
   ctx: BrowserHandlerContext,
 ): void {
   if (ctx.directoryService) {
-    execFileAsync("openspec", ["archive", "--completed"], { cwd: msg.cwd, timeout: 30000 })
-      .catch(() => {})
+    // Delegate to the shared openspec tool module. The runner handles
+    // windowsHide, timeout, and argv-array escaping.
+    // See change: platform-command-executor.
+    openspecArchiveCompleted({ cwd: msg.cwd });
+    Promise.resolve()
       .then(() => ctx.directoryService!.refreshOpenSpec(msg.cwd))
       .then((data) => {
         if (data) ctx.broadcast({ type: "openspec_update", cwd: msg.cwd, data });