@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

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

@@ -0,0 +1,140 @@
+/**
+ * GET /api/doctor — server-side diagnostic endpoint.
+ *
+ * Calls `runSharedChecks(...)` with server-appropriate `deps`, post-stamps
+ * `section` + `suggestion`, returns `{ checks, summary, generatedAt }`.
+ *
+ * Auth-gated identically to `/api/config`; unauthenticated requests yield
+ * the same status code as `/api/config` (the auth plugin's onRequest hook
+ * intercepts before this handler runs).
+ *
+ * On a thrown error from `runSharedChecks`, returns a 200 with a single
+ * fallback `error` row rather than a 500 — the web client always has
+ * something to render. See change: doctor-rich-output (tasks 4.1–4.5).
+ */
+import type { FastifyInstance } from "fastify";
+import path from "node:path";
+import os from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  runSharedChecks,
+  stampSectionsAndSuggestions,
+  safeExec,
+  type DoctorCheck,
+  type DoctorReport,
+  type SharedChecksDeps,
+} from "@blackbelt-technology/pi-dashboard-shared/doctor-core.js";
+
+function getManagedDir(): string {
+  return process.env.MANAGED_DIR || path.join(os.homedir(), ".pi-dashboard");
+}
+
+function detectSystemNode(): { found: boolean; path?: string } {
+  const cmd = process.platform === "win32" ? "where node" : "which node"; // platform-branch-ok: localised PATH-lookup primitive
+  const r = safeExec(cmd, { timeoutMs: 3000 });
+  if (!r.ok) return { found: false };
+  const first = r.stdout.trim().split("\n")[0];
+  return first ? { found: true, path: first } : { found: false };
+}
+
+function detectOnPath(name: string): { found: boolean; path?: string; source?: string } {
+  const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`; // platform-branch-ok: localised PATH-lookup primitive
+  const r = safeExec(cmd, { timeoutMs: 3000 });
+  if (!r.ok) return { found: false };
+  const first = r.stdout.trim().split("\n")[0];
+  return first ? { found: true, path: first, source: "system" } : { found: false };
+}
+
+function isApiKeyConfigured(): boolean {
+  try {
+    const settings = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    if (!existsSync(settings)) return false;
+    const data = JSON.parse(readFileSync(settings, "utf-8"));
+    if (data?.anthropicApiKey || data?.openaiApiKey || data?.apiKey) return true;
+    if (data?.providers && typeof data.providers === "object") {
+      for (const v of Object.values(data.providers as Record<string, unknown>)) {
+        if (v && typeof v === "object" && "apiKey" in (v as object)) return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function buildDefaultDeps(): SharedChecksDeps {
+  return {
+    managedDir: getManagedDir(),
+    detectSystemNode,
+    detectPi: () => detectOnPath("pi"),
+    detectOpenSpec: () => detectOnPath("openspec"),
+    isApiKeyConfigured,
+    probeServer: async () => {
+      const r = safeExec("curl -sf http://localhost:8000/api/health", { timeoutMs: 3000 });
+      if (!r.ok || !r.stdout.trim()) return { running: false };
+      try {
+        const h = JSON.parse(r.stdout);
+        return {
+          running: true,
+          version: typeof h.version === "string" ? h.version : undefined,
+          mode: typeof h.mode === "string" ? h.mode : undefined,
+          starter: typeof h.starter === "string" ? h.starter : null,
+          installable:
+            h.installable && typeof h.installable === "object"
+              ? {
+                  total: h.installable.total ?? 0,
+                  installed: h.installable.installed ?? 0,
+                  failed: Array.isArray(h.installable.failed) ? h.installable.failed : [],
+                }
+              : null,
+        };
+      } catch {
+        return { running: true };
+      }
+    },
+  };
+}
+
+function summarize(checks: DoctorCheck[]): DoctorReport["summary"] {
+  return {
+    ok: checks.filter((c) => c.status === "ok").length,
+    warnings: checks.filter((c) => c.status === "warning").length,
+    errors: checks.filter((c) => c.status === "error").length,
+  };
+}
+
+export interface DoctorRouteDeps {
+  /** Override for tests — substitutes a different `runSharedChecks` deps shape (or throws to exercise fault tolerance). */
+  buildDeps?: () => SharedChecksDeps;
+}
+
+export function registerDoctorRoutes(fastify: FastifyInstance, deps: DoctorRouteDeps = {}): void {
+  fastify.get("/api/doctor", async (_request, _reply): Promise<DoctorReport> => {
+    try {
+      const sharedDeps = deps.buildDeps ? deps.buildDeps() : buildDefaultDeps();
+      const checks = await runSharedChecks(sharedDeps);
+      stampSectionsAndSuggestions(checks);
+      return {
+        checks,
+        summary: summarize(checks),
+        generatedAt: Date.now(),
+      };
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      const fallback: DoctorCheck = {
+        name: "Doctor failed to produce a report",
+        section: "diagnostics",
+        status: "error",
+        message: "Unexpected internal failure",
+        detail: `${e.message}\n${(e.stack || "").split("\n").slice(0, 4).join("\n")}`,
+        suggestion:
+          "Check `~/.pi-dashboard/doctor.log` on the server, then file an issue with the captured error.",
+      };
+      return {
+        checks: [fallback],
+        summary: { ok: 0, warnings: 0, errors: 1 },
+        generatedAt: Date.now(),
+      };
+    }
+  });
+}

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

@@ -0,0 +1,194 @@
+/**
+ * REST route for `GET /api/pi-core/changelog`.
+ *
+ * Returns the parsed `CHANGELOG.md` for a core package filtered to
+ * a `(from, to]` half-open version range, plus a derived `hasBreaking`
+ * flag and a public GitHub URL for the full changelog.
+ *
+ * Gated identically to other `/api/pi-core/*` routes via the shared
+ * bootstrap-status gate.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+import type { FastifyInstance } from "fastify";
+import type {
+  ChangelogResponse,
+} from "@blackbelt-technology/pi-dashboard-shared/changelog-types.js";
+import { CORE_PACKAGE_NAMES } from "../pi-core-checker.js";
+import { parseVersion, compareVersions } from "../pi-version-skew.js";
+import {
+  findChangelogPath,
+  readPackageJson,
+  deriveChangelogUrl,
+} from "../changelog-fs.js";
+import {
+  parseChangelog,
+  readAndParseChangelog,
+  getCachedRemoteChangelog,
+  setRemoteChangelog,
+  refreshRemoteChangelogTtl,
+} from "../changelog-parser.js";
+import {
+  deriveChangelogRawUrl,
+  fetchRemoteChangelog,
+} from "../changelog-remote.js";
+import type { ChangelogRelease } from "@blackbelt-technology/pi-dashboard-shared/changelog-types.js";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
+
+export interface PiChangelogRouteDeps {
+  /** When provided, route returns 503 unless bootstrap status is "ready". */
+  bootstrapState?: BootstrapStateStore;
+}
+
+interface QueryShape {
+  pkg?: string;
+  from?: string;
+  to?: string;
+}
+
+export function registerPiChangelogRoutes(
+  fastify: FastifyInstance,
+  deps: PiChangelogRouteDeps,
+): void {
+  const { bootstrapState } = deps;
+
+  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,
+    });
+  };
+
+  fastify.get<{ Querystring: QueryShape }>(
+    "/api/pi-core/changelog",
+    { preHandler: bootstrapGate as any },
+    async (request, reply) => {
+      const pkg = (request.query.pkg ?? "").trim();
+      const from = (request.query.from ?? "").trim();
+      const to = (request.query.to ?? "").trim();
+
+      // Validate `pkg` against the core whitelist BEFORE touching
+      // the filesystem — prevents arbitrary path reads via crafted
+      // input.
+      if (!pkg || !CORE_PACKAGE_NAMES.includes(pkg)) {
+        return reply.code(400).send({
+          success: false,
+          error: `pkg must be one of: ${CORE_PACKAGE_NAMES.join(", ")}`,
+        });
+      }
+
+      // Validate version range using the existing parseVersion helper
+      // from pi-version-skew. Both endpoints are required.
+      if (!from || !to) {
+        return reply.code(400).send({
+          success: false,
+          error: "from and to query params are required",
+        });
+      }
+      if (!parseVersion(from) || !parseVersion(to)) {
+        return reply.code(400).send({
+          success: false,
+          error: "from and to must be parseable semver versions",
+        });
+      }
+
+      const located = findChangelogPath(pkg);
+
+      // Spec: package not installed / CHANGELOG missing → 200 with empty body.
+      if (!located) {
+        const body: ChangelogResponse = {
+          pkg,
+          from,
+          to,
+          releases: [],
+          hasBreaking: false,
+          changelogUrl: null,
+          parsedAt: new Date().toISOString(),
+        };
+        return body;
+      }
+
+      // Read package.json once for both URLs (raw for the parser,
+      // human for the dialog footer link).
+      const pkgJson = readPackageJson(located.packageDir);
+      const rawUrl = pkgJson ? deriveChangelogRawUrl(pkgJson.repository) : null;
+      const changelogUrl = pkgJson ? deriveChangelogUrl(pkgJson.repository) : null;
+
+      // Try remote first — the upstream CHANGELOG describes versions
+      // newer than the locally-installed tarball. Fall back to local
+      // on failure / offline / non-GitHub repo. See change:
+      // read-changelog-from-github.
+      let allReleases: ChangelogRelease[] | undefined;
+      let usedRemote = false;
+
+      if (rawUrl) {
+        const cached = getCachedRemoteChangelog(pkg);
+        if (cached && !cached.expired) {
+          // Within TTL — reuse cached result, no fetch.
+          allReleases = cached.releases;
+          usedRemote = true;
+        } else {
+          const fetchResult = await fetchRemoteChangelog(rawUrl, {
+            etag: cached?.etag ?? null,
+          });
+          if (fetchResult?.status === "ok") {
+            const parsed = parseChangelog(fetchResult.text);
+            setRemoteChangelog(pkg, parsed, fetchResult.etag);
+            allReleases = parsed;
+            usedRemote = true;
+          } else if (fetchResult?.status === "not-modified" && cached) {
+            refreshRemoteChangelogTtl(pkg);
+            allReleases = cached.releases;
+            usedRemote = true;
+          }
+          // null result (network error / offline / non-2xx): fall through
+          // to local read below.
+        }
+      }
+
+      if (!usedRemote) {
+        try {
+          allReleases = readAndParseChangelog(pkg, located.changelogPath);
+        } catch (err: any) {
+          request.log.warn(
+            { err: err?.message },
+            "[pi-changelog-routes] local read/parse failed; returning empty",
+          );
+          allReleases = [];
+        }
+      }
+
+      // Filter to (from, to]. Unparseable release versions are
+      // dropped — conservative.
+      const filtered = (allReleases ?? []).filter((r) => {
+        const rv = parseVersion(r.version);
+        if (!rv) return false;
+        return compareVersions(r.version, from) > 0 &&
+          compareVersions(r.version, to) <= 0;
+      });
+
+      const hasBreaking = filtered.some((r) => r.breaking.length > 0);
+
+      const body: ChangelogResponse = {
+        pkg,
+        from,
+        to,
+        releases: filtered,
+        hasBreaking,
+        changelogUrl,
+        parsedAt: new Date().toISOString(),
+      };
+      return body;
+    },
+  );
+}
+
+// Re-export for tests that need to bypass the cache.
+export { parseChangelog };

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

