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

package/packages/shared/src/dashboard-plugin/ui-primitives.ts

@@ -0,0 +1,287 @@
+/**
+ * UI primitive registry — public contract types.
+ *
+ * Defines the stable string keys plugins use to look up dashboard-provided
+ * UI primitives (components + helpers) at runtime via `useUiPrimitive(key)`.
+ * Each key has a typed contract in `UiPrimitiveMap`; the contract is the
+ * primitive's public API — adding optional props is non-breaking, renaming
+ * or removing required props is breaking.
+ *
+ * The dashboard's main.tsx is responsible for registering an implementation
+ * for every key in `UI_PRIMITIVE_KEYS`. The registry runtime itself lives in
+ * `@blackbelt-technology/dashboard-plugin-runtime`; this file is just types
+ * and key constants so it can be imported safely from any layer (no React
+ * runtime cost for non-renderer consumers).
+ *
+ * See change: add-plugin-ui-primitive-registry.
+ */
+import type { ComponentType, ReactNode } from "react";
+import type { ModelInfo } from "../types.js";
+
+/**
+ * Frozen set of stable string keys identifying registered UI primitives.
+ *
+ * Keys are namespaced under `ui:` so they're easy to grep and so future
+ * registries (e.g. server-side or extension-specific) won't collide.
+ *
+ * Adding a key is non-breaking. Renaming or removing a key requires a
+ * deprecation cycle (register both keys for one minor release with a
+ * warning, then remove).
+ */
+export const UI_PRIMITIVE_KEYS = {
+  /** Reusable card container with status-colored border, header, optional stats line. */
+  agentCard: "ui:agent-card",
+  /** Markdown renderer with code highlighting, math, mermaid, tables, lightbox. */
+  markdownContent: "ui:markdown-content",
+  /** Modal yes/no confirmation dialog. */
+  confirmDialog: "ui:confirm-dialog",
+  /** Base modal portal: renders children at `document.body` with body-scroll lock. */
+  dialogPortal: "ui:dialog-portal",
+  /** Typeahead-filtered selection dialog with keyboard navigation. */
+  searchableSelectDialog: "ui:searchable-select-dialog",
+  /** Zoom in/out/reset button group, paired with a zoom-pan controller. */
+  zoomControls: "ui:zoom-controls",
+  /** Format a token count as a human-readable string (e.g. 12000 → "12k"). */
+  formatTokens: "ui:format-tokens",
+  /** Format a duration in milliseconds as a human-readable string. */
+  formatDuration: "ui:format-duration",
+  /** Horizontal row of action buttons; used by intent-driven plugin contributions. */
+  actionList: "ui:action-list",
+  /** Status pill (badge) with state-tinted background + optional icon. */
+  statusPill: "ui:status-pill",
+  /** Model picker with provider filter, typeahead, keyboard navigation, pending-state. */
+  modelSelector: "ui:model-selector",
+  /** Floating panel anchored to a DOM element; dismisses on outside-click/Esc. */
+  popover: "ui:popover",
+  /** Rich tool-call card matching the main chat view (per-tool renderers,
+   *  collapsible output, status icon). Used by plugin timelines that want
+   *  parity with the dashboard chat tool rendering. */
+  toolCallStep: "ui:tool-call-step",
+  /** Reasoning / thinking block with collapsible content + elapsed-time badge.
+   *  Matches the main chat view's thinking rendering. */
+  thinkingBlock: "ui:thinking-block",
+} as const;
+
+/** Union of all valid UI primitive keys (literal-string narrowed). */
+export type UiPrimitiveKey = (typeof UI_PRIMITIVE_KEYS)[keyof typeof UI_PRIMITIVE_KEYS];
+
+// ── Public contract types ──────────────────────────────────────────────────
+
+/**
+ * Public prop signature for the agent-card primitive.
+ *
+ * Mirrors `AgentCardShell` in client-utils. Optional fields stay optional;
+ * required fields stay required. Adding a new optional prop is non-breaking;
+ * renaming `name` to `title` would be breaking.
+ */
+export interface UiAgentCardProps {
+  name: string;
+  status: string;
+  headerRight?: ReactNode;
+  stats?: ReactNode;
+  onClick?: () => void;
+  selected?: boolean;
+  children?: ReactNode;
+}
+
+/** Public prop signature for the markdown-content primitive. */
+export interface UiMarkdownContentProps {
+  content: string;
+}
+
+/** Public prop signature for the confirm-dialog primitive. */
+export interface UiConfirmDialogProps {
+  message: string;
+  confirmLabel?: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+/** Public prop signature for the dialog-portal primitive. */
+export interface UiDialogPortalProps {
+  children: ReactNode;
+}
+
+/**
+ * One option in a searchable-select-dialog. Mirrors `SelectOption` in
+ * client-utils so the existing component implementation is contract-compatible
+ * without adapter shims.
+ */
+export interface UiSelectOption {
+  value: string;
+  label: string;
+  description?: string;
+  badge?: string;
+  badgeColor?: string;
+}
+
+/** Public prop signature for the searchable-select-dialog primitive. */
+export interface UiSearchableSelectDialogProps {
+  title: string;
+  options: UiSelectOption[];
+  onSelect: (value: string) => void;
+  onCancel: () => void;
+  placeholder?: string;
+  emptyMessage?: string;
+}
+
+/** Public prop signature for the zoom-controls primitive. */
+export interface UiZoomControlsProps {
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onReset: () => void;
+  scale: number;
+}
+
+/** A single entry in an action-list primitive. */
+export interface UiActionListItem {
+  /** Display label for the action button. */
+  label: string;
+  /** Optional MDI icon key from `@mdi/js` (e.g. `mdiPlay`). */
+  icon?: string;
+  /** Optional tooltip on hover. */
+  tooltip?: string;
+  /** Optional click handler (wired by IntentRenderer from action descriptor). */
+  onClick?: () => void;
+  /** Optional disabled flag. */
+  disabled?: boolean;
+}
+
+/** Public prop signature for the action-list primitive. */
+export interface UiActionListProps {
+  actions: UiActionListItem[];
+}
+
+/** Stable state tokens for the status-pill primitive. */
+export type UiStatusPillState =
+  | "running"
+  | "success"
+  | "error"
+  | "info"
+  | "warn"
+  | "muted";
+
+/** Public prop signature for the status-pill primitive. */
+export interface UiStatusPillProps {
+  state: UiStatusPillState;
+  text: string;
+  /** Optional MDI icon key from `@mdi/js`. */
+  icon?: string;
+  /** Optional tooltip on hover. */
+  tooltip?: string;
+}
+
+/**
+ * Public prop signature for the model-selector primitive.
+ *
+ * Mirrors the existing `ModelSelector` component (`packages/client/src/
+ * components/ModelSelector.tsx`) used by `StatusBar`. The primitive exposes
+ * the same model-picker UX (provider filter, typeahead, keyboard navigation,
+ * pending-state with 10 s timeout) to plugins without forcing them to depend
+ * on the client package.
+ *
+ * Role/preset props that historically existed on `ModelSelector` are NOT part
+ * of this contract — role management is a host concern (see
+ * `BuiltInRolesSettings` in roles-plugin) layered on top.
+ */
+export interface UiModelSelectorProps {
+  /** Currently-selected model label in `"<provider>/<id>"` form, or undefined. */
+  current?: string;
+  /** Available models. When undefined, the primitive renders non-interactive text. */
+  models?: ModelInfo[];
+  /** Invoked with the full `"<provider>/<id>"` string of the chosen model. */
+  onSelect: (modelLabel: string) => void;
+}
+
+/**
+ * Public prop signature for the popover primitive.
+ *
+ * A floating panel positioned relative to `anchorEl`. Dismisses on Esc or
+ * clicks outside the popover (and outside the anchor). The host owns the
+ * open/closed state; rendering the primitive at all is the "open" signal.
+ *
+ * Differs from `dialogPortal`: no scroll lock, no modal backdrop, position
+ * is computed from the anchor's viewport rect (not centered).
+ */
+export interface UiPopoverProps {
+  /** DOM element the popover is anchored to. */
+  anchorEl: HTMLElement;
+  /** Invoked when the user clicks outside or presses Esc. */
+  onDismiss: () => void;
+  /** Popover content (any React tree). */
+  children: ReactNode;
+  /** Optional gap (px) between anchor and popover edge. Default 6. */
+  offset?: number;
+}
+
+// ── The map ────────────────────────────────────────────────────────────────
+
+/**
+ * Type-level mapping from each `UI_PRIMITIVE_KEYS` value to its public
+ * implementation contract.
+ *
+ * Component contracts use `ComponentType<P>` (React functional or class
+ * component); helper contracts use plain function signatures. The runtime
+ * registry uses this map to type-check both registration and lookup.
+ *
+ * Adding a key: extend `UI_PRIMITIVE_KEYS` AND add the corresponding entry
+ * here. TypeScript will fail builds that reference the new key without
+ * matching registration in main.tsx.
+ */
+export interface UiPrimitiveMap {
+  "ui:agent-card": ComponentType<UiAgentCardProps>;
+  "ui:markdown-content": ComponentType<UiMarkdownContentProps>;
+  "ui:confirm-dialog": ComponentType<UiConfirmDialogProps>;
+  "ui:dialog-portal": ComponentType<UiDialogPortalProps>;
+  "ui:searchable-select-dialog": ComponentType<UiSearchableSelectDialogProps>;
+  "ui:zoom-controls": ComponentType<UiZoomControlsProps>;
+  "ui:format-tokens": (n: number) => string;
+  "ui:format-duration": (ms: number) => string;
+  "ui:action-list": ComponentType<UiActionListProps>;
+  "ui:status-pill": ComponentType<UiStatusPillProps>;
+  "ui:model-selector": ComponentType<UiModelSelectorProps>;
+  "ui:popover": ComponentType<UiPopoverProps>;
+  "ui:tool-call-step": ComponentType<UiToolCallStepProps>;
+  "ui:thinking-block": ComponentType<UiThinkingBlockProps>;
+}
+
+/**
+ * Image attachment shape carried by tool-call rendering. Structurally
+ * compatible with the shell's `ChatImage` and the shared
+ * `ImageContent` (the `type: "image"` field is optional here so plugins
+ * don't need to manufacture it).
+ */
+export interface UiToolCallImage {
+  data: string;
+  mimeType: string;
+}
+
+/**
+ * Public prop signature for the rich tool-call card. The shell registers
+ * an implementation backed by its `ToolCallStep` component (which fans
+ * out to per-tool renderers — Bash, Read, Edit, Write, Agent, AskUser,
+ * Generic). Optional fields stay optional; required fields stay required.
+ */
+export interface UiToolCallStepProps {
+  toolName: string;
+  /** Identifier used by per-tool renderers to scope click handlers; synthetic ids are fine. */
+  toolCallId: string;
+  args?: Record<string, unknown>;
+  status: "running" | "complete" | "error";
+  result?: string;
+  images?: UiToolCallImage[];
+  toolDetails?: Record<string, unknown>;
+  startedAt?: number;
+  duration?: number;
+  /** Session id passed through to per-tool renderers that need session scope. */
+  sessionId?: string;
+}
+
+/** Public prop signature for the thinking-block primitive. */
+export interface UiThinkingBlockProps {
+  content: string;
+  isStreaming?: boolean;
+  defaultExpanded?: boolean;
+  startedAt?: number;
+  duration?: number;
+}

package/packages/shared/src/dashboard-starter.ts

@@ -31,3 +31,25 @@ export function parseDashboardStarter(
   );
   return "Standalone";
 }
