quoxcli 0.0.0-stage → 0.3.1

package/lib/tui/components/Layout.jsx

@@ -0,0 +1,129 @@
+/**
+ * Layout component — header + dual-panel + status bar
+ *
+ * Provides the two-panel layout (35% left / 65% right) used by most views.
+ * Mirrors the QuoxBastion BubbleTea TUI layout pattern.
+ */
+
+import React from 'react';
+import { Box, Text } from 'ink';
+import { colors } from '../theme.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { useTui } from '../app.jsx';
+import { Breadcrumb } from './Breadcrumb.jsx';
+import { SCREEN_TITLES } from '../registry.js';
+
+/** Separator width: fills the terminal, with a small margin, floor of 20. */
+function separatorWidth(columns) {
+  return Math.max(20, columns - 2);
+}
+
+/**
+ * Build the breadcrumb trail from nav history + the current screen, e.g.
+ * ['Main', 'Fleet']. Renders nothing (via Breadcrumb's own empty-path
+ * guard) when the trail is trivial — i.e. we're still on the menu.
+ */
+function useBreadcrumbPath() {
+  const ctx = useTui();
+  const screen = ctx?.screen;
+  const history = ctx?.history || [];
+
+  if (!screen || screen === 'menu') return [];
+
+  return [...history, screen].map((id) => SCREEN_TITLES[id] || id);
+}
+
+export function Layout({ title, subtitle, left, right, footer, children }) {
+  const { columns } = useTerminalSize();
+  const breadcrumbPath = useBreadcrumbPath();
+
+  return (
+    <Box flexDirection="column" width="100%" height="100%">
+      {/* Header */}
+      <Box height={1} width="100%">
+        <Text color={colors.primary} bold> {title || 'QuoxCLI'}</Text>
+        {subtitle && (
+          <Text color={colors.dim}> {subtitle}</Text>
+        )}
+        {breadcrumbPath.length > 0 && (
+          <Box marginLeft={2}>
+            <Breadcrumb path={breadcrumbPath} />
+          </Box>
+        )}
+      </Box>
+
+      {/* Separator */}
+      <Box height={1} width="100%">
+        <Text color={colors.subtle}>{' ' + '\u2500'.repeat(separatorWidth(columns))}</Text>
+      </Box>
+
+      {/* Content area */}
+      <Box flexGrow={1} width="100%">
+        {children ? (
+          children
+        ) : (
+          <>
+            {/* Left panel (35%) */}
+            <Box width="35%" flexDirection="column" borderStyle="single" borderColor={colors.primary} paddingX={1}>
+              {left}
+            </Box>
+
+            {/* Right panel (65%) */}
+            <Box width="65%" flexDirection="column" borderStyle="single" borderColor={colors.subtle} paddingX={1}>
+              {right}
+            </Box>
+          </>
+        )}
+      </Box>
+
+      {/* Footer hint bar */}
+      {footer && (
+        <Box height={1} width="100%">
+          <Text color={colors.dim}> {footer}</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Single-panel layout for views like Chat that need full width.
+ */
+export function FullLayout({ title, subtitle, footer, children }) {
+  const { columns } = useTerminalSize();
+  const breadcrumbPath = useBreadcrumbPath();
+
+  return (
+    <Box flexDirection="column" width="100%" height="100%">
+      {/* Header */}
+      <Box height={1} width="100%">
+        <Text color={colors.primary} bold> {title || 'QuoxCLI'}</Text>
+        {subtitle && (
+          <Text color={colors.dim}> {subtitle}</Text>
+        )}
+        {breadcrumbPath.length > 0 && (
+          <Box marginLeft={2}>
+            <Breadcrumb path={breadcrumbPath} />
+          </Box>
+        )}
+      </Box>
+
+      {/* Separator */}
+      <Box height={1} width="100%">
+        <Text color={colors.subtle}>{' ' + '\u2500'.repeat(separatorWidth(columns))}</Text>
+      </Box>
+
+      {/* Content */}
+      <Box flexGrow={1} flexDirection="column" paddingX={1}>
+        {children}
+      </Box>
+
+      {/* Footer */}
+      {footer && (
+        <Box height={1} width="100%">
+          <Text color={colors.dim}> {footer}</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/lib/tui/components/Palette.jsx

@@ -0,0 +1,141 @@
+/**
+ * Palette — command palette overlay
+ *
+ * Opened from app.jsx on Ctrl+K or ':' (nav mode only). Renders in place
+ * of the current screen — mirrors HelpOverlay's content-swap pattern, no
+ * layout shift. Owns its own keystrokes via its own useInput while open.
+ *
+ * A text query filters SCREEN_REGISTRY (case-insensitive substring match
+ * on title + keywords). Up/Down or Ctrl+P/Ctrl+N move the selection,
+ * Enter calls onSelect(id), Esc calls onClose().
+ *
+ * Props:
+ *   onSelect(id) - called with the chosen screen id
+ *   onClose()    - called when the user dismisses the palette
+ */
+
+import React, { useState, useMemo } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { SCREEN_REGISTRY } from '../registry.js';
+import { colors } from '../theme.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+
+const PREFERRED_WIDTH = 56;
+const MIN_WIDTH = 24;
+const MAX_VISIBLE = 8;
+
+/** Case-insensitive substring match against title + keywords. */
+function filterEntries(query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return SCREEN_REGISTRY;
+  return SCREEN_REGISTRY.filter((entry) => {
+    if (entry.title.toLowerCase().includes(q)) return true;
+    return entry.keywords.some((kw) => kw.toLowerCase().includes(q));
+  });
+}
+
+export function Palette({ onSelect, onClose }) {
+  const { columns } = useTerminalSize();
+  const [query, setQuery] = useState('');
+  const [selected, setSelected] = useState(0);
+
+  const results = useMemo(() => filterEntries(query), [query]);
+
+  useInput((input, key) => {
+    if (key.escape) {
+      onClose?.();
+      return;
+    }
+
+    if (key.return) {
+      const entry = results[selected];
+      if (entry) onSelect?.(entry.id);
+      return;
+    }
+
+    if (key.upArrow || (key.ctrl && input === 'p')) {
+      setSelected((s) => (results.length === 0 ? 0 : (s > 0 ? s - 1 : results.length - 1)));
+      return;
+    }
+
+    if (key.downArrow || (key.ctrl && input === 'n')) {
+      setSelected((s) => (results.length === 0 ? 0 : (s < results.length - 1 ? s + 1 : 0)));
+      return;
+    }
+
+    if (key.backspace || key.delete) {
+      setQuery((q) => q.slice(0, -1));
+      setSelected(0);
+      return;
+    }
+
+    // Printable characters only — ignore other ctrl/meta/tab combos.
+    if (input && !key.ctrl && !key.meta && !key.tab) {
+      setQuery((q) => q + input);
+      setSelected(0);
+    }
+  });
+
+  const width = Math.max(MIN_WIDTH, Math.min(PREFERRED_WIDTH, columns - 4));
+
+  // Keep the selected row inside the visible window as the list scrolls.
+  const start = Math.max(
+    0,
+    Math.min(selected - Math.floor(MAX_VISIBLE / 2), Math.max(0, results.length - MAX_VISIBLE))
+  );
+  const visible = results.slice(start, start + MAX_VISIBLE);
+
+  return (
+    <Box flexDirection="column" alignItems="center" width="100%" paddingTop={1}>
+      <Box
+        flexDirection="column"
+        borderStyle="round"
+        borderColor={colors.primary}
+        paddingX={2}
+        paddingY={1}
+        width={width}
+      >
+        {/* Header */}
+        <Box justifyContent="center" marginBottom={1}>
+          <Text color={colors.primary} bold>Jump to Screen</Text>
+        </Box>
+
+        {/* Query input */}
+        <Box borderStyle="single" borderColor={colors.cyberBlue} paddingX={1} marginBottom={1}>
+          <Text color={colors.cyberBlue} bold>{'> '}</Text>
+          {query ? (
+            <Text color={colors.text}>{query}</Text>
+          ) : (
+            <Text color={colors.dim}>Type to filter...</Text>
+          )}
+          <Text color={colors.cyberBlue}>{'█'}</Text>
+        </Box>
+
+        {/* Results */}
+        {visible.length === 0 ? (
+          <Text color={colors.dim}>No matching screens</Text>
+        ) : (
+          visible.map((entry, i) => {
+            const isSelected = start + i === selected;
+            return (
+              <Box key={entry.id} height={1}>
+                <Text color={isSelected ? colors.primary : colors.subtle}>
+                  {isSelected ? ' ▶ ' : '   '}
+                </Text>
+                <Text color={colors.cyberBlue} bold>[{entry.hotkey}] </Text>
+                <Text color={isSelected ? colors.text : colors.textMuted} bold={isSelected}>
+                  {entry.title}
+                </Text>
+              </Box>
+            );
+          })
+        )}
+
+        {/* Footer hint */}
+        <Box marginTop={1}>
+          <Text color={colors.dim}>{'↑/↓'} Navigate  Enter Jump  Esc Close</Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}

package/lib/tui/components/SearchInput.jsx

@@ -0,0 +1,125 @@
+/**
+ * SearchInput — Text input for search/filter operations
+ *
+ * Uses @inkjs/ui TextInput when available, with a fallback
+ * implementation using ink's useInput for basic text entry.
+ *
+ * Props:
+ *   placeholder - placeholder text (default: 'Search...')
+ *   value       - current search value
+ *   onChange    - callback when value changes
+ *   onSubmit   - callback when Enter is pressed
+ *   active     - whether input accepts keyboard input (default: true)
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { colors } from '../theme.js';
+
+// ── Try to load @inkjs/ui TextInput ────────────────────────────────────
+let InkTextInput = null;
+try {
+  const mod = await import('@inkjs/ui');
+  InkTextInput = mod.TextInput;
+} catch {
+  // Fallback to custom implementation below
+}
+
+/**
+ * Fallback text input using useInput.
+ * Handles printable characters, backspace, and Enter.
+ */
+function FallbackTextInput({ placeholder, value, onChange, onSubmit, active }) {
+  useInput((input, key) => {
+    if (!active) return;
+
+    // Enter submits
+    if (key.return) {
+      if (onSubmit) onSubmit(value);
+      return;
+    }
+
+    // Backspace / delete
+    if (key.backspace || key.delete) {
+      if (onChange && value.length > 0) {
+        onChange(value.slice(0, -1));
+      }
+      return;
+    }
+
+    // Escape is handled by parent, not here
+
+    // Printable characters
+    if (input && !key.ctrl && !key.meta && !key.escape && !key.tab) {
+      if (onChange) {
+        onChange(value + input);
+      }
+    }
+  });
+
+  const showPlaceholder = !value || value.length === 0;
+
+  return (
+    <Box>
+      <Text color={colors.cyberBlue} bold>/ </Text>
+      {showPlaceholder ? (
+        <Text color={colors.dim}>{placeholder}</Text>
+      ) : (
+        <Text color={colors.text}>{value}</Text>
+      )}
+      {active && <Text color={colors.cyberBlue}>{'\u2588'}</Text>}
+    </Box>
+  );
+}
+
+/**
+ * Wrapper that uses @inkjs/ui TextInput if available.
+ */
+function InkUITextInput({ placeholder, value, onChange, onSubmit, active }) {
+  // @inkjs/ui TextInput uses defaultValue + onChange, not controlled value.
+  // We track the internal value and sync via onChange.
+  const [initialized, setInitialized] = useState(false);
+
+  useEffect(() => {
+    setInitialized(true);
+  }, []);
+
+  return (
+    <Box>
+      <Text color={colors.cyberBlue} bold>/ </Text>
+      <InkTextInput
+        placeholder={placeholder}
+        defaultValue={value || ''}
+        isDisabled={!active}
+        onChange={(newVal) => {
+          if (onChange) onChange(newVal);
+        }}
+        onSubmit={(val) => {
+          if (onSubmit) onSubmit(val);
+        }}
+      />
+    </Box>
+  );
+}
+
+export function SearchInput({
+  placeholder = 'Search...',
+  value = '',
+  onChange,
+  onSubmit,
+  active = true,
+}) {
+  const InputComponent = InkTextInput ? InkUITextInput : FallbackTextInput;
+
+  return (
+    <Box borderStyle="single" borderColor={active ? colors.cyberBlue : colors.subtle} paddingX={1}>
+      <InputComponent
+        placeholder={placeholder}
+        value={value}
+        onChange={onChange}
+        onSubmit={onSubmit}
+        active={active}
+      />
+    </Box>
+  );
+}

package/lib/tui/components/Sparkline.jsx

@@ -0,0 +1,55 @@
+/**
+ * Sparkline — pure presentational block-ramp trend renderer
+ *
+ * Maps a numeric series onto the unicode block ramp (▁▂▃▄▅▆▇█), scaled
+ * between the min/max of the (optionally windowed) series, and renders it
+ * as a single <Text> line. Used for btop-style "line went up/down" trends
+ * inside dense TUI views (e.g. HealthView).
+ *
+ * Props:
+ *   data  {number[]} - the series to render (oldest -> newest)
+ *   width {number}   - optional max number of points to show; when the
+ *                       series is longer than width, only the most recent
+ *                       `width` points are rendered (and the ramp is
+ *                       scaled to that visible window)
+ *   color {string}   - optional hex color (defaults to theme cyberBlue)
+ */
+
+import React from 'react';
+import { Text } from 'ink';
+import { colors } from '../theme.js';
+
+// ── Block ramp (low -> high) ────────────────────────────────────────────
+const RAMP = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+const MID_CHAR = RAMP[Math.floor(RAMP.length / 2)];
+
+/**
+ * Convert a numeric series into a string of ramp characters.
+ * Exported for direct unit testing without rendering ink output.
+ */
+export function sparklineChars(data, width) {
+  if (!Array.isArray(data) || data.length === 0) return '';
+
+  const series = width && data.length > width ? data.slice(-width) : data;
+
+  const min = Math.min(...series);
+  const max = Math.max(...series);
+  const range = max - min;
+
+  if (range === 0) {
+    return MID_CHAR.repeat(series.length);
+  }
+
+  return series
+    .map((v) => {
+      const ratio = (v - min) / range;
+      const idx = Math.min(RAMP.length - 1, Math.floor(ratio * RAMP.length));
+      return RAMP[idx];
+    })
+    .join('');
+}
+
+export function Sparkline({ data, width, color }) {
+  const chars = sparklineChars(data, width);
+  return <Text color={color || colors.cyberBlue}>{chars}</Text>;
+}

package/lib/tui/components/StatusBar.jsx

@@ -0,0 +1,133 @@
+/**
+ * Status bar — bottom of the TUI
+ *
+ * Shows: user email, active org, profile name, current screen, a live
+ * service-health dot (polled every 30s), a refresh/staleness indicator,
+ * a clock, and key hints.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { Box, Text } from 'ink';
+import { colors } from '../theme.js';
+import { useTui } from '../app.jsx';
+import { useHealth } from '../hooks/useHealth.js';
+
+// Display labels for each navigable screen id (see MainMenu.jsx MENU_ITEMS).
+const SCREEN_LABELS = {
+  menu: 'Menu',
+  fleet: 'Fleet',
+  agents: 'Agents',
+  tools: 'Tools',
+  orgs: 'Organizations',
+  memory: 'Memory',
+  brain: 'Brain',
+  workflows: 'Workflows',
+  chat: 'Chat',
+  admin: 'Admin',
+  files: 'Files',
+  backups: 'Backups',
+  objectives: 'Objectives',
+  inbox: 'Inbox',
+  vault: 'Vault',
+  governance: 'Governance',
+};
+
+const HEALTH_DOT_COLORS = {
+  green: colors.success,
+  amber: colors.warning,
+  red: colors.error,
+  grey: colors.dim,
+};
+
+function formatClock(date) {
+  const hh = String(date.getHours()).padStart(2, '0');
+  const mm = String(date.getMinutes()).padStart(2, '0');
+  return `${hh}:${mm}`;
+}
+
+function formatAge(lastFetched, isStale) {
+  if (lastFetched == null) return '';
+  if (isStale) return 'stale';
+  const secs = Math.max(0, Math.floor((Date.now() - lastFetched) / 1000));
+  return `${secs}s`;
+}
+
+export function StatusBar() {
+  const ctx = useTui();
+  const config = ctx?.config;
+  const client = ctx?.client;
+  const screen = ctx?.screen || '';
+
+  // Try to extract user/org info from auth store
+  let userEmail = '';
+  let orgName = '';
+  let profileName = '';
+
+  try {
+    const profile = config?.getActiveProfile?.();
+    userEmail = profile?.auth?.email || profile?.auth?.user_email || '';
+    orgName = profile?.auth?.org_name || profile?.auth?.org_slug || '';
+    profileName = config?.getActiveProfileName?.() || '';
+  } catch {
+    // Config might not be loaded
+  }
+
+  const { color: healthColor, loading: healthLoading, lastFetched, isStale } = useHealth(client);
+
+  // Clock — recomputed on a 30s tick (no 1s timer).
+  const [now, setNow] = useState(() => new Date());
+  useEffect(() => {
+    const id = setInterval(() => setNow(new Date()), 30000);
+    return () => clearInterval(id);
+  }, []);
+
+  const screenLabel = SCREEN_LABELS[screen] ?? (screen || '');
+  const ageText = formatAge(lastFetched, isStale);
+  const dotColor = HEALTH_DOT_COLORS[healthColor] || HEALTH_DOT_COLORS.grey;
+
+  return (
+    <Box height={1} width="100%">
+      <Box flexGrow={1}>
+        <Text color={colors.primary} bold> QUOX</Text>
+        {screenLabel && (
+          <>
+            <Text color={colors.dim}> | </Text>
+            <Text color={colors.accent} bold>{screenLabel}</Text>
+          </>
+        )}
+        <Text color={colors.dim}> | </Text>
+        {userEmail ? (
+          <>
+            <Text color={colors.text}>{userEmail}</Text>
+            <Text color={colors.dim}> | </Text>
+          </>
+        ) : (
+          <>
+            <Text color={colors.warning}>not logged in</Text>
+            <Text color={colors.dim}> | </Text>
+          </>
+        )}
+        {orgName && (
+          <>
+            <Text color={colors.accent}>{orgName}</Text>
+            <Text color={colors.dim}> | </Text>
+          </>
+        )}
+        {profileName && (
+          <Text color={colors.dim}>{profileName}</Text>
+        )}
+      </Box>
+      <Box>
+        {healthLoading && <Text color={colors.dim}>{'⟳ '}</Text>}
+        <Text color={dotColor}>{'●'}</Text>
+        {ageText && (
+          <Text color={isStale ? colors.warning : colors.dim}> {ageText}</Text>
+        )}
+        <Text color={colors.dim}>  {formatClock(now)}  </Text>
+        <Text color={colors.dim}>
+          {screen === 'menu' ? 'q:quit  ?:help' : 'Esc:back  ?:help  q:quit'}
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/lib/tui/components/Toast.jsx

@@ -0,0 +1,52 @@
+/**
+ * Toast — Auto-dismissing notification component
+ *
+ * Shows a message at the top of the view that auto-dismisses after a timeout.
+ * Supports success, error, warning, and info variants.
+ *
+ * Props:
+ *   message  - notification text
+ *   type     - 'success' | 'error' | 'warning' | 'info' (default: 'info')
+ *   duration - auto-dismiss ms (default: 3000, 0 = no auto-dismiss)
+ *   onDismiss- called when the toast is dismissed
+ *   visible  - whether the toast is shown (default: true when message is truthy)
+ */
+
+import React, { useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { colors } from '../theme.js';
+
+const TYPE_CONFIG = {
+  success: { color: colors.success, icon: '\u2714' },  // ✔
+  error:   { color: colors.error,   icon: '\u2718' },  // ✘
+  warning: { color: colors.warning, icon: '\u26A0' },  // ⚠
+  info:    { color: colors.cyberBlue, icon: '\u2139' }, // ℹ
+};
+
+export function Toast({ message, type = 'info', duration = 3000, onDismiss, visible }) {
+  const show = visible !== undefined ? visible : !!message;
+
+  useEffect(() => {
+    if (!show || duration <= 0) return;
+    const timer = setTimeout(() => {
+      onDismiss?.();
+    }, duration);
+    return () => clearTimeout(timer);
+  }, [show, duration, onDismiss]);
+
+  if (!show || !message) return null;
+
+  const config = TYPE_CONFIG[type] || TYPE_CONFIG.info;
+
+  return (
+    <Box
+      borderStyle="single"
+      borderColor={config.color}
+      paddingX={1}
+      marginBottom={1}
+    >
+      <Text color={config.color} bold>{config.icon} </Text>
+      <Text color={config.color}>{message}</Text>
+    </Box>
+  );
+}

package/lib/tui/hooks/useApi.js

@@ -0,0 +1,44 @@
+/**
+ * useApi — React hook for API calls with loading/error/data state
+ *
+ * Wraps an async fetch function and manages its lifecycle state.
+ * Automatically calls the fetch function on mount and when deps change.
+ * Provides a `refresh` function for manual re-fetching.
+ *
+ * Usage:
+ *   const { data, loading, error, refresh } = useApi(
+ *     () => client.fleet.list(),
+ *     [client]
+ *   );
+ *
+ * @param {Function} fetchFn  - async function that returns data
+ * @param {Array}    deps     - dependency array (re-fetch when changed)
+ * @returns {{ data: any, loading: boolean, error: Error|null, refresh: Function }}
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+export function useApi(fetchFn, deps = []) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await fetchFn();
+      setData(result);
+    } catch (err) {
+      setError(err);
+    } finally {
+      setLoading(false);
+    }
+  }, deps);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { data, loading, error, refresh };
+}