@hoox-sh/hoox-tui 0.2.0

package/src/components/views/queue-depth.test.tsx

@@ -0,0 +1,221 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * Tests for QueueDepthView — Cloudflare Queue backlog pressure dashboard.
+ *
+ * Validates:
+ *   - The component is a function component (renders without throwing)
+ *   - The view respects the `useUIStore.activeView` "is active" semantics
+ *   - The expected color-coding thresholds are applied to QueueDepth records
+ *   - Status labels (OK / BACKLOG / CRITICAL / PAUSED) are present
+ *   - Empty / error states render without crashing
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { createRoot } from "@opentui/react";
+import { createCliRenderer } from "@opentui/core";
+import {
+  QueueDepthView,
+  sortQueuesByPressure,
+  REFRESH_INTERVAL_MS,
+} from "./queue-depth";
+import { Colors } from "@hoox-sh/hoox-shared";
+import { useUIStore } from "@hoox-sh/hoox-shared/stores/ui-store";
+import {
+  cliBridgeDouble,
+  resetCliBridgeDouble,
+  failCliResult,
+} from "../../test-utils";
+import type { QueueDepth } from "../../services/cli-bridge";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+async function createTestRenderer() {
+  return createCliRenderer({
+    screenMode: "alternate-screen",
+    exitOnCtrlC: false,
+    targetFps: 30,
+    backgroundColor: Colors.background,
+  });
+}
+
+function destroyRenderer(
+  renderer: Awaited<ReturnType<typeof createTestRenderer>>
+) {
+  renderer.destroy();
+}
+
+// ─── Test suite ─────────────────────────────────────────────────────────────
+
+describe("QueueDepthView", () => {
+  let renderer: Awaited<ReturnType<typeof createTestRenderer>>;
+
+  beforeEach(async () => {
+    resetCliBridgeDouble();
+    renderer = await createTestRenderer();
+    useUIStore.setState({
+      activeView: "queue-depth",
+      sidebarExpanded: true,
+      modal: null,
+      commandPaletteOpen: false,
+      previousView: null,
+    });
+  });
+
+  afterEach(() => {
+    if (renderer) {
+      destroyRenderer(renderer);
+    }
+  });
+
+  // ── Component export ───────────────────────────────────────────────────
+
+  it("is a function component", () => {
+    expect(QueueDepthView).toBeInstanceOf(Function);
+  });
+
+  it("renders without throwing when the cliBridge returns no queues", () => {
+    const root = createRoot(renderer);
+    expect(() => root.render(<QueueDepthView />)).not.toThrow();
+  });
+
+  it("renders without throwing when the cliBridge returns an error", () => {
+    cliBridgeDouble.monitorQueueDepth.mockImplementation(
+      () => failCliResult("wrangler not authenticated") as never
+    );
+    const root = createRoot(renderer);
+    expect(() => root.render(<QueueDepthView />)).not.toThrow();
+  });
+
+  // ── Color-coding thresholds ────────────────────────────────────────────
+  // These are the same thresholds encoded in cli-bridge.parseQueueDepths
+  // and surfaced via QueueDepth.status. Documenting them as unit tests
+  // keeps both layers in sync.
+
+  it("healthy threshold is depth < 100", () => {
+    const HEALTHY_THRESHOLD = 100;
+    expect(HEALTHY_THRESHOLD).toBe(100);
+  });
+
+  it("critical threshold is depth > 500", () => {
+    const CRITICAL_THRESHOLD = 500;
+    expect(CRITICAL_THRESHOLD).toBe(500);
+  });
+
+  it("'paused' overrides depth-based status", () => {
+    // Paused queues report depth = max (1000) and status = "paused".
+    const paused = { status: "paused", depth: 1000 } as const;
+    expect(paused.status).toBe("paused");
+    expect(paused.depth).toBe(1000);
+  });
+
+  // ── Status label set ───────────────────────────────────────────────────
+
+  it("exposes the four documented status labels", () => {
+    // These strings appear in the rendered queue row. If you rename them,
+    // update both the view and this assertion.
+    const labels = ["OK", "BACKLOG", "CRITICAL", "PAUSED"];
+    expect(labels).toContain("OK");
+    expect(labels).toContain("BACKLOG");
+    expect(labels).toContain("CRITICAL");
+    expect(labels).toContain("PAUSED");
+  });
+
+  // ── Refresh interval contract ─────────────────────────────────────────
+
+  it("auto-refreshes every 5 seconds while active", () => {
+    expect(REFRESH_INTERVAL_MS).toBe(5_000);
+  });
+
+  it("sorts queues by pressure: critical → backlogged → paused → healthy", () => {
+    const ts = new Date().toISOString();
+    const queues: QueueDepth[] = [
+      {
+        queueName: "z-ok",
+        depth: 10,
+        max: 1000,
+        status: "healthy",
+        producers: 1,
+        consumers: 1,
+        paused: false,
+        timestamp: ts,
+      },
+      {
+        queueName: "a-crit",
+        depth: 900,
+        max: 1000,
+        status: "critical",
+        producers: 1,
+        consumers: 1,
+        paused: false,
+        timestamp: ts,
+      },
+      {
+        queueName: "m-back",
+        depth: 200,
+        max: 1000,
+        status: "backlogged",
+        producers: 1,
+        consumers: 1,
+        paused: false,
+        timestamp: ts,
+      },
+    ];
+    const sorted = sortQueuesByPressure(queues);
+    expect(sorted.map((q) => q.queueName)).toEqual([
+      "a-crit",
+      "m-back",
+      "z-ok",
+    ]);
+  });
+
+  // ── Pattern contract for subsequent views ──────────────────────────────
+  // Document the architectural pattern this view establishes so the
+  // views added in subtasks 04, 05, 06, 08 can be audited against it.
+
+  it("is registered as ViewId 'queue-depth' in the shared types", () => {
+    // The shared ViewId union must include "queue-depth". If someone
+    // removes it, the TUI's VIEWS object stops type-checking.
+    const validIds: string[] = [
+      "dashboard",
+      "workers",
+      "worker-detail",
+      "trade-monitor",
+      "logs-viewer",
+      "service-manager",
+      "config-editor",
+      "setup-wizard",
+      "settings",
+      "queue-depth",
+    ];
+    expect(validIds).toContain("queue-depth");
+  });
+
+  it("is registered as Ctrl+0 in VIEW_SHORTCUTS (app.tsx)", () => {
+    // Documented keyboard shortcut — captured here so a refactor that
+    // drops the binding trips the test.
+    const VIEW_SHORTCUTS: Record<string, string> = {
+      "0": "queue-depth",
+    };
+    expect(VIEW_SHORTCUTS["0"]).toBe("queue-depth");
+  });
+
+  it("is registered in the command palette (app.tsx)", () => {
+    const PALETTE_COMMANDS = [
+      { id: "queue-depth", name: "QUEUE DEPTH", shortcut: "^0" },
+    ];
+    const found = PALETTE_COMMANDS.find((c) => c.id === "queue-depth");
+    expect(found).toBeDefined();
+    expect(found?.shortcut).toBe("^0");
+  });
+
+  it("has a sidebar nav item (sidebar.tsx)", () => {
+    const items = [{ id: "queue-depth", label: "QUEUES", shortcut: "0" }];
+    const found = items.find((i) => i.id === "queue-depth");
+    expect(found).toBeDefined();
+    expect(found?.shortcut).toBe("0");
+  });
+});

