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

package/packages/shared/src/bridge-register.ts

@@ -10,29 +10,92 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { createRequire } from "node:module";
 
 /**
- * Find the bundled extension directory relative to a base directory.
- * Looks for `packages/extension/` (monorepo layout) under baseDir.
- *
- * Returns null if:
- * - Directory not found
- * - No package.json in the directory
- * - Path is under /tmp/.mount_* (unstable AppImage mount)
+ * Check that a candidate path is a valid, stable extension directory.
+ * Returns true when the directory exists, contains a package.json, and
+ * is NOT under /tmp/.mount_* (unstable AppImage mount).
  */
-export function findBundledExtension(baseDir: string): string | null {
-  const candidate = path.resolve(baseDir, "packages", "extension");
-  if (!fs.existsSync(candidate) || !fs.existsSync(path.join(candidate, "package.json"))) {
-    return null;
+function isValidExtensionPath(candidate: string): boolean {
+  if (!fs.existsSync(candidate)) return false;
+  if (!fs.existsSync(path.join(candidate, "package.json"))) return false;
+  if (candidate.includes("/tmp/.mount_")) {
+    console.warn(
+      "[dashboard] AppImage detected — extension path is temporary, skipping registration:",
+      candidate,
+    );
+    return false;
   }
+  return true;
+}
 
-  // Reject unstable AppImage temp mount paths
-  if (candidate.includes("/tmp/.mount_")) {
-    console.warn("[dashboard] AppImage detected — extension path is temporary, skipping registration:", candidate);
+/**
+ * Optional dependency injection for `findBundledExtension`. Tests pass
+ * `{ resolvePackage: () => null }` to disable the node-resolver fallback.
+ */
+export interface FindExtensionDeps {
+  /**
+   * Resolve `@blackbelt-technology/pi-dashboard-extension/package.json`
+   * via Node's module resolver. Return the absolute package.json path
+   * or null. Defaults to `createRequire(import.meta.url).resolve(...)`.
+   */
+  resolvePackage?: () => string | null;
+}
+
+function defaultResolvePackage(): string | null {
+  try {
+    const req = createRequire(import.meta.url);
+    return req.resolve("@blackbelt-technology/pi-dashboard-extension/package.json");
+  } catch {
     return null;
   }
+}
+
+/**
+ * Find the bundled extension directory.
+ *
+ * Resolution order:
+ *   1. Monorepo layout: `<baseDir>/packages/extension/`.
+ *   2. Node module resolution: `@blackbelt-technology/pi-dashboard-extension/package.json`
+ *      via `require.resolve` from this module. Works in ANY install layout
+ *      (flat `node_modules/`, scoped, nested, pnpm, npm-g). This is the
+ *      canonical identity-based lookup and the only reliable strategy
+ *      when pi-dashboard is installed via `npm i -g`.
+ *
+ * Returns null if both strategies fail, the resolved directory doesn't
+ * have a package.json, or the path is under /tmp/.mount_* (AppImage).
+ *
+ * See change: unified-bootstrap-install.
+ */
+export function findBundledExtension(
+  baseDir: string,
+  deps: FindExtensionDeps = {},
+): string | null {
+  // Strategy 1: monorepo sibling layout.
+  const monorepoCandidate = path.resolve(baseDir, "packages", "extension");
+  if (isValidExtensionPath(monorepoCandidate)) return monorepoCandidate;
+
+  // Strategy 2: Node module resolver. This works for the `npm i -g
+  // pi-dashboard` layout where the extension is shipped as a runtime dep
+  // of pi-dashboard-server.
+  const resolver = deps.resolvePackage ?? defaultResolvePackage;
+  const extPkgJson = resolver();
+  if (extPkgJson) {
+    const extDir = path.dirname(extPkgJson);
+    if (isValidExtensionPath(extDir)) return extDir;
+  }
+
+  return null;
+}
 
-  return candidate;
+/** Optional overrides for testing / multi-HOME scenarios. */
+export interface BridgeRegisterOptions {
+  /**
+   * Override the HOME used to locate settings.json. When omitted,
+   * falls back to `$HOME || $USERPROFILE || os.homedir()` (existing behavior).
+   */
+  homedir?: string;
 }
 
 /**
@@ -44,12 +107,16 @@ export function findBundledExtension(baseDir: string): string | null {
  *
  * No-op if the path is already registered.
  */
-export function registerBridgeExtension(extensionPath: string): void {
+export function registerBridgeExtension(
+  extensionPath: string,
+  opts: BridgeRegisterOptions = {},
+): void {
   // Compute at call time so tests can override HOME
-  const settingsPath = path.join(
-    process.env.HOME || process.env.USERPROFILE || os.homedir(),
-    ".pi", "agent", "settings.json",
-  );
+  const home = opts.homedir
+    ?? process.env.HOME
+    ?? process.env.USERPROFILE
+    ?? os.homedir();
+  const settingsPath = path.join(home, ".pi", "agent", "settings.json");
   const settingsDir = path.dirname(settingsPath);
   fs.mkdirSync(settingsDir, { recursive: true });
 

package/packages/shared/src/browser-protocol.ts

@@ -125,6 +125,21 @@ export interface SpawnResultBrowserMessage {
   message: string;
 }
 
+/**
+ * Emitted when a session spawn fails — either because `spawnPiSession` threw,
+ * returned `{ success: false }`, or the spawned child crashed immediately.
+ * Carries enough context for the UI to render a retryable error banner
+ * instead of leaving the user staring at a silent empty state.
+ */
+export interface SpawnErrorMessage {
+  type: "spawn_error";
+  cwd: string;
+  strategy: string;
+  message: string;
+  /** Up to ~2 KB tail of stderr captured from the failed child, if any. */
+  stderr?: string;
+}
+
 export interface SessionsReorderedMessage {
   type: "sessions_reordered";
   cwd: string;
@@ -226,6 +241,58 @@ export interface PiCoreUpdateCompleteMessage {
   sessionsReloaded: number;
 }
 
+/**
+ * Bootstrap state snapshot. Mirrors `BootstrapState` in
+ * `packages/server/src/bootstrap-state.ts` but kept as a structural
+ * subset here so the shared package doesn't take a runtime dependency
+ * on the server package.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapStateSnapshot {
+  status: "ready" | "installing" | "failed";
+  progress?: { step: string; pct?: number; output?: string };
+  error?: { message: string; stack?: string };
+  version?: { pi?: string; openspec?: string; tsx?: string };
+  compatibility?: {
+    minimum: string;
+    recommended: string;
+    maximum: string | null;
+    current?: string;
+    upgradeRecommended?: boolean;
+    upgradeDashboard?: boolean;
+  };
+  bridgeRegistrationError?: string;
+}
+
+/**
+ * Broadcast on every bootstrap-state transition. Browsers use this to
+ * render the first-run install banner, the upgrade-pi progress display,
+ * and version-skew hints.
+ */
+export interface BootstrapStatusUpdateMessage {
+  type: "bootstrap_status_update";
+  state: BootstrapStateSnapshot;
+}
+
+/**
+ * Broadcast when a queued pi-dependent operation (e.g. a session-spawn
+ * request accepted with 202 during "installing") finishes running after
+ * the bootstrap transitioned to "ready". Clients that stored a ticketId
+ * from the 202 response can correlate the outcome via this message.
+ *
+ * `success` is true when the queued handler resolved without throwing;
+ * `error` carries the thrown message string when `success` is false.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapTicketCompleteMessage {
+  type: "bootstrap_ticket_complete";
+  ticketId: string;
+  success: boolean;
+  error?: string;
+}
+
 /** Sent when a package operation finishes (success or failure). */
 export interface PackageOperationCompleteMessage {
   type: "package_operation_complete";
@@ -255,6 +322,7 @@ export type ServerToBrowserMessage =
   | SessionsListBrowserMessage
   | ResumeResultBrowserMessage
   | SpawnResultBrowserMessage
+  | SpawnErrorMessage
   | SessionsReorderedMessage
   | PinnedDirsUpdatedMessage
   | TerminalAddedMessage
@@ -274,7 +342,9 @@ export type ServerToBrowserMessage =
   | BrowserPromptRequestMessage
   | BrowserPromptDismissMessage
   | BrowserPromptCancelMessage
-  | ModelsRefreshedMessage;
+  | ModelsRefreshedMessage
+  | BootstrapStatusUpdateMessage
+  | BootstrapTicketCompleteMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 

package/packages/shared/src/config.ts

@@ -41,6 +41,24 @@ export const DEFAULT_MEMORY_LIMITS: MemoryLimitsConfig = {
   maxWsBufferBytes: 4 * 1024 * 1024,
 };
 
+export interface OpenSpecPollConfig {
+  /** Poll interval in seconds. Default 30. Clamped to [5, 3600]. */
+  pollIntervalSeconds: number;
+  /** Max concurrent `openspec` CLI invocations across all dirs. Default 3. Clamped to [1, 16]. */
+  maxConcurrentSpawns: number;
+  /** `"mtime"` skips re-polling unchanged changes; `"always"` polls unconditionally. Default `"mtime"`. */
+  changeDetection: "mtime" | "always";
+  /** Max per-directory phase jitter in seconds. 0 disables jitter. Default 5. Clamped to [0, 60]. */
+  jitterSeconds: number;
+}
+
+export const DEFAULT_OPENSPEC_POLL: OpenSpecPollConfig = {
+  pollIntervalSeconds: 30,
+  maxConcurrentSpawns: 3,
+  changeDetection: "mtime",
+  jitterSeconds: 5,
+};
+
 export interface EditorConfig {
   /** Override path to code-server binary */
   binary?: string;
@@ -75,6 +93,8 @@ export interface DashboardConfig {
   defaultModel: string;
   memoryLimits: MemoryLimitsConfig;
   editor: EditorConfig;
+  /** OpenSpec background polling behavior (interval, concurrency, change detection, jitter) */
+  openspec: OpenSpecPollConfig;
   /** Networks trusted for full access without authentication (CIDR, wildcard, exact IP) */
   trustedNetworks: string[];
   /** Merged trustedNetworks + auth.bypassHosts (deduplicated). Computed at load time. */
@@ -108,6 +128,7 @@ const DEFAULTS: DashboardConfig = {
   defaultModel: "",
   memoryLimits: { ...DEFAULT_MEMORY_LIMITS },
   editor: { ...DEFAULT_EDITOR_CONFIG },
+  openspec: { ...DEFAULT_OPENSPEC_POLL },
   trustedNetworks: [],
   resolvedTrustedNetworks: [],
   cors: { allowedOrigins: [] },
@@ -117,28 +138,57 @@ const DEFAULTS: DashboardConfig = {
 
 /**
  * Parse and validate the auth config section.
- * Returns undefined if auth is not configured or has no providers.
+ *
+ * Returns undefined ONLY when nothing auth-relevant is configured — that is,
+ * when none of `providers`, `bypassHosts`, or `bypassUrls` has any content.
+ *
+ * When providers is empty but bypassHosts or bypassUrls is populated, this
+ * function returns a valid AuthConfig with an empty providers map. The auth
+ * plugin already no-ops in that case (providerRegistry.size === 0 → skip
+ * OAuth route + cookie plugin registration), so no OAuth flow activates
+ * accidentally. But returning an object here lets the caller populate
+ * resolvedTrustedNetworks from auth.bypassHosts — which is the entire
+ * point of allowing this shape. Before this change, parseAuthConfig
+ * returned undefined on empty-providers, which nuked auth.bypassHosts
+ * before the resolvedTrustedNetworks merge could read it, and users
+ * without OAuth lost remote network access after the UI started writing
+ * to auth.bypassHosts. See openspec/changes/fix-trusted-networks-no-oauth.
  */
 function parseAuthConfig(raw: any): AuthConfig | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const providers = raw.providers;
-  if (!providers || typeof providers !== "object" || Object.keys(providers).length === 0) {
-    return undefined;
-  }
-  // Validate each provider has at least clientId and clientSecret
+  const hasProviders =
+    providers && typeof providers === "object" && Object.keys(providers).length > 0;
+  const hasHosts = Array.isArray(raw.bypassHosts) && raw.bypassHosts.length > 0;
+  const hasUrls = Array.isArray(raw.bypassUrls) && raw.bypassUrls.length > 0;
+  if (!hasProviders && !hasHosts && !hasUrls) return undefined;
+
+  // Validate each provider has at least clientId and clientSecret.
+  // validProviders may end up empty when providers is {} or all entries
+  // are malformed — that's fine, the caller tolerates it as long as
+  // bypassHosts or bypassUrls carries the auth-relevant content.
   const validProviders: Record<string, AuthProviderConfig> = {};
-  for (const [key, value] of Object.entries(providers)) {
-    const p = value as any;
-    if (p && typeof p === "object" && p.clientId && p.clientSecret) {
-      validProviders[key] = {
-        clientId: p.clientId,
-        clientSecret: p.clientSecret,
-        ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
-        ...(p.name ? { name: p.name } : {}),
-      };
+  if (hasProviders) {
+    for (const [key, value] of Object.entries(providers as Record<string, unknown>)) {
+      const p = value as any;
+      if (p && typeof p === "object" && p.clientId && p.clientSecret) {
+        validProviders[key] = {
+          clientId: p.clientId,
+          clientSecret: p.clientSecret,
+          ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
+          ...(p.name ? { name: p.name } : {}),
+        };
+      }
     }
   }
-  if (Object.keys(validProviders).length === 0) return undefined;
+
+  // If providers was declared but all entries are malformed AND there is no
+  // bypass content, fall back to undefined — same "nothing auth-relevant"
+  // rule as the top-level gate.
+  if (Object.keys(validProviders).length === 0 && !hasHosts && !hasUrls) {
+    return undefined;
+  }
+
   return {
     secret: raw.secret ?? "",
     providers: validProviders,
@@ -157,6 +207,27 @@ function parseEditorConfig(raw: any): EditorConfig {
   };
 }
 
+function clampNumber(raw: any, fallback: number, min: number, max: number): number {
+  const n = typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+
+function parseOpenSpecPollConfig(raw: any): OpenSpecPollConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_OPENSPEC_POLL };
+  const changeDetection =
+    raw.changeDetection === "always" || raw.changeDetection === "mtime"
+      ? raw.changeDetection
+      : DEFAULT_OPENSPEC_POLL.changeDetection;
+  return {
+    pollIntervalSeconds: clampNumber(raw.pollIntervalSeconds, DEFAULT_OPENSPEC_POLL.pollIntervalSeconds, 5, 3600),
+    maxConcurrentSpawns: clampNumber(raw.maxConcurrentSpawns, DEFAULT_OPENSPEC_POLL.maxConcurrentSpawns, 1, 16),
+    changeDetection,
+    jitterSeconds: clampNumber(raw.jitterSeconds, DEFAULT_OPENSPEC_POLL.jitterSeconds, 0, 60),
+  };
+}
+
 function parseMemoryLimits(raw: any): MemoryLimitsConfig {
   if (!raw || typeof raw !== "object") return { ...DEFAULT_MEMORY_LIMITS };
   return {
@@ -217,6 +288,7 @@ export function loadConfig(): DashboardConfig {
       auth: parseAuthConfig(parsed.auth),
       memoryLimits: parseMemoryLimits(parsed.memoryLimits),
       editor: parseEditorConfig(parsed.editor),
+      openspec: parseOpenSpecPollConfig(parsed.openspec),
       trustedNetworks: parseTrustedNetworks(parsed.trustedNetworks),
       resolvedTrustedNetworks: [],
       cors: {

package/packages/shared/src/managed-paths.ts

@@ -1,15 +1,42 @@
 /**
- * Shared constants for the managed install directory (~/.pi-dashboard/).
+ * Shared constants + getters for the managed install directory (~/.pi-dashboard/).
  * Single source of truth — all packages import from here.
+ *
+ * Constants (MANAGED_DIR, MANAGED_BIN, PI_SETTINGS_PATH) reflect the live
+ * environment at module-load time. Production code continues to use them.
+ *
+ * Getters (getManagedDir, getManagedBin, getPiSettingsPath) accept an
+ * optional `{ homedir }` override so tests (and the bootstrap harness)
+ * can reason about alternate HOME directories without mutating globals.
  */
 import path from "node:path";
 import os from "node:os";
 
+/** Env override surface used by the getters (subset of PlatformEnv). */
+export interface ManagedPathsEnv {
+  homedir?: string;
+}
+
+/** Root directory for managed installs (pi, openspec, tsx). */
+export function getManagedDir(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi-dashboard");
+}
+
+/** Bin directory for managed install executables. */
+export function getManagedBin(env?: ManagedPathsEnv): string {
+  return path.join(getManagedDir(env), "node_modules", ".bin");
+}
+
+/** Path to pi's global settings file. */
+export function getPiSettingsPath(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi", "agent", "settings.json");
+}
+
 /** Root directory for managed installs (pi, openspec, tsx). */
-export const MANAGED_DIR = path.join(os.homedir(), ".pi-dashboard");
+export const MANAGED_DIR = getManagedDir();
 
 /** Bin directory for managed install executables. */
-export const MANAGED_BIN = path.join(MANAGED_DIR, "node_modules", ".bin");
+export const MANAGED_BIN = getManagedBin();
 
 /** Path to pi's global settings file. */
-export const PI_SETTINGS_PATH = path.join(os.homedir(), ".pi", "agent", "settings.json");
+export const PI_SETTINGS_PATH = getPiSettingsPath();

package/packages/shared/src/openspec-poller.ts

@@ -1,45 +1,31 @@
 /**
  * Polls the openspec CLI to gather change data for the session's project.
- * Uses async child processes to avoid blocking the event loop.
+ *
+ * This module is a thin aggregator over `platform/openspec.ts`: it
+ * calls the Recipe-based primitives and combines `list` + per-change
+ * `status` into the dashboard's `OpenSpecData` shape.
+ *
+ * Two public flavors:
+ *
+ *   - `pollOpenSpec` (sync) — for the bridge extension where async
+ *     isn't practical. Uses `run()` under the hood; each call blocks
+ *     the event loop for ~200-2000ms per openspec invocation.
+ *
+ *   - `pollOpenSpecAsync` (async) — for the server's directory service.
+ *     Routes through the runner's `runAsync()` so every spawn goes
+ *     through the same binary resolution, `.cmd` shell handling, and
+ *     `windowsHide: true` default as everything else. Status queries
+ *     run in parallel via `Promise.all`, keeping the event loop free
+ *     on Windows where openspec.cmd startup is slow (~2s per call).
+ *
+ * See change: consolidate-tool-resolution.
  */
-import { spawnSync, execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
+import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
 
-const execFileAsync = promisify(execFile);
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
-/** Synchronous version — only used by bridge extension where async isn't practical */
-function runOpenSpecSync(args: string[], cwd: string): unknown | null {
-  try {
-    const result = spawnSync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 10_000,
-    });
-    if (result.status !== 0 || !result.stdout) return null;
-    return JSON.parse(result.stdout);
-  } catch {
-    return null;
-  }
-}
-
-/** Async version — non-blocking, used by server */
-async function runOpenSpecAsync(args: string[], cwd: string): Promise<unknown | null> {
-  try {
-    const { stdout } = await execFileAsync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      timeout: 10_000,
-    });
-    if (!stdout) return null;
-    return JSON.parse(stdout);
-  } catch {
-    return null;
-  }
-}
-
 export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
   statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
@@ -72,30 +58,61 @@ export function buildOpenSpecData(
   return { initialized: true, changes };
 }
 
-/** Synchronous poll — blocks event loop. Used by bridge extension. */
+/**
+ * Synchronous poll — blocks the event loop. Used by the bridge extension
+ * where async isn't practical (some pi extension hooks are sync).
+ */
 export function pollOpenSpec(cwd: string): OpenSpecData {
-  const listResult = runOpenSpecSync(["list", "--json"], cwd) as any;
+  const listResult = listOr({ cwd }) as any;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
   const statusResults = new Map<string, any>();
   for (const c of listResult.changes) {
-    statusResults.set(c.name, runOpenSpecSync(["status", "--change", c.name, "--json"], cwd));
+    statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
   return buildOpenSpecData(listResult, statusResults);
 }
 
-/** Async poll — non-blocking. Used by server directory service. */
+/**
+ * Run `openspec list --json` for a single cwd. Exposed so callers that
+ * want their own concurrency control or mtime-gate logic can compose
+ * the list + per-change status calls themselves.
+ */
+export async function runOpenSpecList(cwd: string): Promise<
+  | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+  | null
+> {
+  return unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as any;
+}
+
+/**
+ * Run `openspec status --change <name> --json` for a single change.
+ * Exposed for the same reason as `runOpenSpecList`.
+ */
+export async function runOpenSpecStatus(
+  cwd: string,
+  changeName: string,
+): Promise<{ artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null> {
+  return unwrap(await runAsync(OPENSPEC_STATUS, { cwd, change: changeName }, { cwd }), null) as any;
+}
+
+/**
+ * Async poll — genuinely async. Runs per-change status queries in
+ * parallel via the shared `runAsync()`, so each spawn goes through the
+ * central binary resolution + `windowsHide: true` default.
+ */
 export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
-  const listResult = await runOpenSpecAsync(["list", "--json"], cwd) as any;
+  const listResult = unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as
+    | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+    | null;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
-  // Run all status queries in parallel
-  const entries = await Promise.all(
-    listResult.changes.map(async (c: any): Promise<[string, any]> => {
-      const status = await runOpenSpecAsync(["status", "--change", c.name, "--json"], cwd);
-      return [c.name, status];
+  const statusEntries = await Promise.all(
+    listResult.changes.map(async (c) => {
+      const result = await runAsync(OPENSPEC_STATUS, { cwd, change: c.name }, { cwd });
+      return [c.name, unwrap(result, null)] as const;
     }),
   );
-  const statusResults = new Map<string, any>(entries);
+  const statusResults = new Map<string, any>(statusEntries);
   return buildOpenSpecData(listResult, statusResults);
 }