|
| 1 | +# AI Developer & Agent Onboarding Guide (AGENTS.md) |
| 2 | + |
| 3 | +Welcome, agent! This document serves as your technical manual and architectural reference for developing, debugging, and extending **CoDriver**. Refer to this guide to align with existing design patterns, technology choices, and structural constraints. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 🚀 Repository Identity & Mission |
| 8 | + |
| 9 | +**CoDriver** is a high-performance, cross-platform desktop file explorer built with **Tauri v2** and **Rust**. |
| 10 | +- **No path caching**: Directory exploration is done in real-time, relying on the raw speed of Rust, concurrent disk access (`rayon` & `jwalk`), and CPU power. |
| 11 | +- **Cross-platform**: Native feel on Windows, macOS, and Linux. |
| 12 | +- **Rich features**: Includes dual-pane layout, miller columns, quick file preview (images, PDFs, video, code), drag-and-drop, multi-format archive compression/extraction, SSHFS mount integration, and Gemini AI-powered features (like image background removal). |
| 13 | + |
| 14 | +--- |
| 15 | + |
| 16 | +## 📂 Directory Structure |
| 17 | + |
| 18 | +Here is a map of the repository's major files and folders: |
| 19 | + |
| 20 | +``` |
| 21 | +CoDriver/ |
| 22 | +├── .vscode/ # Workspace settings for VS Code |
| 23 | +├── .zed/ # Workspace settings for Zed |
| 24 | +├── arch/ # Architecture-specific scripts/files |
| 25 | +├── docs/ # Specifications, plans, release notes, and documentation |
| 26 | +│ ├── design/ # UI/UX mockups and feature specs |
| 27 | +│ └── superpowers/ # Active sprint specifications and plans |
| 28 | +├── memories/ # AI-agent working state and project context |
| 29 | +│ └── project_context.md # High-level summary of active sprints and tech stacks |
| 30 | +├── snap/ # Snap packaging configurations (Linux) |
| 31 | +├── src-tauri/ # Rust backend code (Tauri Core) |
| 32 | +│ ├── src/ |
| 33 | +│ │ ├── applications.rs # Desktop application integration helpers |
| 34 | +│ │ ├── main.rs # Entry point, state, and Tauri command declarations (heavy) |
| 35 | +│ │ ├── utils.rs # Heavy duty FS operations, watchers, compression |
| 36 | +│ │ └── window_tauri_ext.rs # Platform window custom styling integrations |
| 37 | +│ ├── Cargo.toml # Rust crate dependency map |
| 38 | +│ └── tauri.conf.json # Tauri configuration (window sizes, allowlists, assets) |
| 39 | +├── ui/ # Frontend assets loaded by Tauri (Vanilla JS + jQuery) |
| 40 | +│ ├── index.html # Main app shell & modal containers |
| 41 | +│ ├── main_logic.js # Core UI state manager and operation orchestration (heavy) |
| 42 | +│ ├── events.js # Global listeners for Tauri-emitted backend events |
| 43 | +│ ├── contextmenu.js # Custom right-click menu management |
| 44 | +│ ├── utils.js # Shared DOM and IPC helpers |
| 45 | +│ ├── models.js # Core JS model definitions (e.g. ActiveAction, Popups) |
| 46 | +│ └── style.css # Premium glassmorphism design system & styles |
| 47 | +└── README.md # Public orientation document |
| 48 | +``` |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## 💻 Tech Stack & Architecture |
| 53 | + |
| 54 | +### 1. The Frontend (ui/) |
| 55 | +- **Core UI Structure**: Single-page application built on pure HTML5 and vanilla CSS. |
| 56 | +- **DOM Orchestration**: Uses **jQuery** (`$`) for event handling, animations, and DOM manipulation. Avoid introducing complex front-end frameworks (React, Vue, etc.) as the project structure relies on global namespace orchestration. |
| 57 | +- **Visual Design**: Sleek glassmorphism theme defined in `ui/style.css` leveraging modern CSS variables (e.g., `--primaryColor`, `--textColor`, `--glass-blur`). Features responsive grid/list/miller layouts. |
| 58 | +- **Third-Party Libraries**: |
| 59 | + - `DragSelect` (`ds.min.js`) for click-and-drag file selections. |
| 60 | + - `Font Awesome` (`font-awesome/`) for clean iconography. |
| 61 | + |
| 62 | +### 2. The Backend (src-tauri/) |
| 63 | +- **Core**: **Tauri v2** (Tauri v2 has been adopted for the codebase). |
| 64 | +- **Disk Walking**: **jwalk** and **walkdir** for highly parallel directory traversals. |
| 65 | +- **Concurrency**: **rayon** for multi-threaded operation mapping. |
| 66 | +- **FS Watching**: **notify** crate registers platform-specific filesystem watchers to push live updates to the UI. |
| 67 | +- **Archive Integrations**: `sevenz-rust`, `zip`, `tar`, `flate2`, `zstd`, `brotlic`, `density-rs`. |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## 🔄 IPC & Tauri Command Integration |
| 72 | + |
| 73 | +Communication between the frontend and the backend is done via Tauri's IPC bridge. |
| 74 | + |
| 75 | +```mermaid |
| 76 | +sequenceDiagram |
| 77 | + participant UI as ui/main_logic.js |
| 78 | + participant IPC as Tauri Invoke Bridge |
| 79 | + participant Rust as src-tauri/src/main.rs |
| 80 | + participant FS as Local Filesystem |
| 81 | +
|
| 82 | + UI->>IPC: invoke("open_dir", { path: "/Users/..." }) |
| 83 | + IPC->>Rust: open_dir(path) |
| 84 | + Rust->>FS: Read directory entries |
| 85 | + FS-->>Rust: Entries vector |
| 86 | + Rust-->>IPC: FDir Array |
| 87 | + IPC-->>UI: Array of JS objects |
| 88 | +``` |
| 89 | + |
| 90 | +### IPC Convention |
| 91 | +1. **Rust Command Declaration** (`src-tauri/src/main.rs`): |
| 92 | + ```rust |
| 93 | + #[tauri::command] |
| 94 | + fn your_command_name(custom_argument: String) -> Result<String, String> { |
| 95 | + // Backend logic |
| 96 | + Ok("Success".into()) |
| 97 | + } |
| 98 | + ``` |
| 99 | +2. **Registration**: Ensure your command is registered inside the `.invoke_handler` list in `main.rs`: |
| 100 | + ```rust |
| 101 | + .invoke_handler(tauri::generate_handler![ |
| 102 | + list_dirs, |
| 103 | + // ... |
| 104 | + your_command_name |
| 105 | + ]) |
| 106 | + ``` |
| 107 | +3. **JS Invocation** (`ui/main_logic.js`): |
| 108 | + Tauri bridges snake_case Rust arguments to camelCase JS properties automatically. |
| 109 | + ```javascript |
| 110 | + const result = await invoke("your_command_name", { customArgument: "value" }); |
| 111 | + ``` |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## 🎨 UI & Styling Guidelines |
| 116 | + |
| 117 | +To maintain visual excellence, follow these rules: |
| 118 | +1. **Glassmorphism Theme**: Always utilize the design system's variables from `style.css` rather than static colors. |
| 119 | + ```css |
| 120 | + background: var(--glass-bg); |
| 121 | + border: var(--glass-border); |
| 122 | + backdrop-filter: var(--glass-blur); |
| 123 | + ``` |
| 124 | +2. **Unified Modals & Popups (`.props-card`)**: Refrain from using crude custom layouts or old `.uni-popup` overlays. All interactive modal dialogs (such as Properties, Compress, Extract, Delete Confirm, and FTP Connection) must inherit from the `.props-card` design pattern: |
| 125 | + - **Hero Header (`.props-card__hero`)**: Houses a `.props-card__thumb` holding a dedicated Font Awesome icon (or a circular progress loader styled with `.preloader-small-invert` for ongoing processes), and a `.props-card__heading` containing the `.props-card__name` (title) and `.props-card__meta` (subtext or `.props-card__chip` labels). |
| 126 | + - **Form Grid Items (`.props-card__list`)**: Wrapped in a `<dl>` list using `<div class="props-card__row">` grid containers (`88px 1fr` layout split). Labels (`<dt class="props-card__label">`) should feature small, clean icons. Value fields (`<dd class="props-card__value">`) house high-contrast text inputs, number fields, or dropdown select boxes styled with the `.props-card__input` class. |
| 127 | + - **Form Layout**: Prefer simple vertical stacking for multiple inputs over dynamic horizontal row division to avoid alignment splits and wrap breaks. |
| 128 | + - **Structured Footer (`.props-card__footer`)**: Placed at the bottom holding primary and secondary buttons styled with `.props-card__btn` and `.props-card__btn--primary`. |
| 129 | + - **Display Activation (JS)**: When showing the modal, always invoke `.style.display = "flex"` (never `"block"`) to allow the card's native flexbox and stretch behaviors to function. |
| 130 | +3. **Prevent Placeholder Assets**: When displaying visual helpers, do not use dead layout placeholders. Generate or use proper icon sheets and local resources found in `ui/resources/` or `ui/font-awesome`. |
| 131 | +4. **Asynchronous Previews & Circular Loaders**: When displaying large or heavy preview elements (such as PDF files) in modals, avoid setting the resource source immediately inside the HTML template to prevent the UI from freezing. Instead: |
| 132 | + - Immediately display the modal container with a centered circular progress loader (using the style of the indicators from the action items, e.g. `.preloader-invert` or `.preloader-small-invert`). |
| 133 | + - Load the resource asynchronously in the background by dynamically setting the target element's `src` attribute. |
| 134 | + - Listen to the `"load"` event of the element, and once fired, hide the loading indicator, make the preview visible, and transition the background properties (e.g. to a solid white background for high PDF legibility). |
| 135 | + |
| 136 | +--- |
| 137 | + |
| 138 | +## 🛠️ Key Developer Workflows & Recipes |
| 139 | + |
| 140 | +### 1. Working with Paths |
| 141 | +> [!CAUTION] |
| 142 | +> **Path Separator Trap**: Paths are highly platform-dependent. Always normalize paths by replacing double-backslashes `\\` with forward slashes `/` where appropriate on the frontend, and verify that your path adjustments are Windows-safe. |
| 143 | +
|
| 144 | +### 2. State & Focus Flags |
| 145 | +When implementing new keyboard shortcuts or popups, protect the global UI namespace by checking the state flags in `main_logic.js`: |
| 146 | +- `IsPopUpOpen`: Set to `true` when a modal/popup is visible. Prevents general explorer keyboard events (like navigating or deleting) from triggering. |
| 147 | +- `IsInputFocused`: Set to `true` when an `<input>` is active. Prevents search shortcuts or navigation commands from intercepting typing. |
| 148 | +- `IsDisableShortcuts`: Use to globally silence key interception. |
| 149 | + |
| 150 | +### 3. File Operations & Progress Bars |
| 151 | +File operations are handled asynchronously to keep the UI smooth: |
| 152 | +- Selecting items buffers them in `ArrSelectedItems` or `ArrCopyItems` (for copy/cut). |
| 153 | +- Invoking `arr_copy_paste` runs chunked operations in the Rust backend. |
| 154 | +- Rust emits events like `"update-progress-bar"` and `"finish-progress-bar"` which are picked up in `ui/events.js` to update the `.active-actions-container` layout. |
| 155 | +- Dismissing the detailed progress modal via **Run in Background** tracks progress silently. Users can click on a progress action item within the active actions popup to invoke `reopenProgressModal()`, which resets the dismissal state, closes the active actions popup, and opens the detailed progress modal populated with live data. |
| 156 | + |
| 157 | +### 4. Running a Local Build |
| 158 | +Ensure you have the tauri-cli installed: |
| 159 | +```bash |
| 160 | +cargo install tauri-cli |
| 161 | +``` |
| 162 | +Run the development environment locally: |
| 163 | +```bash |
| 164 | +cargo tauri dev |
| 165 | +``` |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## 🤖 AI Guidelines & Prompt Engineering |
| 170 | + |
| 171 | +When developing or debugging this repository, you should prioritize: |
| 172 | +1. **Vanilla Style Preservation**: Do not attempt to refactor the jQuery layout into modern JS frameworks (React, Vue, Svelte) unless explicitly requested. |
| 173 | +2. **Keep Calculations in Rust**: Heavy calculations, recursive walks, filtering, and heavy text parsing should always reside on the Rust backend (`utils.rs` or `main.rs`) to maintain high desktop performance. |
| 174 | +3. **Graceful IPC Failures**: Always wrap Tauri commands in JS `try/catch` and display human-readable notifications using the global toast notification functions: |
| 175 | + ```javascript |
| 176 | + showToast("Action failed: " + error, ToastType.ERROR); |
| 177 | + ``` |
| 178 | +4. **Respect AI Provider Selection**: Do not hardcode a specific AI provider (such as Gemini or OpenAI). Always check the active `ai_provider` configuration (e.g. the global `AiProvider` on the frontend, and the settings map in `app_config.json` on the backend). AI commands must query the selected provider and model to ensure user settings and keychain API keys are fully respected. |
| 179 | + |
0 commit comments