+
+/**
+ * `LaunchSource` — lowercase alias of `DashboardStarter` exposed on
+ * `/api/health` as a stable client contract for arm-aware gating
+ * (notably hiding pi-core update UI when running under Electron, since
+ * the bundled `node_modules/` is read-only under the .app).
+ *
+ * Detection follows `parseDashboardStarter` then lowercases:
+ *   DASHBOARD_STARTER=Electron   → "electron"
+ *   DASHBOARD_STARTER=Bridge     → "bridge"
+ *   else                          → "standalone"
+ *
+ * See change: eliminate-electron-runtime-install (task 3.2).
+ */
+export type LaunchSource = "electron" | "standalone" | "bridge";
+
+export function parseLaunchSource(
+  env: Record<string, string | undefined>,
+): LaunchSource {
+  const s = parseDashboardStarter(env);
+  return s === "Electron" ? "electron" : s === "Bridge" ? "bridge" : "standalone";
+}

package/packages/shared/src/doctor-core.ts

@@ -11,7 +11,7 @@
  * See change: doctor-rich-output (proposal.md, design.md).
  */
 import { execSync } from "./platform/exec.js";
-import { existsSync, readFileSync, statSync, renameSync, appendFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, renameSync, appendFileSync, rmSync } from "node:fs";
 import path from "node:path";
 
 // ─── Types ─────────────────────────────────────────────────────────────
