Metadata: phase 1

- Add decisions
- Enhance file structure: Add new fields to the `FileEntry` struct in `operations.rs`. Update `types.ts` with new fields.
- Add `uzers` crate for uid→name resolution (used instead of users due to RUSTSEC-2023-0059)
- Create owner name cache
- Add metadata transmission
- Handle symlinks and permission errors gracefully
- Update frontend mock service (created `test-helpers.ts`)
- Test: All checks pass

Author: vdavid

docs/adr/006-file-metadata-scope.md

@@ -0,0 +1,85 @@
+# ADR 006: File metadata scope and cost tiers
+
+## Status
+
+Accepted
+
+## Context
+
+When displaying files in the explorer, we can retrieve various metadata. macOS provides extensive file information, but
+each piece has different performance characteristics. With lists of 50k+ files, we must be deliberate about what to
+fetch eagerly vs. on-demand.
+
+## Decision
+
+We will categorize metadata into tiers by cost and load accordingly:
+
+### Tier 1: Free (from single `stat()` call, already performed)
+
+| Field         | Source                               | Notes          |
+| ------------- | ------------------------------------ | -------------- |
+| Name          | `DirEntry::file_name()`              | Already have   |
+| Size          | `metadata.len()`                     | Already have   |
+| Is directory  | `metadata.is_dir()`                  | Already have   |
+| Modified date | `metadata.modified()`                | Already have   |
+| Created date  | `MetadataExt::st_birthtime()`        | Same syscall   |
+| Permissions   | `metadata.permissions().mode()`      | Unix mode bits |
+| Owner uid/gid | `MetadataExt::st_uid()` / `st_gid()` | Same syscall   |
+| Is symlink    | `metadata.is_symlink()`              | Same syscall   |
+
+### Tier 2: Cheap (extra syscall, cacheable)
+
+| Field          | How to get                        | Cost            |
+| -------------- | --------------------------------- | --------------- |
+| Owner name     | `users` crate to resolve uid→name | ~1μs, cacheable |
+| Symlink target | `std::fs::read_link()`            | ~1μs if symlink |
+
+### Tier 3: macOS-specific (requires Objective-C APIs)
+
+| Field               | API                                               | Cost                |
+| ------------------- | ------------------------------------------------- | ------------------- |
+| Added date          | Spotlight / `NSURL resourceValuesForKeys:`        | ~50-100μs/file      |
+| Last opened date    | Spotlight / NSURL                                 | Same                |
+| Locked flag         | `NSURL` with `NSURLIsUserImmutableKey`            | ~50μs               |
+| Stationery pad flag | `NSURL` with `NSURLStationeryKey`                 | Same                |
+| Kind (localized)    | `NSURL.localizedTypeDescription`                  | Requires macOS APIs |
+| Cloud sync status   | xattrs like `com.apple.icloud.itemDownloadStatus` | ~10μs               |
+
+### Tier 4: Extended/content-based
+
+| Category             | How to get                     | Cost                 |
+| -------------------- | ------------------------------ | -------------------- |
+| EXIF/media metadata  | `kamadak-exif`, `image` crates | 1-50ms+ (reads file) |
+| PDF metadata         | `lopdf` crate                  | 10-100ms+            |
+| Audio/video metadata | `lofty` crate                  | 10-100ms+            |
+
+## Chosen scope for initial implementation
+
+**Include in list view (Tier 1-2)**:
+
+- All Tier 1 fields (zero extra cost)
+- Owner name (cached uid→name resolution)
+
+**Defer (Tier 3-4)**:
+
+- Added/opened dates (Spotlight-dependent, unreliable)
+- Locked/Stationery flags (rarely used)
+- Kind (can derive from extension on frontend)
+- EXIF and media metadata (on-demand only)
+
+**Future work**:
+
+- Cloud sync status (iCloud, Dropbox, GDrive) - valuable, requires xattr reads
+
+## Consequences
+
+### Positive
+
+- Zero performance regression for current functionality
+- Created/permissions/owner cost nothing extra
+- Clear path for adding macOS-specific metadata later
+
+### Negative
+
+- Some Finder-equivalent fields not immediately available
+- macOS-specific features require platform-gated code

docs/adr/007-json-for-ipc.md

@@ -0,0 +1,52 @@
+# ADR 007: Use JSON for Tauri IPC, optimize with chunking
+
+## Status
+
+Accepted
+
+## Context
+
+Tauri 2.0 supports both JSON (default) and binary formats via Raw Payloads (MessagePack, Protobuf, etc.). For lists of
+50k files, we need to choose the right serialization approach.
+
+### Options considered
+
+1. **JSON (default)** - Simple, debuggable, no extra dependencies
+2. **MessagePack** - ~37% smaller, ~4x faster serialization
+3. **Protobuf** - Schema-based, very compact, complex setup
+
+### Benchmarks (from research)
+
+For 50k file entries (~200 bytes/entry):
+
+- JSON: ~10MB payload, ~50ms serialization
+- MessagePack: ~6.3MB payload, ~12ms serialization
+
+## Decision
+
+Use **JSON** for IPC, combined with **chunking** (1000 entries per response).
+
+Rationale:
+
+1. The chunking strategy reduces per-request payload to ~200KB regardless of format
+2. JSON is simpler to debug (readable in browser devtools)
+3. No additional dependencies (`rmp-serde`, `@msgpack/msgpack`)
+4. Can always switch to MessagePack later if profiling shows bottleneck
+
+## Consequences
+
+### Positive
+
+- Simpler implementation, no binary serialization libraries
+- Easier debugging with browser devtools
+- Tauri's default path, best documented
+
+### Negative
+
+- Slightly larger payloads (~37% overhead vs MessagePack)
+- Slightly slower serialization (negligible with chunking)
+
+### Notes
+
+If profiling reveals IPC as a bottleneck with 50k+ files after virtual scrolling and chunking are implemented, we can
+revisit this decision and switch to MessagePack using Tauri 2.0's `Response::new(bytes)` API.

