@hoox-sh/hoox-tui 0.2.0 → 0.3.1

package/src/hooks/shell-overlay.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shell overlay helpers — command palette / quit modal ownership of keys.
+ * View-local keyboard handlers should no-op while an overlay is open so
+ * typing in the palette (or confirming quit) does not fire view shortcuts.
+ */
+import { useKeyboard } from "@opentui/react";
+import { useUIStore } from "@hoox-sh/hoox-shared";
+
+/** True when palette or a UI-store modal owns the keyboard. */
+export function isShellOverlayOpen(): boolean {
+  const s = useUIStore.getState();
+  return Boolean(s.commandPaletteOpen || s.modal);
+}
+
+/** Key shape from OpenTUI; fields optional at the type boundary. */
+export type ViewKeyEvent = {
+  name?: string;
+  ctrl?: boolean;
+  alt?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+  sequence?: string;
+  /** Some OpenTUI builds expose the raw character as `raw`. */
+  raw?: string;
+};
+
+/**
+ * View-scoped keyboard hook: skips the handler while shell overlays are open.
+ * Drop-in for `@opentui/react` `useKeyboard` in primary views.
+ */
+export function useViewKeyboard(handler: (key: ViewKeyEvent) => void): void {
+  useKeyboard((key) => {
+    if (isShellOverlayOpen()) return;
+    handler(key as ViewKeyEvent);
+  });
+}

package/src/hooks/use-polling.ts

@@ -18,6 +18,89 @@ export interface UsePollingOptions {
   immediate?: boolean;
 }
 
+/** Max poll delay after repeated failures (ms). Exported for unit tests. */
+export const POLLING_MAX_BACKOFF_MS = 16_000;
+
+/**
+ * Exponential backoff for poll failures, capped at {@link POLLING_MAX_BACKOFF_MS}.
+ * Exported for unit tests (pure).
+ */
+export function computePollingBackoff(
+  baseIntervalMs: number,
+  retryCount: number,
+  maxBackoffMs: number = POLLING_MAX_BACKOFF_MS
+): number {
+  return Math.min(baseIntervalMs * Math.pow(2, retryCount), maxBackoffMs);
+}
+
+/**
+ * Non-React poll scheduler used by {@link usePolling}.
+ * Exported so unit tests can cover success/failure/cancel without a renderer.
+ */
+export function createPollingController(options: {
+  getCallback: () => () => Promise<void>;
+  getIntervalMs: () => number;
+  immediate?: boolean;
+  maxBackoffMs?: number;
+  /** Mutable retry counter (shared with the React ref when used from the hook). */
+  retryCountRef?: { current: number };
+}): { start: () => void; stop: () => void; getRetryCount: () => number } {
+  const {
+    getCallback,
+    getIntervalMs,
+    immediate = true,
+    maxBackoffMs = POLLING_MAX_BACKOFF_MS,
+    retryCountRef = { current: 0 },
+  } = options;
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let cancelled = false;
+
+  const poll = async () => {
+    if (cancelled) return;
+    try {
+      await getCallback()();
+      if (cancelled) return;
+      retryCountRef.current = 0;
+    } catch {
+      if (cancelled) return;
+      retryCountRef.current++;
+    }
+    // cancelled is already checked in both branches above (no await between
+    // those checks and here), so schedule the next tick directly.
+    // Read fresh interval on every iteration so config changes take effect.
+    const currentInterval = getIntervalMs();
+    const backoff = computePollingBackoff(
+      currentInterval,
+      retryCountRef.current,
+      maxBackoffMs
+    );
+    timeoutId = setTimeout(() => {
+      void poll();
+    }, backoff);
+  };
+
+  return {
+    getRetryCount: () => retryCountRef.current,
+    start: () => {
+      cancelled = false;
+      if (immediate) {
+        void poll();
+      } else {
+        const initialInterval = getIntervalMs();
+        timeoutId = setTimeout(() => {
+          void poll();
+        }, initialInterval);
+      }
+    },
+    stop: () => {
+      cancelled = true;
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      timeoutId = undefined;
+    },
+  };
+}
+
 export function usePolling(options: UsePollingOptions): void {
   const { callback, enabled = true, immediate = true } = options;
   const intervalMs = useConfigStore((s) => s.refreshIntervalMs);
@@ -32,42 +115,15 @@ export function usePolling(options: UsePollingOptions): void {
       return;
     }
 
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-    let cancelled = false;
-    const MAX_BACKOFF = 16_000;
-
-    const poll = async () => {
-      if (cancelled) return;
-      try {
-        await callbackRef.current();
-        if (cancelled) return;
-        retryCount.current = 0;
-      } catch {
-        if (cancelled) return;
-        retryCount.current++;
-      }
-      if (cancelled) return;
-      // Read fresh from store on every iteration so config changes take effect
-      const currentInterval = useConfigStore.getState().refreshIntervalMs;
-      const backoff = Math.min(
-        currentInterval * Math.pow(2, retryCount.current),
-        MAX_BACKOFF
-      );
-      timeoutId = setTimeout(poll, backoff);
-    };
-
-    if (immediate) {
-      void poll();
-    } else {
-      const initialInterval = useConfigStore.getState().refreshIntervalMs;
-      timeoutId = setTimeout(() => {
-        void poll();
-      }, initialInterval);
-    }
-
+    const controller = createPollingController({
+      getCallback: () => callbackRef.current,
+      getIntervalMs: () => useConfigStore.getState().refreshIntervalMs,
+      immediate,
+      retryCountRef: retryCount,
+    });
+    controller.start();
     return () => {
-      cancelled = true;
-      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      controller.stop();
     };
   }, [intervalMs, enabled, immediate]);
 }

