@hoox-sh/hoox-tui 0.2.0

package/src/stores/session-restore.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Session restore/save tests — validates that all 16 ViewIds round-trip
+ * through `$HOME/.hoox/.tui-state/session.json` and invalid views fall back
+ * to dashboard (fail-closed for unknown IDs).
+ *
+ * Uses a temp HOOX_HOME so production ~/.hoox is never touched.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdir, rm, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { saveSession, restoreSession } from "@hoox-sh/hoox-shared";
+import type { ViewId } from "@hoox-sh/hoox-shared";
+import { ALL_VIEW_IDS } from "../test-utils";
+
+const PREV_HOOX_HOME = process.env.HOOX_HOME;
+const PREV_HOME = process.env.HOME;
+
+let tempRoot: string;
+
+async function setupTempHome(): Promise<void> {
+  tempRoot = join(
+    tmpdir(),
+    `hoox-tui-session-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  await mkdir(tempRoot, { recursive: true });
+  // path-utils / session prefer HOOX_HOME when set
+  process.env.HOOX_HOME = tempRoot;
+  process.env.HOME = tempRoot;
+}
+
+async function teardownTempHome(): Promise<void> {
+  if (PREV_HOOX_HOME === undefined) delete process.env.HOOX_HOME;
+  else process.env.HOOX_HOME = PREV_HOOX_HOME;
+  if (PREV_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = PREV_HOME;
+  if (tempRoot) {
+    await rm(tempRoot, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/** session.json lives under HOOX_HOME/.tui-state (getHooxHome() + .tui-state). */
+function sessionPath(): string {
+  return join(tempRoot, ".tui-state", "session.json");
+}
+
+describe("session restore / save", () => {
+  beforeEach(async () => {
+    await setupTempHome();
+  });
+
+  afterEach(async () => {
+    await teardownTempHome();
+  });
+
+  it("returns defaults when no session file exists", async () => {
+    const session = await restoreSession();
+    expect(session.activeView).toBe("dashboard");
+    expect(session.sidebarExpanded).toBe(true);
+    expect(session.lastData).toBe(0);
+  });
+
+  it("round-trips every ViewId (all 16)", async () => {
+    expect(ALL_VIEW_IDS).toHaveLength(16);
+    for (const view of ALL_VIEW_IDS) {
+      await saveSession(view, true, { cols: 100, rows: 40 }, 12345);
+      const restored = await restoreSession();
+      expect(restored.activeView).toBe(view);
+      expect(restored.sidebarExpanded).toBe(true);
+      expect(restored.windowSize).toEqual({ cols: 100, rows: 40 });
+      expect(restored.lastData).toBe(12345);
+    }
+  });
+
+  it("preserves sidebarExpanded=false", async () => {
+    await saveSession("workers", false, { cols: 80, rows: 24 }, 0);
+    const restored = await restoreSession();
+    expect(restored.sidebarExpanded).toBe(false);
+    expect(restored.activeView).toBe("workers");
+  });
+
+  it("falls back to dashboard for unknown view IDs", async () => {
+    await mkdir(join(tempRoot, ".tui-state"), { recursive: true });
+    await writeFile(
+      sessionPath(),
+      JSON.stringify({
+        activeView: "not-a-real-view",
+        sidebarExpanded: true,
+        windowSize: { cols: 80, rows: 24 },
+        lastData: 0,
+        savedAt: new Date().toISOString(),
+      }),
+      "utf8"
+    );
+    const restored = await restoreSession();
+    expect(restored.activeView).toBe("dashboard");
+  });
+
+  it("restores chord views (kv, secrets, ai-chat, db-query, edge, worker-settings)", async () => {
+    const chordViews: ViewId[] = [
+      "kv-viewer",
+      "secrets-viewer",
+      "ai-chat",
+      "db-query",
+      "edge-topology",
+      "worker-settings",
+    ];
+    for (const view of chordViews) {
+      await saveSession(view, true, { cols: 80, rows: 24 }, 1);
+      expect((await restoreSession()).activeView).toBe(view);
+    }
+  });
+
+  it("returns defaults on corrupt JSON", async () => {
+    await mkdir(join(tempRoot, ".tui-state"), { recursive: true });
+    await writeFile(sessionPath(), "{not-json!!!", "utf8");
+    const restored = await restoreSession();
+    expect(restored.activeView).toBe("dashboard");
+    expect(restored.sidebarExpanded).toBe(true);
+  });
+
+  it("saveSession writes readable session.json under .tui-state", async () => {
+    await saveSession("queue-depth", true, { cols: 120, rows: 36 }, 99);
+    const raw = await readFile(sessionPath(), "utf8");
+    const parsed = JSON.parse(raw) as { activeView: string; lastData: number };
+    expect(parsed.activeView).toBe("queue-depth");
+    expect(parsed.lastData).toBe(99);
+  });
+});

package/src/stores/ui-store.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * UI Store Tests — Navigation, sidebar, modals, command palette.
+ *
+ * Tests Zustand store actions in isolation (no rendering).
+ * Uses Bun test runner.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { useUIStore } from "@hoox-sh/hoox-shared/stores/ui-store";
+import type { ViewId, ModalState } from "@hoox-sh/hoox-shared";
+import { ALL_VIEW_IDS } from "../test-utils";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Reset store to initial state before each test */
+function resetStore() {
+  useUIStore.setState({
+    activeView: "dashboard",
+    sidebarExpanded: true,
+    modal: null,
+    commandPaletteOpen: false,
+    previousView: null,
+  });
+}
+
+// ─── Test Suite ───────────────────────────────────────────────────────────────
+
+describe("useUIStore", () => {
+  beforeEach(() => {
+    resetStore();
+  });
+
+  // ── setView ──────────────────────────────────────────────────────────────
+
+  describe("setView", () => {
+    it("sets the active view", () => {
+      useUIStore.getState().setView("workers");
+      expect(useUIStore.getState().activeView).toBe("workers");
+    });
+
+    it("accepts all valid view IDs (16)", () => {
+      expect(ALL_VIEW_IDS).toHaveLength(16);
+      for (const view of ALL_VIEW_IDS) {
+        useUIStore.getState().setView(view);
+        expect(useUIStore.getState().activeView).toBe(view);
+      }
+    });
+
+    it("tracks previous view when navigating to a different view", () => {
+      useUIStore.getState().setView("workers");
+      expect(useUIStore.getState().previousView).toBe("dashboard");
+    });
+
+    it("does not overwrite previousView when setting same view", () => {
+      useUIStore.getState().setView("dashboard"); // already on dashboard
+      expect(useUIStore.getState().previousView).toBeNull();
+    });
+
+    it("closes command palette when switching views", () => {
+      useUIStore.getState().openPalette();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(true);
+
+      useUIStore.getState().setView("settings");
+      expect(useUIStore.getState().commandPaletteOpen).toBe(false);
+    });
+
+    it("preserves previousView through multiple navigations", () => {
+      useUIStore.getState().setView("workers");
+      useUIStore.getState().setView("trade-monitor");
+      expect(useUIStore.getState().previousView).toBe("workers");
+      expect(useUIStore.getState().activeView).toBe("trade-monitor");
+    });
+  });
+
+  // ── toggleSidebar ─────────────────────────────────────────────────────────
+
+  describe("toggleSidebar", () => {
+    it("toggles sidebar from expanded to collapsed", () => {
+      expect(useUIStore.getState().sidebarExpanded).toBe(true);
+      useUIStore.getState().toggleSidebar();
+      expect(useUIStore.getState().sidebarExpanded).toBe(false);
+    });
+
+    it("toggles sidebar from collapsed to expanded", () => {
+      useUIStore.getState().toggleSidebar(); // collapse
+      useUIStore.getState().toggleSidebar(); // expand
+      expect(useUIStore.getState().sidebarExpanded).toBe(true);
+    });
+
+    it("handles multiple toggles correctly", () => {
+      for (let i = 0; i < 5; i++) {
+        useUIStore.getState().toggleSidebar();
+      }
+      expect(useUIStore.getState().sidebarExpanded).toBe(false); // 5 toggles from true = false
+    });
+
+    it("does not affect other UI state", () => {
+      const before = { ...useUIStore.getState() };
+      useUIStore.getState().toggleSidebar();
+      const after = useUIStore.getState();
+      expect(after.activeView).toBe(before.activeView);
+      expect(after.commandPaletteOpen).toBe(before.commandPaletteOpen);
+      expect(after.modal).toBe(before.modal);
+    });
+  });
+
+  // ── openPalette / closePalette ────────────────────────────────────────────
+
+  describe("command palette", () => {
+    it("opens the command palette", () => {
+      useUIStore.getState().openPalette();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(true);
+    });
+
+    it("closes the command palette", () => {
+      useUIStore.getState().openPalette();
+      useUIStore.getState().closePalette();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(false);
+    });
+
+    it("closePalette is idempotent when already closed", () => {
+      useUIStore.getState().closePalette();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(false);
+    });
+
+    it("openPalette is idempotent when already open", () => {
+      useUIStore.getState().openPalette();
+      useUIStore.getState().openPalette();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(true);
+    });
+
+    it("palette state is independent of sidebar state", () => {
+      useUIStore.getState().openPalette();
+      useUIStore.getState().toggleSidebar();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(true);
+      expect(useUIStore.getState().sidebarExpanded).toBe(false);
+    });
+  });
+
+  // ── showModal / dismissModal ──────────────────────────────────────────────
+
+  describe("modal lifecycle", () => {
+    it("sets modal state when showing a modal", () => {
+      const modal: ModalState = {
+        type: "confirm",
+        title: "Delete Worker",
+        message: "Are you sure?",
+      };
+      useUIStore.getState().showModal(modal);
+      expect(useUIStore.getState().modal).toEqual(modal);
+    });
+
+    it("dismisses modal by setting it to null", () => {
+      const modal: ModalState = {
+        type: "alert",
+        title: "Error",
+        message: "Something went wrong",
+      };
+      useUIStore.getState().showModal(modal);
+      useUIStore.getState().dismissModal();
+      expect(useUIStore.getState().modal).toBeNull();
+    });
+
+    it("dismissModal is idempotent when no modal is shown", () => {
+      useUIStore.getState().dismissModal();
+      expect(useUIStore.getState().modal).toBeNull();
+    });
+
+    it("shows alert type modals", () => {
+      const modal: ModalState = {
+        type: "alert",
+        title: "Warning",
+        message: "Disk space low",
+      };
+      useUIStore.getState().showModal(modal);
+      expect(useUIStore.getState().modal?.type).toBe("alert");
+    });
+
+    it("shows prompt type modals", () => {
+      const modal: ModalState = {
+        type: "prompt",
+        title: "Rename",
+        message: "Enter new name",
+      };
+      useUIStore.getState().showModal(modal);
+      expect(useUIStore.getState().modal?.type).toBe("prompt");
+    });
+
+    it("shows custom type modals with data", () => {
+      const modal: ModalState = {
+        type: "custom",
+        title: "Advanced",
+        message: "Custom dialog",
+        data: { key: "value" },
+      };
+      useUIStore.getState().showModal(modal);
+      expect(useUIStore.getState().modal?.data).toEqual({ key: "value" });
+    });
+
+    it("replaces existing modal when showing a new one", () => {
+      useUIStore.getState().showModal({ type: "alert", title: "First" });
+      useUIStore.getState().showModal({ type: "confirm", title: "Second" });
+      expect(useUIStore.getState().modal?.title).toBe("Second");
+    });
+  });
+
+  // ── goBack ────────────────────────────────────────────────────────────────
+
+  describe("goBack", () => {
+    it("navigates back to the previous view", () => {
+      useUIStore.getState().setView("workers");
+      useUIStore.getState().setView("trade-monitor");
+      // Now on trade-monitor, previousView = workers
+
+      useUIStore.getState().goBack();
+      expect(useUIStore.getState().activeView).toBe("workers");
+      expect(useUIStore.getState().previousView).toBeNull();
+    });
+
+    it("does nothing when there is no previous view", () => {
+      expect(useUIStore.getState().previousView).toBeNull();
+      useUIStore.getState().goBack();
+      expect(useUIStore.getState().activeView).toBe("dashboard");
+    });
+
+    it("only goes back one level", () => {
+      useUIStore.getState().setView("workers"); // prev = dashboard
+      useUIStore.getState().setView("trade-monitor"); // prev = workers
+      useUIStore.getState().setView("settings"); // prev = trade-monitor
+
+      useUIStore.getState().goBack();
+      expect(useUIStore.getState().activeView).toBe("trade-monitor");
+    });
+
+    it("clears previousView after going back", () => {
+      useUIStore.getState().setView("settings");
+      useUIStore.getState().goBack();
+      useUIStore.getState().goBack();
+      // Second goBack should be a no-op since previousView is null
+      expect(useUIStore.getState().activeView).toBe("dashboard");
+    });
+  });
+
+  // ── Initial State ─────────────────────────────────────────────────────────
+
+  describe("initial state", () => {
+    it("starts on dashboard view", () => {
+      resetStore();
+      expect(useUIStore.getState().activeView).toBe("dashboard");
+    });
+
+    it("starts with sidebar expanded", () => {
+      resetStore();
+      expect(useUIStore.getState().sidebarExpanded).toBe(true);
+    });
+
+    it("starts with no modal", () => {
+      resetStore();
+      expect(useUIStore.getState().modal).toBeNull();
+    });
+
+    it("starts with command palette closed", () => {
+      resetStore();
+      expect(useUIStore.getState().commandPaletteOpen).toBe(false);
+    });
+
+    it("starts with no previous view", () => {
+      resetStore();
+      expect(useUIStore.getState().previousView).toBeNull();
+    });
+  });
+});

package/src/test-setup.ts

@@ -0,0 +1,265 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Test setup / preload for TUI package.
+ *
+ * Pre-loads @opentui/core so its top-level await resolves BEFORE any test
+ * code runs. This prevents the Temporal Dead Zone (TDZ) race condition
+ * that causes:
+ *   "Cannot access 'FFIRenderLib' before initialization"
+ *
+ * OpenTUI's bundled index-ysvpktsp.js has:
+ *   line 12404: await import(`@opentui/core-${platform}-${arch}`)
+ *   line 13725: class FFIRenderLib { ... }      // AFTER the await
+ *   line 15202: function resolveRenderLib() { ... }
+ *
+ * If resolveRenderLib() is called while the module is still suspended by
+ * the top-level await, FFIRenderLib is in the TDZ → ReferenceError.
+ *
+ * This preload ensures the module finishes evaluating before any test
+ * imports trigger resolveRenderLib. It also wraps createTestRenderer with
+ * error handling for environments where the native library is absent.
+ */
+
+// yoga-layout (dep of @opentui/core) uses fetch() to load its WASM binary.
+// Must be set BEFORE @opentui/core is imported below.
+global.fetch = fetch;
+
+import { mock } from "bun:test";
+
+// ── Module-level state ────────────────────────────────────────────────────────
+
+type CoreTestingModule = typeof import("@opentui/core/testing");
+type CreateTestRendererFn = CoreTestingModule["createTestRenderer"];
+let realCreateTestRenderer: CreateTestRendererFn | null = null;
+let coreAvailable = false;
+
+// ── Load real module (pre-resolves the top-level await) ────────────────────────
+
+try {
+  // 1. Load @opentui/core first — this triggers its top-level await
+  //    which loads the platform-specific native library package.
+  //    If the native library is present, the await resolves quickly and
+  //    the module finishes evaluating (FFIRenderLib becomes defined).
+  await import("@opentui/core");
+
+  // 2. Now load the testing module and capture its createTestRenderer
+  const coreTesting = await import("@opentui/core/testing");
+  realCreateTestRenderer = coreTesting.createTestRenderer;
+  coreAvailable = true;
+} catch {
+  // Core not available — tests that require rendering will get a clear error
+  coreAvailable = false;
+}
+
+// ── Mock @opentui/core/testing ─────────────────────────────────────────────────
+//
+// This mock intercepts all imports of @opentui/core/testing so that:
+//   - If the real module loaded successfully → uses real createTestRenderer
+//     (with error-wrapping for defensive handling)
+//   - If the real module failed → provides a mock that throws a clear
+//     error message about the missing native library
+//   - The Temporal Dead Zone race condition is avoided because we've
+//     already pre-loaded @opentui/core above
+
+mock.module("@opentui/core/testing", () => {
+  if (coreAvailable && realCreateTestRenderer) {
+    return {
+      // Spread any other exports from the real module (setRendererCapabilities,
+      // createTerminalCapabilities, MockTreeSitterClient, etc.)
+      ...shareTestingExports(),
+
+      // Wrap createTestRenderer with defensive error handling
+      createTestRenderer: async (...args: Parameters<CreateTestRendererFn>) => {
+        try {
+          return await realCreateTestRenderer!(...args);
+        } catch (cause) {
+          throw new Error(
+            `OpenTUI render library initialization failed: ${
+              cause instanceof Error ? cause.message : String(cause)
+            }. ` +
+              "Ensure @opentui/core native library is installed for your platform.",
+            { cause }
+          );
+        }
+      },
+    };
+  }
+
+  // Fallback: native library not available → provide a mock that throws
+  // a clear, actionable error (instead of the confusing TDZ ReferenceError)
+  return {
+    createTestRenderer: async (..._args: Parameters<CreateTestRendererFn>) => {
+      throw new Error(
+        "OpenTUI native render library is not available in this environment. " +
+          "Render-dependent tests cannot run. " +
+          "Install @opentui/core native library for your platform, " +
+          "or run tests on a supported platform (linux-x64, darwin-arm64, etc.)."
+      );
+    },
+
+    setRendererCapabilities: () => {},
+    createTerminalCapabilities: (overrides = {}) => overrides,
+    createSpy: () => ({
+      calls: [],
+      callCount: () => 0,
+      calledWith: () => false,
+      reset: () => {},
+    }),
+    MockTreeSitterClient: class {},
+    KeyCodes: {},
+    MouseButtons: {},
+    pasteBytes: (_s: string) => new Uint8Array(),
+    createMockKeys: () => ({}),
+    createMockMouse: () => ({}),
+    TestRecorder: class {},
+  };
+});
+
+// ── Mock helper exports ─────────────────────────────────────────────────────────
+
+/** Re-export testing utilities from the real module for convenience. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function shareTestingExports(): Record<string, any> {
+  return {
+    setRendererCapabilities: () => {},
+    createTerminalCapabilities: (o: Record<string, unknown> = {}) => o,
+    createSpy: () => ({
+      calls: [],
+      callCount: () => 0,
+      calledWith: () => false,
+      reset: () => {},
+    }),
+    MockTreeSitterClient: class {},
+    KeyCodes: {},
+    MouseButtons: {},
+    pasteBytes: (_s: string) => new Uint8Array(),
+    createMockKeys: () => ({}),
+    createMockMouse: () => ({}),
+    TestRecorder: class {},
+  };
+}
+
+// Prevent tests from accidentally spawning real wrangler, hoox CLI, or
+// other heavy processes during unit/integration runs. Set
+// HOOX_TEST_ALLOW_WRANGLER=1 to allow the real spawn during live testing.
+import { installSpawnShim } from "@hoox/test-utils/spawn-shim";
+installSpawnShim();
+
+// ── Shared CLI bridge test double (process-wide, full surface) ───────────────
+//
+// Install ONE complete mock of `cli-bridge` here so individual test files do
+// not each call mock.module with partial stubs (which strip methods other
+// suites need under Bun's process-wide module mock).
+//
+// Per-test overrides: import { cliBridgeDouble, resetCliBridgeDouble } from
+// "./cli-bridge-test-double" and use mockResolvedValue / mockImplementation.
+import {
+  cliBridgeDouble,
+  createCliBridgeModuleMock,
+} from "./cli-bridge-test-double";
+
+const cliBridgeModule = await createCliBridgeModuleMock();
+
+/** Register under every import specifier used across the suite. */
+function installCliBridgeDouble(): void {
+  const paths = [
+    // Absolute file URL (Bun resolves relative imports to this)
+    new URL("./services/cli-bridge/index.ts", import.meta.url).href,
+    new URL("./services/cli-bridge/", import.meta.url).href,
+    // Relative from this preload file
+    "./services/cli-bridge",
+    "./services/cli-bridge/index.ts",
+    // Relative paths used by view tests under components/views/
+    "../../services/cli-bridge",
+    // Relative paths used by store tests
+    "../services/cli-bridge",
+  ];
+  for (const p of paths) {
+    try {
+      mock.module(p, () => cliBridgeModule);
+    } catch {
+      // Specifier may be invalid in some environments — ignore
+    }
+  }
+}
+
+installCliBridgeDouble();
+
+// Expose for tests that need the double without importing the helper path
+(
+  globalThis as unknown as { __hooxCliBridgeDouble?: typeof cliBridgeDouble }
+).__hooxCliBridgeDouble = cliBridgeDouble;
+
+// ── Shared network doubles (api-client + SSE) ────────────────────────────────
+//
+// service-store (and views that call fetchWorkers / stream*) must not hit a
+// real HTTP API in unit tests. One full mock here replaces per-file
+// mock.module of api-client / sse.
+import {
+  hooxFetchMock,
+  subscribeSSEMock,
+  resetNetworkDoubles,
+} from "./network-test-double";
+
+resetNetworkDoubles();
+
+async function installNetworkDoubles(): Promise<void> {
+  let realApi: Record<string, unknown> = {};
+  try {
+    realApi = (await import("@hoox-sh/hoox-shared/api-client")) as Record<
+      string,
+      unknown
+    >;
+  } catch {
+    realApi = {};
+  }
+
+  const apiFactory = () => ({
+    ...realApi,
+    hooxFetch: hooxFetchMock,
+  });
+
+  const sseFactory = () => ({
+    subscribeSSE: subscribeSSEMock,
+  });
+
+  // From packages/tui/src → ../../shared/src (sibling package)
+  const apiPaths = [
+    new URL("../../shared/src/api-client.ts", import.meta.url).href,
+    new URL("../../shared/src/api-client.ts", import.meta.url).pathname,
+    "@hoox-sh/hoox-shared/api-client",
+    // Relative as resolved from packages/shared/src/stores/service-store.ts
+    "../api-client",
+    "../api-client.ts",
+    "../../../../packages/shared/src/api-client",
+  ];
+  const ssePaths = [
+    new URL("../../shared/src/sse.ts", import.meta.url).href,
+    new URL("../../shared/src/sse.ts", import.meta.url).pathname,
+    "@hoox-sh/hoox-shared/sse",
+    "../sse",
+    "../sse.ts",
+    "../../../../packages/shared/src/sse",
+  ];
+
+  for (const p of apiPaths) {
+    try {
+      mock.module(p, apiFactory);
+    } catch {
+      // ignore bad specifier
+    }
+  }
+  for (const p of ssePaths) {
+    try {
+      mock.module(p, sseFactory);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+await installNetworkDoubles();