@agent-relay/dashboard 2.0.81 → 2.0.82

package/src/lib/colors.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseAgentHierarchy,
+  getAgentPrefix,
+  getAgentColor,
+  getAgentInitials,
+  groupAgentsByPrefix,
+  sortAgentsByHierarchy,
+  STATUS_COLORS,
+} from './colors.js';
+
+describe('colors', () => {
+  describe('parseAgentHierarchy', () => {
+    it('parses single-level name', () => {
+      expect(parseAgentHierarchy('Lead')).toEqual(['lead']);
+    });
+
+    it('parses two-level name', () => {
+      expect(parseAgentHierarchy('backend-api')).toEqual(['backend', 'api']);
+    });
+
+    it('parses three-level name', () => {
+      expect(parseAgentHierarchy('frontend-ui-components')).toEqual([
+        'frontend',
+        'ui',
+        'components',
+      ]);
+    });
+
+    it('handles uppercase names', () => {
+      expect(parseAgentHierarchy('Backend-API')).toEqual(['backend', 'api']);
+    });
+
+    it('handles empty string', () => {
+      expect(parseAgentHierarchy('')).toEqual([]);
+    });
+  });
+
+  describe('getAgentPrefix', () => {
+    it('returns first segment for hyphenated name', () => {
+      expect(getAgentPrefix('backend-api-auth')).toBe('backend');
+    });
+
+    it('returns lowercase name for single segment', () => {
+      expect(getAgentPrefix('Lead')).toBe('lead');
+    });
+
+    it('handles empty string', () => {
+      expect(getAgentPrefix('')).toBe('');
+    });
+  });
+
+  describe('getAgentColor', () => {
+    it('returns predefined color for known prefix', () => {
+      const color = getAgentColor('backend-api');
+      expect(color.primary).toBe('#1264a3'); // Blue for backend
+    });
+
+    it('returns predefined color for frontend prefix', () => {
+      const color = getAgentColor('frontend-ui');
+      expect(color.primary).toBe('#7c3aed'); // Purple for frontend
+    });
+
+    it('returns predefined color for lead prefix', () => {
+      const color = getAgentColor('lead-main');
+      expect(color.primary).toBe('#2bac76'); // Green for lead
+    });
+
+    it('returns consistent fallback color for unknown prefix', () => {
+      const color1 = getAgentColor('custom-agent');
+      const color2 = getAgentColor('custom-other');
+      // Same prefix should get same color
+      expect(color1).toEqual(color2);
+    });
+
+    it('returns different colors for different unknown prefixes', () => {
+      const color1 = getAgentColor('alpha-agent');
+      const color2 = getAgentColor('beta-agent');
+      // Different prefixes should likely get different colors
+      // (not guaranteed due to hash collisions, but likely)
+      expect(color1.primary).not.toBe(color2.primary);
+    });
+
+    it('includes all required color properties', () => {
+      const color = getAgentColor('any-agent');
+      expect(color).toHaveProperty('primary');
+      expect(color).toHaveProperty('light');
+      expect(color).toHaveProperty('dark');
+      expect(color).toHaveProperty('text');
+    });
+  });
+
+  describe('getAgentInitials', () => {
+    it('returns first two letters for single segment', () => {
+      expect(getAgentInitials('Lead')).toBe('LE');
+    });
+
+    it('returns first letter of each segment for two segments', () => {
+      expect(getAgentInitials('backend-api')).toBe('BA');
+    });
+
+    it('returns first letter of first two segments for three segments', () => {
+      expect(getAgentInitials('frontend-ui-components')).toBe('FU');
+    });
+
+    it('handles single character segments', () => {
+      expect(getAgentInitials('a-b-c')).toBe('AB');
+    });
+  });
+
+  describe('groupAgentsByPrefix', () => {
+    it('groups agents by their prefix', () => {
+      const agents = [
+        { name: 'backend-api' },
+        { name: 'backend-db' },
+        { name: 'frontend-ui' },
+        { name: 'Lead' },
+      ];
+
+      const groups = groupAgentsByPrefix(agents);
+
+      expect(groups.get('backend')).toHaveLength(2);
+      expect(groups.get('frontend')).toHaveLength(1);
+      expect(groups.get('lead')).toHaveLength(1);
+    });
+
+    it('handles empty array', () => {
+      const groups = groupAgentsByPrefix([]);
+      expect(groups.size).toBe(0);
+    });
+  });
+
+  describe('sortAgentsByHierarchy', () => {
+    it('sorts agents by prefix then by name', () => {
+      const agents = [
+        { name: 'frontend-ui' },
+        { name: 'backend-db' },
+        { name: 'backend-api' },
+        { name: 'Lead' },
+      ];
+
+      const sorted = sortAgentsByHierarchy(agents);
+
+      expect(sorted.map((a) => a.name)).toEqual([
+        'backend-api',
+        'backend-db',
+        'frontend-ui',
+        'Lead',
+      ]);
+    });
+
+    it('does not mutate original array', () => {
+      const agents = [{ name: 'z-agent' }, { name: 'a-agent' }];
+      const original = [...agents];
+
+      sortAgentsByHierarchy(agents);
+
+      expect(agents).toEqual(original);
+    });
+  });
+
+  describe('STATUS_COLORS', () => {
+    it('has all required status colors', () => {
+      expect(STATUS_COLORS.online).toBeDefined();
+      expect(STATUS_COLORS.offline).toBeDefined();
+      expect(STATUS_COLORS.busy).toBeDefined();
+      expect(STATUS_COLORS.error).toBeDefined();
+      expect(STATUS_COLORS.attention).toBeDefined();
+    });
+
+    it('uses green for online status', () => {
+      expect(STATUS_COLORS.online).toBe('#22c55e');
+    });
+  });
+});

