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

package/packages/server/src/provider-probe.ts

@@ -0,0 +1,234 @@
+/**
+ * Provider probe — ping a custom LLM provider's base URL + API key to verify the
+ * combination is reachable and authenticated. Used by `POST /api/providers/test`
+ * (client Test button) and re-used by the bridge's startup discovery path via
+ * the same per-API request builders.
+ *
+ * Pure helpers first (`buildProbeRequest`, `resolveProbeApiKey`), then the
+ * I/O-bearing `probeProvider`. All responses are scrubbed to never echo the
+ * resolved api key.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "providers.json");
+const REDACTED = "***";
+const DEFAULT_TIMEOUT_MS = 8000;
+const MAX_ERROR_BODY_CHARS = 500;
+const SAMPLE_LIMIT = 5;
+
+// -- Types ----------------------------------------------------------------
+
+export type ProbeApi =
+  | "openai-completions"
+  | "openai-responses"
+  | "anthropic-messages"
+  | "google-generative-ai";
+
+export interface ProbeInput {
+  baseUrl: string;
+  apiKey: string;
+  api: ProbeApi;
+  timeoutMs?: number;
+}
+
+export interface ProbeRequest {
+  url: string;
+  headers: Record<string, string>;
+}
+
+export type ProbeResult =
+  | { ok: true; status: number; modelCount: number; sample: string[] }
+  | { ok: false; status?: number; error: string };
+
+interface StoredProviderEntry {
+  baseUrl: string;
+  apiKey: string;
+  api?: string;
+}
+
+// -- Pure: build per-API-type probe request --------------------------------
+
+function stripTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+export function buildProbeRequest(input: {
+  baseUrl: string;
+  apiKey: string;
+  api: ProbeApi;
+}): ProbeRequest {
+  const base = stripTrailingSlash(input.baseUrl);
+  switch (input.api) {
+    case "openai-completions":
+    case "openai-responses":
+      return {
+        url: `${base}/models`,
+        headers: {
+          Authorization: `Bearer ${input.apiKey}`,
+          "Content-Type": "application/json",
+        },
+      };
+    case "anthropic-messages":
+      return {
+        url: `${base}/v1/models`,
+        headers: {
+          "x-api-key": input.apiKey,
+          "anthropic-version": "2023-06-01",
+          "Content-Type": "application/json",
+        },
+      };
+    case "google-generative-ai":
+      return {
+        url: `${base}/models?key=${encodeURIComponent(input.apiKey)}`,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      };
+    default:
+      throw new Error(`Unsupported api type: ${String(input.api)}`);
+  }
+}
+
+// -- Pure: resolve an apiKey value (literal / $ENV / *** REDACTED) --------
+
+export type ProvidersReader = () => Record<string, StoredProviderEntry>;
+
+export function readProvidersFromDisk(): Record<string, StoredProviderEntry> {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    return raw.providers ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export type ResolveResult =
+  | { ok: true; key: string }
+  | { ok: false; error: string };
+
+export function resolveProbeApiKey(args: {
+  apiKey: string;
+  name?: string;
+  readProviders: ProvidersReader;
+}): ResolveResult {
+  let raw = args.apiKey;
+
+  if (!raw) {
+    return { ok: false, error: "apiKey is required" };
+  }
+
+  // REDACTED sentinel: look up the real key in providers.json by name
+  if (raw === REDACTED) {
+    if (!args.name) {
+      return { ok: false, error: "No provider name given for saved API key lookup" };
+    }
+    const providers = args.readProviders();
+    const entry = providers[args.name];
+    if (!entry) {
+      return { ok: false, error: `No saved API key for provider "${args.name}"` };
+    }
+    raw = entry.apiKey;
+    if (!raw) {
+      return { ok: false, error: `Stored API key for "${args.name}" is empty` };
+    }
+  }
+
+  // $ENV_VAR indirection
+  if (raw.startsWith("$")) {
+    const envName = raw.slice(1);
+    const value = process.env[envName];
+    if (!value) {
+      return { ok: false, error: `Environment variable ${envName} is not set` };
+    }
+    return { ok: true, key: value };
+  }
+
+  return { ok: true, key: raw };
+}
+
+// -- Helpers --------------------------------------------------------------
+
+function redactErrorText(text: string, apiKey: string): string {
+  // Belt-and-braces: never let the resolved api key leak back to the caller.
+  let out = text;
+  if (apiKey && out.includes(apiKey)) {
+    out = out.split(apiKey).join("[REDACTED]");
+  }
+  return out.length > MAX_ERROR_BODY_CHARS ? out.slice(0, MAX_ERROR_BODY_CHARS) : out;
+}
+
+function extractModelIds(body: any): string[] {
+  // OpenAI-style { data: [{ id }, ...] }
+  if (body && Array.isArray(body.data)) {
+    return body.data
+      .filter((m: any) => m && typeof m.id === "string")
+      .map((m: any) => m.id as string);
+  }
+  // Google-style { models: [{ name: "models/gemini-..." }] }
+  if (body && Array.isArray(body.models)) {
+    return body.models
+      .filter((m: any) => m && typeof m.name === "string")
+      .map((m: any) => (m.name as string).replace(/^models\//, ""));
+  }
+  return [];
+}
+
+// -- I/O: probe ----------------------------------------------------------
+
+export async function probeProvider(input: ProbeInput): Promise<ProbeResult> {
+  let req: ProbeRequest;
+  try {
+    req = buildProbeRequest(input);
+  } catch (err: any) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(req.url, {
+      method: "GET",
+      headers: req.headers,
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!response.ok) {
+      let bodyText = "";
+      try {
+        bodyText = await response.text();
+      } catch {
+        bodyText = "";
+      }
+      const excerpt = redactErrorText(
+        bodyText || response.statusText || `HTTP ${response.status}`,
+        input.apiKey,
+      );
+      return { ok: false, status: response.status, error: excerpt };
+    }
+
+    let body: any = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = null;
+    }
+    const ids = extractModelIds(body);
+    return {
+      ok: true,
+      status: response.status,
+      modelCount: ids.length,
+      sample: ids.slice(0, SAMPLE_LIMIT),
+    };
+  } catch (err: any) {
+    clearTimeout(timer);
+    const message = err?.message ?? String(err);
+    return { ok: false, error: redactErrorText(message, input.apiKey) };
+  }
+}

package/packages/server/src/restart-helper.ts

@@ -0,0 +1,130 @@
+/**
+ * Cross-platform restart helper for POST /api/restart.
+ *
+ * Replaces the previous `sh -c` script that depended on `lsof` and `curl` —
+ * neither of which exists on Windows. The new implementation spawns a
+ * detached plain-Node orchestrator (via `node -e`) that:
+ *   1. Polls the port via net.createConnection until free
+ *   2. Spawns the new server with the same loader + args as the current run
+ *   3. Polls /api/health via http.get until it returns ok
+ *   4. On failure, appends a line to ~/.pi/dashboard/restart.log
+ *
+ * See change: fix-windows-server-parity.
+ */
+import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import os from "node:os";
+import path from "node:path";
+
+export interface RestartParams {
+  /** Absolute path to the server CLI (typically process.argv[1]) */
+  cliPath: string;
+  /** Loader value from --import (e.g. file:// URL). Empty string = none. */
+  loader: string;
+  /** Port the server listens on */
+  port: number;
+  /** Extra args to pass to `cli start` (e.g. ["--dev"]) */
+  extraArgs: string[];
+  /** Override Node binary (defaults to process.execPath) */
+  execPath?: string;
+}
+
+/**
+ * Build the JS source (to run via `node -e`) that performs the restart
+ * orchestration. Exported for testing. Pure function — no I/O.
+ */
+export function buildOrchestratorScript(params: RestartParams): string {
+  const execPath = params.execPath ?? process.execPath;
+  const logPath = path.join(os.homedir(), ".pi", "dashboard", "restart.log");
+  const spawnArgs: string[] = [];
+  if (params.loader) {
+    spawnArgs.push("--import", params.loader);
+  }
+  spawnArgs.push(params.cliPath, "start", ...params.extraArgs);
+
+  // The script runs in a fresh Node process. Keep it self-contained and use
+  // only built-ins (net, http, fs, child_process). JSON.stringify is used to
+  // embed strings safely (handles quotes, backslashes, Windows paths).
+  return `
+const net = require("node:net");
+const http = require("node:http");
+const { spawn } = require("node:child_process"); // ban:child_process-ok — runs in a detached 'node -e' process, not in-host
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PORT = ${params.port};
+const EXEC = ${JSON.stringify(execPath)};
+const ARGS = ${JSON.stringify(spawnArgs)};
+const LOG_PATH = ${JSON.stringify(logPath)};
+
+function log(msg) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, "[" + new Date().toISOString() + "] " + msg + "\\n");
+  } catch (_) { /* ignore */ }
+}
+
+function portFree(port) {
+  return new Promise(resolve => {
+    const sock = net.createConnection({ port, host: "127.0.0.1" });
+    let done = false;
+    const finish = (free) => { if (done) return; done = true; try { sock.destroy(); } catch(_){} resolve(free); };
+    sock.setTimeout(500);
+    sock.once("connect", () => finish(false));
+    sock.once("error", () => finish(true));
+    sock.once("timeout", () => finish(true));
+  });
+}
+
+function healthOk() {
+  return new Promise(resolve => {
+    const req = http.get({ host: "127.0.0.1", port: PORT, path: "/api/health", timeout: 1000 }, res => {
+      resolve(res.statusCode === 200);
+      res.resume();
+    });
+    req.once("error", () => resolve(false));
+    req.once("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+(async () => {
+  // 1. Wait for port to be free (up to 10s)
+  for (let i = 0; i < 20; i++) {
+    if (await portFree(PORT)) break;
+    await sleep(500);
+  }
+
+  // 2. Spawn new server
+  const child = spawn(EXEC, ARGS, { detached: true, stdio: "ignore", env: process.env });
+  child.unref();
+
+  // 3. Poll health (up to 10s)
+  for (let i = 0; i < 20; i++) {
+    await sleep(500);
+    if (await healthOk()) {
+      process.exit(0);
+    }
+  }
+
+  log("restart failed: new server did not respond to /api/health within 10s");
+  process.exit(1);
+})();
+`;
+}
+
+/**
+ * Spawn a detached orchestrator child that restarts the server.
+ * Returns immediately (the caller is expected to exit shortly after).
+ */
+export function spawnRestart(params: RestartParams): void {
+  const script = buildOrchestratorScript(params);
+  const execPath = params.execPath ?? process.execPath;
+  const child = spawn(execPath, ["-e", script], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env },
+    windowsHide: true,
+  });
+  child.unref();
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Bootstrap REST API routes: `/api/bootstrap/status`, `/api/bootstrap/upgrade-pi`,
+ * `/api/bootstrap/retry`.
+ *
+ * The routes are thin — they read/write the injected `BootstrapStateStore`
+ * and delegate actual install work to the supplied `trigger` callbacks.
+ * Keeping triggers as callbacks lets the CLI wire them to `bootstrapInstall`
+ * while tests wire them to mocks.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import type { FastifyInstance } from "fastify";
+import { randomUUID } from "node:crypto";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
+import type { NetworkGuard } from "./route-deps.js";
+
+export interface BootstrapRouteDeps {
+  bootstrapState: BootstrapStateStore;
+  networkGuard: NetworkGuard;
+  /**
+   * Trigger a pi upgrade. Called when `POST /api/bootstrap/upgrade-pi`
+   * succeeds the 409-gate. Implementation is responsible for setting
+   * state to "installing" before returning, and to "ready"/"failed"
+   * when complete. Must NOT throw synchronously.
+   */
+  triggerUpgradePi: (ticketId: string) => Promise<void>;
+  /**
+   * Trigger a retry of the last bootstrap install. Called when
+   * `POST /api/bootstrap/retry` succeeds the 409-gate. Implementation
+   * should re-run the same install that failed and flip status back to
+   * "installing" before returning.
+   */
+  triggerRetry: (ticketId: string) => Promise<void>;
+}
+
+export function registerBootstrapRoutes(
+  fastify: FastifyInstance,
+  deps: BootstrapRouteDeps,
+): void {
+  const { bootstrapState, networkGuard, triggerUpgradePi, triggerRetry } = deps;
+
+  fastify.get(
+    "/api/bootstrap/status",
+    { preHandler: networkGuard },
+    async () => {
+      return bootstrapState.get();
+    },
+  );
+
+  fastify.post(
+    "/api/bootstrap/upgrade-pi",
+    { preHandler: networkGuard },
+    async (_request, reply) => {
+      const current = bootstrapState.get();
+      if (current.status === "installing") {
+        return reply.code(409).send({
+          error: "bootstrap is currently installing; try again when status becomes ready or failed",
+          status: current.status,
+        });
+      }
+      const ticketId = randomUUID();
+      // Fire-and-forget. Errors flow through state.
+      void triggerUpgradePi(ticketId).catch((err) => {
+        console.error("[bootstrap-routes] upgrade-pi trigger failed:", err);
+      });
+      return reply.code(202).send({ ticketId, status: "accepted" });
+    },
+  );
+
+  fastify.post(
+    "/api/bootstrap/retry",
+    { preHandler: networkGuard },
+    async (_request, reply) => {
+      const current = bootstrapState.get();
+      if (current.status !== "failed") {
+        return reply.code(409).send({
+          error: "retry is only valid when status is failed",
+          status: current.status,
+        });
+      }
+      const ticketId = randomUUID();
+      void triggerRetry(ticketId).catch((err) => {
+        console.error("[bootstrap-routes] retry trigger failed:", err);
+      });
+      return reply.code(202).send({ ticketId, status: "accepted" });
+    },
+  );
+}

