@nexus-ai-fs/tui 0.9.18

package/src/shared/navigation.ts

@@ -0,0 +1,110 @@
+import type { TabDef } from "./hooks/use-visible-tabs.js";
+import type { PanelId } from "../stores/global-store.js";
+import type { AccessTab } from "../stores/access-store.js";
+import type { AgentTab } from "../stores/agents-store.js";
+import type { SearchTab } from "../stores/search-store.js";
+import type { ZoneTab } from "../stores/zones-store.js";
+import type { WorkflowTab } from "../stores/workflows-store.js";
+import type { PaymentsTab } from "../stores/payments-store.js";
+import type { EventsPanelTab } from "../stores/infra-store.js";
+import { NAV_ITEMS, type NavItem } from "./nav-items.js";
+
+export interface TopLevelTab {
+  readonly id: PanelId;
+  readonly label: string;
+  readonly shortcut: string;
+}
+
+export interface PanelDescriptor {
+  readonly id: PanelId;
+  readonly tabLabel: string;
+  readonly breadcrumbLabel: string;
+  readonly shortcut: string;
+}
+
+function navItemToPanelDescriptor(item: NavItem): PanelDescriptor {
+  return {
+    id: item.id,
+    tabLabel: item.label,
+    breadcrumbLabel: item.fullLabel,
+    shortcut: item.shortcut,
+  };
+}
+
+export const PANEL_DESCRIPTORS: Readonly<Record<PanelId, PanelDescriptor>> = Object.fromEntries(
+  NAV_ITEMS.map((item) => [item.id, navItemToPanelDescriptor(item)]),
+) as Readonly<Record<PanelId, PanelDescriptor>>;
+
+export const PANEL_TABS: readonly TopLevelTab[] = NAV_ITEMS.map(({ id, label, shortcut }) => ({
+  id,
+  label,
+  shortcut,
+}));
+
+export const ACCESS_TABS: readonly TabDef<AccessTab>[] = [
+  { id: "manifests", label: "Manifests", brick: "access_manifest" },
+  { id: "alerts", label: "Alerts", brick: "governance" },
+  { id: "credentials", label: "Credentials", brick: "auth" },
+  { id: "fraud", label: "Fraud", brick: "governance" },
+  { id: "delegations", label: "Delegations", brick: "delegation" },
+];
+
+export const AGENT_TABS: readonly TabDef<AgentTab>[] = [
+  { id: "status", label: "Status", brick: "agent_runtime" },
+  { id: "delegations", label: "Delegations", brick: "delegation" },
+  { id: "inbox", label: "Inbox", brick: "ipc" },
+  { id: "trajectories", label: "Trajectories", brick: "agent_runtime" },
+];
+
+export const SEARCH_TABS: readonly TabDef<SearchTab>[] = [
+  { id: "search", label: "Search", brick: "search" },
+  { id: "knowledge", label: "Knowledge", brick: "catalog" },
+  { id: "memories", label: "Memories", brick: "memory" },
+  { id: "playbooks", label: "Playbooks", brick: null },
+  { id: "ask", label: "Ask", brick: "rlm" },
+  { id: "columns", label: "Columns", brick: "catalog" },
+];
+
+export const ZONE_TABS: readonly TabDef<ZoneTab>[] = [
+  { id: "zones", label: "Zones", brick: null },
+  { id: "bricks", label: "Bricks", brick: null },
+  { id: "drift", label: "Drift", brick: null },
+  { id: "reindex", label: "Reindex", brick: ["search", "versioning"] },
+  { id: "workspaces", label: "Workspaces", brick: "workspace" },
+  { id: "mcp", label: "MCP", brick: "mcp" },
+  { id: "cache", label: "Cache", brick: "cache" },
+];
+
+export const WORKFLOW_TABS: readonly TabDef<WorkflowTab>[] = [
+  { id: "workflows", label: "Workflows", brick: null },
+  { id: "executions", label: "Executions", brick: null },
+  { id: "scheduler", label: "Scheduler", brick: null },
+];
+
+export const PAYMENTS_TABS: readonly TabDef<PaymentsTab>[] = [
+  { id: "balance", label: "Balance", brick: null },
+  { id: "reservations", label: "Reservations", brick: null },
+  { id: "transactions", label: "Transactions", brick: null },
+  { id: "policies", label: "Policies", brick: null },
+  { id: "approvals", label: "Approvals", brick: null },
+];
+
+export const EVENTS_TABS: readonly TabDef<EventsPanelTab>[] = [
+  { id: "events", label: "Events", brick: "eventlog" },
+  { id: "mcl", label: "MCL", brick: "catalog" },
+  { id: "replay", label: "Replay", brick: "eventlog" },
+  { id: "operations", label: "Operations", brick: "eventlog" },
+  { id: "connectors", label: "Connectors", brick: null },
+  { id: "subscriptions", label: "Subscriptions", brick: "eventlog" },
+  { id: "locks", label: "Locks", brick: null },
+  { id: "secrets", label: "Secrets", brick: "auth" },
+  { id: "audit", label: "Audit", brick: "auth" },
+];
+
+export function getTabLabel<T extends string>(
+  tabs: readonly { readonly id: T; readonly label: string }[],
+  activeTab: T | null | undefined,
+): string | null {
+  if (!activeTab) return null;
+  return tabs.find((tab) => tab.id === activeTab)?.label ?? null;
+}

