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

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

@@ -0,0 +1,172 @@
+/**
+ * Pi core package updater.
+ *
+ * Runs `npm update -g <pkg>` for globally-installed packages or
+ * `npm update <pkg>` in `~/.pi-dashboard/` for managed installs.
+ * Coordinates with PackageManagerWrapper's busy-lock so extension
+ * operations and core updates can't run concurrently.
+ */
+import { spawn } from "node:child_process"; // ban:child_process-ok npm-update streams stdout/stderr via pipe for progress events; refactor to platform/spawn Recipe is tracked tech debt
+import path from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import type { PiCorePackage, PiCoreUpdateResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import type { PackageManagerWrapper } from "./package-manager-wrapper.js";
+
+const UPDATE_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per package
+
+const MANAGED_DIR = path.join(os.homedir(), ".pi-dashboard");
+
+export interface UpdateProgressEvent {
+	name: string;
+	phase: "start" | "output" | "complete" | "error";
+	message?: string;
+}
+
+export type UpdateProgressListener = (event: UpdateProgressEvent) => void;
+
+export interface PiCoreUpdaterOptions {
+	packageManagerWrapper: PackageManagerWrapper;
+	/** Test seam: override spawner. */
+	runNpmUpdate?: (pkg: PiCorePackage, onOutput: (line: string) => void) => Promise<void>;
+	/** Optional: called after successful update of at least one package. */
+	onAllComplete?: () => Promise<number>;
+}
+
+/** Default npm-update runner. */
+function defaultRunNpmUpdate(
+	pkg: PiCorePackage,
+	onOutput: (line: string) => void,
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const args =
+			pkg.installSource === "global"
+				? ["update", "-g", pkg.name]
+				: ["update", pkg.name];
+		const cwd = pkg.installSource === "managed" ? MANAGED_DIR : process.cwd();
+
+		if (pkg.installSource === "managed" && !existsSync(MANAGED_DIR)) {
+			reject(new Error(`Managed install directory not found: ${MANAGED_DIR}`));
+			return;
+		}
+
+		// On Windows, system npm is npm.cmd (batch wrapper) — spawn("npm")
+		// without the .cmd extension fails with ENOENT. shell:true routes
+		// the invocation through cmd.exe which resolves via PATHEXT.
+		// See change: route-kill-paths-through-platform (same class of bug).
+		const child = spawn("npm", args, {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: process.env,
+			shell: process.platform === "win32", // platform-branch-ok: shell:true required on Windows so PATHEXT resolves npm.cmd (spawn('npm') without .cmd ENOENTs)
+			windowsHide: true,
+		});
+
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			reject(new Error(`npm update timed out after ${UPDATE_TIMEOUT_MS / 1000}s`));
+		}, UPDATE_TIMEOUT_MS);
+
+		let stderrBuf = "";
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			const lines = chunk.toString().split("\n").filter((l) => l.trim());
+			for (const line of lines) onOutput(line);
+		});
+
+		child.stderr?.on("data", (chunk: Buffer) => {
+			const text = chunk.toString();
+			stderrBuf += text;
+			const lines = text.split("\n").filter((l) => l.trim());
+			for (const line of lines) onOutput(line);
+		});
+
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) {
+				resolve();
+			} else {
+				const hint =
+					pkg.installSource === "global" && /permission|EACCES|EPERM|EROFS/i.test(stderrBuf)
+						? ` (permission error — try: sudo npm update -g ${pkg.name})`
+						: "";
+				reject(new Error(`npm update exited with code ${code}${hint}`));
+			}
+		});
+	});
+}
+
+export class PiCoreUpdater {
+	private listener: UpdateProgressListener | undefined;
+	private readonly pmWrapper: PackageManagerWrapper;
+	private readonly runNpmUpdate: (
+		pkg: PiCorePackage,
+		onOutput: (line: string) => void,
+	) => Promise<void>;
+	private readonly onAllComplete: (() => Promise<number>) | undefined;
+
+	constructor(opts: PiCoreUpdaterOptions) {
+		this.pmWrapper = opts.packageManagerWrapper;
+		this.runNpmUpdate = opts.runNpmUpdate ?? defaultRunNpmUpdate;
+		this.onAllComplete = opts.onAllComplete;
+	}
+
+	setProgressListener(listener: UpdateProgressListener | undefined): void {
+		this.listener = listener;
+	}
+
+	/**
+	 * Update a set of core packages sequentially. Acquires the shared
+	 * busy-lock via PackageManagerWrapper.runExclusive — will throw
+	 * PackageOperationBusyError if an extension operation is running.
+	 *
+	 * Returns per-package results plus the count of sessions reloaded
+	 * after a successful update.
+	 */
+	async update(
+		packages: PiCorePackage[],
+	): Promise<{ results: PiCoreUpdateResult[]; sessionsReloaded: number }> {
+		return this.pmWrapper.runExclusive(async () => {
+			const results: PiCoreUpdateResult[] = [];
+
+			for (const pkg of packages) {
+				this.emit({ name: pkg.name, phase: "start", message: `Updating ${pkg.name}...` });
+				try {
+					await this.runNpmUpdate(pkg, (line) => {
+						this.emit({ name: pkg.name, phase: "output", message: line });
+					});
+					results.push({ name: pkg.name, success: true });
+					this.emit({ name: pkg.name, phase: "complete", message: `Updated ${pkg.name}` });
+				} catch (err) {
+					const msg = (err as Error).message ?? String(err);
+					results.push({ name: pkg.name, success: false, error: msg });
+					this.emit({ name: pkg.name, phase: "error", message: msg });
+				}
+			}
+
+			let sessionsReloaded = 0;
+			if (results.some((r) => r.success) && this.onAllComplete) {
+				try {
+					sessionsReloaded = await this.onAllComplete();
+				} catch (err) {
+					console.error("[pi-core-updater] session reload failed:", err);
+				}
+			}
+
+			return { results, sessionsReloaded };
+		});
+	}
+
+	private emit(event: UpdateProgressEvent): void {
+		try {
+			this.listener?.(event);
+		} catch (err) {
+			console.error("[pi-core-updater] progress listener error:", err);
+		}
+	}
+}

