Skip to content

Node File Manager

Jump to bottom
MoribundMurdoch edited this page May 15, 2026 · 1 revision

Node File Manager: System Documentation

What is this?

The Node File Manager is a visual, graph-based directory explorer. It moves away from standard tree-view file browsers, representing your project’s files and folders as interactive circular nodes arranged in an SVG grid. It includes a robust "Peek" engine that parses file contents on the fly to show useful metadata, structure previews, and LLM anchors without requiring you to open the files.

Where is it in the UI?

It occupies the main graph container area in the UI, completely replacing the standard ArchitectureModuleTree.

  • To Access: It becomes visible when the application's GraphViewMode is set to node_file_manager.
  • Visual Appearance: It features a top navigation bar (with back/forward/up arrows and breadcrumbs), a path bar, and an SVG canvas filled with circular nodes. The current directory is denoted by a larger node with a "⌂" icon, folders by "▣", and files by "◦".

UI Interactions

What does left-click do?

  • On a Folder Node: Navigates into that directory, updating the visual grid, the pathbar, and your breadcrumbs.
  • On the Background: Closes any open context menus.
  • On Topbar Navigation: * Arrows (←, →, ↑): Navigate backward/forward through your history stack, or up to the parent directory.
  • Breadcrumbs: Instantly jumps to that specific parent directory.
  • Show/Hide dotfiles: Toggles the visibility of hidden files and folders.
  • Root: Returns you instantly to the active workspace root.

What does right-click do?

Right-clicking any node opens the Manager Context Menu, with options depending on the node type:

  • For Folders: * Open Folder Node: Navigates into the folder within the app.

  • Open in System File Manager: Launches the folder using your OS default (xdg-open).

  • Open Terminal Here: Spawns a new terminal session at that path (xdg-terminal-exec).

  • For Files:

  • Open File: Opens the file in your default system editor.

  • Open Containing Folder: Opens the parent directory in your system file manager.

  • Automations...: Opens the FileAutomationDialog targeting this specific file.

  • (Conditional) [Wiki Page Name]: If the file matches known project configuration files, a quick link to relevant documentation will appear.

Hover Action (Peek)

  • Hovering over a Node: Generates a "Context Peek" popup. For folders, it shows child/file counts. For files, it shows size, type, and (for text files) extracts key symbols (structs, enums, fns) and declaration previews.

File System Permissions

Does it read files?

Yes, extensively. * It reads directory structures to build the visual grid.

  • The peek.rs engine actively reads file contents when you hover over nodes to generate the "Context Peek" window, extracting code structure (like pub struct or impl) for quick reference.

Does it write files?

No. The Node File Manager itself is strictly a read-only visualizer and navigation tool. However, it acts as a gateway; selecting Automations... from the right-click menu hands off control to the FileAutomationDialog, which can write files if the app is in Automate Mode.

Operational Guidelines

What safety rules apply?

  1. Binary and Size Safeguards: The Peek engine will safely ignore binary files, unknown extensions, and text files larger than 128 KB to prevent memory bloat, crashes, or rendering garbage data.
  2. Hardcoded Ignore Lists: To maintain a clean UI, the file manager automatically filters out heavy or irrelevant directories such as .git, target, node_modules, build, and __pycache__.
  3. Workspace Initialization Check: The file manager will refuse to render nodes until a valid ActiveWorkspacePath has been selected via the Control Panel.

What should the user use it for?

  • Rapid Code Discovery: Use the hover "Peek" feature to quickly scan a file's structs, enums, and imports without having to context-switch into a full text editor.
  • Spatial Navigation: Moving through large Rust projects visually rather than digging through nested dropdown trees.
  • Targeting Automations: Quickly locating a specific file deep in the project to apply a template or module registration via the context menu.

Common mistakes / weird edge cases

  • "Where are my .env files?" By default, hidden files are filtered out. You must click the "Show dotfiles" button in the topbar to see them.
  • Empty Screen on Startup: If you haven't clicked "Select Project Root" in the Control Panel, the Node File Manager will simply display "Select or drop a project root before using Node File Manager."
  • Linux Tooling Reliance: Options like "Open Terminal Here" rely explicitly on xdg-terminal-exec and xdg-open. If your system environment does not have these configured, clicking those context menu items will silently fail (though an error will be sent to the app's internal logger).

Clone this wiki locally