package/src/shared/status-breadcrumb.ts

@@ -0,0 +1,74 @@
+import type { ConnectionStatus, PanelId } from "../stores/global-store.js";
+import type { AccessTab } from "../stores/access-store.js";
+import type { AgentTab } from "../stores/agents-store.js";
+import type { SearchTab } from "../stores/search-store.js";
+import type { ZoneTab } from "../stores/zones-store.js";
+import type { WorkflowTab } from "../stores/workflows-store.js";
+import type { PaymentsTab } from "../stores/payments-store.js";
+import type { EventsPanelTab } from "../stores/infra-store.js";
+import {
+  ACCESS_TABS,
+  AGENT_TABS,
+  EVENTS_TABS,
+  PANEL_DESCRIPTORS,
+  PAYMENTS_TABS,
+  SEARCH_TABS,
+  WORKFLOW_TABS,
+  ZONE_TABS,
+  getTabLabel,
+} from "./navigation.js";
+
+export interface StatusBreadcrumbState {
+  readonly connectionStatus: ConnectionStatus;
+  readonly activePanel: PanelId | null | undefined;
+  readonly accessTab?: AccessTab | null;
+  readonly agentTab?: AgentTab | null;
+  readonly paymentsTab?: PaymentsTab | null;
+  readonly searchTab?: SearchTab | null;
+  readonly workflowTab?: WorkflowTab | null;
+  readonly zoneTab?: ZoneTab | null;
+  readonly eventsTab?: EventsPanelTab | null;
+}
+
+export function deriveStatusBreadcrumb(state: StatusBreadcrumbState): string | null {
+  const { activePanel, connectionStatus } = state;
+  if (connectionStatus !== "connected" || !activePanel) return null;
+
+  const panelLabel = PANEL_DESCRIPTORS[activePanel]?.breadcrumbLabel;
+  if (!panelLabel) return null;
+
+  let subTabLabel: string | null = null;
+
+  switch (activePanel) {
+    case "access":
+      subTabLabel = getTabLabel(ACCESS_TABS, state.accessTab);
+      break;
+    case "agents":
+      subTabLabel = getTabLabel(AGENT_TABS, state.agentTab);
+      break;
+    case "payments":
+      subTabLabel = getTabLabel(PAYMENTS_TABS, state.paymentsTab);
+      break;
+    case "infrastructure":
+      subTabLabel = getTabLabel(EVENTS_TABS, state.eventsTab);
+      break;
+    case "search":
+      subTabLabel = getTabLabel(SEARCH_TABS, state.searchTab);
+      break;
+    case "workflows":
+      subTabLabel = getTabLabel(WORKFLOW_TABS, state.workflowTab);
+      break;
+    case "zones":
+      subTabLabel = getTabLabel(ZONE_TABS, state.zoneTab);
+      break;
+    default:
+      subTabLabel = null;
+      break;
+  }
+
+  if (!subTabLabel || subTabLabel === panelLabel) {
+    return panelLabel;
+  }
+
+  return `${panelLabel} > ${subTabLabel}`;
+}

package/src/shared/syntax-style.ts