package/src/lib/colors.ts

@@ -0,0 +1,218 @@
+/**
+ * Hierarchical Color Coding System
+ *
+ * Inspired by AI Maestro's naming convention:
+ * - Agent names use hyphens to denote hierarchy: project-category-agent
+ * - Each top-level prefix gets a consistent color
+ * - Colors are visually distinct and accessible
+ */
+
+export interface ColorScheme {
+  primary: string;
+  light: string;
+  dark: string;
+  text: string;
+}
+
+// Predefined color schemes for common agent prefixes
+const PREFIX_COLORS: Record<string, ColorScheme> = {
+  backend: {
+    primary: '#1264a3',
+    light: '#e8f4fd',
+    dark: '#0d4f82',
+    text: '#ffffff',
+  },
+  frontend: {
+    primary: '#7c3aed',
+    light: '#f3e8ff',
+    dark: '#5b21b6',
+    text: '#ffffff',
+  },
+  infra: {
+    primary: '#ea580c',
+    light: '#fff7ed',
+    dark: '#c2410c',
+    text: '#ffffff',
+  },
+  lead: {
+    primary: '#2bac76',
+    light: '#ecfdf5',
+    dark: '#059669',
+    text: '#ffffff',
+  },
+  test: {
+    primary: '#0d9488',
+    light: '#f0fdfa',
+    dark: '#0f766e',
+    text: '#ffffff',
+  },
+  data: {
+    primary: '#dc2626',
+    light: '#fef2f2',
+    dark: '#b91c1c',
+    text: '#ffffff',
+  },
+  api: {
+    primary: '#2563eb',
+    light: '#eff6ff',
+    dark: '#1d4ed8',
+    text: '#ffffff',
+  },
+  worker: {
+    primary: '#9333ea',
+    light: '#faf5ff',
+    dark: '#7e22ce',
+    text: '#ffffff',
+  },
+  monitor: {
+    primary: '#0891b2',
+    light: '#ecfeff',
+    dark: '#0e7490',
+    text: '#ffffff',
+  },
+  security: {
+    primary: '#be123c',
+    light: '#fff1f2',
+    dark: '#9f1239',
+    text: '#ffffff',
+  },
+};
+
+// Fallback colors for unknown prefixes (generated from name hash)
+const FALLBACK_COLORS: ColorScheme[] = [
+  { primary: '#6366f1', light: '#eef2ff', dark: '#4f46e5', text: '#ffffff' },
+  { primary: '#ec4899', light: '#fdf2f8', dark: '#db2777', text: '#ffffff' },
+  { primary: '#14b8a6', light: '#f0fdfa', dark: '#0d9488', text: '#ffffff' },
+  { primary: '#f59e0b', light: '#fffbeb', dark: '#d97706', text: '#000000' },
+  { primary: '#8b5cf6', light: '#f5f3ff', dark: '#7c3aed', text: '#ffffff' },
+  { primary: '#06b6d4', light: '#ecfeff', dark: '#0891b2', text: '#ffffff' },
+  { primary: '#f43f5e', light: '#fff1f2', dark: '#e11d48', text: '#ffffff' },
+  { primary: '#84cc16', light: '#f7fee7', dark: '#65a30d', text: '#000000' },
+];
+
+// Status colors
+export const STATUS_COLORS = {
+  online: '#22c55e',      // Green
+  offline: '#6b7280',     // Gray
+  busy: '#eab308',        // Yellow
+  processing: '#6366f1',  // Indigo (thinking/processing)
+  error: '#ef4444',       // Red
+  attention: '#ef4444',   // Red (for badge)
+  stuck: '#f97316',       // Orange (received message but no response)
+} as const;
+
+export type AgentStatus = keyof typeof STATUS_COLORS;
+
+/**
+ * Parse agent name into hierarchy levels
+ * e.g., "backend-api-auth" => ["backend", "api", "auth"]
+ */
+export function parseAgentHierarchy(name: string): string[] {
+  return name.toLowerCase().split('-').filter(Boolean);
+}
+
+/**
+ * Get the top-level prefix from an agent name
+ * e.g., "backend-api-auth" => "backend"
+ */
+export function getAgentPrefix(name: string): string {
+  const parts = parseAgentHierarchy(name);
+  return parts[0] || name.toLowerCase();
+}
+
+/**
+ * Generate a hash code from a string for consistent color assignment
+ */
+function hashCode(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash);
+}
+
+/**
+ * Get color scheme for an agent based on its name
+ * Uses prefix matching first, falls back to hash-based color
+ */
+export function getAgentColor(name: string): ColorScheme {
+  const prefix = getAgentPrefix(name);
+
+  // Check for predefined prefix color
+  if (prefix in PREFIX_COLORS) {
+    return PREFIX_COLORS[prefix];
+  }
+
+  // Fall back to hash-based color for consistency
+  const hash = hashCode(prefix);
+  return FALLBACK_COLORS[hash % FALLBACK_COLORS.length];
+}
+
+/**
+ * Get CSS custom properties for an agent's color scheme
+ * Useful for inline styles or CSS variables
+ */
+export function getAgentColorVars(name: string): Record<string, string> {
+  const colors = getAgentColor(name);
+  return {
+    '--agent-primary': colors.primary,
+    '--agent-light': colors.light,
+    '--agent-dark': colors.dark,
+    '--agent-text': colors.text,
+  };
+}
+
+/**
+ * Get initials from agent name (first 2 chars of first segment)
+ */
+export function getAgentInitials(name: string): string {
+  const parts = parseAgentHierarchy(name);
+  if (parts.length === 0) return name.substring(0, 2).toUpperCase();
+
+  // Use first letter of first two segments, or first two letters of first segment
+  if (parts.length >= 2) {
+    return (parts[0][0] + parts[1][0]).toUpperCase();
+  }
+  return parts[0].substring(0, 2).toUpperCase();
+}
+
+/**
+ * Group agents by their top-level prefix
+ */
+export function groupAgentsByPrefix<T extends { name: string }>(
+  agents: T[]
+): Map<string, T[]> {
+  const groups = new Map<string, T[]>();
+
+  for (const agent of agents) {
+    const prefix = getAgentPrefix(agent.name);
+    const group = groups.get(prefix) || [];
+    group.push(agent);
+    groups.set(prefix, group);
+  }
+
+  return groups;
+}
+
+/**
+ * Sort agents by hierarchy for display
+ * Groups by prefix, then sorts alphabetically within groups
+ */
+export function sortAgentsByHierarchy<T extends { name: string }>(
+  agents: T[]
+): T[] {
+  return [...agents].sort((a, b) => {
+    const prefixA = getAgentPrefix(a.name);
+    const prefixB = getAgentPrefix(b.name);
+
+    // Sort by prefix first
+    if (prefixA !== prefixB) {
+      return prefixA.localeCompare(prefixB);
+    }
+
+    // Then by full name
+    return a.name.localeCompare(b.name);
+  });
+}

