@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/server/src/bootstrap-install-from-list.ts

@@ -1,232 +0,0 @@
-/**
- * Bootstrap install reconciler driven by ~/.pi/dashboard/installable.json.
- * Invoked by cli.ts before app.listen.
- *
- * File-absent path is a deliberate no-op: Bridge and Standalone starters
- * never write installable.json; only Electron seeds it on first run.
- * When the file is absent, this function logs and returns immediately so
- * bootstrap.status transitions to "ready" without delay.
- *
- * See change: simplify-electron-bootstrap-derived-state.
- */
-import os from "node:os";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { getManagedDir } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
-import {
-  readInstallableList,
-  type InstallablePackage,
-} from "@blackbelt-technology/pi-dashboard-shared/installable-list.js";
-import { bootstrapInstall } from "@blackbelt-technology/pi-dashboard-shared/bootstrap-install.js";
-import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
-import type { BootstrapStateStore } from "./bootstrap-state.js";
-
-// ── Injectable helpers (overridable in tests) ──────────────────────────────
-
-export type InstallProgressCallback = (line: string) => void;
-export type PackageInstaller = (
-  pkg: InstallablePackage,
-  onOutput: InstallProgressCallback,
-) => Promise<void>;
-
-// ── Installed-check ────────────────────────────────────────────────────────
-
-/**
- * Return true if `pkgName` is resolvable from `managedDir/node_modules`.
- * Version satisfies check is intentionally omitted (no semver dep) —
- * we treat "resolves at all" as satisfied. This is sufficient for the
- * Phase B bootstrap use case.
- */
-export function isNpmPackageInstalled(pkgName: string, managedDir: string): boolean {
-  try {
-    // createRequire resolves from the given path; look in managedDir/node_modules.
-    const req = createRequire(path.join(managedDir, "package.json"));
-    req.resolve(pkgName + "/package.json");
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ── Default installers ─────────────────────────────────────────────────────
-
-async function defaultNpmInstall(
-  pkg: InstallablePackage,
-  managedDir: string,
-  onOutput: InstallProgressCallback,
-): Promise<void> {
-  const spec =
-    pkg.version && pkg.version !== "*"
-      ? `${pkg.name}@${pkg.version}`
-      : pkg.name;
-  const res = await bootstrapInstall({
-    packages: [spec],
-    managedDir,
-    progress: (p) => {
-      if (p.output) onOutput(p.output);
-    },
-  });
-  if (!res.ok) {
-    throw new Error(res.error);
-  }
-}
-
-async function defaultPiExtensionInstall(
-  pkg: InstallablePackage,
-  onOutput: InstallProgressCallback,
-): Promise<void> {
-  const registry = getDefaultRegistry();
-  const { module: piModule } = await registry.resolveModule<{
-    DefaultPackageManager: any;
-    SettingsManager: any;
-  }>("pi-coding-agent");
-  const agentDir = path.join(os.homedir(), ".pi", "agent");
-  const settingsManager = piModule.SettingsManager.create(process.cwd(), agentDir);
-  const pm = new piModule.DefaultPackageManager({
-    cwd: process.cwd(),
-    agentDir,
-    settingsManager,
-  });
-  pm.setProgressCallback((event: { message?: string }) => {
-    if (event.message) onOutput(event.message);
-  });
-  await pm.installAndPersist(pkg.name, { local: false });
-}
-
-// ── Options ────────────────────────────────────────────────────────────────
-
-export interface BootstrapInstallFromListOptions {
-  /** Override config dir for installable.json (default: ~/.pi/dashboard/). */
-  configDir?: string;
-  /** Override managed dir for npm installs (default: ~/.pi-dashboard/). */
-  managedDir?: string;
-  /**
-   * Injectable npm installer. Defaults to bootstrapInstall.
-   * Receives the InstallablePackage and a streaming output callback.
-   */
-  npmInstall?: PackageInstaller;
-  /**
-   * Injectable pi-extension installer. Defaults to pi DefaultPackageManager.
-   * Receives the InstallablePackage and a streaming output callback.
-   */
-  piInstall?: PackageInstaller;
-  /**
-   * Injectable installed-check for npm packages.
-   * Defaults to isNpmPackageInstalled.
-   */
-  isInstalled?: (pkg: InstallablePackage, managedDir: string) => boolean;
-}
-
-// ── Main reconciler ────────────────────────────────────────────────────────
-
-/**
- * Reconcile packages from installable.json against the managed directory.
- *
- * - File absent: log and return immediately (not a failure).
- * - Per package: check installed → skip or install.
- * - Required failure: set bootstrap status=failed, throw (abort server start).
- * - Optional failure: log, record in failed[], continue.
- */
-export async function bootstrapInstallFromList(
-  bootstrapState: BootstrapStateStore,
-  opts?: BootstrapInstallFromListOptions,
-): Promise<void> {
-  const configDir =
-    opts?.configDir ?? path.join(os.homedir(), ".pi", "dashboard");
-  const managedDir = opts?.managedDir ?? getManagedDir();
-
-  // Read installable.json; absent file is a deliberate no-op.
-  const list = await readInstallableList(configDir);
-  if (list === null) {
-    console.log(
-      "[bootstrap] bootstrap.installable.skipped reason=file-not-found",
-    );
-    return;
-  }
-
-  // Only process packages that are active (not deprecated, not defaultOff).
-  const packages = list.packages.filter((p) => !p.deprecated && !p.defaultOff);
-  const total = packages.length;
-  let installedCount = 0;
-  const failed: string[] = [];
-
-  // Stamp initial installable progress into bootstrap state.
-  bootstrapState.set({ installable: { total, installed: 0, failed: [] } });
-
-  const checkInstalled =
-    opts?.isInstalled ?? ((p, dir) => isNpmPackageInstalled(p.name, dir));
-  const doNpmInstall: PackageInstaller =
-    opts?.npmInstall ??
-    ((p, cb) => defaultNpmInstall(p, managedDir, cb));
-  const doPiInstall: PackageInstaller =
-    opts?.piInstall ?? defaultPiExtensionInstall;
-
-  for (const pkg of packages) {
-    // Fast path: already installed (npm packages only; pi-extension always attempts).
-    if (pkg.kind === "npm" && checkInstalled(pkg, managedDir)) {
-      console.log(
-        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=satisfied`,
-      );
-      installedCount++;
-      bootstrapState.set({
-        installable: { total, installed: installedCount, failed },
-      });
-      continue;
-    }
-
-    // Emit installing progress.
-    bootstrapState.set({
-      progress: { step: pkg.name, output: "installing..." },
-      installable: { total, installed: installedCount, failed },
-    });
-
-    try {
-      const onOutput = (line: string): void => {
-        bootstrapState.set({ progress: { step: pkg.name, output: line } });
-      };
-
-      if (pkg.kind === "npm") {
-        await doNpmInstall(pkg, onOutput);
-      } else {
-        await doPiInstall(pkg, onOutput);
-      }
-
-      installedCount++;
-      bootstrapState.set({
-        progress: undefined,
-        installable: { total, installed: installedCount, failed },
-      });
-      console.log(
-        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=done`,
-      );
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      console.error(
-        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=error error=${message}`,
-      );
-      failed.push(pkg.name);
-      bootstrapState.set({
-        progress: undefined,
-        installable: { total, installed: installedCount, failed: [...failed] },
-      });
-
-      if (pkg.required) {
-        const errorMessage = `Required package "${pkg.name}" failed to install: ${message}`;
-        bootstrapState.set({
-          status: "failed",
-          error: { message: errorMessage },
-        });
-        throw new Error(errorMessage);
-      }
-      // Optional package failure: log, continue to next package.
-    }
-  }
-
-  // Final state snapshot.
-  bootstrapState.set({
-    installable: { total, installed: installedCount, failed },
-  });
-  console.log(
-    `[bootstrap] bootstrap.installable.done total=${total} installed=${installedCount} failed=${failed.length}`,
-  );
-}

package/packages/server/src/bootstrap-queue.ts

@@ -1,130 +0,0 @@
-/**
- * In-memory queue for pi-dependent operations deferred during bootstrap
- * install. When `bootstrapState.status === "installing"`, callers should
- * enqueue their handler and return a 202 Accepted with the ticketId.
- * When status transitions to "ready", `flushAll()` runs every queued
- * handler sequentially in enqueue order.
- *
- * Queue is process-local and NOT persisted. If the dashboard crashes
- * mid-install, queued requests are lost — documented as a known
- * limitation in design.md §16.2.
- *
- * See change: unified-bootstrap-install.
- */
-import { randomUUID } from "node:crypto";
-
-export interface QueuedTicket<T> {
-  ticketId: string;
-  /**
-   * Resolves when the queued handler runs (or rejects if it throws).
-   * Call sites can await this when they want to synchronously return
-   * the eventual result — but 202-Accepted flows MUST NOT await, they
-   * return the ticketId to the client immediately.
-   */
-  result: Promise<T>;
-}
-
-export interface BootstrapQueue {
-  enqueue<T>(handler: () => Promise<T>): QueuedTicket<T>;
-  flushAll(): Promise<void>;
-  /** Number of currently pending tickets. */
-  size(): number;
-  /** Drop all pending tickets without running them (used at shutdown). */
-  clear(reason?: string): void;
-  /**
-   * Register a listener invoked after each ticket runs (success or
-   * failure). The server wires this to a `bootstrap_ticket_complete`
-   * WS broadcast so browser clients can correlate the outcome of a
-   * 202-accepted request via their stored ticketId.
-   * See change: unified-bootstrap-install.
-   */
-  onTicketComplete(
-    listener: (evt: { ticketId: string; success: boolean; error?: string }) => void,
-  ): () => void;
-}
-
-interface PendingEntry {
-  ticketId: string;
-  run: () => Promise<void>;
-  /** Reject the caller's `result` promise. Called by `clear()` to
-   *  drain tickets at shutdown. */
-  reject: (err: unknown) => void;
-}
-
-export function createBootstrapQueue(): BootstrapQueue {
-  const pending: PendingEntry[] = [];
-  const listeners = new Set<
-    (evt: { ticketId: string; success: boolean; error?: string }) => void
-  >();
-
-  function notify(evt: { ticketId: string; success: boolean; error?: string }): void {
-    for (const l of listeners) {
-      try {
-        l(evt);
-      } catch (err) {
-        console.error("[bootstrap-queue] ticket-complete listener threw:", err);
-      }
-    }
-  }
-
-  return {
-    enqueue<T>(handler: () => Promise<T>): QueuedTicket<T> {
-      const ticketId = randomUUID();
-      let resolve!: (value: T) => void;
-      let reject!: (err: unknown) => void;
-      const result = new Promise<T>((res, rej) => {
-        resolve = res;
-        reject = rej;
-      });
-      pending.push({
-        ticketId,
-        reject,
-        run: async () => {
-          try {
-            const value = await handler();
-            resolve(value);
-            notify({ ticketId, success: true });
-          } catch (err) {
-            reject(err);
-            const message = err instanceof Error ? err.message : String(err);
-            notify({ ticketId, success: false, error: message });
-          }
-        },
-      });
-      return { ticketId, result };
-    },
-
-    async flushAll(): Promise<void> {
-      while (pending.length > 0) {
-        const entry = pending.shift();
-        if (!entry) break;
-        try {
-          await entry.run();
-        } catch (err) {
-          // Handler errors propagate via the ticket's `result` promise;
-          // they should never reach here unless there's a bug in `run`.
-          console.error(`[bootstrap-queue] ticket ${entry.ticketId} run threw:`, err);
-        }
-      }
-    },
-
-    size() {
-      return pending.length;
-    },
-
-    clear(reason = "queue cleared") {
-      const drained = pending.splice(0, pending.length);
-      for (const entry of drained) {
-        // Reject the caller's `result` promise directly and broadcast the
-        // completion so any browser holding the ticketId learns the
-        // outcome.
-        entry.reject(new Error(reason));
-        notify({ ticketId: entry.ticketId, success: false, error: reason });
-      }
-    },
-    onTicketComplete(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    },
-  };
-}

package/packages/server/src/bootstrap-state.ts

@@ -1,159 +0,0 @@
-import type { DashboardStarter } from "@blackbelt-technology/pi-dashboard-shared/dashboard-starter.js";
-
-/**
- * In-memory bootstrap state store for the dashboard server.
- *
- * Tracks the degraded-mode status during first-run pi install, upgrade
- * operations, and version-skew detection. Subscribers (browser gateway,
- * CLI progress printer) receive a snapshot on every `set()` call.
- *
- * See change: unified-bootstrap-install.
- */
-
-export type BootstrapStatus = "ready" | "installing" | "failed";
-
-export interface BootstrapProgress {
-  /** Package / phase being processed (e.g. "pi-coding-agent", "bridge-register"). */
-  step: string;
-  /** Optional completion percentage (0..100). */
-  pct?: number;
-  /** Last line of npm output or other streaming context. */
-  output?: string;
-}
-
-export interface BootstrapError {
-  message: string;
-  stack?: string;
-}
-
-export interface BootstrapVersions {
-  pi?: string;
-  openspec?: string;
-  tsx?: string;
-}
-
-export interface BootstrapCompatibility {
-  minimum: string;
-  recommended: string;
-  /** null = no upper bound enforced yet. */
-  maximum: string | null;
-  /** Current resolved pi version, or undefined when pi is unresolved. */
-  current?: string;
-  /** Hint that the user should upgrade pi (below recommended). */
-  upgradeRecommended?: boolean;
-  /** Hint that the user should upgrade the dashboard itself (above maximum). */
-  upgradeDashboard?: boolean;
-}
-
-export interface BootstrapState {
-  status: BootstrapStatus;
-  progress?: BootstrapProgress;
-  error?: BootstrapError;
-  version?: BootstrapVersions;
-  compatibility?: BootstrapCompatibility;
-  /** Set when `registerBridgeExtension` fails after a successful install. */
-  bridgeRegistrationError?: string;
-  /**
-   * Who started this server process. Defaults to "Standalone" (direct CLI).
-   * Set at boot time from `parseDashboardStarter(process.env)`.
-   */
-  starter?: DashboardStarter;
-  /**
-   * Installable list reconciliation progress.
-   * Set by bootstrapInstallFromList during Phase B reconcile.
-   * See change: simplify-electron-bootstrap-derived-state.
-   */
-  installable?: {
-    total: number;
-    installed: number;
-    /** Package names that failed to install. */
-    failed: string[];
-  };
-  /**
-   * Legacy `@mariozechner/pi-coding-agent` installs detected on disk.
-   * Populated at server start and after every cleanup POST. See
-   * `legacy-pi-cleanup.ts`.
-   */
-  legacyPiInstalls?: Array<{
-    scope: "npm-global" | "npx-cache" | "managed";
-    path: string;
-    version: string | null;
-  }>;
-}
-
-export type BootstrapListener = (state: BootstrapState) => void;
-
-export interface BootstrapStateStore {
-  get(): BootstrapState;
-  /**
-   * Merge `partial` into the current state. Passing `undefined` for a
-   * key explicitly clears it (e.g. `set({ progress: undefined })` removes
-   * the progress line after completion). Broadcasts to all subscribers.
-   */
-  set(partial: Partial<BootstrapState>): void;
-  subscribe(listener: BootstrapListener): () => void;
-  /** Clear all listeners (used in tests + server shutdown). */
-  dispose(): void;
-  /**
-   * Record the package list used by the most recent `bootstrapInstall`
-   * call. Used by `POST /api/bootstrap/retry` to re-run the exact failed
-   * set rather than a hard-coded default. Not part of the WS-broadcast
-   * snapshot — it's purely side-channel metadata for the server.
-   * See change: unified-bootstrap-install (verification follow-up).
-   */
-  setLastInstallPackages(packages: readonly string[]): void;
-  /** Read the last install set. Returns a fresh copy. */
-  getLastInstallPackages(): string[];
-}
-
-/**
- * Create a fresh bootstrap state store. `initial` is merged over the
- * default `{ status: "ready" }`.
- */
-export function createBootstrapState(
-  initial?: Partial<BootstrapState>,
-): BootstrapStateStore {
-  let state: BootstrapState = { status: "ready", ...initial };
-  let lastInstallPackages: string[] = [];
-  const listeners = new Set<BootstrapListener>();
-
-  function notify(): void {
-    const snapshot = { ...state };
-    for (const l of listeners) {
-      try {
-        l(snapshot);
-      } catch (err) {
-        // Listener errors are non-fatal — log but continue.
-        console.error("[bootstrap-state] listener threw:", err);
-      }
-    }
-  }
-
-  return {
-    get() {
-      return { ...state };
-    },
-    set(partial) {
-      // Merge: explicit `undefined` in partial clears the field.
-      state = { ...state, ...partial } as BootstrapState;
-      // Strip keys whose value is undefined to keep the snapshot tidy.
-      for (const key of Object.keys(partial) as (keyof BootstrapState)[]) {
-        if (partial[key] === undefined) delete state[key];
-      }
-      notify();
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    },
-    dispose() {
-      listeners.clear();
-    },
-    setLastInstallPackages(packages) {
-      lastInstallPackages = [...packages];
-    },
-    getLastInstallPackages() {
-      return [...lastInstallPackages];
-    },
-  };
-}

package/packages/server/src/legacy-pi-cleanup.ts

@@ -1,151 +0,0 @@
-/**
- * Detects and removes legacy `@mariozechner/pi-coding-agent` installs.
- *
- * Pi was renamed to `@earendil-works/pi-coding-agent` at v0.74. The legacy
- * scope is published only up to v0.73.x and conflicts with the new scope's
- * `bin/pi` symlink in npm-global (EEXIST). This module surfaces legacy
- * installs so the UI can offer a one-click cleanup.
- *
- * Detection is read-only and cheap (3 fs.stat calls + optional `npm root
- * -g`). Cleanup is gated behind a POST endpoint — never silent.
- *
- * Scopes scanned:
- *   - npm-global:  `$(npm root -g)/@mariozechner/pi-coding-agent`
- *   - npx-cache:   `~/.npm/_npx/<hash>/node_modules/@mariozechner/pi-coding-agent`
- *   - managed:     `~/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent`
- */
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { execSync } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
-
-export const LEGACY_PI_PACKAGE = "@mariozechner/pi-coding-agent";
-
-export type LegacyPiScope = "npm-global" | "npx-cache" | "managed";
-
-export interface LegacyPiInstall {
-  scope: LegacyPiScope;
-  path: string;
-  version: string | null;
-}
-
-export interface LegacyPiCleanupResult {
-  scope: LegacyPiScope;
-  path: string;
-  removed: boolean;
-  error?: string;
-}
-
-// ── Pure helpers (no I/O) ──────────────────────────────────────────
-
-/** Build the legacy package path under a given node_modules root. */
-export function legacyPathUnder(nodeModulesDir: string): string {
-  return path.join(nodeModulesDir, ...LEGACY_PI_PACKAGE.split("/"));
-}
-
-/** Read `version` from a package.json blob; returns null on any parse failure. */
-export function parseVersion(packageJsonRaw: string): string | null {
-  try {
-    const parsed = JSON.parse(packageJsonRaw);
-    return typeof parsed.version === "string" ? parsed.version : null;
-  } catch {
-    return null;
-  }
-}
-
-// ── Detection ──────────────────────────────────────────────────────
-
-function safeStatDir(p: string): boolean {
-  try { return fs.statSync(p).isDirectory(); } catch { return false; }
-}
-
-function readVersionOf(packageDir: string): string | null {
-  try {
-    const raw = fs.readFileSync(path.join(packageDir, "package.json"), "utf-8");
-    return parseVersion(raw);
-  } catch {
-    return null;
-  }
-}
-
-function detectNpmGlobal(): LegacyPiInstall | null {
-  let globalRoot: string;
-  try {
-    globalRoot = execSync("npm root -g", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return null; // npm not available, or call failed — treat as no install
-  }
-  if (!globalRoot) return null;
-  const pkgDir = legacyPathUnder(globalRoot);
-  if (!safeStatDir(pkgDir)) return null;
-  return { scope: "npm-global", path: pkgDir, version: readVersionOf(pkgDir) };
-}
-
-function detectNpxCache(): LegacyPiInstall[] {
-  const root = path.join(os.homedir(), ".npm", "_npx");
-  let entries: string[];
-  try { entries = fs.readdirSync(root); } catch { return []; }
-  const found: LegacyPiInstall[] = [];
-  for (const hash of entries) {
-    const pkgDir = legacyPathUnder(path.join(root, hash, "node_modules"));
-    if (safeStatDir(pkgDir)) {
-      found.push({ scope: "npx-cache", path: pkgDir, version: readVersionOf(pkgDir) });
-    }
-  }
-  return found;
-}
-
-function detectManaged(): LegacyPiInstall | null {
-  const pkgDir = legacyPathUnder(path.join(os.homedir(), ".pi-dashboard", "node_modules"));
-  if (!safeStatDir(pkgDir)) return null;
-  return { scope: "managed", path: pkgDir, version: readVersionOf(pkgDir) };
-}
-
-/**
- * Scan all three locations for legacy pi installs. Synchronous because
- * the cost is dominated by one `npm root -g` invocation (~50ms once);
- * everything else is fs.statSync. Called at startup and on POST refresh.
- */
-export function detectLegacyPiInstalls(): LegacyPiInstall[] {
-  const found: LegacyPiInstall[] = [];
-  const g = detectNpmGlobal();
-  if (g) found.push(g);
-  found.push(...detectNpxCache());
-  const m = detectManaged();
-  if (m) found.push(m);
-  return found;
-}
-
-// ── Cleanup ────────────────────────────────────────────────────────
-
-function rmrf(target: string): void {
-  fs.rmSync(target, { recursive: true, force: true });
-}
-
-function removeOne(install: LegacyPiInstall): LegacyPiCleanupResult {
-  const base: Pick<LegacyPiCleanupResult, "scope" | "path"> = { scope: install.scope, path: install.path };
-  try {
-    if (install.scope === "npm-global") {
-      // npm-global needs the package-manager call so any bin symlinks are
-      // cleaned up too. Using `--no-fund --no-audit` to keep output quiet.
-      execSync(`npm uninstall -g --no-fund --no-audit ${LEGACY_PI_PACKAGE}`, {
-        stdio: ["ignore", "pipe", "pipe"],
-        encoding: "utf-8",
-      });
-    } else {
-      // npx-cache and managed are plain node_modules subtrees we can rm.
-      rmrf(install.path);
-    }
-    return { ...base, removed: true };
-  } catch (err: any) {
-    return { ...base, removed: false, error: err?.message ?? String(err) };
-  }
-}
-
-/**
- * Remove all detected legacy installs. Each scope is attempted
- * independently; one failure does not abort the others.
- */
-export function uninstallLegacyPi(installs: readonly LegacyPiInstall[]): LegacyPiCleanupResult[] {
-  return installs.map(removeOne);
-}