package/src/hooks/use-service-data.ts

@@ -11,8 +11,25 @@
  */
 import { useServiceStore } from "@hoox-sh/hoox-shared";
 
-export function useServiceData<T>(
-  selector: (state: ReturnType<typeof useServiceStore.getState>) => T
-): T {
-  return useServiceStore(selector);
+export type ServiceStoreState = ReturnType<typeof useServiceStore.getState>;
+export type ServiceStoreSelector<T> = (state: ServiceStoreState) => T;
+
+/**
+ * Store hook used by {@link useServiceData}. Production points at
+ * `useServiceStore`; unit tests may swap this for a pure selector runner
+ * via {@link __setServiceStoreHookForTests}.
+ */
+let storeHook: <T>(selector: ServiceStoreSelector<T>) => T =
+  useServiceStore as <T>(selector: ServiceStoreSelector<T>) => T;
+
+/** @internal Test-only seam — pass `null` to restore the real Zustand hook. */
+export function __setServiceStoreHookForTests(
+  hook: (<T>(selector: ServiceStoreSelector<T>) => T) | null
+): void {
+  storeHook =
+    hook ?? (useServiceStore as <T>(selector: ServiceStoreSelector<T>) => T);
+}
+
+export function useServiceData<T>(selector: ServiceStoreSelector<T>): T {
+  return storeHook(selector);
 }

package/src/main.tsx

@@ -102,6 +102,12 @@ async function main() {
   // Set renderer ref so hooks + components can access it via getRendererRef()
   setRendererRef(renderer);
 
+  // Note: @opentui-ui/toast ToasterRenderable is intentionally NOT mounted.
+  // toast@0.0.5 peers on ancient @opentui and nests a second core that
+  // re-registers OPENTUI_FORCE_WCWIDTH (crash on global install). Connection
+  // feedback still surfaces via the status bar + service-store alerts.
+  // Toast helpers in components/ui/toast.tsx are fail-closed no-ops.
+
   // Mouse drag-select → clipboard (OSC 52 + system tools)
   enableAutoCopyOnSelection(
     renderer as unknown as import("./services/clipboard").ClipboardRenderer

package/src/services/cli-bridge/index.ts

@@ -178,7 +178,8 @@ function killProc(
  *   [ { "results": [ {...}, {...} ], "success": true,
  *       "meta": { "duration": 0.123, "rows_read": 42, ... } } ]
  */
-function parseDbQueryResult(stdout: string): DbQueryResult {
+/** Exported for unit tests — pure stdout → DbQueryResult normalizer. */
+export function parseDbQueryResult(stdout: string): DbQueryResult {
   const cleaned = stdout.trim();
   if (!cleaned) {
     return {
@@ -266,7 +267,7 @@ function parseDbQueryResult(stdout: string): DbQueryResult {
 }
 
 /** Compute the {@link QueueDepthStatus} for a given depth + paused flag. */
-function deriveQueueDepthStatus(
+export function deriveQueueDepthStatus(
   depth: number,
   paused: boolean
 ): QueueDepthStatus {
@@ -285,7 +286,8 @@ function deriveQueueDepthStatus(
  * Expected envelope shape:
  *   { "queues": [ { "queue_name": "...", "producers_total_count": 2, ... } ] }
  */
-function parseQueueDepths(stdout: string): QueueDepth[] {
+/** Exported for unit tests — pure queue-depth envelope parser. */
+export function parseQueueDepths(stdout: string): QueueDepth[] {
   const timestamp = new Date().toISOString();
   const cleaned = stdout.trim();
   if (!cleaned) return [];
@@ -349,7 +351,8 @@ function parseQueueDepths(stdout: string): QueueDepth[] {
  * Values are intentionally omitted — the viewer is strictly read-only.
  * The parser never throws on malformed input.
  */
-function parseSecretsList(stdout: string): SecretMetadata[] {
+/** Exported for unit tests — pure secrets-list envelope parser. */
+export function parseSecretsList(stdout: string): SecretMetadata[] {
   const cleaned = stdout.trim();
   if (!cleaned) return [];
 
@@ -357,12 +360,8 @@ function parseSecretsList(stdout: string): SecretMetadata[] {
   if (parsed === null) return [];
 
   // Single-worker envelope: { worker: string, secrets: string[] }
-  if (
-    parsed !== null &&
-    typeof parsed === "object" &&
-    "worker" in parsed &&
-    "secrets" in parsed
-  ) {
+  // `parsed` is non-null after the early return above.
+  if (typeof parsed === "object" && "worker" in parsed && "secrets" in parsed) {
     const envelope = parsed as { worker: string; secrets: unknown };
     if (Array.isArray(envelope.secrets)) {
       const result: SecretMetadata[] = [];
@@ -381,7 +380,7 @@ function parseSecretsList(stdout: string): SecretMetadata[] {
   }
 
   // All-workers envelope: Record<string, string[]>
-  if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+  if (typeof parsed === "object" && !Array.isArray(parsed)) {
     const entries = Object.entries(parsed as Record<string, unknown>);
     const result: SecretMetadata[] = [];
     for (const [, value] of entries) {
@@ -408,7 +407,8 @@ function parseSecretsList(stdout: string): SecretMetadata[] {
  * Cloudflare secrets store does not expose per-secret type metadata,
  * so we derive it from the key name suffix.
  */
-function inferSecretType(name: string): SecretMetadata["type"] {
+/** Exported for unit tests — naming-convention secret type inference. */
+export function inferSecretType(name: string): SecretMetadata["type"] {
   const lower = name.toLowerCase();
   if (lower.includes("key") || lower.includes("api")) return "api_key";
   if (lower.includes("token")) return "token";
@@ -450,7 +450,8 @@ interface WranglerKeyRecord {
  * This parser accepts both. Unknown rows are skipped; the parser never
  * throws on malformed input — it returns an empty `keys` array instead.
  */
-function parseKvList(
+/** Exported for unit tests — pure KV list + manifest merge. */
+export function parseKvList(
   stdout: string,
   manifest: Map<
     string,
@@ -464,10 +465,10 @@ function parseKvList(
   if (parsed === null) return [];
 
   let records: unknown;
+  // `parsed` is non-null after the early return above.
   if (Array.isArray(parsed)) {
     records = parsed;
   } else if (
-    parsed !== null &&
     typeof parsed === "object" &&
     "keys" in parsed &&
     Array.isArray((parsed as { keys: unknown }).keys)
@@ -510,7 +511,8 @@ function parseKvList(
  * return a `Map` keyed by key name. Returns an empty map on any failure
  * — the view still functions, it just cannot flag secret keys.
  */
-function parseKvManifest(
+/** Exported for unit tests — pure KV manifest parser. */
+export function parseKvManifest(
   stdout: string
 ): Map<string, { type: "boolean" | "number" | "string"; secret: boolean }> {
   const map = new Map<
@@ -524,8 +526,8 @@ function parseKvManifest(
   if (parsed === null) return map;
 
   // Manifest shape: { namespace: "CONFIG_KV", keys: [{ key, type, default, ... }] }
+  // `parsed` is non-null after the early return above.
   const keys =
-    parsed !== null &&
     typeof parsed === "object" &&
     "keys" in parsed &&
     Array.isArray((parsed as { keys: unknown }).keys)
@@ -551,8 +553,8 @@ function parseKvManifest(
 // eslint-disable-next-line no-control-regex -- intentional: matches ESC (\x1b) sequences
 const ANSI_PATTERN = /\x1b\[[0-9;]*[A-Za-z]/g;
 
-/** Remove ANSI color escape codes from a string. */
-function stripAnsi(input: string): string {
+/** Remove ANSI color escape codes from a string. Exported for unit tests. */
+export function stripAnsi(input: string): string {
   return input.replace(ANSI_PATTERN, "");
 }
 
@@ -579,7 +581,8 @@ interface WranglerQueueRecord {
  * switches the format for set actions), so we detect the engaged/released
  * state from the message text.
  */
-function parseKillSwitchStatus(
+/** Exported for unit tests — pure kill-switch status parser. */
+export function parseKillSwitchStatus(
   action: KillSwitchAction,
   stdout: string
 ): KillSwitchStatus {
@@ -1521,7 +1524,8 @@ class CliBridgeImpl {
 /**
  * Parse `hoox pyne health --json` stdout into {@link PyneHealthResult}.
  */
-function parsePyneHealth(stdout: string): PyneHealthResult {
+/** Exported for unit tests — pure pyne health envelope parser. */
+export function parsePyneHealth(stdout: string): PyneHealthResult {
   const timestamp = new Date().toISOString();
   const cleaned = stdout.trim();
   if (!cleaned) {
@@ -1567,7 +1571,8 @@ function parsePyneHealth(stdout: string): PyneHealthResult {
   };
 }
 
-function parseAgentHealth(stdout: string): AgentHealthResult {
+/** Exported for unit tests — pure agent health envelope parser. */
+export function parseAgentHealth(stdout: string): AgentHealthResult {
   const timestamp = new Date().toISOString();
   const cleaned = stdout.trim();
   if (!cleaned) {
@@ -1624,7 +1629,8 @@ function parseAgentHealth(stdout: string): AgentHealthResult {
  * exists so future manifest changes can light up the namespace column
  * without touching the viewer.
  */
-function extractNamespaceId(_manifestStdout: string): string | null {
+/** Exported for unit tests — reserved namespace-id extractor (currently always null). */
+export function extractNamespaceId(_manifestStdout: string): string | null {
   // Reserved for future CLI versions — manifest envelope does not yet
   // surface the namespace ID. Kept as a separate function to keep the
   // test surface stable.

package/src/services/cli-bridge/standalone.ts

@@ -197,6 +197,33 @@ export function agentChatStream(
   let completed = false;
 
   const finished = (async () => {
+    // Match workers/SSE: Bearer + optional CF Access service-token headers
+    let authHeaders: Record<string, string> = {};
+    let resolvedBase = apiBase;
+    try {
+      const { resolveOperatorTransportProfile, buildOperatorAuthHeaders } =
+        await import("@hoox-sh/hoox-shared");
+      const profile = resolveOperatorTransportProfile(process.env as never, {
+        configApiUrl: apiBase,
+        configApiToken: apiToken,
+      });
+      authHeaders = buildOperatorAuthHeaders(profile);
+      // Prefer profile base when caller passed default localhost but env has remote
+      if (apiBase === "http://localhost:8787" && profile.apiBase) {
+        resolvedBase = profile.apiBase;
+      } else {
+        resolvedBase = apiBase.replace(/\/$/, "") || profile.apiBase;
+      }
+      // Ensure Bearer from explicit apiToken if profile missed it
+      if (apiToken && !authHeaders.Authorization) {
+        authHeaders.Authorization = `Bearer ${apiToken}`;
+      }
+    } catch {
+      if (apiToken) {
+        authHeaders = { Authorization: `Bearer ${apiToken}` };
+      }
+    }
+
     let attempt = 0;
 
     while (
@@ -204,7 +231,7 @@ export function agentChatStream(
       attempt < SSE_MAX_RECONNECT_ATTEMPTS
     ) {
       try {
-        const url = `${apiBase.replace(/\/$/, "")}/api/agent/chat`;
+        const url = `${resolvedBase.replace(/\/$/, "")}/api/agent/chat`;
         const body = JSON.stringify({
           messages: params.messages.map((m) => ({
             role: m.role,
@@ -224,7 +251,7 @@ export function agentChatStream(
           headers: {
             "Content-Type": "application/json",
             Accept: "text/event-stream",
-            ...(apiToken ? { Authorization: `Bearer ${apiToken}` } : {}),
+            ...authHeaders,
           },
           body,
           signal: abortController.signal,