@@ -290,8 +290,7 @@ function rotateDoctorLogIfNeeded(logPath: string): void {
     } catch {
       // try once more after best-effort cleanup
       try {
-        const fs = require("node:fs") as typeof import("node:fs");
-        if (existsSync(rotated)) fs.rmSync(rotated, { force: true });
+        if (existsSync(rotated)) rmSync(rotated, { force: true });
         renameSync(logPath, rotated);
       } catch {
         // give up silently
@@ -321,7 +320,7 @@ export const SECTION_OF: Record<string, DoctorSection> = {
   // server
   "Dashboard server code": "server",
   "Offline packages bundle": "server",
-  "TypeScript loader (tsx)": "server",
+  "TypeScript loader": "server",
   "Dashboard server": "server",
   "Server starter": "server",
   "Installable list": "server",
@@ -399,10 +398,10 @@ export const SUGGESTIONS: Record<string, SuggestionFn> = {
     status === "ok"
       ? undefined
       : "Offline packages bundle absent. First-run install will require network access to `registry.npmjs.org`.",
-  "TypeScript loader (tsx)": (status) =>
+  "TypeScript loader": (status) =>
     status === "ok"
       ? undefined
-      : "`tsx` not found. Required to run the dashboard server. Run the setup wizard (Help → Setup).",
+      : "No TypeScript loader (jiti or tsx) found. Required to run the dashboard server. Run the setup wizard (Help → Setup).",
   "Dashboard server": (status) =>
     status === "ok"
       ? undefined
@@ -548,43 +547,66 @@ export async function runSharedChecks(deps: SharedChecksDeps): Promise<DoctorChe
     }),
   );
 
-  // tsx (TypeScript loader)
+  // TypeScript loader (jiti preferred; tsx accepted as fallback)
+  // The dashboard server runs via jiti by default (see shared/server-launcher.ts
+  // resolveJiti). tsx was the legacy choice and is still accepted if jiti is
+  // unavailable. The check passes when EITHER loader is resolvable so users
+  // running on jiti don't see a spurious error.
   checks.push(
-    await safeCheck("TypeScript loader (tsx)", "server", () => {
+    await safeCheck("TypeScript loader", "server", () => {
+      const managedJitiPkg = path.join(managedDir, "node_modules", "jiti", "package.json");
       const managedTsxPkg = path.join(managedDir, "node_modules", "tsx", "package.json");
-      let tsxVersion: string | null = null;
-      try {
-        if (existsSync(managedTsxPkg)) {
-          const pkg = JSON.parse(readFileSync(managedTsxPkg, "utf-8"));
-          tsxVersion = pkg.version || null;
+
+      function readVersion(pkgPath: string): string | null {
+        try {
+          if (!existsSync(pkgPath)) return null;
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+          return pkg.version || null;
+        } catch {
+          return null;
         }
-      } catch {
-        // ignore
       }
+      const jitiVersion = readVersion(managedJitiPkg);
+      const tsxVersion = readVersion(managedTsxPkg);
+
       let systemTsx: string | null = null;
       const lookupCmd = process.platform === "win32" ? "where tsx" : "which tsx"; // platform-branch-ok: localised PATH-lookup primitive
       const lookup = safeExec(lookupCmd, { timeoutMs: 5000 });
       if (lookup.ok) {
         systemTsx = lookup.stdout.trim().split("\n")[0] || null;
       }
-      const found = !!tsxVersion || !!systemTsx;
-      if (!found) {
+
+      if (jitiVersion) {
         return {
-          name: "TypeScript loader (tsx)",
+          name: "TypeScript loader",
           section: "server",
-          status: "error",
-          message: "Not found — required to run the dashboard server",
-          detail: `Looked under ${managedTsxPkg} and on PATH`,
-          fixable: true,
+          status: "ok",
+          message: `jiti v${jitiVersion} (managed) at ${path.dirname(managedJitiPkg)}`,
+        };
+      }
+      if (tsxVersion) {
+        return {
+          name: "TypeScript loader",
+          section: "server",
+          status: "ok",
+          message: `tsx v${tsxVersion} (managed) at ${path.dirname(managedTsxPkg)}`,
+        };
+      }
+      if (systemTsx) {
+        return {
+          name: "TypeScript loader",
+          section: "server",
+          status: "ok",
+          message: `tsx (system) at ${systemTsx}`,
         };
       }
       return {
-        name: "TypeScript loader (tsx)",
+        name: "TypeScript loader",
         section: "server",
-        status: "ok",
-        message: tsxVersion
-          ? `v${tsxVersion} (managed) at ${path.dirname(managedTsxPkg)}`
-          : `(system) at ${systemTsx}`,
+        status: "error",
+        message: "Not found — required to run the dashboard server",
+        detail: `Looked under ${managedJitiPkg}, ${managedTsxPkg}, and on PATH`,
+        fixable: true,
       };
     }),
   );

package/packages/shared/src/launch-source-types.ts

@@ -2,17 +2,17 @@
  * LaunchSource — discriminated union describing how the dashboard server was (or should be) started.
  *
  * "attach"      — a server is already running; Electron attaches to it.
- * "devMonorepo" — running from a checked-out monorepo (dev workflow).
- * "piExtension" — the pi bridge extension owns a server package in node_modules.
- * "npmGlobal"   — `pi-dashboard` is installed globally via npm.
- * "extracted"   — bundled Electron resources provide the server (managed install).
+ * "bundled"     — bundled Electron resources provide the server (immutable .app/Contents/Resources tree).
+ * "devMonorepo" — running from a checked-out monorepo (dev workflow only, gated by ELECTRON_DEV).
+ *
+ * Pre-R3 layouts (`piExtension`, `npmGlobal`, `extracted`) are removed:
+ * the immutable bundle is the only runtime layout under packaged Electron.
+ * See change: eliminate-electron-runtime-install.
  */
 
-export type SourceKind = "attach" | "devMonorepo" | "piExtension" | "npmGlobal" | "extracted";
+export type SourceKind = "attach" | "bundled" | "devMonorepo";
 
 export type LaunchSource =
   | { kind: "attach"; url: string; starter: "Bridge" | "Standalone" | "Electron" }
-  | { kind: "devMonorepo"; cliPath: string; cwd: string }
-  | { kind: "piExtension"; cliPath: string; cwd: string }
-  | { kind: "npmGlobal"; cliPath: string; cwd: string }
-  | { kind: "extracted"; cliPath: string; cwd: string; didExtract?: boolean };
+  | { kind: "bundled"; cliPath: string; cwd: string }
+  | { kind: "devMonorepo"; cliPath: string; cwd: string };

package/packages/shared/src/legacy-managed-dir.ts

@@ -0,0 +1,97 @@
+/**
+ * Detect the legacy `~/.pi-dashboard/` install directory left behind from
+ * pre-R3 versions where the Electron app (and the standalone bootstrap
+ * orchestrator) installed pi/openspec/tsx at runtime into a user-writable
+ * directory.
+ *
+ * Under the immutable-bundle architecture (change:
+ * eliminate-electron-runtime-install) nothing reads from or writes to
+ * this directory on the Electron arm. This module exists solely so the
+ * Doctor UI can surface an advisory row, and the server CLI can log a
+ * one-time hint, telling the user the directory is safe to delete.
+ *
+ * NEVER move runtime install logic back into this directory. If you find
+ * yourself reaching for `~/.pi-dashboard/`, you are working against R3.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export type LegacyManagedDir =
+  | { present: false }
+  | { present: true; path: string; pkgCount: number; sizeMb: number };
+
+export interface DetectDeps {
+  /** Override HOME for tests. */
+  homedir?: string;
+}
+
+const LEGACY_DIRNAME = ".pi-" + "dashboard"; // split literal so the no-managed-dir lint stays clean
+
+function getLegacyDirPath(env?: DetectDeps): string {
+  return path.join(env?.homedir ?? os.homedir(), LEGACY_DIRNAME);
+}
+
+/** Sum file sizes under a directory tree, capped to avoid pathological scans. */
+function dirSizeBytes(dir: string, cap = 500 * 1024 * 1024): number {
+  let total = 0;
+  const stack: string[] = [dir];
+  while (stack.length > 0 && total < cap) {
+    const cur = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      try {
+        if (e.isSymbolicLink()) continue;
+        if (e.isDirectory()) {
+          stack.push(full);
+        } else if (e.isFile()) {
+          const st = fs.statSync(full);
+          total += st.size;
+          if (total >= cap) return cap;
+        }
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  }
+  return total;
+}
+
+function countDirectChildren(dir: string): number {
+  try {
+    return fs.readdirSync(dir).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Detect whether the legacy `~/.pi-dashboard/` directory is present.
+ * Returns `{ present: false }` when missing. When present, returns a
+ * `pkgCount` (entries directly under `node_modules/`, 0 if missing) and
+ * `sizeMb` (recursive byte sum, capped at 500 MB).
+ */
+export function detectLegacyManagedDir(deps: DetectDeps = {}): LegacyManagedDir {
+  const dir = getLegacyDirPath(deps);
+  try {
+    const st = fs.statSync(dir);
+    if (!st.isDirectory()) return { present: false };
+  } catch {
+    return { present: false };
+  }
+  const nodeModules = path.join(dir, "node_modules");
+  const pkgCount = countDirectChildren(nodeModules);
+  const sizeMb = Math.round(dirSizeBytes(dir) / (1024 * 1024));
+  return { present: true, path: dir, pkgCount, sizeMb };
+}
+
+/** Path-only accessor for callers that want to display the path without scanning. */
+export function getLegacyManagedDirPath(deps: DetectDeps = {}): string {
+  return getLegacyDirPath(deps);
+}

package/packages/shared/src/mdns-discovery.ts

@@ -5,8 +5,11 @@
 import { Bonjour, type Service, type Browser } from "bonjour-service";
 import os from "node:os";
 import { EventEmitter } from "node:events";
+import { createRequire } from "node:module";
 import { isDashboardRunning } from "./server-identity.js";
 
+const _require = createRequire(import.meta.url);
+
 const SERVICE_TYPE = "pi-dashboard";
 
 export interface DiscoveredServer {
@@ -43,7 +46,7 @@ export function advertiseDashboard(port: number, piPort: number): void {
   const bonjour = getBonjour();
   const pkg = { version: "0.0.0" }; // Will be replaced by actual version
   try {
-    const pkgJson = require("../../package.json");
+    const pkgJson = _require("../../package.json");
     pkg.version = pkgJson.version ?? "0.0.0";
   } catch { /* ignore */ }