@nexus-ai-fs/tui 0.9.18

package/src/shared/components/brick-gate.tsx

@@ -0,0 +1,60 @@
+/**
+ * Gate component that shows children only when required brick(s) are enabled.
+ *
+ * When the brick is disabled, shows a standardized "not available" message
+ * with profile info and mount guidance (Decision 7A).
+ */
+
+import React from "react";
+import { useBrickAvailable, useAnyBrickAvailable } from "../hooks/use-brick-available.js";
+import { useGlobalStore } from "../../stores/global-store.js";
+import { Spinner } from "./spinner.js";
+import { textStyle } from "../text-style.js";
+
+interface BrickGateProps {
+  /** Brick name or array of brick names (any-of semantics). */
+  readonly brick: string | readonly string[];
+  /** Content to render when the brick is available. */
+  readonly children: React.ReactNode;
+  /** Custom fallback. Defaults to BrickUnavailable message. */
+  readonly fallback?: React.ReactNode;
+}
+
+function BrickUnavailableMessage({ names }: { names: readonly string[] }): React.ReactNode {
+  const profile = useGlobalStore((s) => s.profile);
+  const brickList = names.join(", ");
+
+  return (
+    <box height="100%" width="100%" justifyContent="center" alignItems="center" flexDirection="column">
+      <text>{`Feature not available`}</text>
+      <text> </text>
+      <text style={textStyle({ dim: true })}>{`Required brick${names.length > 1 ? "s" : ""}: ${brickList}`}</text>
+      {profile && <text style={textStyle({ dim: true })}>{`Current profile: ${profile}`}</text>}
+      <text> </text>
+      <text style={textStyle({ dim: true })}>{`To enable: mount the brick via Zones > Bricks`}</text>
+    </box>
+  );
+}
+
+export function BrickGate({ brick, children, fallback }: BrickGateProps): React.ReactNode {
+  const bricks = Array.isArray(brick) ? brick : [brick];
+
+  // Use the appropriate hook based on single vs multiple bricks
+  const { available, loading } = bricks.length === 1
+    ? useBrickAvailable(bricks[0])
+    : useAnyBrickAvailable(bricks);
+
+  if (loading) {
+    return (
+      <box height="100%" width="100%" justifyContent="center" alignItems="center">
+        <Spinner label="Loading features..." />
+      </box>
+    );
+  }
+
+  if (!available) {
+    return fallback ?? <BrickUnavailableMessage names={bricks} />;
+  }
+
+  return <>{children}</>;
+}

package/src/shared/components/command-output.tsx

