@blackbelt-technology/pi-agent-dashboard 0.2.9 → 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/file-routes.ts

@@ -6,7 +6,7 @@ import type { SessionManager } from "../memory-session-manager.js";
 import type { PreferencesStore } from "../preferences-store.js";
 import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { NetworkGuard } from "./route-deps.js";
-import { listDirectories } from "../browse.js";
+import { listDirectories, createDirectory } from "../browse.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 
@@ -21,12 +21,15 @@ export function registerFileRoutes(
   const { sessionManager, preferencesStore, networkGuard } = deps;
 
   // Directory browse endpoint
-  fastify.get<{ Querystring: { path?: string } }>(
+  fastify.get<{ Querystring: { path?: string; q?: string } }>(
     "/api/browse",
     { preHandler: networkGuard },
     async (request) => {
       try {
-        const result = await listDirectories(request.query.path || undefined);
+        const result = await listDirectories(
+          request.query.path || undefined,
+          request.query.q || undefined,
+        );
         return { success: true, data: result } satisfies ApiResponse;
       } catch {
         return { success: false, error: "directory not found" } satisfies ApiResponse;
@@ -34,6 +37,30 @@ export function registerFileRoutes(
     },
   );
 
+  // Directory create endpoint
+  fastify.post<{ Body: { parent?: unknown; name?: unknown } }>(
+    "/api/browse/mkdir",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const body = request.body ?? {};
+      const parent = typeof body.parent === "string" ? body.parent : "";
+      const name = typeof body.name === "string" ? body.name : "";
+      try {
+        const newPath = await createDirectory(parent, name);
+        return { success: true, data: { path: newPath } } satisfies ApiResponse;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "mkdir failed";
+        // Map known errors to status codes; unknown → 500
+        if (msg === "invalid name") reply.code(400);
+        else if (msg === "parent not found") reply.code(404);
+        else if (msg === "parent is not a directory") reply.code(400);
+        else if (msg === "already exists") reply.code(409);
+        else reply.code(500);
+        return { success: false, error: msg } satisfies ApiResponse;
+      }
+    },
+  );
+
   // File read endpoint — read file content or list directory
   fastify.get<{ Querystring: { cwd?: string; path?: string } }>(
     "/api/file",

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

@@ -8,9 +8,19 @@ import type { DirectoryService } from "../directory-service.js";
 import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { NetworkGuard } from "./route-deps.js";
 import { scanOpenSpecArchive } from "../openspec-archive.js";
+import {
+  readTasks,
+  toggleTask,
+  NotFoundError,
+  LineMismatchError,
+  NotACheckboxError,
+} from "../openspec-tasks.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 
+/** Callback to broadcast an openspec_update after a successful toggle. */
+export type OpenSpecBroadcaster = (cwd: string) => void;
+
 export function registerOpenSpecRoutes(
   fastify: FastifyInstance,
   deps: {
@@ -18,9 +28,18 @@ export function registerOpenSpecRoutes(
     preferencesStore: PreferencesStore;
     directoryService: DirectoryService;
     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 } = deps;
+  const { sessionManager, preferencesStore, directoryService, networkGuard, onOpenSpecChanged, bootstrapState } = deps;
 
   // OpenSpec archive listing endpoint
   fastify.get<{ Querystring: { cwd?: string } }>(
@@ -47,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) {
@@ -96,4 +132,74 @@ export function registerOpenSpecRoutes(
       }
     },
   );
+
+  // --- Tasks.md list + toggle ---
+
+  fastify.get<{ Querystring: { cwd?: string; change?: string } }>(
+    "/api/openspec/tasks",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd, change } = request.query;
+      if (!cwd || !change) {
+        reply.code(400);
+        return { success: false, error: "cwd and change query params required" } satisfies ApiResponse;
+      }
+      try {
+        const tasks = await readTasks(cwd, change);
+        const groups = Array.from(new Set(tasks.map((t) => t.group).filter((g) => g.length > 0)));
+        return { success: true, data: { tasks, groups } } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof NotFoundError) {
+          reply.code(404);
+          return { success: false, error: "tasks.md not found" } satisfies ApiResponse;
+        }
+        reply.code(500);
+        return { success: false, error: err?.message ?? "read error" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  fastify.post<{
+    Body: { cwd?: string; change?: string; id?: string; done?: boolean; line?: number };
+  }>(
+    "/api/openspec/tasks/toggle",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const body = request.body ?? {};
+      const { cwd, change, id, done, line } = body;
+      if (
+        typeof cwd !== "string" ||
+        typeof change !== "string" ||
+        typeof id !== "string" ||
+        typeof done !== "boolean" ||
+        typeof line !== "number"
+      ) {
+        reply.code(400);
+        return { success: false, error: "invalid body" } satisfies ApiResponse;
+      }
+      try {
+        const task = await toggleTask(cwd, change, id, done, line);
+        // Fire-and-forget: refresh cache + broadcast openspec_update.
+        directoryService.refreshOpenSpec(cwd).then(() => {
+          onOpenSpecChanged?.(cwd);
+        }).catch(() => {});
+        return { success: true, data: { task } } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof NotFoundError) {
+          reply.code(404);
+          return { success: false, error: "tasks.md not found" } satisfies ApiResponse;
+        }
+        if (err instanceof LineMismatchError) {
+          reply.code(409);
+          return { success: false, error: "line mismatch" } satisfies ApiResponse;
+        }
+        if (err instanceof NotACheckboxError) {
+          reply.code(400);
+          return { success: false, error: "target line is not a checkbox" } satisfies ApiResponse;
+        }
+        reply.code(500);
+        return { success: false, error: err?.message ?? "toggle error" } satisfies ApiResponse;
+      }
+    },
+  );
 }