package/packages/server/src/pi-gateway.ts

@@ -17,6 +17,8 @@ export interface PiGatewayOptions {
 export interface PiGateway {
   start(port: number): void;
   stop(): void;
+  /** Resolved listening port after start() (useful when start(0) is used). Returns null if not started or closed. */
+  address(): number | null;
   sendToSession(sessionId: string, msg: ServerToExtensionMessage): boolean;
   broadcast(msg: ServerToExtensionMessage): void;
   connectionCount(): number;
@@ -172,6 +174,11 @@ export function createPiGateway(
       onSessionCreated = handler;
     },
 
+    address() {
+      const addr = wss?.address();
+      if (addr && typeof addr === "object") return addr.port;
+      return null;
+    },
     start(port: number) {
       wss = new WebSocketServer({ port });
 

package/packages/server/src/pi-resource-scanner.ts

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { execSync } from "node:child_process";
+import * as npm from "@blackbelt-technology/pi-dashboard-shared/platform/npm.js";
 import type { PiResource, PiResourceScope, PiPackageInfo, PiResourcesResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
 
 // ── Frontmatter Parsing ─────────────────────────────────────────────
@@ -179,13 +179,10 @@ let cachedNpmGlobalRoot: string | null = null;
 
 function getNpmGlobalRoot(): string | null {
   if (cachedNpmGlobalRoot !== null) return cachedNpmGlobalRoot;
-  try {
-    cachedNpmGlobalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 10_000 }).trim();
-    return cachedNpmGlobalRoot;
-  } catch {
-    cachedNpmGlobalRoot = "";
-    return null;
-  }
+  // Delegate to shared npm module which caches the result itself and
+  // handles windowsHide / timeout. See change: platform-command-executor.
+  cachedNpmGlobalRoot = npm.rootGlobalOr("");
+  return cachedNpmGlobalRoot || null;
 }
 
 /** Visible for testing — reset cached npm root */

package/packages/server/src/pi-version-skew.ts

@@ -0,0 +1,196 @@
+/**
+ * Version-skew detection for pi-coding-agent.
+ *
+ * Reads `piCompatibility` from `packages/server/package.json` and the
+ * currently-resolved pi version from its `package.json`, then populates
+ * `bootstrapState.compatibility` with hints the UI banner uses to show
+ * upgrade suggestions.
+ *
+ * See change: unified-bootstrap-install \u00a79.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import type { BootstrapCompatibility, BootstrapStateStore } from "./bootstrap-state.js";
+import { getDefaultRegistry, type ToolRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+
+/**
+ * Parse a semver-ish string into its three numeric segments. Returns
+ * null when the string doesn't match `<n>.<n>.<n>` (with optional
+ * pre-release / build suffix which we ignore for comparison). This is
+ * deliberately minimal \u2014 pi versions have always been `0.x.y` and we
+ * don't want to pull in the `semver` dep.
+ */
+export function parseVersion(v: string): [number, number, number] | null {
+  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+/**
+ * Compare two version strings. Returns -1 if `a < b`, 0 if equal, 1 if
+ * `a > b`. Unparseable strings sort as equal (conservative \u2014 don't flag
+ * weird versions as outdated).
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const A = parseVersion(a);
+  const B = parseVersion(b);
+  if (!A || !B) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (A[i] < B[i]) return -1;
+    if (A[i] > B[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Return true if `version` is less than `threshold`. Delegates to
+ * `compareVersions` so unparseable strings never flag as "too old".
+ */
+export function isBelow(version: string, threshold: string): boolean {
+  return compareVersions(version, threshold) < 0;
+}
+
+/**
+ * Return true if `version` is strictly above `threshold`. `threshold`
+ * may include a `.x` wildcard in the patch slot (e.g. `"0.9.x"`); in
+ * that case the wildcard matches any patch, so `"0.9.5"` is NOT above
+ * `"0.9.x"` but `"0.10.0"` is.
+ */
+export function isAbove(version: string, threshold: string): boolean {
+  const thresholdClean = threshold.replace(/\.x$/i, ".99999");
+  return compareVersions(version, thresholdClean) > 0;
+}
+
+/**
+ * Read the server's declared compatibility range from its own package.json.
+ * Falls back to the hard-coded defaults when the field is missing or
+ * malformed (shouldn't happen in practice).
+ */
+export function readPiCompatibility(serverPkgJsonPath: string): Pick<
+  BootstrapCompatibility,
+  "minimum" | "recommended" | "maximum"
+> {
+  try {
+    const raw = fs.readFileSync(serverPkgJsonPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      piCompatibility?: { minimum?: string; recommended?: string; maximum?: string | null };
+    };
+    const c = parsed.piCompatibility;
+    if (c && typeof c.minimum === "string" && typeof c.recommended === "string") {
+      return {
+        minimum: c.minimum,
+        recommended: c.recommended,
+        maximum: c.maximum ?? null,
+      };
+    }
+  } catch {
+    /* fall through */
+  }
+  return { minimum: "0.6.7", recommended: "0.6.7", maximum: null };
+}
+
+/**
+ * Read the currently-resolved pi version from `<pi-module>/../package.json`.
+ * Returns undefined when pi isn't resolvable or the package.json can't
+ * be parsed.
+ */
+export function readCurrentPiVersion(registry: ToolRegistry = getDefaultRegistry()): string | undefined {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgJson = req.resolve("@mariozechner/pi-coding-agent/package.json");
+    const raw = fs.readFileSync(pkgJson, "utf8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    if (typeof parsed.version === "string") return parsed.version;
+  } catch {
+    /* not resolvable yet */
+  }
+  // Fall back to the registry's resolved path + ../package.json.
+  try {
+    const res = registry.resolve("pi");
+    if (res.ok && res.path) {
+      const candidate = path.join(path.dirname(path.dirname(res.path)), "package.json");
+      if (fs.existsSync(candidate)) {
+        const raw = fs.readFileSync(candidate, "utf8");
+        const parsed = JSON.parse(raw) as { version?: string };
+        if (typeof parsed.version === "string") return parsed.version;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/**
+ * Compute the `compatibility` snapshot from a compatibility range and
+ * the current pi version (or undefined when not yet installed). Pure
+ * function \u2014 all I/O is done by callers.
+ */
+export function computeCompatibility(
+  range: Pick<BootstrapCompatibility, "minimum" | "recommended" | "maximum">,
+  current: string | undefined,
+): BootstrapCompatibility {
+  const out: BootstrapCompatibility = { ...range, current };
+  if (!current) return out;
+  if (isBelow(current, range.minimum)) {
+    // Minimum-violated is signalled by leaving `upgradeRecommended` true
+    // AND letting callers populate `bootstrapState.error` with the
+    // block-ops message.
+    out.upgradeRecommended = true;
+    return out;
+  }
+  if (isBelow(current, range.recommended)) {
+    out.upgradeRecommended = true;
+  }
+  if (range.maximum && isAbove(current, range.maximum)) {
+    out.upgradeDashboard = true;
+  }
+  return out;
+}
+
+interface CacheEntry {
+  value: BootstrapCompatibility;
+  /** Milliseconds epoch when this entry should be discarded. */
+  expiresAt: number;
+}
+
+let cached: CacheEntry | undefined;
+const CACHE_TTL_MS = 60_000;
+
+/**
+ * Convenience wrapper: read range + current version, compute result,
+ * cache for 60 s. `store` is called with a structured compatibility
+ * update and (when minimum is violated) a blocking `error` message.
+ */
+export function updateBootstrapCompatibility(
+  store: BootstrapStateStore,
+  serverPkgJsonPath: string,
+  registry: ToolRegistry = getDefaultRegistry(),
+  now: () => number = Date.now,
+): BootstrapCompatibility {
+  const t = now();
+  if (cached && t < cached.expiresAt) {
+    store.set({ compatibility: cached.value });
+    return cached.value;
+  }
+  const range = readPiCompatibility(serverPkgJsonPath);
+  const current = readCurrentPiVersion(registry);
+  const computed = computeCompatibility(range, current);
+  cached = { value: computed, expiresAt: t + CACHE_TTL_MS };
+  store.set({ compatibility: computed });
+  // Minimum-violated → block pi-dependent ops by setting `error`.
+  if (current && isBelow(current, range.minimum)) {
+    store.set({
+      error: {
+        message: `pi version ${current} is below minimum ${range.minimum}. Please run \`pi-dashboard upgrade-pi\`.`,
+      },
+    });
+  }
+  return computed;
+}
+
+/** Test helper: clear the 60-second cache between runs. */
+export function _resetVersionSkewCache(): void {
+  cached = undefined;
+}

package/packages/server/src/preferences-store.ts

@@ -7,6 +7,7 @@ import path from "node:path";
 import { CONFIG_DIR } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { readJsonFile, writeJsonFile } from "./json-store.js";
 import { safeRealpathSync } from "./resolve-path.js";
+import { normalizePath } from "@blackbelt-technology/pi-dashboard-shared/platform/paths.js";
 
 export const PREFERENCES_FILE = path.join(CONFIG_DIR, "preferences.json");
 
@@ -32,10 +33,23 @@ const DEBOUNCE_MS = 1000;
 export function createPreferencesStore(filePath: string = PREFERENCES_FILE): PreferencesStore {
   const data: PreferencesData = readJsonFile<PreferencesData>(filePath, { sessionOrder: {}, pinnedDirectories: [] });
   let sessionOrder: Record<string, string[]> = data.sessionOrder ?? {};
-  // Resolve symlinks in stored pinned paths on load
+  // Normalize + resolve symlinks in stored pinned paths on load. Normalize
+  // FIRST so cosmetic drift (trailing separator, mixed separators,
+  // drive-letter case on Windows) collapses before realpath — then
+  // realpath handles symlinks. Order matters: realpath can fail for
+  // not-yet-existing paths, so we keep its best-effort fallback.
+  // See change: platform-path-normalization.
   const rawPinned = data.pinnedDirectories ?? [];
-  let pinnedDirectories: string[] = rawPinned.map(safeRealpathSync);
-  // Deduplicate in case symlinks resolved to the same path
+  // IMPORTANT: wrap in arrow fn — `Array.prototype.map` passes `(element,
+  // index, array)`, and `normalizePath`'s 2nd param is a `platform:
+  // NodeJS.Platform`. Passing the index (a number) silently disables the
+  // Windows branch at runtime.
+  let pinnedDirectories: string[] = rawPinned
+    .map((p) => normalizePath(p))
+    .map((p) => safeRealpathSync(p));
+  // Deduplicate post-normalization. Two previously-different entries that
+  // collapse to the same canonical form (e.g., with and without trailing
+  // slash) become one stored entry.
   pinnedDirectories = [...new Set(pinnedDirectories)];
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let dirty = pinnedDirectories.length !== rawPinned.length || pinnedDirectories.some((p, i) => p !== rawPinned[i]);