@@ -0,0 +1,95 @@
+/**
+ * CommandOutput — renders streaming output from local nexus CLI commands.
+ *
+ * Uses StyledText for ANSI rendering and the CommandRunnerStore for state.
+ * Shows a spinner while running (Decision 15A).
+ */
+
+import React from "react";
+import { useCommandRunnerStore } from "../../services/command-runner.js";
+import { StyledText } from "./styled-text.js";
+import { Spinner } from "./spinner.js";
+import { statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+const ERROR_HINTS: ReadonlyArray<{ pattern: RegExp; hint: string }> = [
+  { pattern: /authentication required|unauthorized|401/i, hint: "Check your API key (NEXUS_API_KEY or nexus.yaml api_key)" },
+  { pattern: /connection refused/i, hint: "Is the server running? Try Shift+U to start it" },
+  { pattern: /grpc.*unavailable|failed to connect/i, hint: "gRPC endpoint unreachable — check server logs" },
+  { pattern: /timed? ?out|deadline exceeded/i, hint: "Request timed out — the server may be overloaded" },
+  { pattern: /address already in use|EADDRINUSE/i, hint: "Port is already in use — stop the existing process or change ports" },
+  { pattern: /permission denied|EACCES/i, hint: "Permission denied — check file/directory permissions" },
+  { pattern: /no such file|ENOENT|not found/i, hint: "File or command not found — check paths and installation" },
+];
+
+function findErrorHint(lines: readonly string[]): string | null {
+  const tail = lines.slice(-20);
+  for (const line of tail) {
+    for (const { pattern, hint } of ERROR_HINTS) {
+      if (pattern.test(line)) return hint;
+    }
+  }
+  return null;
+}
+
+export function CommandOutput(): React.ReactNode {
+  const status = useCommandRunnerStore((s) => s.status);
+  const outputLines = useCommandRunnerStore((s) => s.outputLines);
+  const commandLabel = useCommandRunnerStore((s) => s.commandLabel);
+  const exitCode = useCommandRunnerStore((s) => s.exitCode);
+  const spawnError = useCommandRunnerStore((s) => s.spawnError);
+
+  if (status === "idle") {
+    return null;
+  }
+
+  const output = outputLines.join("\n");
+
+  return (
+    <box flexDirection="column" width="100%">
+      {/* Header */}
+      <box height={1} width="100%">
+        <text>
+          <span style={textStyle({ dim: true })}>{"$ "}</span>
+          <span style={textStyle({ bold: true })}>{commandLabel}</span>
+        </text>
+      </box>
+
+      {/* Output */}
+      {output ? (
+        <box width="100%">
+          <StyledText>{output}</StyledText>
+        </box>
+      ) : status === "running" ? (
+        <Spinner label="Running..." />
+      ) : null}
+
+      {/* Spawn error */}
+      {spawnError && (
+        <box height={1} width="100%">
+          <text style={textStyle({ fg: statusColor.error })}>{"Error: "}{spawnError}</text>
+        </box>
+      )}
+
+      {/* Status footer */}
+      {status === "success" && (
+        <box height={1} width="100%">
+          <text style={textStyle({ fg: statusColor.success })}>{"Command completed successfully"}</text>
+        </box>
+      )}
+      {status === "error" && exitCode !== null && (
+        <box height={1} width="100%">
+          <text style={textStyle({ fg: statusColor.error })}>{`Command failed with exit code ${exitCode}`}</text>
+        </box>
+      )}
+      {status === "error" && (() => {
+        const hint = findErrorHint(outputLines);
+        return hint ? (
+          <box height={1} width="100%">
+            <text style={textStyle({ fg: statusColor.warning })}>{`  Hint: ${hint}`}</text>
+          </box>
+        ) : null;
+      })()}
+    </box>
+  );
+}

package/src/shared/components/command-palette.tsx

@@ -0,0 +1,97 @@
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import { statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+import {
+  filterCommandPaletteItems,
+  type CommandPaletteItem,
+} from "../command-palette.js";
+
+interface CommandPaletteProps {
+  readonly visible: boolean;
+  readonly commands: readonly CommandPaletteItem[];
+  readonly onClose: () => void;
+}
+
+export function CommandPalette({
+  visible,
+  commands,
+  onClose,
+}: CommandPaletteProps): React.ReactNode {
+  const [query, setQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useEffect(() => {
+    if (!visible) {
+      setQuery("");
+      setSelectedIndex(0);
+    }
+  }, [visible]);
+
+  const filtered = useMemo(
+    () => filterCommandPaletteItems(commands, query),
+    [commands, query],
+  );
+
+  useEffect(() => {
+    setSelectedIndex((prev) => Math.min(prev, Math.max(filtered.length - 1, 0)));
+  }, [filtered.length]);
+
+  const executeSelected = useCallback(() => {
+    const selected = filtered[selectedIndex];
+    if (!selected) return;
+    selected.run();
+    onClose();
+  }, [filtered, selectedIndex, onClose]);
+
+  useKeyboard(
+    visible
+      ? {
+          escape: onClose,
+          return: executeSelected,
+          down: () => setSelectedIndex((prev) => Math.min(prev + 1, Math.max(filtered.length - 1, 0))),
+          up: () => setSelectedIndex((prev) => Math.max(prev - 1, 0)),
+          j: () => setSelectedIndex((prev) => Math.min(prev + 1, Math.max(filtered.length - 1, 0))),
+          k: () => setSelectedIndex((prev) => Math.max(prev - 1, 0)),
+          backspace: () => setQuery((prev) => prev.slice(0, -1)),
+        }
+      : {},
+    visible
+      ? (key) => {
+          if (key.length === 1) {
+            setQuery((prev) => prev + key);
+          } else if (key === "space") {
+            setQuery((prev) => prev + " ");
+          }
+        }
+      : undefined,
+  );
+
+  if (!visible) return null;
+
+  return (
+    <box height="100%" width="100%" justifyContent="center" alignItems="flex-start">
+      <box flexDirection="column" borderStyle="double" width={72} padding={1} marginTop={2}>
+        <text style={textStyle({ bold: true })}>Command Palette</text>
+        <text style={textStyle({ fg: statusColor.info })}>{`> ${query}${query.length >= 0 ? "\u2588" : ""}`}</text>
+        <text style={textStyle({ dim: true })}>Type to filter. Enter runs. Esc closes.</text>
+        <text>{""}</text>
+
+        {filtered.length === 0 ? (
+          <text style={textStyle({ dim: true })}>No matching commands</text>
+        ) : (
+          filtered.slice(0, 10).map((command, index) => {
+            const selected = index === selectedIndex;
+            return (
+              <box key={command.id} height={1} width="100%">
+                <text style={selected ? textStyle({ inverse: true }) : undefined}>
+                  {`${selected ? "> " : "  "}${command.section.padEnd(8)} ${command.title}${command.hint ? `  [${command.hint}]` : ""}`}
+                </text>
+              </box>
+            );
+          })
+        )}
+      </box>
+    </box>
+  );
+}

package/src/shared/components/confirm-dialog.tsx

@@ -0,0 +1,61 @@
+/**
+ * Reusable confirmation dialog for destructive actions.
+ *
+ * Renders a centered modal overlay with a message and Y/N keybindings.
+ * Follows the same overlay pattern as IdentitySwitcher.
+ */
+
+import React from "react";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+
+interface ConfirmDialogProps {
+  readonly visible: boolean;
+  readonly title: string;
+  readonly message: string;
+  readonly onConfirm: () => void;
+  readonly onCancel: () => void;
+}
+
+export function ConfirmDialog({
+  visible,
+  title,
+  message,
+  onConfirm,
+  onCancel,
+}: ConfirmDialogProps): React.ReactNode {
+  useKeyboard(
+    visible
+      ? {
+          y: onConfirm,
+          return: onConfirm,
+          n: onCancel,
+          escape: onCancel,
+        }
+      : {},
+  );
+
+  if (!visible) return null;
+
+  return (
+    <box
+      height="100%"
+      width="100%"
+      justifyContent="center"
+      alignItems="center"
+    >
+      <box
+        flexDirection="column"
+        borderStyle="double"
+        width={50}
+        height={7}
+        padding={1}
+      >
+        <text>{title}</text>
+        <text>{""}</text>
+        <text>{message}</text>
+        <text>{""}</text>
+        <text>{"Y:confirm  N/Esc:cancel"}</text>
+      </box>
+    </box>
+  );
+}

package/src/shared/components/diff-viewer.tsx

@@ -0,0 +1,219 @@
+/**
+ * Reusable diff viewer component.
+ *
+ * Generates a unified diff from oldText/newText and renders it
+ * using OpenTUI's built-in <diff> component for syntax-highlighted,
+ * scrollable diff display.
+ */
+
+import React from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface DiffViewerProps {
+  readonly oldText: string;
+  readonly newText: string;
+  readonly oldLabel?: string;
+  readonly newLabel?: string;
+  readonly view?: "unified" | "split";
+}
+
+// =============================================================================
+// Minimal unified diff generator
+// =============================================================================
+
+/**
+ * Produce a unified diff string from two texts.
+ *
+ * Uses a simple LCS-based line diff (O(n*m) but fine for typical file sizes
+ * viewed in a TUI). Output follows the standard unified diff format that
+ * OpenTUI's DiffRenderable can parse.
+ */
+function generateUnifiedDiff(
+  oldText: string,
+  newText: string,
+  oldLabel: string,
+  newLabel: string,
+): string {
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+
+  // Build LCS table
+  const m = oldLines.length;
+  const n = newLines.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    new Array<number>(n + 1).fill(0),
+  );
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (oldLines[i - 1] === newLines[j - 1]) {
+        dp[i]![j] = dp[i - 1]![j - 1]! + 1;
+      } else {
+        dp[i]![j] = Math.max(dp[i - 1]![j]!, dp[i]![j - 1]!);
+      }
+    }
+  }
+
+  // Back-trace to produce edit operations
+  const ops: Array<{ type: "keep" | "remove" | "add"; line: string }> = [];
+  let i = m;
+  let j = n;
+
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+      ops.push({ type: "keep", line: oldLines[i - 1]! });
+      i--;
+      j--;
+    } else if (j > 0 && (i === 0 || dp[i]![j - 1]! >= dp[i - 1]![j]!)) {
+      ops.push({ type: "add", line: newLines[j - 1]! });
+      j--;
+    } else {
+      ops.push({ type: "remove", line: oldLines[i - 1]! });
+      i--;
+    }
+  }
+
+  ops.reverse();
+
+  // Group into hunks with 3-line context
+  const CONTEXT = 3;
+  const hunks: Array<{
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: string[];
+  }> = [];
+
+  let oldIdx = 0;
+  let newIdx = 0;
+
+  let opIdx = 0;
+  while (opIdx < ops.length) {
+    // Skip context-only regions until we find a change
+    if (ops[opIdx]!.type === "keep") {
+      oldIdx++;
+      newIdx++;
+      opIdx++;
+      continue;
+    }
+
+    // Start a new hunk with leading context
+    const contextStart = Math.max(0, opIdx - CONTEXT);
+    let hunkOldStart = oldIdx;
+    let hunkNewStart = newIdx;
+
+    // Rewind counters for leading context
+    let rewind = opIdx - contextStart;
+    hunkOldStart -= rewind;
+    hunkNewStart -= rewind;
+
+    const hunkLines: string[] = [];
+    let hunkOldCount = 0;
+    let hunkNewCount = 0;
+
+    // Add leading context
+    for (let c = contextStart; c < opIdx; c++) {
+      hunkLines.push(` ${ops[c]!.line}`);
+      hunkOldCount++;
+      hunkNewCount++;
+    }
+
+    // Add changes and trailing context
+    let trailingContext = 0;
+    while (opIdx < ops.length) {
+      const op = ops[opIdx]!;
+      if (op.type === "keep") {
+        trailingContext++;
+        hunkLines.push(` ${op.line}`);
+        hunkOldCount++;
+        hunkNewCount++;
+        if (trailingContext >= CONTEXT * 2) {
+          // Enough trailing context, end hunk
+          break;
+        }
+      } else {
+        // Reset trailing context counter on any change
+        trailingContext = 0;
+        if (op.type === "remove") {
+          hunkLines.push(`-${op.line}`);
+          hunkOldCount++;
+        } else {
+          hunkLines.push(`+${op.line}`);
+          hunkNewCount++;
+        }
+      }
+      opIdx++;
+    }
+
+    // Trim excess trailing context to CONTEXT lines
+    while (trailingContext > CONTEXT) {
+      hunkLines.pop();
+      hunkOldCount--;
+      hunkNewCount--;
+      trailingContext--;
+    }
+
+    hunks.push({
+      oldStart: hunkOldStart + 1,
+      oldCount: hunkOldCount,
+      newStart: hunkNewStart + 1,
+      newCount: hunkNewCount,
+      lines: hunkLines,
+    });
+
+    // Advance past remaining keep ops that were consumed
+    oldIdx = hunkOldStart + hunkOldCount;
+    newIdx = hunkNewStart + hunkNewCount;
+  }
+
+  if (hunks.length === 0) {
+    return "";
+  }
+
+  // Build unified diff output
+  const output: string[] = [
+    `--- ${oldLabel}`,
+    `+++ ${newLabel}`,
+  ];
+
+  for (const hunk of hunks) {
+    output.push(
+      `@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@`,
+    );
+    output.push(...hunk.lines);
+  }
+
+  return output.join("\n");
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function DiffViewer({
+  oldText,
+  newText,
+  oldLabel = "a",
+  newLabel = "b",
+  view = "unified",
+}: DiffViewerProps): React.ReactNode {
+  const diffString = generateUnifiedDiff(oldText, newText, oldLabel, newLabel);
+
+  if (diffString === "") {
+    return (
+      <box height="100%" width="100%">
+        <text>No differences found.</text>
+      </box>
+    );
+  }
+
+  return (
+    <scrollbox height="100%" width="100%">
+      <diff diff={diffString} view={view} showLineNumbers />
+    </scrollbox>
+  );
+}

