@nexus-ai-fs/tui 0.9.18

package/src/panels/files/file-lineage.tsx

@@ -0,0 +1,163 @@
+/**
+ * Lineage sub-view for the Files panel.
+ * Shows upstream inputs, downstream dependents, and agent provenance.
+ * Issue #3417.
+ */
+
+import React, { useEffect } from "react";
+import crypto from "node:crypto";
+import type { FileItem } from "../../stores/files-store.js";
+import { useLineageStore } from "../../stores/lineage-store.js";
+import { useApi } from "../../shared/hooks/use-api.js";
+import { statusColor } from "../../shared/theme.js";
+
+interface FileLineageProps {
+  readonly item: FileItem | null;
+}
+
+function computeUrn(item: FileItem): string | null {
+  if (!item.path) return null;
+  const zone = item.zoneId || "default";
+  const pathHash = crypto
+    .createHash("sha256")
+    .update(item.path)
+    .digest("hex")
+    .slice(0, 32);
+  return `urn:nexus:file:${zone}:${pathHash}`;
+}
+
+function truncate(value: string, max: number = 20): string {
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+export function FileLineage({ item }: FileLineageProps): React.ReactNode {
+  const client = useApi();
+  const lineageCache = useLineageStore((s) => s.lineageCache);
+  const downstreamCache = useLineageStore((s) => s.downstreamCache);
+  const loading = useLineageStore((s) => s.loading);
+  const fetchLineage = useLineageStore((s) => s.fetchLineage);
+
+  const urn = item ? computeUrn(item) : null;
+
+  useEffect(() => {
+    if (client && urn && item?.path) {
+      fetchLineage(urn, item.path, client);
+    }
+  }, [client, urn, item?.path, fetchLineage]);
+
+  if (!item) {
+    return <text>No file selected</text>;
+  }
+
+  if (!urn) {
+    return <text>Cannot compute URN</text>;
+  }
+
+  if (loading && !lineageCache.has(urn)) {
+    return <text>Loading lineage...</text>;
+  }
+
+  const lineage = lineageCache.get(urn) ?? undefined;
+  const downstream = downstreamCache.get(urn) ?? [];
+  const hasLineage = lineage !== undefined && lineage !== null;
+  const hasDownstream = downstream.length > 0;
+
+  if (!hasLineage && !hasDownstream) {
+    return (
+      <box flexDirection="column" height="100%" width="100%">
+        <text>{"─── Lineage ───"}</text>
+        <text> </text>
+        <text>{"  No lineage recorded for this file."}</text>
+        <text> </text>
+        <text foregroundColor={statusColor.dim}>
+          {"  Agents declare lineage via scopes or"}
+        </text>
+        <text foregroundColor={statusColor.dim}>
+          {"  PUT /api/v2/lineage/{urn}"}
+        </text>
+      </box>
+    );
+  }
+
+  return (
+    <box flexDirection="column" height="100%" width="100%">
+      <text>{"─── Lineage ───"}</text>
+
+      {/* Producer info */}
+      {hasLineage && lineage && (
+        <>
+          <box height={1} width="100%">
+            <text>
+              <span foregroundColor={statusColor.dim}>{"Agent    "}</span>
+              <span foregroundColor={statusColor.identity}>{lineage.agent_id || "unknown"}</span>
+            </text>
+          </box>
+          <box height={1} width="100%">
+            <text>
+              <span foregroundColor={statusColor.dim}>{"Op       "}</span>
+              <span>{lineage.operation || "write"}</span>
+            </text>
+          </box>
+          {lineage.agent_generation != null && (
+            <box height={1} width="100%">
+              <text>
+                <span foregroundColor={statusColor.dim}>{"Gen      "}</span>
+                <span>{`#${lineage.agent_generation}`}</span>
+              </text>
+            </box>
+          )}
+          <text> </text>
+        </>
+      )}
+
+      {/* Upstream inputs */}
+      {hasLineage && lineage && lineage.upstream.length > 0 && (
+        <>
+          <text foregroundColor={statusColor.info}>
+            {`▸ Upstream (${lineage.upstream.length})${lineage.truncated ? " [truncated]" : ""}`}
+          </text>
+          {lineage.upstream.slice(0, 15).map((u, i) => (
+            <box key={`up-${i}`} height={1} width="100%">
+              <text>
+                <span foregroundColor={statusColor.reference}>{"  "}{truncate(u.path, 34)}</span>
+                <span foregroundColor={statusColor.dim}>{` v${u.version}`}</span>
+              </text>
+            </box>
+          ))}
+          {lineage.upstream.length > 15 && (
+            <text foregroundColor={statusColor.dim}>
+              {`  ... +${lineage.upstream.length - 15} more`}
+            </text>
+          )}
+          <text> </text>
+        </>
+      )}
+
+      {/* Downstream dependents */}
+      {hasDownstream && (
+        <>
+          <text foregroundColor={statusColor.info}>
+            {`▸ Downstream (${downstream.length})`}
+          </text>
+          {downstream.slice(0, 10).map((d, i) => (
+            <box key={`dn-${i}`} height={1} width="100%">
+              <text>
+                <span foregroundColor={statusColor.reference}>
+                  {"  "}{truncate(d.downstream_path || d.downstream_urn, 30)}
+                </span>
+                {d.agent_id && (
+                  <span foregroundColor={statusColor.dim}>{` by ${d.agent_id}`}</span>
+                )}
+              </text>
+            </box>
+          ))}
+          {downstream.length > 10 && (
+            <text foregroundColor={statusColor.dim}>
+              {`  ... +${downstream.length - 10} more`}
+            </text>
+          )}
+        </>
+      )}
+    </box>
+  );
+}

package/src/panels/files/file-list-item.tsx

@@ -0,0 +1,28 @@
+/**
+ * Single row in the file list: icon + name + size + modified date.
+ *
+ * Wrapped with React.memo — re-renders only when item or selected changes.
+ * @see Issue #3102, Decisions 4A + 5A
+ */
+
+import React from "react";
+import type { FileItem } from "../../stores/files-store.js";
+import { formatSize } from "../../shared/utils/format-size.js";
+
+interface FileListItemProps {
+  readonly item: FileItem;
+  readonly selected: boolean;
+}
+
+export const FileListItem = React.memo(function FileListItem({ item, selected }: FileListItemProps): React.ReactNode {
+  const icon = item.isDirectory ? "📁" : "📄";
+  const prefix = selected ? "▸ " : "  ";
+  const size = item.isDirectory ? "<DIR>" : formatSize(item.size);
+
+  return (
+    <box height={1} width="100%" flexDirection="row">
+      <text>{`${prefix}${icon} ${item.name}`}</text>
+      <text>{`  ${size}`}</text>
+    </box>
+  );
+});

package/src/panels/files/file-metadata.tsx

@@ -0,0 +1,62 @@
+/**
+ * File metadata sidebar displaying path, size, etag, version, owner, permissions, etc.
+ */
+
+import React from "react";
+import type { FileItem } from "../../stores/files-store.js";
+import { textStyle } from "../../shared/text-style.js";
+import { formatTimestamp } from "../../shared/utils/format-time.js";
+import { statusColor } from "../../shared/theme.js";
+
+interface FileMetadataProps {
+  readonly item: FileItem | null;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}
+
+function truncate(value: string | null | undefined, max: number = 30): string {
+  if (value === null || value === undefined) return "n/a";
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+function MetaRow({ label, value, color }: { label: string; value: string; color?: string }): React.ReactNode {
+  return (
+    <box height={1} width="100%">
+      <text>
+        <span style={textStyle({ fg: statusColor.dim })}>{`${label.padEnd(8)} `}</span>
+        <span style={color ? textStyle({ fg: color }) : undefined}>{value}</span>
+      </text>
+    </box>
+  );
+}
+
+export function FileMetadata({ item }: FileMetadataProps): React.ReactNode {
+  if (!item) {
+    return (
+      <box height="100%" width="100%">
+        <text>No file selected</text>
+      </box>
+    );
+  }
+
+  return (
+    <box height="100%" width="100%" flexDirection="column">
+      <MetaRow label="Name" value={item.name} color={statusColor.info} />
+      <MetaRow label="Path" value={truncate(item.path, 40)} color={statusColor.reference} />
+      <MetaRow label="Type" value={item.isDirectory ? "Directory" : "File"} />
+      {!item.isDirectory && <MetaRow label="Size" value={formatBytes(item.size)} />}
+      <MetaRow label="ETag" value={truncate(item.etag, 20)} />
+      <MetaRow label="Version" value={truncate(item.version != null ? String(item.version) : null)} />
+      <MetaRow label="MIME" value={truncate(item.mimeType)} />
+      <MetaRow label="Owner" value={truncate(item.owner)} />
+      <MetaRow label="Perms" value={truncate(item.permissions)} />
+      <MetaRow label="Zone" value={item.zoneId ?? "n/a"} color={item.zoneId ? statusColor.reference : undefined} />
+      <MetaRow label="Modified" value={item.modifiedAt ? formatTimestamp(item.modifiedAt) : "n/a"} />
+    </box>
+  );
+}

package/src/panels/files/file-preview.tsx

@@ -0,0 +1,108 @@
+/**
+ * File content preview panel with syntax highlighting.
+ */
+
+import React, { useEffect } from "react";
+import { useFilesStore } from "../../stores/files-store.js";
+import { useApi } from "../../shared/hooks/use-api.js";
+import { Spinner } from "../../shared/components/spinner.js";
+import { StyledText } from "../../shared/components/styled-text.js";
+import { textStyle } from "../../shared/text-style.js";
+import { defaultSyntaxStyle } from "../../shared/syntax-style.js";
+
+export function FilePreview(): React.ReactNode {
+  const client = useApi();
+  const previewPath = useFilesStore((s) => s.previewPath);
+  const previewContent = useFilesStore((s) => s.previewContent);
+  const previewLoading = useFilesStore((s) => s.previewLoading);
+  const previewError = useFilesStore((s) => s.error);
+  const fetchPreview = useFilesStore((s) => s.fetchPreview);
+
+  useEffect(() => {
+    if (client && previewPath) {
+      fetchPreview(previewPath, client);
+    }
+  }, [client, previewPath, fetchPreview]);
+
+  if (!previewPath) {
+    return (
+      <box height="100%" width="100%" justifyContent="center" alignItems="center">
+        <text>Select a file to preview</text>
+      </box>
+    );
+  }
+
+  if (previewLoading) {
+    return (
+      <box height="100%" width="100%" justifyContent="center" alignItems="center">
+        <Spinner label={`Loading ${previewPath}...`} />
+      </box>
+    );
+  }
+
+  if (previewContent === null) {
+    return (
+      <box height="100%" width="100%" flexDirection="column">
+        <text>Unable to load preview</text>
+        {previewError && (
+          <text style={textStyle({ dim: true })}>{previewError}</text>
+        )}
+      </box>
+    );
+  }
+
+  // Detect file extension for syntax highlighting
+  const ext = previewPath.split(".").pop()?.toLowerCase() ?? "";
+  const language = extensionToLanguage(ext);
+
+  // Files that may contain ANSI escape sequences get rendered with StyledText
+  const ansiExtensions = new Set(["log", "out", "err", "ans", "ansi"]);
+  const hasAnsi = ansiExtensions.has(ext) || previewContent.includes("\x1b[");
+
+  if (hasAnsi) {
+    return (
+      <scrollbox height="100%" width="100%">
+        <StyledText>{previewContent}</StyledText>
+      </scrollbox>
+    );
+  }
+
+  // Use OpenTUI's Code component for syntax highlighting
+  return (
+    <scrollbox height="100%" width="100%">
+      <code content={previewContent} filetype={language} syntaxStyle={defaultSyntaxStyle} />
+    </scrollbox>
+  );
+}
+
+function extensionToLanguage(ext: string): string {
+  const map: Record<string, string> = {
+    ts: "typescript",
+    tsx: "tsx",
+    js: "javascript",
+    jsx: "jsx",
+    py: "python",
+    rs: "rust",
+    go: "go",
+    rb: "ruby",
+    java: "java",
+    c: "c",
+    cpp: "cpp",
+    h: "c",
+    hpp: "cpp",
+    json: "json",
+    yaml: "yaml",
+    yml: "yaml",
+    toml: "toml",
+    md: "markdown",
+    sh: "bash",
+    bash: "bash",
+    zsh: "bash",
+    sql: "sql",
+    html: "html",
+    css: "css",
+    xml: "xml",
+    proto: "protobuf",
+  };
+  return map[ext] ?? "text";
+}

package/src/panels/files/file-schema.tsx

@@ -0,0 +1,89 @@
+/**
+ * Schema sub-view for the Files panel.
+ * Shows extracted column schema for CSV/JSON/Parquet files.
+ * Issue #2930.
+ */
+
+import React, { useEffect } from "react";
+import type { FileItem } from "../../stores/files-store.js";
+import { useKnowledgeStore } from "../../stores/knowledge-store.js";
+import { useApi } from "../../shared/hooks/use-api.js";
+
+interface FileSchemaProps {
+  readonly item: FileItem | null;
+}
+
+const DATA_EXTENSIONS = new Set([
+  "csv",
+  "tsv",
+  "json",
+  "jsonl",
+  "ndjson",
+  "parquet",
+  "pq",
+]);
+
+function isDataFile(item: FileItem): boolean {
+  if (item.isDirectory) return false;
+  const ext = item.name.split(".").pop()?.toLowerCase() ?? "";
+  return DATA_EXTENSIONS.has(ext);
+}
+
+export function FileSchema({ item }: FileSchemaProps): React.ReactNode {
+  const client = useApi();
+  const schemaCache = useKnowledgeStore((s) => s.schemaCache);
+  const loading = useKnowledgeStore((s) => s.schemaLoading);
+  const fetchSchema = useKnowledgeStore((s) => s.fetchSchema);
+
+  useEffect(() => {
+    if (client && item && isDataFile(item)) {
+      fetchSchema(item.path, client);
+    }
+  }, [client, item, fetchSchema]);
+
+  if (!item) {
+    return <text>No file selected</text>;
+  }
+
+  if (!isDataFile(item)) {
+    return (
+      <box flexDirection="column" height="100%" width="100%">
+        <text>{"─── Schema ───"}</text>
+        <text>{"Not a data file (CSV/JSON/Parquet)"}</text>
+      </box>
+    );
+  }
+
+  if (loading) {
+    return <text>Extracting schema...</text>;
+  }
+
+  const schema = schemaCache.get(item.path);
+
+  if (schema === undefined) {
+    return <text>{"Schema not loaded yet"}</text>;
+  }
+
+  if (schema === null) {
+    return (
+      <box flexDirection="column" height="100%" width="100%">
+        <text>{"─── Schema ───"}</text>
+        <text>{"No schema available"}</text>
+      </box>
+    );
+  }
+
+  return (
+    <box flexDirection="column" height="100%" width="100%">
+      <text>{`─── Schema (${schema.format}) ───`}</text>
+      <text>{`  Rows: ${schema.rowCount ?? "n/a"}  Confidence: ${(schema.confidence * 100).toFixed(0)}%`}</text>
+      <text> </text>
+      <text>{"  Column                Type         Nullable"}</text>
+      {schema.columns.map((col) => (
+        <text key={col.name}>
+          {`  ${col.name.padEnd(20)} ${col.type.padEnd(12)} ${col.nullable}`}
+        </text>
+      ))}
+    </box>
+  );
+}

package/src/panels/files/file-tree-node.tsx

@@ -0,0 +1,44 @@
+/**
+ * Single tree node row: indent + expand/collapse icon + file/folder icon + name + size.
+ *
+ * Wrapped with React.memo — re-renders only when node, selected, or marked changes.
+ * Shows selection checkmark for multi-select (Decision 3A).
+ * @see Issue #3102, Decisions 4A + 5A
+ */
+
+import React from "react";
+import type { TreeNode } from "../../stores/files-store.js";
+import { formatSize } from "../../shared/utils/format-size.js";
+
+interface FileTreeNodeProps {
+  readonly node: TreeNode;
+  readonly selected: boolean;
+  /** Whether this node is in the current multi-selection set. */
+  readonly marked: boolean;
+}
+
+export const FileTreeNode = React.memo(function FileTreeNode({ node, selected, marked }: FileTreeNodeProps): React.ReactNode {
+  const indent = "  ".repeat(node.depth);
+  const cursor = selected ? "▸ " : "  ";
+  const check = marked ? "✓ " : "  ";
+
+  let expandIcon = "  ";
+  if (node.isDirectory) {
+    if (node.loading) {
+      expandIcon = "⟳ ";
+    } else if (node.expanded) {
+      expandIcon = "▾ ";
+    } else {
+      expandIcon = "▸ ";
+    }
+  }
+
+  const fileIcon = node.isDirectory ? "📁" : "📄";
+  const sizeSuffix = !node.isDirectory && node.size > 0 ? ` (${formatSize(node.size)})` : "";
+
+  return (
+    <box height={1} width="100%">
+      <text>{`${cursor}${check}${indent}${expandIcon}${fileIcon} ${node.name}${sizeSuffix}`}</text>
+    </box>
+  );
+});

package/src/panels/files/file-tree.tsx

@@ -0,0 +1,169 @@
+/**
+ * Recursive file tree with lazy-expand for directories.
+ * Flattens the visible tree, then uses VirtualList for windowed rendering.
+ * Auto-loads more children when the user scrolls near the end of a paginated directory.
+ *
+ * Supports client-side fuzzy filtering (Decision 4A, 13A)
+ * and rendering multi-selection state (Decision 3A).
+ *
+ * @see Issue #3102, Decisions 1A (virtualization) + 4A (React.memo on children)
+ */
+
+import React, { useCallback, useEffect, useMemo } from "react";
+import { useFilesStore, type TreeNode } from "../../stores/files-store.js";
+import { useApi } from "../../shared/hooks/use-api.js";
+import { FileTreeNode } from "./file-tree-node.js";
+import { Spinner } from "../../shared/components/spinner.js";
+import { ScrollIndicator } from "../../shared/components/scroll-indicator.js";
+import { VirtualList } from "../../shared/components/virtual-list.js";
+
+const VIEWPORT_HEIGHT = 20;
+
+/** Sentinel value used to mark "load more" placeholder nodes in the flattened list. */
+export const LOAD_MORE_SENTINEL = "__load_more__";
+
+/** A synthetic TreeNode representing a "load more" placeholder. */
+export function makeLoadMoreNode(parentPath: string, depth: number, loading: boolean): TreeNode {
+  return {
+    path: `${parentPath}/${LOAD_MORE_SENTINEL}`,
+    name: loading ? "Loading more..." : "▼ Load more...",
+    isDirectory: false,
+    expanded: false,
+    children: [],
+    loading: false,
+    depth,
+    size: 0,
+    nextCursor: null,
+    hasMore: false,
+    loadingMore: false,
+  };
+}
+
+interface FileTreeProps {
+  /** Client-side fuzzy filter query. Empty string = no filter. */
+  readonly filterQuery?: string;
+  /** Set of currently selected file paths (for multi-select rendering). */
+  readonly effectiveSelection?: ReadonlySet<string>;
+}
+
+export function FileTree({ filterQuery = "", effectiveSelection }: FileTreeProps): React.ReactNode {
+  const client = useApi();
+  const treeNodes = useFilesStore((s) => s.treeNodes);
+  const currentPath = useFilesStore((s) => s.currentPath);
+  const selectedIndex = useFilesStore((s) => s.selectedIndex);
+  const expandNode = useFilesStore((s) => s.expandNode);
+  const loadMoreChildren = useFilesStore((s) => s.loadMoreChildren);
+
+  // Initialize root on mount
+  useEffect(() => {
+    if (client && !treeNodes.has(currentPath)) {
+      expandNode(currentPath, client);
+    }
+  }, [client, currentPath, treeNodes, expandNode]);
+
+  // Flatten visible tree nodes, then apply filter (Decision 13A).
+  // Inserts "load more" sentinel nodes at the end of paginated directories.
+  const visibleNodes = useMemo(() => {
+    const all = flattenVisibleNodes(currentPath, treeNodes);
+    if (!filterQuery) return all;
+    const lowerQuery = filterQuery.toLowerCase();
+    return all.filter((node) => fuzzyMatch(node.name.toLowerCase(), lowerQuery));
+  }, [currentPath, treeNodes, filterQuery]);
+
+  // Auto-load more: when the selected node is a "load more" sentinel, trigger fetch
+  useEffect(() => {
+    if (!client) return;
+    const selectedNode = visibleNodes[selectedIndex];
+    if (!selectedNode || !selectedNode.path.endsWith(LOAD_MORE_SENTINEL)) return;
+
+    // Extract the parent path from the sentinel node
+    const parentPath = selectedNode.path.slice(0, -(LOAD_MORE_SENTINEL.length + 1));
+    const parentNode = treeNodes.get(parentPath);
+    if (parentNode?.hasMore && !parentNode.loadingMore) {
+      loadMoreChildren(parentPath, client);
+    }
+  }, [client, selectedIndex, visibleNodes, treeNodes, loadMoreChildren]);
+
+  // Stable render callback for VirtualList (avoids inline closure per-render)
+  const renderNode = useCallback(
+    (node: TreeNode, index: number) => (
+      <FileTreeNode
+        key={node.path}
+        node={node}
+        selected={index === selectedIndex}
+        marked={effectiveSelection?.has(node.path) ?? false}
+      />
+    ),
+    [selectedIndex, effectiveSelection],
+  );
+
+  if (!client) {
+    return <text>No connection configured</text>;
+  }
+
+  if (visibleNodes.length === 0) {
+    const rootNode = treeNodes.get(currentPath);
+    if (rootNode?.loading) {
+      return <Spinner label="Loading..." />;
+    }
+    return <text>{filterQuery ? "No matches" : "Empty directory"}</text>;
+  }
+
+  return (
+    <ScrollIndicator selectedIndex={selectedIndex} totalItems={visibleNodes.length} visibleItems={VIEWPORT_HEIGHT}>
+      <VirtualList
+        items={visibleNodes}
+        renderItem={renderNode}
+        viewportHeight={VIEWPORT_HEIGHT}
+        selectedIndex={selectedIndex}
+        overscan={5}
+      />
+    </ScrollIndicator>
+  );
+}
+
+/** Simple fuzzy match: all characters of query appear in order in target. */
+function fuzzyMatch(target: string, query: string): boolean {
+  let qi = 0;
+  for (let ti = 0; ti < target.length && qi < query.length; ti++) {
+    if (target[ti] === query[qi]) qi++;
+  }
+  return qi === query.length;
+}
+
+/**
+ * Flatten tree into ordered list of visible nodes (expanded directories show children).
+ * Appends a synthetic "load more" node after the last child of any directory with hasMore.
+ */
+export function flattenVisibleNodes(
+  rootPath: string,
+  nodes: ReadonlyMap<string, TreeNode>,
+): readonly TreeNode[] {
+  const result: TreeNode[] = [];
+  const root = nodes.get(rootPath);
+  if (!root) return result;
+
+  function walk(nodePath: string): void {
+    const node = nodes.get(nodePath);
+    if (!node) return;
+
+    // Don't include the root itself — only its children
+    if (nodePath !== rootPath) {
+      result.push(node);
+    }
+
+    if (node.expanded) {
+      for (const childPath of node.children) {
+        walk(childPath);
+      }
+
+      // If this directory has more pages, show a "load more" placeholder
+      if (node.hasMore) {
+        result.push(makeLoadMoreNode(nodePath, node.depth + 1, node.loadingMore));
+      }
+    }
+  }
+
+  walk(rootPath);
+  return result;
+}