File Explorer & File Watching
Relevant source files
The following files were used as context for generating this wiki page:
The File Explorer provides a visual interface for managing project files and directories within the Termul Manager. It enables users to perform standard filesystem operations such as creating, renaming, deleting, and searching for files, while maintaining real-time synchronization with the underlying disk state through a file watching system.
Sources: README.md:31-35, src/renderer/components/file-explorer/FileExplorer.tsx:1-50
Architecture and Components
The File Explorer is implemented as a React component that interacts with a centralized Zustand store for state management. It utilizes a platform-aware adapter layer to bridge the gap between the web renderer and the host filesystem, supporting both Tauri-based desktop environments and standalone server environments.
Core Components
| Component | Description |
|---|---|
FileExplorer | The main container that handles layout, resizing, and search integration. |
FileTreeNodeWrapper | Renders individual file and directory nodes within the tree structure. |
FileTreeContextMenuContent | Provides context-sensitive actions for filesystem entries. |
InlineInput | A temporary input field for creating or renaming files and folders. |
Sources: src/renderer/components/file-explorer/FileExplorer.tsx:68-125, src/renderer/components/file-explorer/FileExplorer.test.tsx:112-132
System Interaction Flow
The following diagram illustrates how the File Explorer interacts with the backend services to retrieve and update filesystem data:
File Watching and Synchronization
Termul implements live file watching to ensure the UI remains consistent with changes made to the disk by external processes.
Watcher Implementation
The system uses a recursive watcher that monitors the project root. On desktop, this utilizes the Tauri plugin-fs watchImmediate function. In web environments, the termul-server broadcasts fs_changed events over a WebSocket control channel when changes are detected via the host's notify crate.
Sources: src/renderer/lib/tests/tauri-filesystem-api.test.ts:310-330, src/renderer/lib/tests/parity-checklist.test.ts:580-605
Event Dispatching
Filesystem events are categorized into three primary types for internal subscription:
- Add/Create: Triggered when new files or directories appear.
- Modify/Change: Triggered when file content or metadata is updated.
- Unlink/Delete: Triggered when entries are removed from the disk.
Filesystem Operations
The File Explorer supports standard management tasks. The filesystemApi facade ensures these operations are containment-checked to prevent path traversal outside the project boundary.
File and Directory Creation
Users can create new entries through header buttons or context menus. The system resolves the target directory based on the current selection:
- If a directory is selected, the new entry is created within it.
- If a file is selected, the new entry is created in its parent directory.
- If nothing is selected, the entry is created in the project root.
Sources: src/renderer/components/file-explorer/FileExplorer.tsx:550-600, src/renderer/components/file-explorer/FileExplorer.test.tsx:430-460
Project Templating
When creating new projects, the system can scaffold directories and files using pre-defined templates (e.g., Node.js, Rust, React, Python). The scaffoldProject function performs recursive directory creation and file interpolation to set up the initial structure.
Sources: src/renderer/lib/project-templates.ts:1-20, src/renderer/lib/project-templates.ts:273-315
Search and Mentions
The File Explorer includes a Ripgrep-powered search system for both filename and content matches.
Search Integration
- Filename Search: Uses
search_file_names_stream(desktop) orGET /search/file-names(web). - Content Search: Performs a deep walk through files to find text matches, returning line numbers and context snippets.
- Mentions: The
@-mentionpicker in chat interfaces leverages the same filename search infrastructure.
Sources: src/renderer/components/file-explorer/FileExplorer.tsx:750-800, src/renderer/lib/tests/parity-checklist.test.ts:540-575
Search State Data Model
| Field | Type | Description |
|---|---|---|
searchQuery | string | The current text entered by the user. |
searchResults | Array<ContentMatch> | Objects containing file paths and matching line snippets. |
searchFileNameMatches | string[] | List of file paths matching the query string. |
searchLoading | boolean | Indicates an in-flight search operation. |
Sources: src/renderer/components/file-explorer/FileExplorer.test.tsx:60-80, src/renderer/components/file-explorer/FileExplorer.tsx:900-950
Error Handling and Recovery
The File Explorer implements specific recovery logic for connection outages:
- Stale State Protection: If a root load fails, the UI displays a "Retry" button.
- Auto-Recovery: In web environments, the system monitors the
controlChannel. If the channel transitions toconnectedwhile the explorer is in an error state or missing root data, it automatically triggersretryRootLoad. - Containment Guards: Every filesystem operation is validated to ensure it stays within the
projectPathboundary to prevent accidental deletions or modifications in system directories.
Sources: src/renderer/components/file-explorer/FileExplorer.tsx:285-305, src/renderer/components/file-explorer/FileExplorer.test.tsx:220-250, src/renderer/lib/tests/parity-checklist.test.ts:510-520