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

package/packages/server/src/fix-pty-permissions.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime fix for node-pty spawn-helper permissions.
+ *
+ * On macOS/Linux, the prebuilt spawn-helper binary may lack the execute bit
+ * (especially in Electron bundles where npm hoisting skips the postinstall fix).
+ * This module finds and fixes all spawn-helper binaries at runtime.
+ *
+ * Called once when the terminal manager is created.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+let fixed = false;
+
+export function fixPtyPermissions(): void {
+  if (fixed || process.platform === "win32") return;
+  fixed = true;
+
+  try {
+    // Resolve node-pty's actual location (works with hoisting)
+    const require_ = createRequire(import.meta.url);
+    const ptyMain = require_.resolve("node-pty");
+    const ptyDir = path.dirname(ptyMain);
+    const prebuildsDir = path.join(ptyDir, "..", "prebuilds");
+
+    if (!fs.existsSync(prebuildsDir)) return;
+
+    for (const dir of fs.readdirSync(prebuildsDir)) {
+      const helper = path.join(prebuildsDir, dir, "spawn-helper");
+      try {
+        const stat = fs.statSync(helper);
+        if (!(stat.mode & 0o111)) {
+          fs.chmodSync(helper, 0o755);
+          console.log(`[pty] Fixed spawn-helper permissions: ${helper}`);
+        }
+      } catch {
+        // spawn-helper doesn't exist for this platform, skip
+      }
+    }
+  } catch {
+    // node-pty not installed or not resolvable, skip silently
+  }
+}

package/packages/server/src/headless-pid-registry.ts

@@ -8,6 +8,7 @@ import { EventEmitter } from "node:events";
 import { readJsonFile, writeJsonFile } from "./json-store.js";
 import path from "node:path";
 import os from "node:os";
+import { isUnsafeTestHomeScan } from "./test-env-guard.js";
 
 /** Default PID file path */
 const DEFAULT_PID_FILE = path.join(os.homedir(), ".pi", "dashboard", "headless-pids.json");
