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

package/packages/server/src/cli.ts

@@ -17,17 +17,74 @@
  */
 import { createServer, type ServerConfig } from "./server.js";
 import { loadConfig, ensureConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
-import { spawn } from "node:child_process";
+import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import { spawnNodeScript } from "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { readPid, isProcessAlive, removePid, isServerRunning } from "./server-pid.js";
+import { readPid, removePid, isServerRunning } from "./server-pid.js";
+import {
+  findPortHolders as platformFindPortHolders,
+  isProcessAlive as platformIsProcessAlive,
+  killProcess as platformKillProcess,
+  parseNetstatListeners as platformParseNetstatListeners,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+
+// Re-exports for back-compat — other modules / tests may import these from cli.
+export const parseNetstatListeners = platformParseNetstatListeners;
+export function findPortHolders(
+  port: number,
+  execImpl?: (cmd: string, opts: { encoding: "utf-8" }) => string,
+): number[] {
+  return platformFindPortHolders(port, execImpl ? { exec: execImpl } : undefined);
+}
 import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
 import { discoverDashboard } from "@blackbelt-technology/pi-dashboard-shared/mdns-discovery.js";
 import { resolveJitiImport } from "@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js";
+import { assertNodeVersionSupported } from "./node-guard.js";
+import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { bootstrapInstall } from "@blackbelt-technology/pi-dashboard-shared/bootstrap-install.js";
+import {
+  findBundledExtension,
+  registerBridgeExtension,
+} from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
+import type { DashboardServer } from "./server.js";
+import { updateBootstrapCompatibility } from "./pi-version-skew.js";
+import type { BootstrapStateStore } from "./bootstrap-state.js";
 
-const SUBCOMMANDS = ["start", "stop", "restart", "status"] as const;
+/**
+ * Emit a stderr warning at CLI startup when the resolved pi version is
+ * below `piCompatibility.minimum` (blocking) or below `.recommended`
+ * (advisory). Reads from the already-populated `bootstrapState` so no
+ * additional I/O happens here. See change: warn-pi-version-skew-in-cli.
+ */
+function logCompatibilityWarning(store: BootstrapStateStore): void {
+  const s = store.get();
+  const c = s.compatibility;
+  if (!c || !c.current) return;
+  // Below minimum: `updateBootstrapCompatibility` sets `error.message`.
+  // We treat the presence of a blocking error + upgradeRecommended as the
+  // below-minimum signal; `upgradeRecommended` alone means below-recommended.
+  if (s.error?.message && c.upgradeRecommended) {
+    console.error(
+      `[bootstrap] ⚠ pi ${c.current} is below the required minimum ${c.minimum}.`,
+    );
+    console.error(
+      `[bootstrap]   All pi-dependent features (sessions, resources, openspec) will return 503.`,
+    );
+    console.error(`[bootstrap]   Run: pi-dashboard upgrade-pi`);
+    return;
+  }
+  if (c.upgradeRecommended) {
+    console.warn(
+      `[bootstrap] pi ${c.current} is below the recommended ${c.recommended} — consider running \`pi-dashboard upgrade-pi\``,
+    );
+  }
+}
+
+const SUBCOMMANDS = ["start", "stop", "restart", "status", "upgrade-pi"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
 export interface ParsedArgs {
@@ -87,6 +144,7 @@ export function buildConfig(flags: Partial<ServerConfig>): ServerConfig {
     maxStringFieldSize: fileConfig.memoryLimits.maxStringFieldSize,
     maxWsBufferBytes: fileConfig.memoryLimits.maxWsBufferBytes,
     editor: fileConfig.editor,
+    openspec: fileConfig.openspec,
     resolvedTrustedNetworks: fileConfig.resolvedTrustedNetworks,
     corsAllowedOrigins: fileConfig.cors.allowedOrigins,
   };
@@ -94,8 +152,17 @@ export function buildConfig(flags: Partial<ServerConfig>): ServerConfig {
 
 /**
  * Run the server in the foreground (original behavior).
+ *
+ * After the server starts listening, the degraded-mode bootstrap kicks
+ * off: if `pi` is not resolvable via the ToolRegistry, the server flips
+ * `bootstrapState` to "installing" and begins a background
+ * `bootstrapInstall`. Session-spawn and other pi-dependent endpoints
+ * queue or 503 during this window (see change tasks §5).
+ *
+ * See change: unified-bootstrap-install.
  */
 async function runForeground(config: ServerConfig): Promise<void> {
+  assertNodeVersionSupported();
   const server = await createServer(config);
 
   let shuttingDown = false;
@@ -114,12 +181,141 @@ async function runForeground(config: ServerConfig): Promise<void> {
   process.on("SIGTERM", shutdown);
 
   await server.start();
+
+  // Kick off the degraded-mode first-run bootstrap if pi is unresolvable.
+  // Runs async — server is already listening, so UI + non-pi endpoints
+  // remain fully operational during the ~30s install window.
+  // TODO(single-dashboard-per-home): when home-lock wiring lands, wrap
+  // this inside the acquired lock to serialize concurrent first-run
+  // installs from multiple dashboard invocations on the same HOME.
+  runDegradedModeBootstrap(server).catch((err) => {
+    console.error("[bootstrap] unexpected failure in bootstrap orchestrator:", err);
+  });
+}
+
+/**
+ * Orchestrate the first-run bootstrap flow.
+ *
+ *  - If pi is already resolvable → leave `bootstrapState` at the default
+ *    "ready" and return immediately.
+ *  - Otherwise flip to "installing", run `bootstrapInstall`, then:
+ *      • on success, rescan the registry, attempt bridge registration
+ *        (failures are non-fatal and land in `bridgeRegistrationError`),
+ *        flip to "ready".
+ *      • on failure, flip to "failed" with the error.
+ *
+ * Structured log lines at each transition aid diagnosis in daemon-mode
+ * (stdout goes to ~/.pi/dashboard/server.log).
+ */
+async function runDegradedModeBootstrap(server: DashboardServer): Promise<void> {
+  const registry = getDefaultRegistry();
+  const initial = registry.resolve("pi");
+
+  if (initial.ok) {
+    // Default state is "ready" — no change needed. Log once for clarity.
+    console.log(`[bootstrap] ready (pi resolved via ${initial.source})`);
+    // Populate version-skew compatibility info even when no install was
+    // needed — the UI banner renders upgradeRecommended hints.
+    try {
+      const serverPkg = path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        "..",
+        "package.json",
+      );
+      updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
+    } catch (err) {
+      console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
+    }
+    return;
+  }
+
+  const installPackages = ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"];
+  server.bootstrapState.setLastInstallPackages(installPackages);
+  console.log("[bootstrap] installing (pi unresolved, running background install)");
+  server.bootstrapState.set({
+    status: "installing",
+    progress: { step: "pi", output: "starting install…" },
+    error: undefined,
+  });
+
+  try {
+    const res = await bootstrapInstall({
+      packages: installPackages,
+      progress: (p) => {
+        server.bootstrapState.set({
+          progress: { step: p.step, output: p.output },
+        });
+      },
+    });
+
+    if (!res.ok) {
+      console.error(`[bootstrap] failed: ${res.error}`);
+      server.bootstrapState.set({
+        status: "failed",
+        error: { message: res.error },
+        progress: undefined,
+      });
+      return;
+    }
+
+    // Rescan registry so pi is re-resolved after the fresh install.
+    // If `rescan` is not exposed, the resolver's strategy chain re-runs
+    // on the next `resolve()` call anyway; we just want fresh timing.
+    type Rescannable = { rescan?: (name: string) => void };
+    const maybeRescan = (registry as unknown as Rescannable).rescan;
+    if (typeof maybeRescan === "function") maybeRescan.call(registry, "pi");
+
+    // Attempt bridge registration. Failures are non-fatal per spec §10.3.
+    let bridgeErr: string | undefined;
+    try {
+      const extPath = findBundledExtension(process.cwd());
+      if (extPath) {
+        registerBridgeExtension(extPath);
+      } else {
+        bridgeErr = "bundled extension not found after install";
+      }
+    } catch (err) {
+      bridgeErr = err instanceof Error ? err.message : String(err);
+    }
+
+    server.bootstrapState.set({
+      status: "ready",
+      progress: undefined,
+      error: undefined,
+      bridgeRegistrationError: bridgeErr,
+    });
+    // Populate compatibility info after a successful install.
+    try {
+      const serverPkg = path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        "..",
+        "package.json",
+      );
+      updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
+    } catch (err) {
+      console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
+    }
+    console.log(
+      `[bootstrap] ready (installed ${res.installed.join(", ")}${bridgeErr ? `; bridge warning: ${bridgeErr}` : ""})`,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[bootstrap] failed: ${message}`);
+    server.bootstrapState.set({
+      status: "failed",
+      error: { message },
+      progress: undefined,
+    });
+  }
 }
 
 /**
  * Start the server as a detached background daemon.
  */
 async function cmdStart(config: ServerConfig): Promise<void> {
+  assertNodeVersionSupported();
   const running = await isServerRunning(config.port);
   if (running) {
     console.log(`Dashboard server is already running (pid ${running})`);
@@ -146,10 +342,14 @@ async function cmdStart(config: ServerConfig): Promise<void> {
   try {
     tsLoader = resolveJitiImport();
   } catch {
-    // Fallback to tsx when jiti is not available (e.g. running outside pi)
+    // Fallback to tsx when jiti is not available (e.g. running outside pi).
+    // The loader is passed to `node --import`; on Windows, Node >= 20 rejects
+    // raw absolute paths with a drive letter (parsed as URL scheme), so we
+    // return a file:// URL. See change: fix-windows-server-parity.
     try {
       const tsxMain = createRequire(cliPath).resolve("tsx");
-      tsLoader = path.join(path.dirname(tsxMain), "esm", "index.mjs");
+      const tsxLoaderPath = path.join(path.dirname(tsxMain), "esm", "index.mjs");
+      tsLoader = pathToFileURL(tsxLoaderPath).href;
     } catch {
       console.error(
         "[pi-dashboard] Cannot find TypeScript loader. " +
@@ -159,22 +359,45 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     }
   }
 
-  // Redirect daemon stdout/stderr to a log file for crash diagnosis
-  const logDir = path.join(process.env.HOME ?? "~", ".pi", "dashboard");
+  // Redirect daemon stdout/stderr to a log file for crash diagnosis.
+  // Log is opened in append mode ("a") so output from prior start attempts
+  // is preserved across retries — critical for diagnosing intermittent or
+  // silent launch failures. A timestamped header line distinguishes runs.
+  // See change: fix-windows-server-parity.
+  const logDir = path.join(os.homedir(), ".pi", "dashboard");
   fs.mkdirSync(logDir, { recursive: true });
-  const logFd = fs.openSync(path.join(logDir, "server.log"), "w");
-
-  const child = spawn(process.execPath, ["--import", tsLoader, cliPath, ...args], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: { ...process.env },
+  const logPath = path.join(logDir, "server.log");
+  const logFd = fs.openSync(logPath, "a");
+  fs.writeSync(
+    logFd,
+    `\n[${new Date().toISOString()}] pi-dashboard start (parent pid ${process.pid}, port ${config.port})\n`,
+  );
+
+  // Both tsLoader and cliPath are wrapped as file:// URLs by spawnNodeScript.
+  // Required on Windows for node --import (see change: fix-windows-entry-script-url).
+  const child = spawnNodeScript({
+    loader: tsLoader,
+    entry: cliPath,
+    args,
+    spawnOptions: {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env },
+    },
   });
   child.unref();
-
-  // Wait for dashboard to become available (up to 5 seconds)
-  const deadline = Date.now() + 5000;
+  // Close the parent's copy of the fd — child has its own via stdio inheritance.
+  try { fs.closeSync(logFd); } catch { /* ignore */ }
+
+  // Wait for dashboard to become available. Windows + jiti cold-start can
+  // take 10s+ (TS compile on first boot, native module loads). 30s is the
+  // outer bound — if the server isn't up by then, something's genuinely wrong.
+  const READINESS_TIMEOUT_MS = 30_000;
+  const deadline = Date.now() + READINESS_TIMEOUT_MS;
   let started = false;
   while (Date.now() < deadline) {
+    // Also bail if the child has already exited (fast-path crash detection).
+    if (child.exitCode !== null) break;
     await new Promise((r) => setTimeout(r, 300));
     const status = await isDashboardRunning(config.port);
     if (status.running) {
@@ -187,7 +410,10 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     const pid = readPid();
     console.log(`Dashboard server started (pid ${pid ?? child.pid}) at http://localhost:${config.port}`);
   } else {
-    console.error("Failed to start dashboard server (timed out after 5s)");
+    const reason = child.exitCode !== null
+      ? `child process exited with code ${child.exitCode}`
+      : `timed out after ${READINESS_TIMEOUT_MS / 1000}s`;
+    console.error(`Failed to start dashboard server (${reason})`);
     console.error(`Check logs at ${path.join(logDir, "server.log")}`);
     process.exit(1);
   }
@@ -196,31 +422,21 @@ async function cmdStart(config: ServerConfig): Promise<void> {
 /**
  * Stop the running server daemon.
  */
-/** Kill a process by PID, wait for exit, force-kill if needed. */
+/**
+ * Kill a process by PID with logging. Delegates to the shared platform
+ * primitive (`packages/shared/src/platform/process.ts`) which handles the
+ * Windows (taskkill) vs Unix (SIGTERM→SIGKILL) split.
+ * See change: consolidate-platform-handlers.
+ */
 async function killProcess(pid: number, label: string): Promise<boolean> {
-  if (!isProcessAlive(pid)) return false;
-  try { process.kill(pid, "SIGTERM"); } catch { return false; }
-  const deadline = Date.now() + 5000;
-  while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, 200));
-    if (!isProcessAlive(pid)) {
-      console.log(`${label} stopped (pid ${pid})`);
-      return true;
-    }
-  }
-  try { process.kill(pid, "SIGKILL"); } catch { /* already dead */ }
-  console.log(`${label} stopped (forced, pid ${pid})`);
+  const result = await platformKillProcess(pid);
+  if (!result.ok) return false;
+  console.log(`${label} stopped${result.forced ? " (forced)" : ""} (pid ${pid})`);
   return true;
 }
 
-/** Find PIDs holding a port via lsof (macOS/Linux). */
-function findPortHolders(port: number): number[] {
-  try {
-    const { execSync } = require("node:child_process");
-    const output = execSync(`lsof -t -i :${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" });
-    return output.trim().split("\n").map(Number).filter((n: number) => n > 0 && n !== process.pid);
-  } catch { return []; }
-}
+// Local alias to preserve prior internal references.
+const isProcessAlive = (pid: number) => platformIsProcessAlive(pid);
 
 async function cmdStop(): Promise<void> {
   const config = loadConfig();
@@ -255,6 +471,58 @@ async function cmdStop(): Promise<void> {
 /**
  * Show server status.
  */
+/**
+ * `pi-dashboard upgrade-pi` — upgrade pi-coding-agent via bootstrap.
+ *
+ * If a dashboard is currently running, POST to /api/bootstrap/upgrade-pi
+ * (so the running server owns the install, broadcasts state, and reloads
+ * connected sessions). Otherwise run `bootstrapInstall` directly with a
+ * streaming progress formatter and exit when done.
+ *
+ * See change: unified-bootstrap-install §8.
+ */
+async function cmdUpgradePi(config: ServerConfig): Promise<void> {
+  const status = await isDashboardRunning(config.port);
+  if (status.running) {
+    console.log(
+      `[upgrade-pi] dashboard running at http://localhost:${config.port}, delegating to server`,
+    );
+    try {
+      const res = await fetch(`http://localhost:${config.port}/api/bootstrap/upgrade-pi`, {
+        method: "POST",
+      });
+      if (!res.ok) {
+        const body = await res.text();
+        console.error(`[upgrade-pi] server rejected upgrade: HTTP ${res.status} ${body}`);
+        process.exit(1);
+      }
+      const body = (await res.json()) as { ticketId?: string };
+      console.log(`[upgrade-pi] queued (ticketId=${body.ticketId ?? "?"})`);
+      console.log("[upgrade-pi] progress is streamed to open dashboard tabs; CLI exits now.");
+      return;
+    } catch (err) {
+      console.error("[upgrade-pi] failed to reach server:", err);
+      process.exit(1);
+    }
+  }
+
+  console.log("[upgrade-pi] no dashboard running — installing directly");
+  const res = await bootstrapInstall({
+    packages: ["@mariozechner/pi-coding-agent"],
+    progress: (p) => {
+      const line = p.output
+        ? `[upgrade-pi] ${p.step} ${p.status}: ${p.output}`
+        : `[upgrade-pi] ${p.step} ${p.status}`;
+      console.log(line);
+    },
+  });
+  if (!res.ok) {
+    console.error(`[upgrade-pi] failed: ${res.error}`);
+    process.exit(1);
+  }
+  console.log(`[upgrade-pi] ✓ installed ${res.installed.join(", ")}`);
+}
+
 async function cmdStatus(port: number): Promise<void> {
   // 1. Try mDNS discovery first
   try {
@@ -328,6 +596,9 @@ async function main() {
     case "status":
       await cmdStatus(config.port);
       break;
+    case "upgrade-pi":
+      await cmdUpgradePi(config);
+      break;
     default:
       // No subcommand — run in foreground (backward compatible)
       await runForeground(config);

package/packages/server/src/config-api.ts

@@ -100,6 +100,17 @@ export function writeConfigPartial(partial: Record<string, any>): WriteConfigRes
         mergedAuth.allowedUsers = partial.auth.allowedUsers;
       }
 
+      // fix-trusted-networks-no-oauth: propagate bypassHosts / bypassUrls
+      // from the incoming partial. Without these, the UI's Trusted Networks
+      // save path silently dropped every entry on disk. `!== undefined`
+      // (not truthiness) lets an empty array clear all entries.
+      if (partial.auth.bypassHosts !== undefined) {
+        mergedAuth.bypassHosts = partial.auth.bypassHosts;
+      }
+      if (partial.auth.bypassUrls !== undefined) {
+        mergedAuth.bypassUrls = partial.auth.bypassUrls;
+      }
+
       partial.auth = mergedAuth;
     }
 
@@ -114,6 +125,11 @@ export function writeConfigPartial(partial: Record<string, any>): WriteConfigRes
       restartRequired = true;
     }
 
+    // Merge openspec sub-object (no restart required — live-reconfigured)
+    if (partial.openspec) {
+      partial.openspec = { ...existing.openspec, ...partial.openspec };
+    }
+
     const merged = { ...existing, ...partial };
 
     // Remove computed fields that shouldn't be persisted