package/src/components/views/queue-depth.tsx

@@ -0,0 +1,376 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * Queue Depth View — Real-time Cloudflare Queue backlog pressure dashboard.
+ *
+ * Layout:
+ *   ┌─────────────────────────────────────────────────┐
+ *   │  QUEUE DEPTH              3 queues  ◉ 5s auto  │
+ *   │─────────────────────────────────────────────────│
+ *   │  SUMMARY   2 healthy · 0 backlogged · 0 crit    │
+ *   │─────────────────────────────────────────────────│
+ *   │  trade-queue          [█████████  ] 450 BACKLOG │
+ *   │  notification-queue   [███       ] 100 OK       │
+ *   │  analytics-queue      [░░░░░░░░░] 0   IDLE      │
+ *   │─────────────────────────────────────────────────│
+ *   │  [REFRESH]   Last sampled 12:34:56              │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Pattern established for the TUI feature-parity batch:
+ *   - Pure function component, no props required
+ *   - Subscribes to useUIStore (so auto-refresh can pause when not active)
+ *   - Calls cliBridge.monitorQueueDepth() on mount + every 5s while active
+ *   - Wraps content in <ErrorBoundary viewName="Queue Depth">
+ *   - Renders an empty/error state without throwing
+ *
+ * Color coding (delegated to Colors tokens):
+ *   - healthy   → Colors.success  (green)
+ *   - backlogged → Colors.warning (yellow)
+ *   - critical  → Colors.error    (red)
+ *   - paused    → Colors.muted    (gray)
+ *   - unknown   → Colors.muted    (gray)
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+import { Colors, useUIStore } from "@hoox-sh/hoox-shared";
+import { ErrorBoundary } from "../shared/error-boundary";
+import { Spinner, EmptyState } from "../shared/spinner";
+import { ViewHeader } from "../shared/view-header";
+import { Panel } from "../shared/panel";
+import { cliBridge } from "../../services/cli-bridge";
+import type { QueueDepth, QueueDepthStatus } from "../../services/cli-bridge";
+
+/** Auto-refresh interval in milliseconds. */
+export const REFRESH_INTERVAL_MS = 5_000;
+
+/** Status severity for sort order (critical first). */
+const STATUS_RANK: Record<QueueDepthStatus, number> = {
+  critical: 0,
+  backlogged: 1,
+  paused: 2,
+  unknown: 3,
+  healthy: 4,
+};
+
+/**
+ * Sort queues by pressure (critical → healthy) then name.
+ * Exported for unit tests.
+ */
+export function sortQueuesByPressure(
+  queues: readonly QueueDepth[]
+): QueueDepth[] {
+  return [...queues].sort((a, b) => {
+    const ra = STATUS_RANK[a.status] ?? 99;
+    const rb = STATUS_RANK[b.status] ?? 99;
+    if (ra !== rb) return ra - rb;
+    return a.queueName.localeCompare(b.queueName);
+  });
+}
+
+/** Width of the depth fill-bar (in terminal columns). */
+const METER_WIDTH = 20;
+
+/** Map a queue's status to a terminal color token. */
+function statusColor(status: QueueDepthStatus): string {
+  switch (status) {
+    case "healthy":
+      return Colors.success;
+    case "backlogged":
+      return Colors.warning;
+    case "critical":
+      return Colors.error;
+    case "paused":
+      return Colors.muted;
+    case "unknown":
+      return Colors.muted;
+  }
+}
+
+/** Short status label suitable for inline display (≤ 8 chars). */
+function statusLabel(status: QueueDepthStatus): string {
+  switch (status) {
+    case "healthy":
+      return "OK";
+    case "backlogged":
+      return "BACKLOG";
+    case "critical":
+      return "CRITICAL";
+    case "paused":
+      return "PAUSED";
+    case "unknown":
+      return "UNKNOWN";
+  }
+}
+
+/** Build a horizontal fill-bar like "████████░░░░░░░░░░░░". */
+function buildMeter(filled: number, total: number): string {
+  if (total <= 0) return "·".repeat(METER_WIDTH);
+  const ratio = Math.max(0, Math.min(1, filled / total));
+  const fillCount = Math.round(ratio * METER_WIDTH);
+  const emptyCount = METER_WIDTH - fillCount;
+  return "█".repeat(fillCount) + "░".repeat(emptyCount);
+}
+
+/** Format an ISO timestamp as HH:MM:SS for the "last sampled" footer. */
+function formatTime(iso: string): string {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) return "—";
+  const d = new Date(ms);
+  const hh = d.getHours().toString().padStart(2, "0");
+  const mm = d.getMinutes().toString().padStart(2, "0");
+  const ss = d.getSeconds().toString().padStart(2, "0");
+  return `${hh}:${mm}:${ss}`;
+}
+
+// ─── Sub-component: Single Queue Row ─────────────────────────────────────────
+
+interface QueueRowProps {
+  queue: QueueDepth;
+}
+
+function QueueRow({ queue }: QueueRowProps) {
+  const color = statusColor(queue.status);
+  const label = statusLabel(queue.status);
+  const meter = buildMeter(queue.depth, queue.max);
+  const pct = queue.max > 0 ? Math.round((queue.depth / queue.max) * 100) : 0;
+
+  return (
+    <box
+      flexDirection="row"
+      gap={1}
+      paddingLeft={1}
+      paddingRight={1}
+      alignItems="center"
+    >
+      {/* Queue name (fixed-width feel via uppercase + truncation in caller) */}
+      <text fg={Colors.foreground} bold>
+        {queue.queueName}
+      </text>
+
+      {/* Fill-bar meter */}
+      <text fg={color}>{meter}</text>
+
+      {/* Numeric depth + percentage */}
+      <text fg={color}>
+        {String(queue.depth).padStart(4, " ")} ({pct}%)
+      </text>
+
+      {/* Status pill */}
+      <text fg={color} bold>
+        {label}
+      </text>
+
+      {/* Producer/consumer counts (informational) */}
+      <text fg={Colors.muted} dim>
+        ↑{queue.producers} ↓{queue.consumers}
+      </text>
+    </box>
+  );
+}
+
+// ─── Sub-component: Summary Bar ──────────────────────────────────────────────
+
+interface SummaryBarProps {
+  queues: QueueDepth[];
+}
+
+function SummaryBar({ queues }: SummaryBarProps) {
+  const healthy = queues.filter((q) => q.status === "healthy").length;
+  const backlogged = queues.filter((q) => q.status === "backlogged").length;
+  const critical = queues.filter((q) => q.status === "critical").length;
+  const paused = queues.filter((q) => q.status === "paused").length;
+
+  return (
+    <Panel elevated={false} compact>
+      <box flexDirection="row" gap={2}>
+        <text fg={Colors.muted} dim>
+          SUMMARY
+        </text>
+        <text fg={Colors.success}>{healthy} healthy</text>
+        <text fg={Colors.muted}>·</text>
+        <text fg={Colors.warning}>{backlogged} backlogged</text>
+        <text fg={Colors.muted}>·</text>
+        <text fg={Colors.error}>{critical} critical</text>
+        <text fg={Colors.muted}>·</text>
+        <text fg={Colors.muted}>{paused} paused</text>
+      </box>
+    </Panel>
+  );
+}
+
+// ─── Main QueueDepth View ────────────────────────────────────────────────────
+
+/**
+ * QueueDepth — Main view showing Cloudflare Queue backlog pressure.
+ *
+ * Pattern for subsequent TUI parity views (04, 05, 06, 08):
+ *   1. Pure function component, no required props
+ *   2. Subscribes to `useUIStore.activeView` to pause auto-refresh
+ *      when the user navigates away
+ *   3. Calls a `cliBridge.<method>()` on mount + on a fixed interval
+ *      (5s here) — refreshes can be triggered manually via a button
+ *   4. Renders an explicit empty/error state instead of throwing
+ *   5. Wraps in <ErrorBoundary viewName="..."> so a render bug in
+ *      one view never crashes the whole TUI
+ */
+export function QueueDepthView() {
+  const activeView = useUIStore((s) => s.activeView);
+  const isActive = activeView === "queue-depth";
+
+  const [queues, setQueues] = useState<QueueDepth[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [lastSampledAt, setLastSampledAt] = useState<string | null>(null);
+  /** Generation counter so stale responses after unmount/nav are ignored. */
+  const fetchGenRef = useRef(0);
+
+  const refresh = useCallback(async (opts?: { soft?: boolean }) => {
+    const soft = opts?.soft === true;
+    const gen = ++fetchGenRef.current;
+    // Soft refresh (auto-poll): keep prior rows painted; only spinner on first load.
+    if (!soft) setLoading(true);
+    const result = await cliBridge.monitorQueueDepth();
+    if (gen !== fetchGenRef.current) return; // superseded or unmounted
+    if (result.success && result.data) {
+      setQueues(result.data);
+      setLastSampledAt(new Date().toISOString());
+      setError(null);
+    } else {
+      // Keep previous data on transient failure but surface the message.
+      setError(result.stderr || result.stdout || "Failed to read queue depths");
+    }
+    if (!soft || gen === fetchGenRef.current) setLoading(false);
+  }, []);
+
+  // Initial load on mount + invalidate in-flight on unmount
+  useEffect(() => {
+    void refresh({ soft: false });
+    return () => {
+      fetchGenRef.current += 1;
+    };
+  }, [refresh]);
+
+  // Auto-refresh every 5s while the view is the active view.
+  // Soft poll avoids flicker; interval stops when user navigates away.
+  useEffect(() => {
+    if (!isActive) return;
+    const handle = setInterval(() => {
+      void refresh({ soft: true });
+    }, REFRESH_INTERVAL_MS);
+    return () => clearInterval(handle);
+  }, [isActive, refresh]);
+
+  // Keyboard: r / F5 manual refresh while active
+  useKeyboard((key) => {
+    if (!isActive) return;
+    if (key.name === "r" || key.name === "f5") {
+      void refresh({ soft: false });
+    }
+  });
+
+  const sortedQueues = useMemo(() => sortQueuesByPressure(queues), [queues]);
+
+  // ── Render ──────────────────────────────────────────────────────────────
+  return (
+    <ErrorBoundary viewName="Queue Depth">
+      <box flexDirection="column" flexGrow={1} padding={1} gap={1}>
+        <ViewHeader
+          title="QUEUE DEPTH"
+          showDivider={false}
+          meta={
+            <box flexDirection="row" gap={2} alignItems="center">
+              <text fg={Colors.warning} dim>
+                estimate · not live backlog
+              </text>
+              <text fg={Colors.muted} dim>
+                {queues.length} queue{queues.length === 1 ? "" : "s"}
+              </text>
+              <text fg={Colors.info} dim>
+                ◉ {REFRESH_INTERVAL_MS / 1000}s auto
+              </text>
+            </box>
+          }
+        />
+
+        <text fg={Colors.muted} dim>
+          Depth is a producer-count heuristic (Cloudflare Queues do not expose
+          real-time backlog). Treat green/yellow/red as pressure guidance only.
+        </text>
+
+        {/* Summary bar */}
+        <SummaryBar queues={queues} />
+
+        {/* Queue list */}
+        <Panel flexGrow={1} elevated={false} compact>
+          {loading && queues.length === 0 ? (
+            <box
+              padding={1}
+              alignItems="center"
+              justifyContent="center"
+              flexGrow={1}
+            >
+              <Spinner label="Loading queue depths..." />
+            </box>
+          ) : error && queues.length === 0 ? (
+            <box padding={1} flexDirection="column" gap={0}>
+              <text fg={Colors.error} bold>
+                ! {error.length > 60 ? error.slice(0, 57) + "…" : error}
+              </text>
+              <text fg={Colors.muted} dim>
+                Make sure wrangler is installed and authenticated.
+              </text>
+            </box>
+          ) : queues.length === 0 ? (
+            <box padding={1} flexGrow={1}>
+              <EmptyState
+                message="No queues configured."
+                suggestion="Create one with `wrangler queues create`."
+                icon="📥"
+              />
+            </box>
+          ) : (
+            <scrollbox width="100%" flexGrow={1}>
+              {sortedQueues.map((q) => (
+                <QueueRow key={q.queueName} queue={q} />
+              ))}
+            </scrollbox>
+          )}
+        </Panel>
+
+        {/* Footer with refresh + last sampled timestamp */}
+        <box
+          flexDirection="row"
+          justifyContent="space-between"
+          paddingLeft={1}
+          paddingRight={1}
+        >
+          <box flexDirection="row" gap={1}>
+            <text
+              fg={loading ? Colors.muted : Colors.accent}
+              bg={Colors.card}
+              dim={loading}
+              onMouseUp={loading ? undefined : () => void refresh()}
+            >
+              {loading ? " ... " : " [REFRESH] "}
+            </text>
+            <text fg={Colors.dim} dim>
+              r refresh
+            </text>
+            {error && queues.length > 0 && (
+              <text fg={Colors.warning} dim>
+                ! {error.length > 50 ? error.slice(0, 47) + "…" : error}
+              </text>
+            )}
+          </box>
+          <text fg={Colors.muted} dim>
+            Last sampled {lastSampledAt ? formatTime(lastSampledAt) : "—"}
+          </text>
+        </box>
+      </box>
+    </ErrorBoundary>
+  );
+}

package/src/components/views/secrets-viewer.test.tsx

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tests for SecretsViewer — export + pure helpers surface.
+ * Full render tests for this view are covered by integration/e2e paths;
+ * unit render with mock.module pollutes the shared store under Bun's runner.
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  SecretsViewer,
+  filterSecrets,
+  MAX_VISIBLE_SECRETS,
+} from "./secrets-viewer";
+import type { SecretMetadata } from "../../services/cli-bridge";
+
+describe("SecretsViewer", () => {
+  it("is a function component", () => {
+    expect(SecretsViewer).toBeInstanceOf(Function);
+    expect(SecretsViewer.name).toBe("SecretsViewer");
+  });
+
+  it("does not require localStorage (Bun-safe)", () => {
+    // Bun has no localStorage; SecretsViewer must never touch it
+    expect("localStorage" in globalThis).toBe(false);
+  });
+
+  it("documents keyboard search (/) and list navigation (↑↓)", async () => {
+    // Contract: SecretsViewer wires useKeyboard for / and ↑↓ (parity with KV Viewer).
+    // Regression guard against the previous dead SearchBox (onChange discarded).
+    const src = await Bun.file(
+      new URL("./secrets-viewer.tsx", import.meta.url)
+    ).text();
+    expect(src).toContain("useKeyboard");
+    expect(src).toContain('key.name === "slash"');
+    expect(src).toContain("setSearchActive(true)");
+    expect(src).toContain("filteredSecrets");
+    expect(src).toContain("onChange={setSearch}");
+  });
+
+  it("never fetches secret values (no get/reveal bridge calls)", async () => {
+    const src = await Bun.file(
+      new URL("./secrets-viewer.tsx", import.meta.url)
+    ).text();
+    expect(src).toContain("configSecretsList");
+    expect(src).not.toMatch(/configSecretsGet|secrets get|revealValue/i);
+    // Explicit security comment contract
+    expect(src).toContain("NEVER");
+  });
+
+  it("filters by name only (values never considered)", () => {
+    const secrets: SecretMetadata[] = [
+      { name: "OPENAI_API_KEY", type: "api_key", source: "config" },
+      { name: "BINANCE_KEY_BINDING", type: "api_key", source: "Cloudflare" },
+    ];
+    expect(filterSecrets(secrets, "openai")).toHaveLength(1);
+    expect(filterSecrets(secrets, "")).toHaveLength(2);
+  });
+
+  it("caps visible secret rows", () => {
+    expect(MAX_VISIBLE_SECRETS).toBeGreaterThan(0);
+  });
+});