@hoox-sh/hoox-tui 0.2.0

package/src/test-utils.ts

@@ -0,0 +1,179 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared test utilities for TUI components.
+ *
+ * Provides:
+ *   - Type aliases matching TUI test expectations
+ *   - Factory functions (makeWorker, makeLog, makeTrade)
+ *   - Mock ErrorBoundary pass-through
+ *   - Re-exports of the shared CLI bridge test double
+ *
+ * Centralises duplicated type definitions + factory functions
+ * that were previously copy-pasted across test files.
+ *
+ * Process-wide `cli-bridge` mocking is installed once in `test-setup.ts`.
+ * Do **not** call `mock.module` for cli-bridge or shared stores in view tests.
+ */
+
+import type { ReactNode } from "react";
+import type { ViewId } from "@hoox-sh/hoox-shared";
+
+export {
+  cliBridgeDouble,
+  resetCliBridgeDouble,
+  okCliResult,
+  failCliResult,
+} from "./cli-bridge-test-double";
+
+export {
+  hooxFetchMock,
+  subscribeSSEMock,
+  resetNetworkDoubles,
+  setMockApiData,
+  setMockApiFailure,
+  setMockApiDelay,
+  emitSseEvent,
+  abortAllSseSubscriptions,
+  mockApiData,
+  sseCallbacks,
+  sseSubscriptions,
+} from "./network-test-double";
+
+/** Canonical 16 ViewIds — keep aligned with types.ts + view-registry. */
+export const ALL_VIEW_IDS: ViewId[] = [
+  "dashboard",
+  "workers",
+  "worker-detail",
+  "trade-monitor",
+  "logs-viewer",
+  "service-manager",
+  "config-editor",
+  "setup-wizard",
+  "settings",
+  "queue-depth",
+  "kv-viewer",
+  "secrets-viewer",
+  "db-query",
+  "ai-chat",
+  "edge-topology",
+  "worker-settings",
+];
+
+// ── Type Aliases ─────────────────────────────────────────────────────────────
+
+export type WorkerStatus = "operational" | "degraded" | "down";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type ConnectionStatus =
+  | "connected"
+  | "polling"
+  | "offline"
+  | "reconnecting";
+export type TradeSide = "buy" | "sell";
+
+export interface TestWorkerInfo {
+  id: string;
+  name: string;
+  status: WorkerStatus;
+  uptime: number;
+  cpu: number;
+  memory: number;
+  requests: number;
+  durableObjectCount: number;
+  edgeCount: number;
+  version?: string;
+  lastDeployed?: number;
+}
+
+export interface TestLogEntry {
+  id: string;
+  level: LogLevel;
+  message: string;
+  timestamp: number;
+  workerId?: string;
+  source?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TestTrade {
+  id: string;
+  symbol: string;
+  side: TradeSide;
+  price: number;
+  quantity: number;
+  timestamp: number;
+  exchange: string;
+  pnl?: number;
+}
+
+// ── Factory Functions ────────────────────────────────────────────────────────
+
+/** Create a test worker fixture with sensible defaults. */
+export function makeWorker(
+  overrides: Partial<TestWorkerInfo> = {}
+): TestWorkerInfo {
+  return {
+    id: "test-worker-1",
+    name: "trade-executor",
+    status: "operational",
+    uptime: 86400,
+    cpu: 42.5,
+    memory: 64,
+    requests: 15000,
+    durableObjectCount: 3,
+    edgeCount: 12,
+    version: "1.2.3",
+    lastDeployed: Date.now() - 3600000,
+    ...overrides,
+  };
+}
+
+/** Create a test log entry with sensible defaults. */
+export function makeLog(overrides: Partial<TestLogEntry> = {}): TestLogEntry {
+  return {
+    id: crypto.randomUUID?.() ?? "log-1",
+    level: "info",
+    message: "Test message",
+    timestamp: Date.now(),
+    workerId: undefined,
+    source: undefined,
+    ...overrides,
+  };
+}
+
+/** Create a test trade with sensible defaults. */
+export function makeTrade(overrides: Partial<TestTrade> = {}): TestTrade {
+  return {
+    id: `trade-${Math.random().toString(36).slice(2, 10)}`,
+    symbol: "BTC",
+    side: "buy",
+    price: 87432.5,
+    quantity: 0.15,
+    timestamp: Date.now() - 60000,
+    exchange: "binance",
+    pnl: 125.5,
+    ...overrides,
+  };
+}
+
+// ── Mock ErrorBoundary ───────────────────────────────────────────────────────
+
+/**
+ * Pass-through ErrorBoundary for tests.
+ *
+ * Usage:
+ *   mock.module("../shared/error-boundary", () => ({
+ *     ErrorBoundary: MockErrorBoundary,
+ *   }))
+ */
+export function MockErrorBoundary({
+  children,
+}: {
+  viewName: string;
+  children: ReactNode;
+}): ReactNode {
+  return children;
+}

package/src/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * TUI-specific types — Navigation, modals, keyboard shortcuts.
+ */
+
+import type { CliErrorType, CliErrorDetails } from "@hoox-sh/hoox-shared";
+
+// Re-export shared CLI error types for convenience so consumers can
+// import everything from the tui/types module.
+export type { CliErrorType, CliErrorDetails };
+
+/** All primary views registered with the TUI. */
+export const ALL_VIEWS = [
+  "dashboard",
+  "workers",
+  "worker-detail",
+  "trade-monitor",
+  "logs-viewer",
+  "service-manager",
+  "config-editor",
+  "setup-wizard",
+  "settings",
+  "queue-depth",
+  "kv-viewer",
+  "secrets-viewer",
+  "db-query",
+  "ai-chat",
+  "edge-topology",
+  "worker-settings",
+] as const;
+
+export type ViewId = (typeof ALL_VIEWS)[number];
+
+export const VIEW_LABELS: Record<ViewId, string> = {
+  dashboard: "DASHBOARD",
+  workers: "WORKERS",
+  "worker-detail": "WORKER DETAIL",
+  "trade-monitor": "TRADES",
+  "logs-viewer": "LOGS",
+  "service-manager": "SERVICES",
+  "config-editor": "CONFIG",
+  "setup-wizard": "SETUP",
+  settings: "SETTINGS",
+  "queue-depth": "QUEUES",
+  "kv-viewer": "KV",
+  "secrets-viewer": "SECRETS",
+  "db-query": "DB QUERY",
+  "ai-chat": "AI CHAT",
+  "edge-topology": "TOPOLOGY",
+  "worker-settings": "W SETTINGS",
+};
+
+export const VIEW_ORDER: ViewId[] = [
+  "dashboard",
+  "workers",
+  "worker-detail",
+  "trade-monitor",
+  "logs-viewer",
+  "service-manager",
+  "config-editor",
+  "setup-wizard",
+  "settings",
+  "queue-depth",
+  "kv-viewer",
+  "secrets-viewer",
+  "db-query",
+  "ai-chat",
+  "edge-topology",
+  "worker-settings",
+];
+
+export function viewIndex(view: ViewId): number {
+  return VIEW_ORDER.indexOf(view);
+}
+
+export type ModalType = "confirm" | "choice" | "loading" | "prompt";
+
+export interface ModalState {
+  type: ModalType;
+  id: string;
+  title?: string;
+  message?: string;
+  resolve?: (value: unknown) => void;
+}
+
+export interface ShortcutMap {
+  [keys: string]: string;
+}
+
+export const DEFAULT_SHORTCUTS: ShortcutMap = {
+  "Ctrl+1": "DASHBOARD",
+  "Ctrl+2": "WORKERS",
+  "Ctrl+3": "WORKER DETAIL",
+  "Ctrl+4": "TRADES",
+  "Ctrl+5": "LOGS",
+  "Ctrl+6": "SERVICES",
+  "Ctrl+7": "CONFIG",
+  "Ctrl+8": "SETUP",
+  "Ctrl+9": "SETTINGS",
+  "Ctrl+0": "QUEUES",
+  "Ctrl+Alt+K": "KV",
+  "Ctrl+Alt+S": "SECRETS",
+  "Ctrl+Alt+C": "AI CHAT",
+  "Ctrl+Alt+Q": "DB QUERY",
+  "Ctrl+Alt+E": "TOPOLOGY",
+  "Ctrl+Alt+W": "W SETTINGS",
+  "Ctrl+P": "COMMAND PALETTE",
+  "Ctrl+B": "TOGGLE SIDEBAR",
+  "Ctrl+R": "REFRESH DATA",
+  "Ctrl+Q": "QUIT",
+  Esc: "BACK / CLOSE",
+  Tab: "NEXT FOCUS",
+  "Shift+Tab": "PREVIOUS FOCUS",
+  Space: "TOGGLE / PAUSE",
+  "/": "SEARCH",
+  Enter: "SELECT / CONFIRM",
+};
+
+// ─── CliBridge Types ─────────────────────────────────────────────
+
+export interface CliResult<T = unknown> {
+  success: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  data: T | null;
+  duration: number;
+  /**
+   * The full command string that was executed, e.g. `"hoox check health"`.
+   * Captured by `cli-bridge.exec()` so the status bar can show exactly
+   * which command failed. Empty string when the binary itself was not found.
+   */
+  command: string;
+  /**
+   * Classification of the failure, or `null` on success.
+   * Drives the icon and recovery hint shown in the expanded error panel.
+   */
+  errorType: CliErrorType | null;
+}
+
+export type CliCommandStatus = "idle" | "running" | "success" | "failure";
+
+export interface CliCommandState {
+  tag: string;
+  description: string;
+  status: CliCommandStatus;
+  result: CliResult | null;
+  startedAt: number | null;
+}

package/src/utils/colors.test.ts

@@ -0,0 +1,326 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Colors Utility Tests — Design token validation.
+ *
+ * Tests that the Hoox design system colors are correctly defined,
+ * follow the black / cool-indigo DNA (#050508 bg, #818CF8 accent),
+ * and provide adequate contrast ratios for TUI readability.
+ *
+ * Source of truth: @hoox-sh/hoox-shared (Colors + status maps).
+ * Uses Bun test runner.
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  Colors,
+  CoolBracketPalette,
+  ConnectionStatusColor,
+  WorkerStatusColor,
+  LogLevelColor,
+  AlertSeverityColor,
+} from "@hoox-sh/hoox-shared";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Parse a hex color string into RGB components */
+function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const match = hex.match(
+    /^#?([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})$/
+  );
+  if (!match) return null;
+  return {
+    r: parseInt(match[1], 16),
+    g: parseInt(match[2], 16),
+    b: parseInt(match[3], 16),
+  };
+}
+
+/** Calculate relative luminance (per WCAG 2.0) */
+function relativeLuminance(hex: string): number {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return 0;
+  const toLinear = (c: number): number => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return (
+    0.2126 * toLinear(rgb.r) +
+    0.7152 * toLinear(rgb.g) +
+    0.0722 * toLinear(rgb.b)
+  );
+}
+
+/** Calculate contrast ratio between two hex colors */
+function contrastRatio(hex1: string, hex2: string): number {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// ─── Test Suite ───────────────────────────────────────────────────────────────
+
+describe("Colors Design System", () => {
+  // ── All tokens are valid hex colors ─────────────────────────────────────
+
+  describe("valid hex colors", () => {
+    it("all color tokens are valid 6-digit hex", () => {
+      for (const [name, value] of Object.entries(Colors)) {
+        expect(value).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      }
+    });
+
+    it("all tokens can be parsed to RGB", () => {
+      for (const [name, value] of Object.entries(Colors)) {
+        const rgb = hexToRgb(value);
+        expect(rgb).not.toBeNull();
+        expect(rgb!.r).toBeGreaterThanOrEqual(0);
+        expect(rgb!.r).toBeLessThanOrEqual(255);
+        expect(rgb!.g).toBeGreaterThanOrEqual(0);
+        expect(rgb!.g).toBeLessThanOrEqual(255);
+        expect(rgb!.b).toBeGreaterThanOrEqual(0);
+        expect(rgb!.b).toBeLessThanOrEqual(255);
+      }
+    });
+  });
+
+  // ── Black / cool DNA ────────────────────────────────────────────────────
+
+  describe("black / cool DNA", () => {
+    it("background is near-black (#050508)", () => {
+      expect(Colors.background).toBe("#050508");
+      const rgb = hexToRgb(Colors.background)!;
+      expect(rgb.r).toBeLessThan(12);
+      expect(rgb.g).toBeLessThan(12);
+      expect(rgb.b).toBeLessThan(16);
+    });
+
+    it("accent is cool indigo (#818CF8)", () => {
+      expect(Colors.accent).toBe("#818CF8");
+      const rgb = hexToRgb(Colors.accent)!;
+      // Indigo: blue-ish, not warm orange
+      expect(rgb.b).toBeGreaterThan(rgb.r);
+      expect(rgb.b).toBeGreaterThan(200);
+    });
+
+    it("highlight is cool cyan (distinct from accent)", () => {
+      expect(Colors.highlight).toBe("#22D3EE");
+      expect(Colors.highlight).not.toBe(Colors.accent);
+      const rgb = hexToRgb(Colors.highlight)!;
+      expect(rgb.b).toBeGreaterThan(200);
+      expect(rgb.g).toBeGreaterThan(180);
+    });
+
+    it("cards are near-black elevated (#0A0A0F)", () => {
+      expect(Colors.card).toBe("#0A0A0F");
+      const bg = hexToRgb(Colors.background)!;
+      const card = hexToRgb(Colors.card)!;
+      // Slightly elevated vs background
+      expect(card.r + card.g + card.b).toBeGreaterThan(bg.r + bg.g + bg.b);
+    });
+
+    it("borders are cool dark, not mid-grey", () => {
+      const rgb = hexToRgb(Colors.border)!;
+      expect(rgb.r).toBeLessThan(40);
+      expect(rgb.g).toBeLessThan(40);
+      expect(rgb.b).toBeLessThan(50);
+    });
+  });
+
+  describe("CoolBracketPalette", () => {
+    it("has multiple cool hues for animation", () => {
+      expect(CoolBracketPalette.length).toBeGreaterThanOrEqual(6);
+      for (const c of CoolBracketPalette) {
+        expect(c).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      }
+    });
+
+    it("starts in cyan/sky range (cool, not orange)", () => {
+      const first = hexToRgb(CoolBracketPalette[0]!)!;
+      expect(first.b).toBeGreaterThan(first.r);
+    });
+  });
+
+  // ── Semantic Colors ─────────────────────────────────────────────────────
+
+  describe("semantic colors", () => {
+    it("success is cool emerald", () => {
+      expect(Colors.success).toBe("#34D399");
+      const rgb = hexToRgb(Colors.success)!;
+      expect(rgb.g).toBeGreaterThan(180);
+    });
+
+    it("error is cool rose", () => {
+      expect(Colors.error).toBe("#FB7185");
+      const rgb = hexToRgb(Colors.error)!;
+      expect(rgb.r).toBeGreaterThan(200);
+    });
+
+    it("warning is amber", () => {
+      expect(Colors.warning).toBe("#FBBF24");
+      const rgb = hexToRgb(Colors.warning)!;
+      expect(rgb.r).toBeGreaterThan(200);
+      expect(rgb.g).toBeGreaterThan(150);
+    });
+
+    it("info is sky blue", () => {
+      expect(Colors.info).toBe("#38BDF8");
+      const rgb = hexToRgb(Colors.info)!;
+      expect(rgb.b).toBeGreaterThan(200);
+    });
+  });
+
+  // ── Contrast Ratios ─────────────────────────────────────────────────────
+
+  describe("contrast ratios", () => {
+    it("foreground on background has sufficient contrast (WCAG AA)", () => {
+      const ratio = contrastRatio(Colors.foreground, Colors.background);
+      // WCAG AA requires 4.5:1 for normal text
+      expect(ratio).toBeGreaterThan(4.5);
+    });
+
+    it("accent on background has sufficient contrast", () => {
+      const ratio = contrastRatio(Colors.accent, Colors.background);
+      // Large/bold text requires 3:1
+      expect(ratio).toBeGreaterThan(3.0);
+    });
+
+    it("success on background has sufficient contrast", () => {
+      const ratio = contrastRatio(Colors.success, Colors.background);
+      expect(ratio).toBeGreaterThan(3.0);
+    });
+
+    it("error on background has sufficient contrast", () => {
+      const ratio = contrastRatio(Colors.error, Colors.background);
+      expect(ratio).toBeGreaterThan(3.0);
+    });
+
+    it("muted on background has at least some contrast (visible)", () => {
+      const ratio = contrastRatio(Colors.muted, Colors.background);
+      // Muted text should be readable but not dominant (>= 3.0)
+      expect(ratio).toBeGreaterThan(3.0);
+    });
+
+    it("foreground on card has sufficient contrast", () => {
+      const ratio = contrastRatio(Colors.foreground, Colors.card);
+      expect(ratio).toBeGreaterThan(4.5);
+    });
+
+    it("accent on card has sufficient contrast", () => {
+      const ratio = contrastRatio(Colors.accent, Colors.card);
+      expect(ratio).toBeGreaterThan(3.0);
+    });
+  });
+
+  // ── Token completeness ──────────────────────────────────────────────────
+
+  describe("token completeness", () => {
+    it("all required semantic tokens exist", () => {
+      const required = [
+        "background",
+        "foreground",
+        "card",
+        "accent",
+        "border",
+        "muted",
+        "muted-foreground",
+        "dim",
+        "success",
+        "error",
+        "warning",
+        "info",
+        "highlight",
+        "backdrop",
+      ] as const;
+      for (const key of required) {
+        expect(Colors[key]).toBeDefined();
+      }
+    });
+
+    it("no two core semantic colors share the same hex value", () => {
+      const semanticKeys = [
+        "background",
+        "foreground",
+        "card",
+        "accent",
+        "border",
+        "muted",
+        "muted-foreground",
+        "dim",
+        "success",
+        "error",
+        "warning",
+        "info",
+        "backdrop",
+      ] as const;
+      const hexes = semanticKeys.map((k) => Colors[k]);
+      // Core tokens must be unique (aliases like highlight/text may duplicate)
+      const uniqueHexes = new Set(hexes);
+      expect(uniqueHexes.size).toBe(semanticKeys.length);
+    });
+  });
+
+  // ── Edge Cases ──────────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("hexToRgb returns null for invalid hex", () => {
+      expect(hexToRgb("not-a-color")).toBeNull();
+      expect(hexToRgb("#FFF")).toBeNull(); // 3-digit not supported
+      expect(hexToRgb("#GGGGGG")).toBeNull();
+      expect(hexToRgb("")).toBeNull();
+    });
+
+    it("contrast ratio of same color is 1.0", () => {
+      expect(contrastRatio(Colors.background, Colors.background)).toBeCloseTo(
+        1.0,
+        1
+      );
+    });
+
+    it("contrast ratio is symmetric", () => {
+      const r1 = contrastRatio(Colors.foreground, Colors.background);
+      const r2 = contrastRatio(Colors.background, Colors.foreground);
+      expect(r1).toBeCloseTo(r2, 5);
+    });
+
+    it("white on black has maximum contrast (~21:1)", () => {
+      const ratio = contrastRatio("#FFFFFF", "#000000");
+      expect(ratio).toBeCloseTo(21, 0);
+    });
+  });
+});
+
+// ─── Status Color Mappings ───────────────────────────────────────────────────
+
+describe("status color mappings", () => {
+  it("connection status maps to correct colors", () => {
+    expect(ConnectionStatusColor.connected).toBe(Colors.success);
+    expect(ConnectionStatusColor.polling).toBe(Colors.highlight);
+    expect(ConnectionStatusColor.reconnecting).toBe(Colors.warning);
+    expect(ConnectionStatusColor.offline).toBe(Colors.error);
+  });
+
+  it("alert severity maps to correct colors", () => {
+    expect(AlertSeverityColor.info).toBe(Colors.info);
+    expect(AlertSeverityColor.warning).toBe(Colors.warning);
+    expect(AlertSeverityColor.error).toBe(Colors.error);
+    expect(AlertSeverityColor.critical).toBe(Colors.error);
+  });
+
+  it("worker status maps to correct colors", () => {
+    expect(WorkerStatusColor.operational).toBe(Colors.success);
+    expect(WorkerStatusColor.degraded).toBe(Colors.warning);
+    expect(WorkerStatusColor.down).toBe(Colors.error);
+  });
+
+  it("log level maps to correct colors", () => {
+    expect(LogLevelColor.debug).toBe(Colors.muted);
+    expect(LogLevelColor.info).toBe(Colors.foreground);
+    expect(LogLevelColor.warn).toBe(Colors.warning);
+    expect(LogLevelColor.error).toBe(Colors.error);
+  });
+});