@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/shared/src/config.ts

@@ -0,0 +1,245 @@
+/**
+ * Shared configuration module for PI Dashboard.
+ * Used by both the server CLI and bridge extension.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".pi", "dashboard");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+export type SpawnStrategy = "tmux" | "headless";
+
+export interface AuthProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  issuerUrl?: string;
+  name?: string;
+}
+
+export interface AuthConfig {
+  secret: string;
+  providers: Record<string, AuthProviderConfig>;
+  allowedUsers?: string[];
+  bypassUrls?: string[];
+  bypassHosts?: string[];
+}
+
+export interface MemoryLimitsConfig {
+  /** Max events stored per session (0 = unlimited). Default: 200 */
+  maxEventsPerSession: number;
+  /** Max chars before truncating string fields in events (0 = no truncation). Default: 0 (disabled) */
+  maxStringFieldSize: number;
+  /** Max bytes in browser WebSocket send buffer before dropping messages (0 = no limit). Default: 4194304 (4MB) */
+  maxWsBufferBytes: number;
+}
+
+export const DEFAULT_MEMORY_LIMITS: MemoryLimitsConfig = {
+  maxEventsPerSession: 5000,
+  maxStringFieldSize: 0,
+  maxWsBufferBytes: 4 * 1024 * 1024,
+};
+
+export interface EditorConfig {
+  /** Override path to code-server binary */
+  binary?: string;
+  /** Minutes before idle instance is killed (default: 10) */
+  idleTimeoutMinutes: number;
+  /** Maximum concurrent code-server instances (default: 3) */
+  maxInstances: number;
+}
+
+export const DEFAULT_EDITOR_CONFIG: EditorConfig = {
+  idleTimeoutMinutes: 10,
+  maxInstances: 3,
+};
+
+export interface DashboardConfig {
+  port: number;
+  piPort: number;
+  autoStart: boolean;
+  autoShutdown: boolean;
+  shutdownIdleSeconds: number;
+  spawnStrategy: SpawnStrategy;
+  tunnel: { enabled: boolean; reservedToken?: string };
+  devBuildOnReload: boolean;
+  auth?: AuthConfig;
+  defaultModel: string;
+  memoryLimits: MemoryLimitsConfig;
+  editor: EditorConfig;
+  /** Networks trusted for full access without authentication (CIDR, wildcard, exact IP) */
+  trustedNetworks: string[];
+  /** Merged trustedNetworks + auth.bypassHosts (deduplicated). Computed at load time. */
+  resolvedTrustedNetworks: string[];
+  /** CORS allowed origins for cross-origin client hosting */
+  cors: CorsConfig;
+  /** Last-used server address (host:port) for reconnection */
+  lastServer?: string;
+  /** Whether the server was launched by the Electron app */
+  electronMode: boolean;
+}
+
+export interface CorsConfig {
+  /** Additional origins allowed for cross-origin requests */
+  allowedOrigins: string[];
+}
+
+const VALID_SPAWN_STRATEGIES: SpawnStrategy[] = ["tmux", "headless"];
+
+const DEFAULTS: DashboardConfig = {
+  port: 8000,
+  piPort: 9999,
+  autoStart: true,
+  autoShutdown: false,
+  shutdownIdleSeconds: 300,
+  spawnStrategy: "headless",
+  tunnel: { enabled: true },
+  devBuildOnReload: false,
+  defaultModel: "",
+  memoryLimits: { ...DEFAULT_MEMORY_LIMITS },
+  editor: { ...DEFAULT_EDITOR_CONFIG },
+  trustedNetworks: [],
+  resolvedTrustedNetworks: [],
+  cors: { allowedOrigins: [] },
+  electronMode: false,
+};
+
+/**
+ * Parse and validate the auth config section.
+ * Returns undefined if auth is not configured or has no providers.
+ */
+function parseAuthConfig(raw: any): AuthConfig | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const providers = raw.providers;
+  if (!providers || typeof providers !== "object" || Object.keys(providers).length === 0) {
+    return undefined;
+  }
+  // Validate each provider has at least clientId and clientSecret
+  const validProviders: Record<string, AuthProviderConfig> = {};
+  for (const [key, value] of Object.entries(providers)) {
+    const p = value as any;
+    if (p && typeof p === "object" && p.clientId && p.clientSecret) {
+      validProviders[key] = {
+        clientId: p.clientId,
+        clientSecret: p.clientSecret,
+        ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
+        ...(p.name ? { name: p.name } : {}),
+      };
+    }
+  }
+  if (Object.keys(validProviders).length === 0) return undefined;
+  return {
+    secret: raw.secret ?? "",
+    providers: validProviders,
+    ...(Array.isArray(raw.allowedUsers) ? { allowedUsers: raw.allowedUsers } : Array.isArray(raw.allowedEmails) ? { allowedUsers: raw.allowedEmails } : {}),
+    bypassUrls: Array.isArray(raw.bypassUrls) ? raw.bypassUrls.filter((u: unknown) => typeof u === "string") : [],
+    bypassHosts: Array.isArray(raw.bypassHosts) ? raw.bypassHosts.filter((u: unknown) => typeof u === "string") : [],
+  };
+}
+
+function parseEditorConfig(raw: any): EditorConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_EDITOR_CONFIG };
+  return {
+    ...(typeof raw.binary === "string" ? { binary: raw.binary } : {}),
+    idleTimeoutMinutes: typeof raw.idleTimeoutMinutes === "number" ? raw.idleTimeoutMinutes : DEFAULT_EDITOR_CONFIG.idleTimeoutMinutes,
+    maxInstances: typeof raw.maxInstances === "number" ? raw.maxInstances : DEFAULT_EDITOR_CONFIG.maxInstances,
+  };
+}
+
+function parseMemoryLimits(raw: any): MemoryLimitsConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_MEMORY_LIMITS };
+  return {
+    maxEventsPerSession: typeof raw.maxEventsPerSession === "number" ? raw.maxEventsPerSession : DEFAULT_MEMORY_LIMITS.maxEventsPerSession,
+    maxStringFieldSize: typeof raw.maxStringFieldSize === "number" ? raw.maxStringFieldSize : DEFAULT_MEMORY_LIMITS.maxStringFieldSize,
+    maxWsBufferBytes: typeof raw.maxWsBufferBytes === "number" ? raw.maxWsBufferBytes : DEFAULT_MEMORY_LIMITS.maxWsBufferBytes,
+  };
+}
+
+function parseTrustedNetworks(raw: any): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((entry: unknown) => typeof entry === "string" && entry.length > 0);
+}
+
+/**
+ * Load configuration from ~/.pi/dashboard/config.json.
+ * Returns defaults for missing fields, malformed JSON, or missing file.
+ */
+export function loadConfig(): DashboardConfig {
+  const configDir = path.join(os.homedir(), ".pi", "dashboard");
+  const configFile = path.join(configDir, "config.json");
+  const defaults: DashboardConfig = { ...DEFAULTS };
+
+  try {
+    if (!fs.existsSync(configFile)) return defaults;
+    const raw = fs.readFileSync(configFile, "utf-8");
+    if (!raw.trim()) return defaults;
+    const parsed = JSON.parse(raw);
+    const rawStrategy = parsed.spawnStrategy;
+    const spawnStrategy: SpawnStrategy =
+      VALID_SPAWN_STRATEGIES.includes(rawStrategy) ? rawStrategy : defaults.spawnStrategy;
+
+    const result: DashboardConfig = {
+      port: parsed.port ?? defaults.port,
+      piPort: parsed.piPort ?? defaults.piPort,
+      autoStart: parsed.autoStart ?? defaults.autoStart,
+      autoShutdown: parsed.autoShutdown ?? defaults.autoShutdown,
+      shutdownIdleSeconds: parsed.shutdownIdleSeconds ?? defaults.shutdownIdleSeconds,
+      spawnStrategy,
+      tunnel: {
+        enabled: parsed.tunnel?.enabled ?? defaults.tunnel.enabled,
+        ...(parsed.tunnel?.reservedToken ? { reservedToken: parsed.tunnel.reservedToken } : {}),
+      },
+      devBuildOnReload: parsed.devBuildOnReload ?? defaults.devBuildOnReload,
+      defaultModel: typeof parsed.defaultModel === "string" ? parsed.defaultModel : defaults.defaultModel,
+      auth: parseAuthConfig(parsed.auth),
+      memoryLimits: parseMemoryLimits(parsed.memoryLimits),
+      editor: parseEditorConfig(parsed.editor),
+      trustedNetworks: parseTrustedNetworks(parsed.trustedNetworks),
+      resolvedTrustedNetworks: [],
+      cors: {
+        allowedOrigins: Array.isArray(parsed.cors?.allowedOrigins)
+          ? parsed.cors.allowedOrigins.filter((o: unknown) => typeof o === "string")
+          : defaults.cors.allowedOrigins,
+      },
+      ...(typeof parsed.lastServer === "string" ? { lastServer: parsed.lastServer } : {}),
+      electronMode: parsed.electronMode === true,
+    };
+
+    // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts
+    const merged = new Set(result.trustedNetworks);
+    if (result.auth?.bypassHosts) {
+      for (const h of result.auth.bypassHosts) merged.add(h);
+    }
+    result.resolvedTrustedNetworks = Array.from(merged);
+    return result;
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Create ~/.pi/dashboard/config.json with defaults if it doesn't exist.
+ * Creates the directory recursively if needed.
+ */
+export function ensureConfig(): void {
+  const configDir = path.join(os.homedir(), ".pi", "dashboard");
+  const configFile = path.join(configDir, "config.json");
+
+  if (fs.existsSync(configFile)) return;
+
+  fs.mkdirSync(configDir, { recursive: true });
+
+  const defaults = {
+    port: DEFAULTS.port,
+    piPort: DEFAULTS.piPort,
+    autoStart: DEFAULTS.autoStart,
+    autoShutdown: DEFAULTS.autoShutdown,
+    shutdownIdleSeconds: DEFAULTS.shutdownIdleSeconds,
+    spawnStrategy: DEFAULTS.spawnStrategy,
+    tunnel: DEFAULTS.tunnel,
+    devBuildOnReload: DEFAULTS.devBuildOnReload,
+  };
+
+  fs.writeFileSync(configFile, JSON.stringify(defaults, null, 2) + "\n");
+}

package/packages/shared/src/diff-types.ts

@@ -0,0 +1,41 @@
+/**
+ * Types for the session file diff API.
+ */
+
+/** A single edit operation (oldText → newText replacement) */
+export interface EditOperation {
+  oldText: string;
+  newText: string;
+}
+
+/** An individual file change event extracted from session events */
+export interface FileChangeEvent {
+  /** "edit" or "write" */
+  type: "edit" | "write";
+  /** Event timestamp (ms since epoch) */
+  timestamp: number;
+  /** Truncated assistant message preceding this change (reason/context) */
+  message?: string;
+  /** Edit operations (only for type "edit") */
+  edits?: EditOperation[];
+  /** Written content (only for type "write") */
+  content?: string;
+}
+
+/** A file entry with all its change events */
+export interface FileDiffEntry {
+  /** File path relative to cwd */
+  path: string;
+  /** Individual change events, ordered by timestamp */
+  changes: FileChangeEvent[];
+  /** Aggregate git diff (unified format) when available */
+  gitDiff?: string;
+}
+
+/** Response from GET /api/session-diff */
+export interface SessionDiffResponse {
+  /** Changed files with their change events */
+  files: FileDiffEntry[];
+  /** Whether the session cwd is a git repository */
+  isGitRepo: boolean;
+}

package/packages/shared/src/editor-types.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared types for the browser-based editor (code-server) feature.
+ */
+
+export type EditorInstanceStatus = "starting" | "ready" | "stopped";
+
+export interface EditorInstance {
+  id: string;
+  cwd: string;
+  port: number;
+  status: EditorInstanceStatus;
+  proxyPath: string;
+}
+
+export interface EditorDetectionResult {
+  available: boolean;
+  binary?: string;
+}

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

@@ -0,0 +1,248 @@
+/**
+ * mDNS discovery module for pi-dashboard.
+ * Advertises and discovers `_pi-dashboard._tcp` services on the local network.
+ */
+import { Bonjour, type Service, type Browser } from "bonjour-service";
+import os from "node:os";
+import { EventEmitter } from "node:events";
+import { isDashboardRunning } from "./server-identity.js";
+
+const SERVICE_TYPE = "pi-dashboard";
+
+export interface DiscoveredServer {
+  /** Hostname of the machine running the server */
+  host: string;
+  /** HTTP port */
+  port: number;
+  /** Pi gateway WebSocket port */
+  piPort: number;
+  /** Dashboard version */
+  version: string;
+  /** Server process PID */
+  pid: number;
+  /** Whether the server is on this machine */
+  isLocal: boolean;
+  /** How the server was discovered: "mdns" or "fallback" */
+  source: "mdns" | "fallback";
+}
+
+let bonjourInstance: Bonjour | null = null;
+let publishedService: Service | null = null;
+
+function getBonjour(): Bonjour {
+  if (!bonjourInstance) {
+    bonjourInstance = new Bonjour();
+  }
+  return bonjourInstance;
+}
+
+/**
+ * Advertise this dashboard server on mDNS.
+ */
+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");
+    pkg.version = pkgJson.version ?? "0.0.0";
+  } catch { /* ignore */ }
+
+  publishedService = bonjour.publish({
+    name: `pi-dashboard-${os.hostname()}-${port}`,
+    type: SERVICE_TYPE,
+    port,
+    txt: {
+      version: pkg.version,
+      pid: String(process.pid),
+      piPort: String(piPort),
+    },
+  });
+}
+
+/**
+ * Stop advertising this dashboard server.
+ */
+export function stopAdvertising(): void {
+  if (publishedService) {
+    publishedService.stop(() => {});
+    publishedService = null;
+  }
+  if (bonjourInstance) {
+    bonjourInstance.destroy();
+    bonjourInstance = null;
+  }
+}
+
+/**
+ * Check if a discovered service is running on the local machine.
+ */
+export function isLocalService(service: Service): boolean {
+  const hostname = os.hostname();
+  const host = service.host ?? "";
+
+  // Direct hostname match
+  if (host === hostname || host === `${hostname}.local` || host === "localhost") {
+    return true;
+  }
+
+  // Check against local network addresses
+  const localAddresses = getLocalAddresses();
+  const serviceAddresses = service.addresses ?? [];
+  return serviceAddresses.some(addr => localAddresses.has(addr));
+}
+
+function getLocalAddresses(): Set<string> {
+  const addresses = new Set<string>(["127.0.0.1", "::1"]);
+  const interfaces = os.networkInterfaces();
+  for (const iface of Object.values(interfaces)) {
+    if (!iface) continue;
+    for (const info of iface) {
+      addresses.add(info.address);
+    }
+  }
+  return addresses;
+}
+
+function serviceToServer(service: Service, isLocal: boolean): DiscoveredServer {
+  const txt = service.txt as Record<string, string> | undefined;
+  return {
+    host: service.host ?? "unknown",
+    port: service.port,
+    piPort: parseInt(txt?.piPort ?? "9999", 10),
+    version: txt?.version ?? "unknown",
+    pid: parseInt(txt?.pid ?? "0", 10),
+    isLocal,
+    source: "mdns",
+  };
+}
+
+/**
+ * One-shot discovery: browse for dashboard servers with timeout.
+ * Returns localhost servers first, then remote.
+ */
+export async function discoverDashboard(timeout = 2000): Promise<DiscoveredServer[]> {
+  return new Promise((resolve) => {
+    const servers: DiscoveredServer[] = [];
+    // Use a fresh Bonjour instance to avoid conflicts with the
+    // singleton used by advertiseDashboard()
+    const bonjour = new Bonjour();
+    let resolved = false;
+
+    const finish = () => {
+      if (resolved) return;
+      resolved = true;
+      browser.stop();
+      bonjour.destroy();
+      // Sort: local first
+      servers.sort((a, b) => (a.isLocal === b.isLocal ? 0 : a.isLocal ? -1 : 1));
+      resolve(servers);
+    };
+
+    const timer = setTimeout(finish, timeout);
+
+    const browser = bonjour.find({ type: SERVICE_TYPE });
+    browser.on("up", (service: Service) => {
+      const isLocal = isLocalService(service);
+      servers.push(serviceToServer(service, isLocal));
+      // Resolve early once a local server is found
+      if (isLocal) {
+        clearTimeout(timer);
+        // Small delay to collect any other simultaneous responses
+        setTimeout(finish, 100);
+      }
+    });
+  });
+}
+
+/**
+ * Fallback discovery: probe localhost via health check when mDNS finds nothing.
+ */
+export async function discoverFallback(port: number): Promise<DiscoveredServer | null> {
+  const status = await isDashboardRunning(port);
+  if (!status.running) return null;
+
+  return {
+    host: "localhost",
+    port,
+    piPort: 9999, // Default — we can't know the actual piPort from health check alone
+    version: "unknown",
+    pid: status.pid ?? 0,
+    isLocal: true,
+    source: "fallback",
+  };
+}
+
+/**
+ * Full discovery: mDNS first, fallback to health check.
+ */
+export async function discoverDashboardWithFallback(
+  configPort: number,
+  mdnsTimeout = 2000,
+): Promise<{ servers: DiscoveredServer[]; portConflict: boolean }> {
+  const servers = await discoverDashboard(mdnsTimeout);
+  if (servers.length > 0) {
+    return { servers, portConflict: false };
+  }
+
+  // mDNS found nothing — try health check fallback
+  const status = await isDashboardRunning(configPort);
+  if (status.running) {
+    return {
+      servers: [{
+        host: "localhost",
+        port: configPort,
+        piPort: 9999,
+        version: "unknown",
+        pid: status.pid ?? 0,
+        isLocal: true,
+        source: "fallback",
+      }],
+      portConflict: false,
+    };
+  }
+
+  return { servers: [], portConflict: status.portConflict ?? false };
+}
+
+/**
+ * Continuous browser that emits events when servers appear/disappear.
+ */
+export interface DashboardBrowser extends EventEmitter {
+  /** Currently known servers */
+  servers: Map<string, DiscoveredServer>;
+  /** Stop browsing */
+  stop(): void;
+}
+
+export function createBrowser(): DashboardBrowser {
+  const emitter = new EventEmitter() as DashboardBrowser;
+  emitter.servers = new Map();
+
+  const bonjour = new Bonjour();
+  const browser: Browser = bonjour.find({ type: SERVICE_TYPE });
+
+  browser.on("up", (service: Service) => {
+    const isLocal = isLocalService(service);
+    const server = serviceToServer(service, isLocal);
+    const key = `${server.host}:${server.port}`;
+    emitter.servers.set(key, server);
+    emitter.emit("server-up", server);
+  });
+
+  browser.on("down", (service: Service) => {
+    const host = service.host ?? "unknown";
+    const key = `${host}:${service.port}`;
+    const server = emitter.servers.get(key);
+    if (server) {
+      emitter.servers.delete(key);
+      emitter.emit("server-down", server);
+    }
+  });
+
+  emitter.stop = () => {
+    browser.stop();
+    bonjour.destroy();
+  };
+
+  return emitter;
+}