package/src/shared/components/empty-state.tsx

@@ -0,0 +1,36 @@
+/**
+ * Consistent empty state component for panels with no data.
+ *
+ * Replaces generic "No X found" with actionable messages that tell
+ * users what to do next.
+ *
+ * @see Issue #3066, Phase E10
+ */
+
+import React from "react";
+import { statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+interface EmptyStateProps {
+  /** Primary message, e.g. "No transactions yet." */
+  readonly message: string;
+  /** Optional hint showing what to do, e.g. "Press n to begin one." */
+  readonly hint?: string;
+}
+
+export function EmptyState({ message, hint }: EmptyStateProps): React.ReactNode {
+  return (
+    <box
+      height="100%"
+      width="100%"
+      justifyContent="center"
+      alignItems="center"
+      flexDirection="column"
+    >
+      <text style={textStyle({ dim: true })}>{message}</text>
+      {hint && (
+        <text style={textStyle({ fg: statusColor.dim })}>{hint}</text>
+      )}
+    </box>
+  );
+}

package/src/shared/components/error-bar.tsx

@@ -0,0 +1,60 @@
+/**
+ * Centralized error display bar.
+ *
+ * Renders the most recent error from the error store above the status bar.
+ * Supports dismissal (any key) and retry (r key).
+ *
+ * @see Issue #3066 Architecture Decision 8A
+ */
+
+import React from "react";
+import { useErrorStore } from "../../stores/error-store.js";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+import { palette } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+const CATEGORY_HINTS: Record<string, string> = {
+  network: "Check connection. r:retry",
+  validation: "Check input values.",
+  server: "Server error. r:retry",
+};
+
+export function ErrorBar(): React.ReactNode {
+  const errors = useErrorStore((s) => s.errors);
+  const dismissError = useErrorStore((s) => s.dismissError);
+
+  const latest = errors.length > 0 ? errors[errors.length - 1]! : null;
+
+  useKeyboard(
+    latest
+      ? {
+          r: () => {
+            if (latest.retryAction) {
+              dismissError(latest.id);
+              latest.retryAction();
+            }
+          },
+          escape: () => {
+            if (latest.dismissable) dismissError(latest.id);
+          },
+        }
+      : {},
+  );
+
+  if (!latest) return null;
+
+  const hint = CATEGORY_HINTS[latest.category] ?? "";
+  const prefix = errors.length > 1 ? `(${errors.length}) ` : "";
+
+  return (
+    <box height={1} width="100%" flexDirection="row">
+      <text>
+        <span style={textStyle({ fg: palette.error, bold: true })}>{`${prefix}✗ ${latest.message}`}</span>
+        <span style={textStyle({ fg: palette.errorDim })}>{`  ${hint}`}</span>
+        {latest.dismissable ? (
+          <span style={textStyle({ fg: palette.faint })}>{"  Esc:dismiss"}</span>
+        ) : ""}
+      </text>
+    </box>
+  );
+}

package/src/shared/components/error-boundary.tsx

@@ -0,0 +1,53 @@
+/**
+ * React error boundary that renders a user-friendly error message
+ * instead of crashing the TUI.
+ */
+
+import React from "react";
+
+interface ErrorBoundaryProps {
+  readonly children: React.ReactNode;
+  readonly fallback?: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+  readonly error: Error | null;
+}
+
+class ErrorBoundaryClass extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  override render(): React.ReactNode {
+    if (this.state.error) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+      return (
+        <box flexDirection="column" padding={1}>
+          <text>Something went wrong:</text>
+          <text>{this.state.error.message}</text>
+        </box>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Function component wrapper for the class-based error boundary.
+ *
+ * OpenTUI v0.1.87 has a bug where JSX.ElementClass extends
+ * React.ComponentClass (constructor) instead of the instance type,
+ * preventing class components from being used directly as JSX elements.
+ * This wrapper sidesteps that issue.
+ */
+export function ErrorBoundary(props: ErrorBoundaryProps): React.ReactNode {
+  return React.createElement(ErrorBoundaryClass, props);
+}