@@ -5,7 +5,7 @@
  *   POST /api/pi-core/update                 { packages?: string[] }
  *
  * Complements /api/packages/* (extension management): this endpoint covers
- * globally-installed pi CLI packages like @mariozechner/pi-coding-agent,
+ * globally-installed pi CLI packages like @earendil-works/pi-coding-agent,
  * pi-dashboard itself, pi-model-proxy, etc.
  */
 import type { FastifyInstance } from "fastify";

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

@@ -18,6 +18,7 @@ import {
   resolveAuthJsonKey,
   type ApiKeyCredential,
 } from "../provider-auth-storage.js";
+import { getLatestCatalogue } from "../provider-catalogue-cache.js";
 import { startCallbackServer } from "../oauth-callback-server.js";
 import type { PiGateway } from "../pi-gateway.js";
 import type { BrowserGateway } from "../browser-gateway.js";
@@ -87,8 +88,12 @@ export function registerProviderAuthRoutes(
   const { piGateway, browserGateway } = deps;
 
   function notifyBridges() {
+    // Tell every bridge to reload auth.json + refresh its model registry.
+    // Each bridge will then push a fresh per-session models_list (and
+    // providers_list); browsers pick those up via the existing per-session
+    // broadcast and update modelsMap / catalogue cache without needing a
+    // global wipe. See change: simplify-model-selection-channels.
     piGateway.broadcast({ type: "credentials_updated" });
-    browserGateway.broadcastToAll({ type: "models_refreshed" });
   }
 
   // List OAuth providers
@@ -98,6 +103,14 @@ export function registerProviderAuthRoutes(
 
   // Full status (OAuth + API key)
   fastify.get("/api/provider-auth/status", async () => {
+    // Cold-cache nudge: if no bridge has pushed a catalogue yet, ask
+    // every connected pi to send one. Best-effort, doesn't block this
+    // response. See change: replace-hardcoded-provider-lists.
+    if (getLatestCatalogue().length === 0) {
+      for (const sid of piGateway.getConnectedSessionIds()) {
+        piGateway.sendToSession(sid, { type: "request_providers", sessionId: sid });
+      }
+    }
     return getAuthStatus();
   });
 

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

@@ -98,13 +98,13 @@ export function registerProviderRoutes(fastify: FastifyInstance, deps: { network
       mkdirSync(dir, { recursive: true });
       writeFileSync(CONFIG_PATH, JSON.stringify(fileData, null, 2) + "\n", "utf-8");
 
-      // Broadcast credentials_updated so all sessions refresh their model registries
+      // Broadcast credentials_updated so each bridge re-reads providers.json
+      // and pushes a fresh per-session models_list. Browsers receive those
+      // pushes via the existing per-session broadcast — no global wipe.
+      // See change: simplify-model-selection-channels.
       if (piGateway) {
         piGateway.broadcast({ type: "credentials_updated" });
       }
-      if (deps.browserGateway) {
-        deps.browserGateway.broadcastToAll({ type: "models_refreshed" });
-      }
 
       return { success: true };
     },

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

@@ -19,8 +19,10 @@ import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.j
 import path from "node:path";
 import os from "node:os";
 import { localhostGuard, netmaskToCidrBits, networkAddress } from "../localhost-guard.js";
+import { readSpawnFailures } from "../spawn-failure-log.js";
 import { getPluginStatusStore } from "@blackbelt-technology/dashboard-plugin-runtime/server";
 import type { NetworkInterface } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
 
 export function registerSystemRoutes(
   fastify: FastifyInstance,
@@ -33,9 +35,10 @@ export function registerSystemRoutes(
     version?: string;
     directoryService?: DirectoryService;
     piGateway?: PiGateway;
+    bootstrapState?: BootstrapStateStore;
   },
 ) {
-  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService, piGateway } = deps;
+  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService, piGateway, bootstrapState } = deps;
 
   // Quiesce windows for the bridge `server_restarting` broadcast. See change
   // `fix-restart-bridge-auto-start-race`. Bridges that receive this message
@@ -189,6 +192,8 @@ export function registerSystemRoutes(
     return {
       ok: true,
       pid: process.pid,
+      starter: bootstrapState?.get().starter ?? "Standalone",
+      installable: bootstrapState?.get().installable,
       version: version ?? "unknown",
       uptime: Math.floor((Date.now() - serverStartTime) / 1000),
       mode: config.dev ? "dev" : "production",
@@ -223,6 +228,26 @@ export function registerSystemRoutes(
     },
   );
 
+  // Re-extract endpoint — Electron-only; 403 for Bridge/Standalone, 202 for Electron.
+  // See change: simplify-electron-bootstrap-derived-state (task 6.4).
+  fastify.post(
+    "/api/electron/reextract",
+    { preHandler: networkGuard },
+    async (_request, reply) => {
+      const starter = bootstrapState?.get().starter ?? "Standalone";
+      if (starter !== "Electron") {
+        reply.status(403);
+        return {
+          error: "reextract_not_allowed",
+          message: `Re-extract is only available when the server was started by Electron (current starter: ${starter})`,
+          starter,
+        };
+      }
+      reply.status(202);
+      return { ok: true, message: "Re-extraction scheduled. Electron will restart the server." };
+    },
+  );
+
   // Restart endpoint — flush state, spawn new server, then exit
   fastify.post<{ Body: { dev?: boolean } }>(
     "/api/restart",
@@ -269,6 +294,18 @@ export function registerSystemRoutes(
   );
 
   // Network interfaces for trusted networks UI (localhost-only for security)
+  // GET /api/spawn-failures — rolling log of failed spawn attempts. See change: spawn-failure-diagnostics.
+  fastify.get<{ Querystring: { limit?: string } }>(
+    "/api/spawn-failures",
+    async (request) => {
+      const rawLimit = request.query.limit;
+      const parsed = rawLimit !== undefined ? parseInt(rawLimit, 10) : NaN;
+      const limit = Number.isNaN(parsed) ? 50 : parsed;
+      const entries = readSpawnFailures(limit);
+      return { entries };
+    },
+  );
+
   fastify.get(
     "/api/network-interfaces",
     { preHandler: localhostGuard },