package/packages/shared/src/openspec-activity-detector.ts

@@ -0,0 +1,109 @@
+/**
+ * Detects OpenSpec activity from tool execution events.
+ * Returns partial activity info (phase and/or changeName) or null if not openspec-related.
+ */
+import type { OpenSpecPhase } from "./types.js";
+
+export interface DetectedActivity {
+  phase?: OpenSpecPhase;
+  changeName?: string;
+}
+
+/** Map from skill directory name suffix to phase */
+const SKILL_PHASE_MAP: Record<string, OpenSpecPhase> = {
+  "apply-change": "apply",
+  "archive-change": "archive",
+  "bulk-archive-change": "archive",
+  "continue-change": "continue",
+  "explore": "explore",
+  "ff-change": "ff",
+  "new-change": "new",
+  "onboard": "onboard",
+  "sync-specs": "sync-specs",
+  "verify-change": "verify",
+};
+
+/** Regex to match openspec skill SKILL.md reads */
+const SKILL_PATH_RE = /\.pi\/skills\/openspec-([^/]+)\/SKILL\.md$/;
+
+/** Regex to match openspec change file reads */
+const CHANGE_PATH_RE = /openspec\/changes\/([^/]+)\//;
+
+/** Regex to match --change "name" or --change name in CLI commands */
+const CLI_CHANGE_FLAG_RE = /openspec\s+\S+.*--change\s+["']?([^\s"']+)["']?/;
+
+/** Regex to match openspec archive <name> */
+const CLI_ARCHIVE_RE = /openspec\s+archive\s+["']?([^\s"']+)["']?/;
+
+/** Regex to match openspec new change "name" (positional arg) */
+const CLI_NEW_CHANGE_RE = /openspec\s+new\s+change\s+["']?([^\s"']+)["']?/;
+
+export function detectOpenSpecActivity(
+  toolName: string,
+  args: Record<string, unknown> | undefined,
+): DetectedActivity | null {
+  if (!args) return null;
+
+  const tool = toolName.toLowerCase();
+
+  if (tool === "read") {
+    const path = args.path as string | undefined;
+    if (!path) return null;
+
+    // Check for skill file read → phase detection
+    const skillMatch = path.match(SKILL_PATH_RE);
+    if (skillMatch) {
+      const suffix = skillMatch[1];
+      const phase = SKILL_PHASE_MAP[suffix];
+      if (phase) return { phase };
+      return null;
+    }
+
+    // Check for openspec change file read → change name detection
+    const changeMatch = path.match(CHANGE_PATH_RE);
+    if (changeMatch) {
+      return { changeName: changeMatch[1] };
+    }
+
+    return null;
+  }
+
+  if (tool === "write") {
+    const path = args.path as string | undefined;
+    if (!path) return null;
+
+    const changeMatch = path.match(CHANGE_PATH_RE);
+    if (changeMatch) {
+      return { changeName: changeMatch[1] };
+    }
+
+    return null;
+  }
+
+  if (tool === "bash") {
+    const command = args.command as string | undefined;
+    if (!command || !command.includes("openspec")) return null;
+
+    // Check for --change flag
+    const flagMatch = command.match(CLI_CHANGE_FLAG_RE);
+    if (flagMatch) {
+      return { changeName: flagMatch[1] };
+    }
+
+    // Check for openspec archive <name>
+    const archiveMatch = command.match(CLI_ARCHIVE_RE);
+    if (archiveMatch) {
+      return { changeName: archiveMatch[1] };
+    }
+
+    // Check for openspec new change "name"
+    const newChangeMatch = command.match(CLI_NEW_CHANGE_RE);
+    if (newChangeMatch) {
+      return { changeName: newChangeMatch[1] };
+    }
+
+    return null;
+  }
+
+  return null;
+}