@@ -0,0 +1,3 @@
+import { SyntaxStyle } from "@opentui/core";
+
+export const defaultSyntaxStyle = SyntaxStyle.fromStyles({});

package/src/shared/tab-visibility.ts

@@ -0,0 +1,15 @@
+import type { TabDef } from "./hooks/use-visible-tabs.js";
+
+export function filterVisibleTabs<T extends string>(
+  allTabs: readonly TabDef<T>[],
+  enabledBricks: readonly string[],
+  featuresLoaded: boolean,
+): readonly TabDef<T>[] {
+  if (!featuresLoaded) return allTabs;
+
+  return allTabs.filter((tab) => {
+    if (tab.brick === null) return true;
+    if (typeof tab.brick === "string") return enabledBricks.includes(tab.brick);
+    return tab.brick.some((b) => enabledBricks.includes(b));
+  });
+}

package/src/shared/text-style.ts

@@ -0,0 +1,23 @@
+import { createTextAttributes } from "@opentui/core";
+
+interface TextStyleOptions {
+  readonly fg?: string;
+  readonly bg?: string;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+  readonly underline?: boolean;
+  readonly inverse?: boolean;
+}
+
+export function textStyle(options: TextStyleOptions = {}): {
+  fg?: string;
+  bg?: string;
+  attributes: number;
+} {
+  const { fg, bg, bold, dim, underline, inverse } = options;
+  return {
+    fg,
+    bg,
+    attributes: createTextAttributes({ bold, dim, underline, inverse }),
+  };
+}

package/src/shared/theme.ts