package/packages/server/src/routes/openspec-routes.ts

@@ -30,9 +30,16 @@ export function registerOpenSpecRoutes(
     networkGuard: NetworkGuard;
     /** Optional — called after a successful toggle to trigger openspec_update. */
     onOpenSpecChanged?: OpenSpecBroadcaster;
+    /**
+     * Optional bootstrap state. When provided AND status !== "ready", the
+     * `/api/pi-resources` endpoint returns an empty result set with a
+     * `bootstrap` passthrough so the UI can render "pi not yet installed".
+     * See change: unified-bootstrap-install §5.4.
+     */
+    bootstrapState?: import("../bootstrap-state.js").BootstrapStateStore;
   },
 ) {
-  const { sessionManager, preferencesStore, directoryService, networkGuard, onOpenSpecChanged } = deps;
+  const { sessionManager, preferencesStore, directoryService, networkGuard, onOpenSpecChanged, bootstrapState } = deps;
 
   // OpenSpec archive listing endpoint
   fastify.get<{ Querystring: { cwd?: string } }>(
@@ -59,6 +66,23 @@ export function registerOpenSpecRoutes(
         reply.code(400);
         return { success: false, error: "cwd parameter required" } satisfies ApiResponse;
       }
+      // Bootstrap gate: during degraded-mode install, return empty result
+      // with a `bootstrap` field so the UI can render the "pi not yet
+      // installed" state. See change: unified-bootstrap-install §5.4.
+      if (bootstrapState) {
+        const bs = bootstrapState.get();
+        if (bs.status !== "ready") {
+          return {
+            success: true,
+            data: {
+              local: { extensions: [], skills: [], prompts: [] },
+              global: { extensions: [], skills: [], prompts: [] },
+              packages: [],
+              bootstrap: bs,
+            },
+          } satisfies ApiResponse;
+        }
+      }
       const forceRefresh = request.query.refresh === "true" || request.query.refresh === "1";
       let data = forceRefresh ? undefined : directoryService.getPiResources(cwd);
       if (!data) {

package/packages/server/src/routes/pi-core-routes.ts

@@ -18,10 +18,16 @@ import type {
 import type { PiCoreChecker } from "../pi-core-checker.js";
 import type { PiCoreUpdater } from "../pi-core-updater.js";
 import { PackageOperationBusyError } from "../package-manager-wrapper.js";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
 
 export interface PiCoreRouteDeps {
 	piCoreChecker: PiCoreChecker;
 	piCoreUpdater: PiCoreUpdater;
+	/**
+	 * When provided, pi-core endpoints return 503 unless bootstrap
+	 * status is "ready". See change: unified-bootstrap-install §5.5.
+	 */
+	bootstrapState?: BootstrapStateStore;
 	/**
 	 * Called after the updater finishes a batch (success or per-package failure).
 	 * The server wires this to broadcast a `pi_core_update_complete` WS message
@@ -38,12 +44,28 @@ export function registerPiCoreRoutes(
 	fastify: FastifyInstance,
 	deps: PiCoreRouteDeps,
 ): void {
-	const { piCoreChecker, piCoreUpdater } = deps;
+	const { piCoreChecker, piCoreUpdater, bootstrapState } = deps;
+
+	/** Gate: 503 unless bootstrap is ready. Returns undefined when OK to proceed. */
+	const bootstrapGate = async (
+		_req: unknown,
+		reply: { code: (n: number) => { send: (body: unknown) => unknown } },
+	): Promise<unknown> => {
+		if (!bootstrapState) return undefined;
+		const status = bootstrapState.get().status;
+		if (status === "ready") return undefined;
+		return reply.code(503).send({
+			success: false,
+			error: `pi not yet installed (bootstrap status: ${status})`,
+			bootstrap: status,
+		});
+	};
 
 	// ── GET /api/pi-core/versions ──────────────────────────────────
 
 	fastify.get<{ Querystring: { refresh?: string } }>(
 		"/api/pi-core/versions",
+		{ preHandler: bootstrapGate as any },
 		async (request) => {
 			const refresh = request.query.refresh === "true";
 			try {
@@ -59,6 +81,7 @@ export function registerPiCoreRoutes(
 
 	fastify.post<{ Body: PiCoreUpdateRequest }>(
 		"/api/pi-core/update",
+		{ preHandler: bootstrapGate as any },
 		async (request, reply) => {
 			const requested = request.body?.packages ?? [];
 

package/packages/server/src/routes/provider-auth-routes.ts

@@ -1,7 +1,6 @@
 /**
  * REST routes for browser-based pi provider authentication.
  */
-import { exec } from "node:child_process";
 import type { FastifyInstance } from "fastify";
 import {
   getProviderHandler,
@@ -66,15 +65,16 @@ function makeFlowId(): string {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
+// Delegate to the shared platform primitive. The cross-OS dispatch
+// (open/start/xdg-open) and URL escaping live in
+// `packages/shared/src/platform/commands.ts`.
+// See change: consolidate-platform-handlers.
+import { openBrowser as platformOpenBrowser } from "@blackbelt-technology/pi-dashboard-shared/platform/commands.js";
+
 /** Open a URL in the system's default browser */
 function openInBrowser(url: string): void {
-  const cmd = process.platform === "darwin"
-    ? `open ${JSON.stringify(url)}`
-    : process.platform === "win32"
-      ? `start "" ${JSON.stringify(url)}`
-      : `xdg-open ${JSON.stringify(url)}`;
-  exec(cmd, (err) => {
-    if (err) console.error("[provider-auth] Failed to open browser:", err.message);
+  platformOpenBrowser(url, {
+    onError: (err) => console.error("[provider-auth] Failed to open browser:", err.message),
   });
 }
 

package/packages/server/src/routes/provider-routes.ts

@@ -8,6 +8,7 @@ import { join, dirname } from "node:path";
 import type { NetworkGuard } from "./route-deps.js";
 import type { PiGateway } from "../pi-gateway.js";
 import type { BrowserGateway } from "../browser-gateway.js";
+import { probeProvider, resolveProbeApiKey, type ProbeApi } from "../provider-probe.js";
 
 const REDACTED = "***";
 const CONFIG_PATH = join(homedir(), ".pi", "agent", "providers.json");
@@ -108,4 +109,46 @@ export function registerProviderRoutes(fastify: FastifyInstance, deps: { network
       return { success: true };
     },
   );
+
+  // Test a provider configuration without saving it. Accepts literal api keys,
+  // $ENV_VAR references, or the REDACTED sentinel (***) for already-saved entries.
+  fastify.post(
+    "/api/providers/test",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const body = request.body as Record<string, any> | null;
+      if (!body || typeof body !== "object") {
+        return reply.code(400).send({ ok: false, error: "Invalid body" });
+      }
+      const name = typeof body.name === "string" ? body.name : undefined;
+      const baseUrl = typeof body.baseUrl === "string" ? body.baseUrl.trim() : "";
+      const apiKey = typeof body.apiKey === "string" ? body.apiKey : "";
+      const api = typeof body.api === "string" ? (body.api as ProbeApi) : undefined;
+      if (!baseUrl) {
+        return reply.code(400).send({ ok: false, error: "baseUrl is required" });
+      }
+      if (!apiKey) {
+        return reply.code(400).send({ ok: false, error: "apiKey is required" });
+      }
+      if (!api) {
+        return reply.code(400).send({ ok: false, error: "api type is required" });
+      }
+
+      const resolved = resolveProbeApiKey({
+        apiKey,
+        name,
+        readProviders: readProvidersRaw,
+      });
+      if (!resolved.ok) {
+        return { ok: false, error: resolved.error };
+      }
+
+      const result = await probeProvider({
+        baseUrl,
+        apiKey: resolved.key,
+        api,
+      });
+      return result;
+    },
+  );
 }

package/packages/server/src/routes/recommended-routes.ts

@@ -195,18 +195,16 @@ export function registerRecommendedRoutes(
 			}>;
 		}
 
-		let installedGlobal: Array<{ source: string; installedPath?: string }> = [];
-		let installedLocal: Array<{ source: string; installedPath?: string }> = [];
-		try {
-			installedGlobal = (await deps.packageManagerWrapper.listInstalled("global")) as any[];
-		} catch {
-			/* proceed with empty */
-		}
-		try {
-			installedLocal = (await deps.packageManagerWrapper.listInstalled("local")) as any[];
-		} catch {
-			/* proceed with empty */
-		}
+		// Run global + local listInstalled in parallel to halve cold-start
+		// latency. On Windows where each call instantiates pi's
+		// DefaultPackageManager (1-3s cold), sequential awaits were making
+		// the "Loading recommended extensions" spinner stick for ~15s.
+		const [installedGlobalRes, installedLocalRes] = await Promise.allSettled([
+			deps.packageManagerWrapper.listInstalled("global"),
+			deps.packageManagerWrapper.listInstalled("local"),
+		]);
+		const installedGlobal = (installedGlobalRes.status === "fulfilled" ? installedGlobalRes.value : []) as Array<{ source: string; installedPath?: string }>;
+		const installedLocal = (installedLocalRes.status === "fulfilled" ? installedLocalRes.value : []) as Array<{ source: string; installedPath?: string }>;
 
 		// Include both global + project-local settings.json `packages[]`.
 		// The server's CWD is a reasonable proxy for the active project.