@@ -148,6 +149,10 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
     },
 
     killAll() {
+      if (isUnsafeTestHomeScan()) {
+        console.warn("[headless-pid-registry] killAll() blocked: running under vitest with real HOME");
+        return;
+      }
       const useGroup = process.platform !== "win32";
       for (const [pid] of entries) {
         try {
@@ -166,6 +171,10 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
     },
 
     cleanupOrphans() {
+      if (isUnsafeTestHomeScan()) {
+        console.warn("[headless-pid-registry] cleanupOrphans() blocked: running under vitest with real HOME");
+        return;
+      }
       const persisted = loadFromDisk();
       const now = Date.now();
 

package/packages/server/src/npm-search-proxy.ts

@@ -136,8 +136,79 @@ export class PackageNotFoundError extends Error {
   }
 }
 
+// ── Lightweight metadata helpers for recommended-extensions enrichment ──
+
+export interface PackageMeta {
+  description?: string;
+  version?: string;
+}
+
+const metaCache = new Map<string, CacheEntry<PackageMeta | null>>();
+
+/**
+ * Fetch a minimal package.json-ish blob for an npm package (description,
+ * version) from the registry's `/<name>/latest` endpoint. Returns `null`
+ * on any network or parse failure.
+ */
+export async function fetchPackageMeta(packageName: string): Promise<PackageMeta | null> {
+  const cached = metaCache.get(`npm:${packageName}`);
+  if (isFresh(cached)) return cached.data;
+  try {
+    const url = `${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}/latest`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+      metaCache.set(`npm:${packageName}`, { data: null, timestamp: Date.now() });
+      return null;
+    }
+    const json: any = await res.json();
+    const meta: PackageMeta = {
+      description: typeof json?.description === "string" ? json.description : undefined,
+      version: typeof json?.version === "string" ? json.version : undefined,
+    };
+    metaCache.set(`npm:${packageName}`, { data: meta, timestamp: Date.now() });
+    return meta;
+  } catch {
+    metaCache.set(`npm:${packageName}`, { data: null, timestamp: Date.now() });
+    return null;
+  }
+}
+
+/**
+ * Fetch `package.json` from a public GitHub repository's default branch
+ * via `raw.githubusercontent.com`. Returns `{description, version}` or
+ * `null` on any failure.
+ */
+export async function fetchGithubPackageJson(
+  owner: string,
+  repo: string,
+): Promise<PackageMeta | null> {
+  const key = `gh:${owner}/${repo}`;
+  const cached = metaCache.get(key);
+  if (isFresh(cached)) return cached.data;
+  // HEAD resolves to the default branch on raw.githubusercontent.com.
+  const url = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/package.json`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+      metaCache.set(key, { data: null, timestamp: Date.now() });
+      return null;
+    }
+    const json: any = await res.json();
+    const meta: PackageMeta = {
+      description: typeof json?.description === "string" ? json.description : undefined,
+      version: typeof json?.version === "string" ? json.version : undefined,
+    };
+    metaCache.set(key, { data: meta, timestamp: Date.now() });
+    return meta;
+  } catch {
+    metaCache.set(key, { data: null, timestamp: Date.now() });
+    return null;
+  }
+}
+
 /** Clear all caches (for testing). */
 export function clearCaches() {
   searchCache.clear();
   readmeCache.clear();
+  metaCache.clear();
 }

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

@@ -0,0 +1,158 @@
+/**
+ * Parser + writer for an OpenSpec change's `tasks.md` file.
+ *
+ * `tasks.md` uses a rigid line-level format:
+ *   ## 1. Group heading
+ *   - [ ] 1.1 Task text
+ *   - [x] 1.2 Done task
+ *
+ * We parse top-level `- [ ]` / `- [x]` lines only; anything else is ignored
+ * (indented sublists, free-form prose, etc.).
+ *
+ * Writes rewrite exactly one line's checkbox marker and preserve everything
+ * else byte-for-byte; atomic via write-then-rename.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export interface OpenSpecTask {
+  /** e.g. "1.1", "8.3" */
+  id: string;
+  /** Text after the id, trimmed. */
+  text: string;
+  done: boolean;
+  /** 1-indexed line number in `tasks.md` — used as an optimistic-concurrency token. */
+  line: number;
+  /** Nearest preceding `## ` heading text (without the leading "## "). Empty string if none. */
+  group: string;
+}
+
+export class NotFoundError extends Error {
+  readonly code = "NOT_FOUND" as const;
+  constructor(message = "tasks.md not found") {
+    super(message);
+  }
+}
+export class LineMismatchError extends Error {
+  readonly code = "LINE_MISMATCH" as const;
+  constructor(message = "line mismatch") {
+    super(message);
+  }
+}
+export class NotACheckboxError extends Error {
+  readonly code = "NOT_A_CHECKBOX" as const;
+  constructor(message = "target line is not a checkbox") {
+    super(message);
+  }
+}
+
+// Top-level checkbox: allow a single leading `- ` with optional `[ ]`/`[x]`/`[X]`,
+// followed by an id-like token (digits and dots) and remaining text.
+const CHECKBOX_RE = /^- \[([ xX])\] +([0-9]+(?:\.[0-9]+)*)\s+(.*)$/;
+const HEADING_RE = /^##\s+(.*)$/;
+
+export function parseTasksMarkdown(content: string): OpenSpecTask[] {
+  // Split on \n only; trailing \r is trimmed so we handle CRLF inputs too.
+  const lines = content.split("\n");
+  const out: OpenSpecTask[] = [];
+  let currentGroup = "";
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const h = HEADING_RE.exec(line);
+    if (h) {
+      currentGroup = h[1].trim();
+      continue;
+    }
+    const m = CHECKBOX_RE.exec(line);
+    if (!m) continue;
+    const done = m[1] === "x" || m[1] === "X";
+    out.push({
+      id: m[2],
+      text: m[3].trim(),
+      done,
+      line: i + 1,
+      group: currentGroup,
+    });
+  }
+  return out;
+}
+
+function tasksMdPath(cwd: string, change: string): string {
+  return path.join(cwd, "openspec", "changes", change, "tasks.md");
+}
+
+export async function readTasks(cwd: string, change: string): Promise<OpenSpecTask[]> {
+  const p = tasksMdPath(cwd, change);
+  let content: string;
+  try {
+    content = await fs.readFile(p, "utf-8");
+  } catch (err: any) {
+    if (err?.code === "ENOENT") throw new NotFoundError();
+    throw err;
+  }
+  return parseTasksMarkdown(content);
+}
+
+export async function toggleTask(
+  cwd: string,
+  change: string,
+  id: string,
+  done: boolean,
+  line: number,
+): Promise<OpenSpecTask> {
+  const p = tasksMdPath(cwd, change);
+  let content: string;
+  try {
+    content = await fs.readFile(p, "utf-8");
+  } catch (err: any) {
+    if (err?.code === "ENOENT") throw new NotFoundError();
+    throw err;
+  }
+
+  // Preserve original line endings by splitting on \n and tracking \r individually.
+  const lines = content.split("\n");
+  if (line < 1 || line > lines.length) throw new LineMismatchError();
+
+  const idx = line - 1;
+  const raw = lines[idx];
+  const hadCR = raw.endsWith("\r");
+  const bare = hadCR ? raw.slice(0, -1) : raw;
+
+  const m = CHECKBOX_RE.exec(bare);
+  if (!m) throw new NotACheckboxError();
+  if (m[2] !== id) throw new LineMismatchError();
+
+  const currentDone = m[1] === "x" || m[1] === "X";
+  // Optimistic concurrency: the caller's `done` is the *target* state; the line
+  // must currently hold the opposite state. If it already matches, we treat
+  // that as a line-mismatch — the file changed under us.
+  if (currentDone === done) throw new LineMismatchError();
+
+  const marker = done ? "x" : " ";
+  const rewritten = bare.replace(CHECKBOX_RE, `- [${marker}] ${m[2]} ${m[3]}`);
+  lines[idx] = hadCR ? rewritten + "\r" : rewritten;
+
+  const newContent = lines.join("\n");
+  const tmp = p + ".tmp";
+  await fs.writeFile(tmp, newContent, "utf-8");
+  await fs.rename(tmp, p);
+
+  return {
+    id,
+    text: m[3].trim(),
+    done,
+    line,
+    group: findGroupForLine(lines, idx),
+  };
+}
+
+function findGroupForLine(lines: string[], idx: number): string {
+  for (let i = idx; i >= 0; i--) {
+    const raw = lines[i];
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const h = HEADING_RE.exec(line);
+    if (h) return h[1].trim();
+  }
+  return "";
+}

