feat: add native file explorer integrations

- Introduced IPC handlers for opening model directories and paths in the file explorer, enhancing user experience by allowing direct access to Hugging Face and Ollama model directories.
- Updated the Electron README to document the new native integrations.
- Enhanced the application menu to include a Log Viewer option.
- Refactored file explorer utility functions to improve error handling and notifications.
- Added tests for the new file explorer functionalities to ensure reliability.

Author: georgi

electron/README.md

@@ -10,6 +10,10 @@ Key folders:
 - `assets/` – icons and other static resources used by Electron
 - `resources/` – templates and additional files bundled into the app
 
+## Native Integrations
+
+- File explorer bridge: IPC handlers (`file-explorer-open-path`, `file-explorer-open-directory`) expose safe OS paths such as the Hugging Face cache and Ollama models directories to the renderer via `window.api.openModelDirectory` / `openModelPath`.
+
 This app is built with React and Vite. In development you can launch the UI with
 hot reload using:
 

electron/src/fileExplorer.ts

@@ -0,0 +1,212 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { shell } from "electron";
+
+import { logMessage } from "./logger";
+import type { FileExplorerResult, ModelDirectory } from "./types";
+
+const DEFAULT_HF_SUBDIR = path.join(".cache", "huggingface", "hub");
+
+function expandUserPath(p?: string | null): string | undefined {
+  if (!p) {
+    return undefined;
+  }
+  if (p.startsWith("~")) {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  return p;
+}
+
+function normalizePath(p: string): string {
+  const expanded = expandUserPath(p) ?? p;
+  return path.resolve(expanded);
+}
+
+function dirExists(target?: string | null): target is string {
+  if (!target) {
+    return false;
+  }
+  try {
+    const stats = fs.statSync(target);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function ensureDir(target?: string | null): string | undefined {
+  if (!target) {
+    return undefined;
+  }
+  const candidate = normalizePath(target);
+  return dirExists(candidate) ? candidate : undefined;
+}
+
+export function getOllamaModelsDir(): string | undefined {
+  const envOverride = expandUserPath(process.env.OLLAMA_MODELS);
+  if (envOverride) {
+    const resolved = normalizePath(envOverride);
+    logMessage(
+      `Using Ollama models directory from OLLAMA_MODELS env var: ${resolved}`,
+      "info"
+    );
+    return resolved;
+  }
+
+  try {
+    let candidate: string | undefined;
+    if (process.platform === "win32") {
+      const base = process.env.USERPROFILE || os.homedir();
+      candidate = ensureDir(path.join(base, ".ollama", "models"));
+    } else if (process.platform === "darwin") {
+      candidate = ensureDir(path.join(os.homedir(), ".ollama", "models"));
+    } else {
+      const userPath = ensureDir(path.join(os.homedir(), ".ollama", "models"));
+      candidate = userPath ?? ensureDir("/usr/share/ollama/.ollama/models");
+    }
+
+    if (candidate) {
+      return candidate;
+    }
+  } catch (error) {
+    logMessage(
+      `Error determining Ollama models directory: ${String(error)}`,
+      "error"
+    );
+  }
+  return undefined;
+}
+
+export function getHuggingFaceCacheDir(): string | undefined {
+  const candidates: (string | undefined)[] = [];
+  const envOverride =
+    process.env.HF_HUB_CACHE ??
+    process.env.HUGGINGFACE_HUB_CACHE ??
+    undefined;
+  if (envOverride) {
+    candidates.push(envOverride);
+  }
+
+  if (process.env.HF_HOME) {
+    candidates.push(path.join(process.env.HF_HOME, "hub"));
+  }
+
+  if (process.env.XDG_CACHE_HOME) {
+    candidates.push(
+      path.join(process.env.XDG_CACHE_HOME, "huggingface", "hub")
+    );
+  }
+
+  candidates.push(path.join(os.homedir(), DEFAULT_HF_SUBDIR));
+
+  for (const candidate of candidates) {
+    const resolved = ensureDir(candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  logMessage("Hugging Face cache directory does not exist or is unavailable.", "warn");
+  return undefined;
+}
+
+function getValidExplorableRoots(): string[] {
+  const safeRoots: string[] = [];
+  const ollamaDir = getOllamaModelsDir();
+  if (ollamaDir) {
+    safeRoots.push(ollamaDir);
+  }
+
+  const hfCache = getHuggingFaceCacheDir();
+  if (hfCache) {
+    safeRoots.push(hfCache);
+  }
+
+  return safeRoots;
+}
+
+function isPathWithin(target: string, root: string): boolean {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+export async function openPathInExplorer(
+  requestedPath: string
+): Promise<FileExplorerResult> {
+  const safeRoots = getValidExplorableRoots();
+  if (safeRoots.length === 0) {
+    return {
+      status: "error",
+      message:
+        "Cannot open path: No safe directories (like Ollama or Hugging Face cache) could be determined.",
+    };
+  }
+
+  let normalized: string;
+  try {
+    normalized = normalizePath(requestedPath);
+  } catch (error) {
+    logMessage(
+      `Failed to normalize path ${requestedPath}: ${String(error)}`,
+      "warn"
+    );
+    return {
+      status: "error",
+      message: "Path could not be resolved on this system.",
+    };
+  }
+
+  const isSafe = safeRoots.some((root) => isPathWithin(normalized, root));
+  if (!isSafe) {
+    logMessage(
+      `Path traversal attempt: ${normalized} is outside allowed directories ${safeRoots.join(
+        ", "
+      )}`,
+      "warn"
+    );
+    return {
+      status: "error",
+      message: "Access denied: Path is outside the allowed directories.",
+    };
+  }
+
+  try {
+    const result = await shell.openPath(normalized);
+    if (result) {
+      throw new Error(result);
+    }
+    return { status: "success", path: normalized };
+  } catch (error) {
+    logMessage(
+      `Failed to open path ${normalized} in explorer: ${String(error)}`,
+      "error"
+    );
+    return {
+      status: "error",
+      message:
+        "An internal error occurred while attempting to open the path. Please check logs for details.",
+    };
+  }
+}
+
+export async function openModelDirectory(
+  target: ModelDirectory
+): Promise<FileExplorerResult> {
+  const dir =
+    target === "ollama" ? getOllamaModelsDir() : getHuggingFaceCacheDir();
+
+  if (!dir) {
+    const label =
+      target === "ollama" ? "Ollama models" : "Hugging Face cache";
+    return {
+      status: "error",
+      message: `${label} directory is not available on this system.`,
+    };
+  }
+
+  return openPathInExplorer(dir);
+}

electron/src/ipc.ts

@@ -28,6 +28,7 @@ import {
   validateRepoId,
   searchNodes,
 } from "./packageManager";
+import { openModelDirectory, openPathInExplorer } from "./fileExplorer";
 
 /**
  * This module handles Inter-Process Communication (IPC) between the Electron main process
@@ -122,6 +123,20 @@ export function initializeIpcHandlers(): void {
       showItemInFolder(fullPath);
     }
   );
+
+  createIpcMainHandler(
+    IpcChannels.FILE_EXPLORER_OPEN_PATH,
+    async (_event, request) => {
+      return openPathInExplorer(request.path);
+    }
+  );
+
+  createIpcMainHandler(
+    IpcChannels.FILE_EXPLORER_OPEN_DIRECTORY,
+    async (_event, target) => {
+      return openModelDirectory(target);
+    }
+  );
   // Continue to app handler
   createIpcMainHandler(IpcChannels.START_SERVER, async () => {
     logMessage("User continued to app from package manager");

electron/src/menu.ts

@@ -1,7 +1,7 @@
 import { Menu, shell } from "electron";
 import { IpcChannels } from "./types.d";
 import { getMainWindow } from "./state";
-import { createPackageManagerWindow } from "./window";
+import { createPackageManagerWindow, createLogViewerWindow } from "./window";
 
 /**
  * Builds the application menu
@@ -219,6 +219,10 @@ const buildMenu = () => {
           label: "Package Manager",
           click: () => createPackageManagerWindow(),
         },
+        {
+          label: "Log Viewer",
+          click: () => createLogViewerWindow(),
+        },
       ],
     },
     {

electron/src/preload.ts

@@ -33,6 +33,7 @@ import {
   UpdateProgressData,
   UpdateInfo,
   Workflow,
+  ModelDirectory,
 } from "./types.d";
 
 /**
@@ -93,6 +94,10 @@ contextBridge.exposeInMainWorld("api", {
   openLogFile: () => ipcRenderer.invoke(IpcChannels.OPEN_LOG_FILE),
   showItemInFolder: (fullPath: string) =>
     ipcRenderer.invoke(IpcChannels.SHOW_ITEM_IN_FOLDER, fullPath),
+  openModelDirectory: (target: ModelDirectory) =>
+    ipcRenderer.invoke(IpcChannels.FILE_EXPLORER_OPEN_DIRECTORY, target),
+  openModelPath: (path: string) =>
+    ipcRenderer.invoke(IpcChannels.FILE_EXPLORER_OPEN_PATH, { path }),
   installToLocation: (location: string, packages: PythonPackages) =>
     ipcRenderer.invoke(IpcChannels.INSTALL_TO_LOCATION, { location, packages }),
   selectCustomInstallLocation: () =>

electron/src/types.d.ts

@@ -8,6 +8,10 @@ declare global {
       openLogFile: () => Promise<void>;
       showItemInFolder: (fullPath: string) => Promise<void>;
       openExternal: (url: string) => void;
+      openModelDirectory: (
+        target: ModelDirectory
+      ) => Promise<FileExplorerResult>;
+      openModelPath: (path: string) => Promise<FileExplorerResult>;
       onUpdateProgress: (
         callback: (data: {
           componentName: string;
@@ -185,11 +189,21 @@ export interface MenuEventData {
     | "fitView";
 }
 
+export type ModelDirectory = "huggingface" | "ollama";
+
+export interface FileExplorerResult {
+  status: "success" | "error";
+  path?: string;
+  message?: string;
+}
+
 // IPC Channel names as const enum for type safety
 export enum IpcChannels {
   GET_SERVER_STATE = "get-server-state",
   OPEN_LOG_FILE = "open-log-file",
   SHOW_ITEM_IN_FOLDER = "show-item-in-folder",
+  FILE_EXPLORER_OPEN_PATH = "file-explorer-open-path",
+  FILE_EXPLORER_OPEN_DIRECTORY = "file-explorer-open-directory",
   INSTALL_TO_LOCATION = "install-to-location",
   SELECT_CUSTOM_LOCATION = "select-custom-location",
   START_SERVER = "start-server",
@@ -231,11 +245,17 @@ export interface InstallToLocationData {
   packages: PythonPackages;
 }
 
+export interface FileExplorerPathRequest {
+  path: string;
+}
+
 // Request/Response types for each IPC channel
 export interface IpcRequest {
   [IpcChannels.GET_SERVER_STATE]: void;
   [IpcChannels.OPEN_LOG_FILE]: void;
   [IpcChannels.SHOW_ITEM_IN_FOLDER]: string; // full path
+  [IpcChannels.FILE_EXPLORER_OPEN_PATH]: FileExplorerPathRequest;
+  [IpcChannels.FILE_EXPLORER_OPEN_DIRECTORY]: ModelDirectory;
   [IpcChannels.INSTALL_TO_LOCATION]: InstallToLocationData;
   [IpcChannels.SELECT_CUSTOM_LOCATION]: void;
   [IpcChannels.START_SERVER]: void;
@@ -267,6 +287,8 @@ export interface IpcResponse {
   [IpcChannels.GET_SERVER_STATE]: ServerState;
   [IpcChannels.OPEN_LOG_FILE]: void;
   [IpcChannels.SHOW_ITEM_IN_FOLDER]: void;
+  [IpcChannels.FILE_EXPLORER_OPEN_PATH]: FileExplorerResult;
+  [IpcChannels.FILE_EXPLORER_OPEN_DIRECTORY]: FileExplorerResult;
   [IpcChannels.INSTALL_TO_LOCATION]: void;
   [IpcChannels.SELECT_CUSTOM_LOCATION]: string | null;
   [IpcChannels.START_SERVER]: void;