@@ -0,0 +1,179 @@
+/**
+ * Semantic color system for the TUI.
+ *
+ * All visual styling should reference these tokens rather than raw color names.
+ * Colors use ANSI 16 names for universal terminal compatibility.
+ *
+ * @see Issue #3066, Phase A1
+ */
+
+// =============================================================================
+// Semantic color tokens
+// =============================================================================
+
+/**
+ * Status-based colors for state indicators across all panels.
+ */
+export const statusColor = {
+  /** Healthy, active, committed, connected */
+  healthy: "green",
+  /** Completed successfully — same as healthy (terminal vs ongoing state) */
+  success: "green",
+  /** Warning, starting, stopping, stale */
+  warning: "yellow",
+  /** Error, failed, rolled_back, expired */
+  error: "red",
+  /** Info, informational highlights */
+  info: "cyan",
+  /** Focus, selected, active UI chrome */
+  focus: "yellow",
+  /** Secondary text, hints, timestamps */
+  dim: "gray",
+  /** Agent identity, delegation chains */
+  identity: "magenta",
+  /** File paths, URNs, zone IDs */
+  reference: "blue",
+} as const;
+
+export type StatusColorKey = keyof typeof statusColor;
+
+// =============================================================================
+// Connection status → color mapping
+// =============================================================================
+
+export const connectionColor: Record<string, string> = {
+  connected: statusColor.healthy,
+  connecting: statusColor.warning,
+  disconnected: statusColor.dim,
+  error: statusColor.error,
+};
+
+// =============================================================================
+// Brick state → color mapping
+// =============================================================================
+
+export const brickStateColor: Record<string, string> = {
+  active: statusColor.healthy,
+  registered: statusColor.info,
+  starting: statusColor.warning,
+  stopping: statusColor.warning,
+  unmounted: statusColor.dim,
+  unregistered: statusColor.dim,
+  failed: statusColor.error,
+};
+
+// =============================================================================
+// Transaction status → color mapping
+// =============================================================================
+
+export const transactionStatusColor: Record<string, string> = {
+  active: statusColor.warning,
+  committed: statusColor.healthy,
+  rolled_back: statusColor.error,
+  expired: statusColor.dim,
+};
+
+// =============================================================================
+// HTTP status code → color mapping
+// =============================================================================
+
+export function httpStatusColor(status: number): string {
+  if (status >= 200 && status < 300) return statusColor.healthy;
+  if (status >= 400 && status < 500) return statusColor.warning;
+  if (status >= 500) return statusColor.error;
+  return statusColor.dim;
+}
+
+// =============================================================================
+// Agent phase → color mapping
+// =============================================================================
+
+export const agentPhaseColor: Record<string, string> = {
+  ready: statusColor.healthy,
+  active: statusColor.healthy,
+  warming: statusColor.warning,
+  evicting: statusColor.warning,
+  evicted: statusColor.dim,
+  failed: statusColor.error,
+};
+
+// =============================================================================
+// Agent state → color mapping (for agent list)
+// =============================================================================
+
+export const agentStateColor: Record<string, string> = {
+  registered: statusColor.info,
+  delegated: statusColor.identity,
+  running: statusColor.healthy,
+  connected: statusColor.healthy,
+  disconnected: statusColor.dim,
+};
+
+// =============================================================================
+// Delegation mode → color mapping
+// =============================================================================
+
+export const delegationModeColor: Record<string, string> = {
+  shared: statusColor.info,
+  copy: statusColor.warning,
+  clean: statusColor.error,
+};
+
+// =============================================================================
+// Delegation status → color mapping
+// =============================================================================
+
+export const delegationStatusColor: Record<string, string> = {
+  active: statusColor.healthy,
+  revoked: statusColor.error,
+  expired: statusColor.dim,
+  completed: statusColor.info,
+};
+
+// =============================================================================
+// Focus / UI chrome colors
+// =============================================================================
+
+export const focusColor = {
+  /** Active pane border */
+  activeBorder: statusColor.focus,
+  /** Inactive pane border */
+  inactiveBorder: statusColor.dim,
+  /** Selected item highlight */
+  selected: statusColor.focus,
+  /** Help bar action keys */
+  actionKey: statusColor.focus,
+  /** Help bar navigation keys */
+  navKey: statusColor.dim,
+} as const;
+
+// =============================================================================
+// Rich color palette — hex values for modern terminals
+//
+// Used by shared chrome components (tab bar, status bar, error bar).
+// Components should prefer semantic tokens (statusColor, focusColor) for
+// state-dependent colors and use palette for structural UI chrome.
+// =============================================================================
+
+export const palette = {
+  /** Primary accent — active tabs, selected items, key bindings */
+  accent: "#D4A017",
+  /** Secondary accent — hover, secondary actions */
+  accentDim: "#B8890F",
+  /** Success — green confirmation */
+  success: "#34D399",
+  /** Error — bright red */
+  error: "#F87171",
+  /** Error secondary — softer red for hints */
+  errorDim: "#FCA5A5",
+  /** Warning — amber */
+  warning: "#FBBF24",
+  /** Muted text — labels, separators */
+  muted: "#8B8B92",
+  /** Very muted — borders, inactive chrome */
+  faint: "#2A2A2E",
+  /** Bright text — active content */
+  bright: "#EDEDEF",
+  /** Header/title text */
+  title: "#EDEDEF",
+} as const;

package/src/shared/utils/format-size.ts

@@ -0,0 +1,20 @@
+/**
+ * Consistent byte-size formatting across all panels.
+ *
+ * Output: "0 B", "1.5 KB", "2.3 MB", "1.1 GB"
+ * - Space before unit, standard suffixes
+ * - Supports up to GB
+ *
+ * @see Issue #3102, Decision 5A
+ */
+
+const KB = 1024;
+const MB = KB * 1024;
+const GB = MB * 1024;
+
+export function formatSize(bytes: number): string {
+  if (bytes < KB) return `${bytes} B`;
+  if (bytes < MB) return `${(bytes / KB).toFixed(1)} KB`;
+  if (bytes < GB) return `${(bytes / MB).toFixed(1)} MB`;
+  return `${(bytes / GB).toFixed(1)} GB`;
+}

package/src/shared/utils/format-text.ts