package/packages/server/src/package-manager-wrapper.ts

@@ -30,6 +30,19 @@ async function loadPiPackageManager() {
     }
   } catch { /* fall through to global resolution */ }
 
+  // Try managed install at ~/.pi-dashboard/node_modules/ (Electron portable/standalone)
+  const managedDir = path.join(os.homedir(), ".pi-dashboard");
+  for (const pkgName of ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"]) {
+    try {
+      const entryPath = path.join(managedDir, "node_modules", pkgName, "dist", "index.js");
+      const mod = await import(pathToFileURL(entryPath).href);
+      if (mod.DefaultPackageManager) {
+        piModuleCache = { DefaultPackageManager: mod.DefaultPackageManager, SettingsManager: mod.SettingsManager };
+        return piModuleCache;
+      }
+    } catch { /* fall through */ }
+  }
+
   // Resolve from global npm install (pi is typically installed globally)
   for (const pkgName of ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"]) {
     try {
@@ -95,6 +108,24 @@ export class PackageManagerWrapper {
     return this.busy;
   }
 
+  /**
+   * Run an arbitrary async operation under the wrapper's busy-lock.
+   * Used by adjacent subsystems (e.g. PiCoreUpdater) to coordinate with
+   * extension install/update operations. Throws PackageOperationBusyError
+   * if a package operation is already running.
+   */
+  async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.busy) {
+      throw new PackageOperationBusyError();
+    }
+    this.busy = true;
+    try {
+      return await fn();
+    } finally {
+      this.busy = false;
+    }
+  }
+
   /**
    * Start a package operation. Returns the operationId immediately.
    * Progress and completion are delivered via listeners.

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

@@ -0,0 +1,290 @@
+/**
+ * Pi core version checker.
+ *
+ * Discovers installed pi-ecosystem CORE packages (pi-coding-agent itself,
+ * pi-agent-dashboard, pi-model-proxy, and similar globally-installed CLI
+ * tooling) and compares their versions against the npm registry.
+ *
+ * Complements the existing PackageManagerWrapper, which only manages
+ * packages listed in `settings.json packages[]` (extensions, skills,
+ * prompts, themes).
+ *
+ * Discovery sources:
+ *   1. Global npm (`npm list -g --depth=0 --json`)
+ *   2. Managed install (`~/.pi-dashboard/node_modules/`) — Electron path
+ *
+ * Version fetch reuses `fetchPackageMeta()` from the npm-search proxy.
+ * Results are cached for 5 minutes.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fetchPackageMeta } from "./npm-search-proxy.js";
+
+const execFileAsync = promisify(execFile);
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const NPM_LIST_TIMEOUT_MS = 30_000;
+
+/** ~/.pi-dashboard/ — Electron managed install dir */
+const MANAGED_DIR = path.join(os.homedir(), ".pi-dashboard");
+const MANAGED_NODE_MODULES = path.join(MANAGED_DIR, "node_modules");
+
+/** Known core packages (not extensions). Order matters for display. */
+export const CORE_PACKAGE_NAMES: readonly string[] = [
+	"@mariozechner/pi-coding-agent",
+	"@oh-my-pi/pi-coding-agent",
+	"@blackbelt-technology/pi-agent-dashboard",
+	"@blackbelt-technology/pi-model-proxy",
+];
+
+/** Display name mapping for known packages. Falls back to package name. */
+const DISPLAY_NAMES: Readonly<Record<string, string>> = {
+	"@mariozechner/pi-coding-agent": "pi (core agent)",
+	"@oh-my-pi/pi-coding-agent": "pi (core agent — fork)",
+	"@blackbelt-technology/pi-agent-dashboard": "pi-dashboard",
+	"@blackbelt-technology/pi-model-proxy": "pi-model-proxy",
+};
+
+export interface PiCorePackage {
+	name: string;
+	displayName: string;
+	currentVersion: string;
+	latestVersion: string | null;
+	updateAvailable: boolean;
+	installSource: "global" | "managed";
+}
+
+export interface PiCoreStatus {
+	packages: PiCorePackage[];
+	updatesAvailable: number;
+	lastChecked: string;
+}
+
+/** Resolve display name for a package. */
+function resolveDisplayName(name: string): string {
+	return DISPLAY_NAMES[name] ?? name;
+}
+
+/**
+ * Heuristic to decide if a package is part of the pi ecosystem but NOT in
+ * the known-names list above. Matches bare-name pi packages on npm:
+ *   - bare `pi-<name>`
+ *   - scoped `@<scope>/pi-<name>`
+ * Note: extensions already managed by PackageManagerWrapper (via
+ * `settings.json packages[]`) are deliberately included if they are ALSO
+ * installed globally — the PiCoreChecker's discovery is a superset, and
+ * the UI layer decides which surface to show a package in.
+ */
+function looksLikePiEcosystem(name: string): boolean {
+	if (CORE_PACKAGE_NAMES.includes(name)) return true;
+	// `pi-foo` or `pi` bare-scoped
+	if (/^pi-[a-z0-9-]+$/i.test(name)) return true;
+	// scoped variant: `@scope/pi-foo`
+	if (/^@[^/]+\/pi-[a-z0-9-]+$/i.test(name)) return true;
+	return false;
+}
+
+export interface NpmListRunner {
+	/** Run `npm list -g --depth=0 --json` and return stdout. */
+	(): Promise<string>;
+}
+
+export interface PiCoreCheckerOptions {
+	/** Inject npm-list runner (for tests). */
+	npmList?: NpmListRunner;
+	/** Inject version fetcher (for tests). */
+	fetchLatest?: (packageName: string) => Promise<string | null>;
+	/** Override managed directory (for tests). */
+	managedDir?: string;
+}
+
+/** Default npm runner uses execFile for safety. */
+const defaultNpmList: NpmListRunner = async () => {
+	const { stdout } = await execFileAsync("npm", ["list", "-g", "--depth=0", "--json"], {
+		timeout: NPM_LIST_TIMEOUT_MS,
+		maxBuffer: 10 * 1024 * 1024,
+	});
+	return stdout;
+};
+
+const defaultFetchLatest = async (packageName: string): Promise<string | null> => {
+	const meta = await fetchPackageMeta(packageName);
+	return meta?.version ?? null;
+};
+
+export class PiCoreChecker {
+	private cache: { at: number; data: PiCoreStatus } | null = null;
+	private readonly npmList: NpmListRunner;
+	private readonly fetchLatest: (packageName: string) => Promise<string | null>;
+	private readonly managedNodeModules: string;
+
+	constructor(opts: PiCoreCheckerOptions = {}) {
+		this.npmList = opts.npmList ?? defaultNpmList;
+		this.fetchLatest = opts.fetchLatest ?? defaultFetchLatest;
+		this.managedNodeModules = opts.managedDir
+			? path.join(opts.managedDir, "node_modules")
+			: MANAGED_NODE_MODULES;
+	}
+
+	/** Invalidate the cache (e.g. after an update completes). */
+	invalidate(): void {
+		this.cache = null;
+	}
+
+	/** Get version status. Returns cached data within 5 min unless `refresh`. */
+	async getStatus(refresh = false): Promise<PiCoreStatus> {
+		const now = Date.now();
+		if (!refresh && this.cache && now - this.cache.at < CACHE_TTL_MS) {
+			return this.cache.data;
+		}
+
+		// Discover packages from both sources. Managed takes precedence on conflict.
+		const global = await this.discoverGlobal();
+		const managed = this.discoverManaged();
+
+		const byName = new Map<string, { version: string; source: "global" | "managed" }>();
+		for (const entry of global) byName.set(entry.name, { version: entry.version, source: "global" });
+		for (const entry of managed) byName.set(entry.name, { version: entry.version, source: "managed" });
+
+		// Fetch latest versions in parallel.
+		const entries = Array.from(byName.entries());
+		const withLatest = await Promise.all(
+			entries.map(async ([name, info]) => {
+				let latest: string | null = null;
+				try {
+					latest = await this.fetchLatest(name);
+				} catch {
+					latest = null;
+				}
+				const updateAvailable = latest !== null && latest !== info.version;
+				const pkg: PiCorePackage = {
+					name,
+					displayName: resolveDisplayName(name),
+					currentVersion: info.version,
+					latestVersion: latest,
+					updateAvailable,
+					installSource: info.source,
+				};
+				return pkg;
+			}),
+		);
+
+		// Sort: known core packages first (in CORE_PACKAGE_NAMES order), then
+		// alphabetically. Then updates-available bubble up.
+		withLatest.sort((a, b) => {
+			const ai = CORE_PACKAGE_NAMES.indexOf(a.name);
+			const bi = CORE_PACKAGE_NAMES.indexOf(b.name);
+			if (ai !== -1 || bi !== -1) {
+				if (ai === -1) return 1;
+				if (bi === -1) return -1;
+				return ai - bi;
+			}
+			return a.name.localeCompare(b.name);
+		});
+
+		const status: PiCoreStatus = {
+			packages: withLatest,
+			updatesAvailable: withLatest.filter((p) => p.updateAvailable).length,
+			lastChecked: new Date().toISOString(),
+		};
+		this.cache = { at: now, data: status };
+		return status;
+	}
+
+	/** Discover pi-ecosystem packages installed via `npm -g`. */
+	private async discoverGlobal(): Promise<Array<{ name: string; version: string }>> {
+		let stdout = "";
+		try {
+			stdout = await this.npmList();
+		} catch (err) {
+			// `npm list` exits non-zero when it has warnings — stdout may still be valid JSON.
+			// execFile throws with .stdout attached in that case.
+			const maybe = (err as { stdout?: string })?.stdout;
+			if (typeof maybe === "string" && maybe.length > 0) {
+				stdout = maybe;
+			} else {
+				console.warn("[pi-core-checker] npm list -g failed:", (err as Error).message);
+				return [];
+			}
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(stdout);
+		} catch (err) {
+			console.warn("[pi-core-checker] npm list -g: failed to parse JSON:", (err as Error).message);
+			return [];
+		}
+
+		const deps = (parsed as { dependencies?: Record<string, { version?: string; resolved?: string }> })?.dependencies;
+		if (!deps || typeof deps !== "object") return [];
+
+		const out: Array<{ name: string; version: string }> = [];
+		for (const [name, info] of Object.entries(deps)) {
+			if (!looksLikePiEcosystem(name)) continue;
+			const version = typeof info?.version === "string" ? info.version : undefined;
+			if (!version) continue;
+			out.push({ name, version });
+		}
+		return out;
+	}
+
+	/** Discover pi-ecosystem packages in ~/.pi-dashboard/node_modules/. */
+	private discoverManaged(): Array<{ name: string; version: string }> {
+		if (!existsSync(this.managedNodeModules)) return [];
+		const out: Array<{ name: string; version: string }> = [];
+		let entries: string[];
+		try {
+			entries = readdirSync(this.managedNodeModules);
+		} catch {
+			return [];
+		}
+
+		for (const entry of entries) {
+			if (entry.startsWith(".")) continue;
+			const full = path.join(this.managedNodeModules, entry);
+			if (entry.startsWith("@")) {
+				// Scoped: iterate one level deeper.
+				let sub: string[];
+				try {
+					sub = readdirSync(full);
+				} catch {
+					continue;
+				}
+				for (const pkg of sub) {
+					const pkgName = `${entry}/${pkg}`;
+					if (!looksLikePiEcosystem(pkgName)) continue;
+					const v = this.readVersion(path.join(full, pkg));
+					if (v) out.push({ name: pkgName, version: v });
+				}
+			} else {
+				if (!looksLikePiEcosystem(entry)) continue;
+				const v = this.readVersion(full);
+				if (v) out.push({ name: entry, version: v });
+			}
+		}
+		return out;
+	}
+
+	private readVersion(pkgDir: string): string | null {
+		try {
+			const pj = path.join(pkgDir, "package.json");
+			if (!existsSync(pj)) return null;
+			if (!statSync(pj).isFile()) return null;
+			const parsed = JSON.parse(readFileSync(pj, "utf-8"));
+			return typeof parsed?.version === "string" ? parsed.version : null;
+		} catch {
+			return null;
+		}
+	}
+}
+
+export const _internal = {
+	looksLikePiEcosystem,
+	resolveDisplayName,
+	DISPLAY_NAMES,
+	MANAGED_NODE_MODULES,
+};