NodeDriveFS (macOS Client)

NodeDriveFS is the native macOS companion client for NodeDrive.

While the core NodeDrive repository handles the Node.js/Express server, file storage, and web interface, NodeDriveFS bridges that server directly into your macOS operating system. By leveraging Apple's File Provider framework, it mounts your remote NodeDrive instance as a virtual drive in the macOS Finder, allowing you to browse, edit, and manage your remote files exactly as if they were local files on your Mac.

🚀 Features

• Native Finder Integration: Mounts a virtual drive named "NodeDrive" directly in the Finder sidebar.
• The Perfect Companion: Designed specifically to consume the API endpoints (folder enumeration, file fetching, uploading, moving, and deleting) exposed by your NodeDrive Express backend.
• On-Demand Fetching: Uses Apple's NSFileProviderReplicatedExtension to only download file contents when you actually open them, saving local disk space.
• Menu Bar App: A lightweight, unobtrusive menu bar accessory app for quick configuration of your server URL and authentication tokens.
• Secure Authentication: Connects to your backend securely using a JSON Web Token (JWT) generated by your NodeDrive server.

🏗 Architecture

The project consists of two main components:

1. NodeDriveFS (Host App): A SwiftUI-based macOS app that runs in the menu bar. It manages the user interface for configuration (Server URL and JWT) and uses NSFileProviderManager to register or remove the File Provider domain.
2. NodeDrive (Extension): An App Extension running in the background. It conforms to NSFileProviderReplicatedExtension and communicates directly with your NodeDrive backend to synchronize file metadata and contents.

Both components share data securely using Apple's App Groups (e.g., group.com.bryce.NodeDriveFS).

🛠 Setup & Installation

Prerequisites

• macOS 11.0 or later.
• Xcode 14 or later.
• A running instance of the NodeDrive backend server.

1. Configure the App Group

Because File Provider Extensions run in a separate process from the main app, they share configuration data via App Groups. You must change the default App Group to one registered to your Apple Developer account:

1. Open NodeDriveFS.xcodeproj in Xcode.
2. In the Project Navigator, select the NodeDriveFS target, go to Signing & Capabilities, and update the App Groups section to your unique identifier (e.g., group.com.yourname.NodeDriveFS).
3. Repeat step 2 for the NodeDrive extension target.
4. Open NodeDriveFS/Config.swift and update the appGroupIdentifier variable to match your new App Group ID.
5. Ensure the Entitlements files (NodeDrive.entitlements and NodeDriveFS.entitlements) reflect this new App Group string.

2. Build and Run

1. Select the NodeDriveFS scheme in Xcode.
2. Build and run the project (Cmd + R).
3. The app will launch as an accessory and place a network drive icon in your macOS Menu Bar.

🔌 Connecting to your NodeDrive Server

Once the macOS app is running, you need to pair it with your NodeDrive backend.

1. Click the NodeDrive icon in your macOS Menu Bar and select Show Settings.
2. In the Server field, enter the base URL where your NodeDrive instance is hosted (e.g., http://127.0.0.1:3000 or your production domain).
3. To get your JWT, you can click the "Get JWT" link in the macOS app (which redirects to <your-server-url>/jwt), or generate it from your NodeDrive backend using the provided authentication setup scripts.
4. Paste the JWT into the app and click Save Configuration.
5. Open a new Finder window. You will now see NodeDrive listed in the sidebar under "Locations". Click on it to start browsing your remote file system natively!

🗑 Uninstalling / Clearing Data

If you need to unmount the drive or connect to a different NodeDrive server, open the NodeDrive Settings from the menu bar and click Clear Local Data. This will safely terminate the extension, wipe the local cache, and remove the virtual drive from Finder.

Note

I do not know Swift very well and this was largely vibe coded. If anyone wants to make improvements, please do.