docs/adr/008-icon-registry-pattern.md

@@ -0,0 +1,75 @@
+# ADR 008: Icon registry pattern for efficient icon transmission
+
+## Status
+
+Accepted
+
+## Context
+
+File icons need to be displayed for every file in the list. Without optimization, 50k JPEG files would transmit 50k
+identical JPEG icons (~2–4KB each = 100–200MB of redundant data).
+
+### Options considered
+
+1. **Inline icons**: Send icon data with each file entry
+2. **Icon IDs**: Send icon reference, fetch icons separately
+3. **CSS sprites**: Prebuilt sprite sheet of common icons
+4. **No icons**: Use emoji or text-only display
+
+## Decision
+
+Use an **icon registry pattern**:
+
+1. Backend generates stable `iconId` for each file:
+    - Extension-based: `"ext:jpg"`, `"ext:pdf"` (99% of files)
+    - Custom icons: `"custom:<hash>"` (apps, special folders)
+
+2. `FileEntry` includes only `iconId`, not icon data
+
+3. Separate `get_icons(icon_ids: Vec<String>)` command returns icon data
+
+4. Frontend caches icons in localStorage/IndexedDB
+
+### Icon format
+
+- Size: 32×32 pixels (good for retina at 2x)
+- Format: WebP (~50% smaller than PNG)
+- Fallback: Extension-based generic icons
+
+### Data flow
+
+```
+┌─────────────┐     ┌───────────────────┐     ┌─────────────┐
+│  File list  │────▶│  iconId refs      │────▶│  Frontend   │
+│  response   │     │  ("ext:jpg", ...) │     │  checks     │
+└─────────────┘     └───────────────────┘     │  cache      │
+                                              └──────┬──────┘
+                                                     │
+                             ┌───────────────────────┘
+                             ▼
+                  ┌─────────────────────┐
+                  │  get_icons() for    │
+                  │  uncached IDs only  │
+                  └─────────────────────┘
+```
+
+## Consequences
+
+### Positive
+
+- 50k files transmit ~50 unique icon IDs (not 50k icon blobs)
+- Icons cached persistently across sessions
+- Lazy loading — only fetch icons as needed
+- Extension-based IDs are stable and predictable
+
+### Negative
+
+- Two-phase loading (file list, then icons)
+- Requires frontend cache management
+- Custom icons (apps, branded folders) need hash-based invalidation
+
+### Implementation notes
+
+- Use `file_icon_provider` crate for cross-platform icon retrieval
+- Icon generation is async (~50–100 μs per unique icon via NSWorkspace)
+- Backend should cache generated icons in memory during a session

src-tauri/Cargo.lock

@@ -26,6 +26,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 notify = "8"
 dirs = "6"
+uzers = "0.12.2"
 
 [target.'cfg(not(any(target_os = "android", target_os = "ios")))'.dependencies]
 tauri-plugin-window-state = "2"

src-tauri/Cargo.toml

@@ -19,12 +19,26 @@ impl MockFileSystemProvider {
     /// Useful for stress testing with large file counts.
     pub fn with_file_count(count: usize) -> Self {
         let entries = (0..count)
-            .map(|i| FileEntry {
-                name: format!("file_{:06}.txt", i),
-                path: format!("/mock/file_{:06}.txt", i),
-                is_directory: i % 10 == 0, // Every 10th entry is a directory
-                size: Some(1024 * (i as u64)),
-                modified_at: Some(1640000000 + i as u64),
+            .map(|i| {
+                let is_dir = i % 10 == 0;
+                let name = format!("file_{:06}.txt", i);
+                FileEntry {
+                    name: name.clone(),
+                    path: format!("/mock/file_{:06}.txt", i),
+                    is_directory: is_dir,
+                    is_symlink: i % 50 == 0, // Every 50th is a symlink for testing
+                    size: Some(1024 * (i as u64)),
+                    modified_at: Some(1640000000 + i as u64),
+                    created_at: Some(1639000000 + i as u64),
+                    permissions: 0o644,
+                    owner: "testuser".to_string(),
+                    group: "staff".to_string(),
+                    icon_id: if is_dir {
+                        "dir".to_string()
+                    } else {
+                        "ext:txt".to_string()
+                    },
+                }
             })
             .collect();
         Self::new(entries)

src-tauri/src/file_system/mock_provider.rs

@@ -10,15 +10,27 @@ fn test_mock_provider_returns_entries() {
             name: "test.txt".to_string(),
             path: "/test/test.txt".to_string(),
             is_directory: false,
+            is_symlink: false,
             size: Some(1024),
             modified_at: Some(1640000000),
+            created_at: Some(1639000000),
+            permissions: 0o644,
+            owner: "testuser".to_string(),
+            group: "staff".to_string(),
+            icon_id: "ext:txt".to_string(),
         },
         FileEntry {
             name: "folder".to_string(),
             path: "/test/folder".to_string(),
             is_directory: true,
+            is_symlink: false,
             size: None,
             modified_at: Some(1640000000),
+            created_at: Some(1639000000),
+            permissions: 0o755,
+            owner: "testuser".to_string(),
+            group: "staff".to_string(),
+            icon_id: "dir".to_string(),
         },
     ];