File System Manager
Relevant source files
The following files were used as context for generating this wiki page:
The File System Manager in Keynobi is a core backend service responsible for managing Android project structures, detecting Gradle roots, and maintaining a registry of recent projects. It serves as the bridge between the user's local file system and the application's internal state, ensuring that project paths are validated, canonicalized, and securely accessed.
The system handles critical tasks such as detecting the applicationId from Gradle scripts, managing project persistence (pinning and recent project history), and providing deep-link integration with Android Studio for source code navigation. Sources: src-tauri/src/commands/file_system.rs, src-tauri/src/lib.rs:41-52
Architecture and State Management
The file system state is encapsulated in the FsState struct, which is managed as a shared state within the Tauri application. It tracks two primary paths: the project_root (the directory opened by the user) and the gradle_root (the specific directory containing settings.gradle(.kts)).
Sources: src-tauri/src/lib.rs:41-52
Global State Details
| Component | Description |
|---|---|
project_root | The absolute path to the directory currently opened in the application. |
gradle_root | The ancestor directory containing Gradle settings, used as the build workspace root and security boundary. |
FsState | Thread-safe, async-accessible wrapper using Arc<Mutex<>> to allow concurrent access by various Tauri commands. |
Sources: src-tauri/src/lib.rs:41-52, src-tauri/src/commands/file_system.rs:94-135
Project Lifecycle and Registry
When a project is opened, the system performs a series of validation and registration steps. It canonicalizes the path, detects the Gradle root, and upserts the project into a persistent registry stored in the application settings.
Project Opening Flow
Registry Management
The system maintains a list of recent projects with the following logic:
- Deterministic IDs: Project IDs are generated as hex strings from the hash of the absolute path.
- Auto-Eviction: The registry maintains a maximum number of entries (
MAX_RECENT_PROJECTS). When the limit is reached, the oldest non-pinned entry is removed. - Persistence: Settings are saved atomically to prevent corruption during crashes.
Sources: src-tauri/src/commands/file_system.rs:17-64
Gradle Integration and Metadata Extraction
The File System Manager interacts with Gradle build files to extract essential project metadata. It specifically searches for applicationId, versionName, and versionCode within build.gradle or build.gradle.kts files.
Metadata Extraction Logic
The system attempts to read metadata from candidates in the following order:
{root}/app/build.gradle.kts{root}/app/build.gradle{root}/build.gradle.kts{root}/build.gradle
Sources: src-tauri/src/commands/file_system.rs:149-165, src-tauri/src/commands/file_system.rs:219-251
Application Info Structure
| Field | Regex Pattern | Description |
|---|---|---|
applicationId | applicationId\s*=?\s*"([^"]+)" | The unique Android application package name. |
versionName | versionName\s*=?\s*"([^"]+)" | The user-visible version string (e.g., "1.0.0"). |
versionCode | versionCode\s*=?\s*(\d+) | The internal version integer used for updates. |
Sources: src-tauri/src/commands/file_system.rs:167-170, src-tauri/src/commands/file_system.rs:276-291
Security and Path Validation
Security is enforced through path canonicalization and Tauri's filesystem scope. Before any directory is accessed, it is validated against the project root.
- Canonicalization: Raw paths are resolved to their absolute, symlink-free equivalents before use.
- FS Scoping: The
open_projectcommand dynamically registers the opened directory in the Tauri FS scope, allowing the frontend to read files strictly within that project. - Path Security Rules: Commands accepting paths must validate them against the project root using canonicalization to prevent path traversal attacks.
Sources: src-tauri/src/commands/file_system.rs:105-107, src-tauri/src/commands/file_system.rs:125-131, AGENTS.md:19-21
Android Studio Integration
The File System Manager facilitates navigation by resolving source files for Android Studio. Given a class path and filename (often from a crash log), it searches the project tree to find the absolute path.
Search Strategy
The file search uses the following priority:
- Ideal Match: A path ending exactly with
<class_dir_suffix>/<filename>(e.g.,com/example/app/MainActivity.kt). - Fallback Match: Any file in the project whose name matches the target filename.
- Pruning: Directories like
build,.gradle,.idea, and.gitare ignored during the search to improve performance and accuracy.
Sources: src-tauri/src/commands/studio.rs:88-135
Conclusion
The File System Manager provides the foundational infrastructure for project management in Keynobi. By combining robust path validation, automated Gradle root detection, and deep-link source navigation, it ensures a secure and efficient development environment that integrates seamlessly with existing Android development tools.