package/src/lib/config.ts

@@ -0,0 +1,109 @@
+/**
+ * Dashboard Configuration
+ *
+ * Centralized configuration for API and WebSocket URLs.
+ * Works out-of-the-box with sensible defaults - no configuration required.
+ *
+ * Defaults (no env vars needed):
+ * - Development: WebSocket connects to localhost:3889 (dashboard server)
+ * - Production: WebSocket auto-detects from page URL (same host/port)
+ * - API: Uses relative URLs (works for same-origin requests)
+ *
+ * Optional overrides (for advanced deployments):
+ * - NEXT_PUBLIC_WS_URL: Override WebSocket URL entirely
+ * - NEXT_PUBLIC_API_URL: Override API base URL
+ * - NEXT_PUBLIC_DEV_SERVER_PORT: Change dev server port (default: 3889)
+ */
+
+// Default port for dashboard server in development
+const DEFAULT_DEV_SERVER_PORT = '3889';
+
+/**
+ * Get the configured dev server port
+ */
+function getDevServerPort(): string {
+  return process.env.NEXT_PUBLIC_DEV_SERVER_PORT || DEFAULT_DEV_SERVER_PORT;
+}
+
+/**
+ * Check if we're in development mode
+ */
+function isDevelopment(): boolean {
+  return process.env.NODE_ENV === 'development';
+}
+
+/**
+ * Check if we're running in the browser
+ */
+function isBrowser(): boolean {
+  return typeof window !== 'undefined';
+}
+
+/**
+ * Get the WebSocket URL for the main dashboard connection
+ *
+ * Priority:
+ * 1. NEXT_PUBLIC_WS_URL environment variable
+ * 2. Development mode: connect to dev server port
+ * 3. Production: auto-detect from page URL
+ */
+export function getWebSocketUrl(path: string = '/ws'): string {
+  // Check for explicit environment variable
+  const envWsUrl = process.env.NEXT_PUBLIC_WS_URL;
+  if (envWsUrl) {
+    // Append path if base URL provided
+    return envWsUrl.endsWith('/') ? `${envWsUrl.slice(0, -1)}${path}` : `${envWsUrl}${path}`;
+  }
+
+  // SSR fallback - return localhost with dev port
+  if (!isBrowser()) {
+    const port = getDevServerPort();
+    return `ws://localhost:${port}${path}`;
+  }
+
+  const host = window.location.hostname || 'localhost';
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+
+  // Development mode: Next.js on 3888, dashboard server on dev port (3889)
+  // Next.js rewrites don't support WebSocket upgrade, so connect directly
+  if (isDevelopment() && window.location.port === '3888') {
+    const devPort = getDevServerPort();
+    return `ws://${host}:${devPort}${path}`;
+  }
+
+  // Production: use same host/port as the page
+  return `${protocol}//${window.location.host}${path}`;
+}
+
+/**
+ * Get the API base URL
+ *
+ * Priority:
+ * 1. NEXT_PUBLIC_API_URL environment variable
+ * 2. Empty string (relative URLs) - works for same-origin
+ */
+export function getApiBaseUrl(): string {
+  return process.env.NEXT_PUBLIC_API_URL || '';
+}
+
+/**
+ * Configuration object for easy access
+ */
+export const config = {
+  /** Get WebSocket URL for a given path */
+  getWebSocketUrl,
+
+  /** Get API base URL */
+  getApiBaseUrl,
+
+  /** Check if in development mode */
+  isDevelopment,
+
+  /** Check if in browser */
+  isBrowser,
+
+  /** Dev server port */
+  devServerPort: getDevServerPort(),
+};
+
+export default config;