@@ -0,0 +1,10 @@
+/**
+ * Text truncation utility for terminal column alignment.
+ *
+ * @see Issue #3102, Decision 8A
+ */
+
+export function truncateText(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen - 3)}...`;
+}

package/src/shared/utils/format-time.ts

@@ -0,0 +1,72 @@
+/**
+ * Consistent date/time formatting across all panels.
+ *
+ * Strategy:
+ * - Relative time for < 24 hours ("2h ago", "5m ago")
+ * - Absolute for >= 24 hours ("Mar 15, 14:30")
+ * - Consistent 19-char max width for absolute timestamps
+ *
+ * @see Issue #3066, Phase E8
+ */
+
+const SECOND = 1_000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const MONTHS = [
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+] as const;
+
+/**
+ * Format a timestamp for display in the TUI.
+ *
+ * @param input - Unix epoch ms, ISO string, or Date object
+ * @param now - Current time in ms (injectable for testing). Defaults to Date.now()
+ * @param utc - If true, use UTC for absolute timestamps (recommended for distributed systems). Default: true.
+ * @returns Formatted time string, max 19 chars
+ */
+export function formatTimestamp(input: number | string | Date, now?: number, utc = true): string {
+  const date = input instanceof Date ? input : new Date(input);
+  const ts = date.getTime();
+
+  if (Number.isNaN(ts)) return "—";
+
+  const currentTime = now ?? Date.now();
+  const delta = currentTime - ts;
+
+  // Future timestamps: show absolute
+  if (delta < 0) {
+    return formatAbsolute(date, utc);
+  }
+
+  // < 1 minute
+  if (delta < MINUTE) {
+    const secs = Math.floor(delta / SECOND);
+    return secs <= 1 ? "just now" : `${secs}s ago`;
+  }
+
+  // < 1 hour
+  if (delta < HOUR) {
+    const mins = Math.floor(delta / MINUTE);
+    return `${mins}m ago`;
+  }
+
+  // < 24 hours
+  if (delta < DAY) {
+    const hours = Math.floor(delta / HOUR);
+    return `${hours}h ago`;
+  }
+
+  return formatAbsolute(date, utc);
+}
+
+function formatAbsolute(date: Date, utc: boolean): string {
+  const month = MONTHS[utc ? date.getUTCMonth() : date.getMonth()]!;
+  const day = utc ? date.getUTCDate() : date.getDate();
+  const hours = String(utc ? date.getUTCHours() : date.getHours()).padStart(2, "0");
+  const minutes = String(utc ? date.getUTCMinutes() : date.getMinutes()).padStart(2, "0");
+  const suffix = utc ? "Z" : "";
+  return `${month} ${String(day).padStart(2, " ")}, ${hours}:${minutes}${suffix}`;
+}

package/src/shared/utils/lru-cache.ts

@@ -0,0 +1,75 @@
+/**
+ * Generic LRU cache with O(n) eviction.
+ *
+ * Uses a monotonic access counter for LRU ordering.
+ * Eviction finds the minimum-access-order entry in a single pass (O(n))
+ * instead of sorting (O(n log n)).
+ *
+ * @see Issue #3102, Decisions 7A + 16A
+ */
+
+interface CacheEntry<T> {
+  data: T;
+  fetchedAt: number;
+}
+
+let accessCounter = 0;
+
+export class LruCache<T = unknown> {
+  private readonly _map = new Map<string, { entry: CacheEntry<T>; accessOrder: number }>();
+  private readonly _maxSize: number;
+
+  constructor(maxSize: number = 200) {
+    this._maxSize = maxSize;
+  }
+
+  get(key: string): CacheEntry<T> | undefined {
+    const item = this._map.get(key);
+    if (!item) return undefined;
+    // Update access order for LRU tracking (monotonic counter avoids Date.now() ties)
+    item.accessOrder = ++accessCounter;
+    return item.entry;
+  }
+
+  set(key: string, entry: CacheEntry<T>): void {
+    this._map.set(key, { entry, accessOrder: ++accessCounter });
+    this._evictIfNeeded();
+  }
+
+  has(key: string): boolean {
+    return this._map.has(key);
+  }
+
+  delete(key: string): void {
+    this._map.delete(key);
+  }
+
+  clear(): void {
+    this._map.clear();
+  }
+
+  get size(): number {
+    return this._map.size;
+  }
+
+  private _evictIfNeeded(): void {
+    while (this._map.size > this._maxSize) {
+      // O(n) min-scan: find the least-recently-accessed entry
+      let minKey: string | undefined;
+      let minOrder = Infinity;
+
+      for (const [key, item] of this._map) {
+        if (item.accessOrder < minOrder) {
+          minOrder = item.accessOrder;
+          minKey = key;
+        }
+      }
+
+      if (minKey !== undefined) {
+        this._map.delete(minKey);
+      } else {
+        break;
+      }
+    }
+  }
+}