Type more IPC commands + sustainability for the bindings

Tightens the typed-IPC surface added in `f1e58011` and shores up the regen / sustainability story.

Group A — drop `skip_serializing_if` to unblock specta

Removed `#[serde(skip_serializing_if = "Option::is_none")]` (and `Vec::is_empty` variants) from `FileEntry`, `PaneState`, `MtpDeviceInfo`, `MtpStorageInfo`, `LocationInfo` (macOS / Linux / stub), `NetworkHost`, and `BundleManifest` fields. Wire format goes from "field absent" to explicit `null` / `[]`. specta's `validate_exported_command` now accepts the types, unblocking 9 commands: `get_file_range`, `get_file_at`, `get_files_at_indices`, `update_left_pane_state`, `update_right_pane_state`, `list_mtp_devices`, `connect_mtp_device`, `get_mtp_device_info`, `get_mtp_storages`, `list_mtp_directory`, `list_volumes`, `resolve_path_volume`, `list_network_hosts`, `resolve_host`, `connect_to_server`.

FE side: migrated each call site from raw `invoke()` to `commands.foo(...)`, dropped the `cmdr/no-raw-tauri-invoke` opt-out comments, fixed four `=== undefined` → `!= null` patterns that the change broke (`smbConnectionState`, `recursiveSize`, `displaySize` × 2). Renamed an inner `FileEntry` in `mcp/pane_state.rs` to `PaneFileEntry` to avoid a name collision with the real `FileEntry` once both types crossed the IPC boundary.

Group B (first 3) — replace `serde_json::Value` at IPC boundaries

- `check_pending_crash_report` / `send_crash_report`: dropped the noop `serde_json::to_value` / `Value` wrapper. The commands now take/return `CrashReport` directly. `CrashReport` and `ActiveSettings` got `#[derive(specta::Type)]` (kept `Deserialize` since the on-disk crash file format still round-trips through it).
- `record_settings_defaults`: replaced `HashMap<String, serde_json::Value>` with `HashMap<String, SettingValue>` where `SettingValue` is an untagged `Bool | Integer | String` enum. The TS surface lands as `boolean | number | string` — covers every value type the registry actually carries.

`record_breadcrumb` stays on raw `invoke()` deliberately. Free-form `ctx` is the design intent for breadcrumbs; none of the typed alternatives (string-only map, JSON-encoded string, tagged-union by `kind`) is genuinely better. `prepare_error_report_preview` stays excluded for the same reason (its `BundleManifest.breadcrumbs` carries the same `Option<Value>`); a future decoupling via `BreadcrumbForManifest { ctx_json: Option<String> }` is documented in `lib/ipc/CLAUDE.md` if it ever becomes worthwhile.

Sustainability wiring

- `export_bindings_test` is now `#[ignore]`d so plain `cargo nextest run` doesn't silently rewrite `bindings.ts` as a test side effect.
- `pnpm bindings:regen` (in `apps/desktop/package.json`) is the canonical regen command — runs the ignored test, then `oxfmt`s the output so the file lands in project format (single quotes, no semis, 2-space indent — which is what `oxfmt` enforces; my earlier confusion about "oxfmt is lenient" was wrong, the file just was already formatted).
- `bindings-fresh` check (Go, `desktop-bindings-fresh.go`) snapshots the committed file, runs the regen, byte-compares, restores the snapshot. Fails on drift with a pointer to `pnpm bindings:regen`. CI catches stale bindings without touching the working tree.
- `lib/ipc/CLAUDE.md` documents the named-variables call-site convention, the "adding a new Tauri command" recipe, the type-shape constraints (`skip_serializing_if`, `serde_json::Value`), the trimmed exclusion table, the version-bump procedure, and the future-work decoupling note.
- `lib/tauri-commands/CLAUDE.md` § Key patterns now reflects that wrappers delegate to the typed bindings; raw `invoke` is the exception (with the documented opt-out).
- AGENTS.md "Type-safe IPC" entry links to the regen flow and the named-variables rule.
- `knip.json` ignores `oxfmt` as an unlisted binary (used by `bindings:regen`).

Numbers

- 4 commands remain excluded (down from 14): `record_breadcrumb`, `prepare_error_report_preview`, `store_font_metrics`, `stream_folder_suggestions`/`cancel_folder_suggestions`. Each has a documented reason and conversion plan.
- All 45 checks pass. 1601 Rust + 1716 Svelte + 124 API + 67 Astro e2e + 28 Rust integration tests pass. `bindings-fresh` confirms `bindings.ts` is in sync.

Author: vdavid

AGENTS.md

@@ -219,6 +219,13 @@ resilience, and common pitfalls.
   bindings into `apps/desktop/src/lib/ipc/`; call them as `commands.commandName(args)` instead.
   - **Enforced by**: `cmdr/no-raw-tauri-invoke` (ESLint rule). Bypassed only inside `lib/ipc/` (the bindings),
     `routes/debug/` (dev-only debug panels), and test files.
+  - **Regenerate** with `cd apps/desktop && pnpm bindings:regen` after any change to a `#[tauri::command]` surface or a
+    Type-derived DTO. CI's `bindings-fresh` check fails if the committed `bindings.ts` is stale.
+  - **At call sites, prefer named locals over inline primitives.** `commands.renameFile(from, to, force, volumeId)` is
+    fine; `commands.foo(true, null, 5)` isn't — extract `const force = true; const volumeId = null; const retries = 5`
+    first. This is the price specta charges for type safety.
+  - For the rules around adding new commands, type shape constraints (`skip_serializing_if`, `serde_json::Value`), and
+    the current exclusion list, read [`apps/desktop/src/lib/ipc/CLAUDE.md`](apps/desktop/src/lib/ipc/CLAUDE.md).
 
 ## Workflow
 

apps/desktop/knip.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "ignoreBinaries": ["only-allow", "rustc"],
+  "ignoreBinaries": ["only-allow", "rustc", "oxfmt"],
   "ignore": ["src/lib/tauri-commands/**", "src/lib/ipc/bindings.ts"],
   "ignoreUnresolved": ["~icons/.+"],
   "ignoreDependencies": [

apps/desktop/package.json

@@ -27,7 +27,8 @@
     "test:e2e:playwright": "npx playwright test --config test/e2e-playwright/playwright.config.ts --project tauri",
     "test:e2e:playwright:build": "node scripts/tauri-wrapper.js build --no-bundle --target $(rustc -vV | grep host | cut -d' ' -f2) -- --features playwright-e2e,virtual-mtp",
     "knip": "knip",
-    "check:type-drift": "tsx scripts/check-type-drift.ts"
+    "check:type-drift": "tsx scripts/check-type-drift.ts",
+    "bindings:regen": "cd src-tauri && cargo nextest run --no-fail-fast --run-ignored=ignored-only ipc::tests::export_bindings_test && cd .. && pnpm exec oxfmt src/lib/ipc/bindings.ts"
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {

apps/desktop/src-tauri/src/commands/crash_reporter.rs

@@ -3,7 +3,7 @@
 //! Thin wrappers for crash file detection, dismissal, and sending.
 
 use crate::config;
-use crate::crash_reporter;
+use crate::crash_reporter::{self, CrashReport};
 
 /// Server URL for crash report ingestion.
 #[cfg(debug_assertions)]
@@ -13,12 +13,11 @@ const CRASH_REPORT_URL: &str = "http://localhost:8787/crash-report";
 const CRASH_REPORT_URL: &str = "https://api.getcmdr.com/crash-report";
 
 /// Checks for a pending crash report from a previous session.
-/// Returns the report as a JSON value, or `null` if none exists.
+/// Returns the report, or `null` if none exists.
 #[tauri::command]
 #[specta::specta]
-pub fn check_pending_crash_report(app: tauri::AppHandle) -> Option<serde_json::Value> {
-    let report = crash_reporter::take_pending_crash_report(&app)?;
-    serde_json::to_value(report).ok()
+pub fn check_pending_crash_report(app: tauri::AppHandle) -> Option<CrashReport> {
+    crash_reporter::take_pending_crash_report(&app)
 }
 
 /// Deletes the crash report file without sending it.
@@ -36,7 +35,7 @@ pub fn dismiss_crash_report(app: tauri::AppHandle) {
 /// Skipped in dev mode and CI to avoid polluting production data.
 #[tauri::command]
 #[specta::specta]
-pub async fn send_crash_report(app: tauri::AppHandle, report: serde_json::Value) -> Result<(), String> {
+pub async fn send_crash_report(app: tauri::AppHandle, report: CrashReport) -> Result<(), String> {
     let should_skip = cfg!(debug_assertions) || std::env::var("CI").is_ok();
 
     if !should_skip {

apps/desktop/src-tauri/src/commands/error_reporter.rs

@@ -3,7 +3,9 @@
 //! Two preview/send commands plus a debug-only save-to-disk command. Business logic lives
 //! in `crate::error_reporter` — these wrappers just shape inputs/outputs for the IPC layer.
 
-use crate::error_reporter::{self, BundleKind, BundleManifest, BundleScope, FLOW_A_BUNDLE_CAP_MB};
+use crate::error_reporter::{
+    self, BundleKind, BundleManifest, BundleScope, FLOW_A_BUNDLE_CAP_MB, settings_defaults::SettingValue,
+};
 use serde::Serialize;
 use std::collections::HashMap;
 
@@ -28,7 +30,7 @@ const MAX_USER_NOTE_CHARS: usize = 100_000;
 /// is missing or doesn't include a given key.
 #[tauri::command]
 #[specta::specta]
-pub fn record_settings_defaults(defaults: HashMap<String, serde_json::Value>) {
+pub fn record_settings_defaults(defaults: HashMap<String, SettingValue>) {
     error_reporter::settings_defaults::record(defaults);
 }
 

apps/desktop/src-tauri/src/crash_reporter/mod.rs

@@ -27,7 +27,7 @@ static APP_START_TIME: OnceLock<Instant> = OnceLock::new();
 static CACHED_SETTINGS: OnceLock<ActiveSettings> = OnceLock::new();
 
 /// Active settings snapshot cached at startup for inclusion in crash reports.
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, specta::Type)]
 #[serde(rename_all = "camelCase")]
 pub struct ActiveSettings {
     pub indexing_enabled: Option<bool>,
@@ -37,7 +37,7 @@ pub struct ActiveSettings {
 }
 
 /// The crash report written to disk (JSON).
-#[derive(Debug, Serialize, Deserialize)]
+#[derive(Debug, Serialize, Deserialize, specta::Type)]
 #[serde(rename_all = "camelCase")]
 pub struct CrashReport {
     pub version: u32,

apps/desktop/src-tauri/src/error_reporter/mod.rs

@@ -288,9 +288,7 @@ pub struct BundleManifest {
     /// first. The last entry of `kind: "command"` is the most recent user-driven UI
     /// command. Empty when nothing was recorded (e.g. very early failures, tests).
     /// See `breadcrumbs.rs` for the buffer semantics.
-    #[serde(skip_serializing_if = "Vec::is_empty", default)]
     pub breadcrumbs: Vec<breadcrumbs::Breadcrumb>,
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub user_note: Option<String>,
     pub generated_at: String,
 }
@@ -1182,39 +1180,67 @@ pub mod log_level_overrides {
 /// Reads are O(1) hash lookups; the mutex is uncontended in practice (one writer at
 /// FE init, then read-only).
 pub mod settings_defaults {
-    use serde_json::Value;
+    use serde::{Deserialize, Serialize};
     use std::collections::HashMap;
     use std::sync::Mutex;
 
-    static DEFAULTS: Mutex<Option<HashMap<String, Value>>> = Mutex::new(None);
+    /// Settings registry default values pushed from FE. The wire format matches JSON
+    /// primitives via `#[serde(untagged)]` — TS sees `boolean | number | string`.
+    /// Extend with more variants only when settings of the new shape appear; any field
+    /// shape outside this set means the value can't fit in `lookup_*` helpers anyway.
+    #[derive(Debug, Clone, Serialize, Deserialize, specta::Type)]
+    #[serde(untagged)]
+    pub enum SettingValue {
+        Bool(bool),
+        Integer(i64),
+        String(String),
+    }
+
+    static DEFAULTS: Mutex<Option<HashMap<String, SettingValue>>> = Mutex::new(None);
 
     /// Replace the stored defaults map. Called from the `record_settings_defaults`
     /// Tauri command. A `None` entry from a buggy FE caller is treated as "no
     /// default available" — `lookup_*` falls through to the hardcoded fallback.
-    pub fn record(map: HashMap<String, Value>) {
+    pub fn record(map: HashMap<String, SettingValue>) {
         if let Ok(mut guard) = DEFAULTS.lock() {
             *guard = Some(map);
         }
     }
 
-    fn get(key: &str) -> Option<Value> {
+    fn get(key: &str) -> Option<SettingValue> {
         DEFAULTS.lock().ok()?.as_ref()?.get(key).cloned()
     }
 
     pub(super) fn lookup_bool(key: &str) -> Option<bool> {
-        get(key)?.as_bool()
+        if let SettingValue::Bool(b) = get(key)? {
+            Some(b)
+        } else {
+            None
+        }
     }
 
     pub(super) fn lookup_string(key: &str) -> Option<String> {
-        Some(get(key)?.as_str()?.to_string())
+        if let SettingValue::String(s) = get(key)? {
+            Some(s)
+        } else {
+            None
+        }
     }
 
     pub(super) fn lookup_u16(key: &str) -> Option<u16> {
-        u16::try_from(get(key)?.as_u64()?).ok()
+        if let SettingValue::Integer(n) = get(key)? {
+            u16::try_from(n).ok()
+        } else {
+            None
+        }
     }
 
     pub(super) fn lookup_u64(key: &str) -> Option<u64> {
-        get(key)?.as_u64()
+        if let SettingValue::Integer(n) = get(key)? {
+            u64::try_from(n).ok()
+        } else {
+            None
+        }
     }
 
     #[cfg(test)]

apps/desktop/src-tauri/src/error_reporter/tests.rs

@@ -500,9 +500,8 @@ fn set_mtime_to_age(path: &Path, age: Duration) {
 /// fields are `None`.
 mod settings_defaults_tests {
     use super::*;
-    use crate::error_reporter::settings_defaults;
+    use crate::error_reporter::settings_defaults::{self, SettingValue};
     use crate::settings::loader::Settings;
-    use serde_json::json;
     use std::collections::HashMap;
     use std::sync::Mutex;
 
@@ -544,9 +543,9 @@ mod settings_defaults_tests {
         // FE registry says indexing is OFF by default (hypothetical — production says
         // true). If `from_settings` ever drifts back to the hardcoded fallback, this
         // test catches it.
-        map.insert("indexing.enabled".to_string(), json!(false));
-        map.insert("developer.mcpPort".to_string(), json!(12345));
-        map.insert("ai.provider".to_string(), json!("cloud"));
+        map.insert("indexing.enabled".to_string(), SettingValue::Bool(false));
+        map.insert("developer.mcpPort".to_string(), SettingValue::Integer(12345));
+        map.insert("ai.provider".to_string(), SettingValue::String("cloud".to_string()));
         settings_defaults::record(map);
 
         // Field with no user override → FE default applies.
@@ -576,8 +575,12 @@ mod settings_defaults_tests {
         settings_defaults::reset_for_test();
 
         let mut map = HashMap::new();
-        map.insert("indexing.enabled".to_string(), json!("not a bool"));
-        map.insert("developer.mcpPort".to_string(), json!(true));
+        // Wrong types for these fields: String instead of Bool, Bool instead of Integer.
+        map.insert(
+            "indexing.enabled".to_string(),
+            SettingValue::String("not a bool".to_string()),
+        );
+        map.insert("developer.mcpPort".to_string(), SettingValue::Bool(true));
         settings_defaults::record(map);
 
         let resolved = ResolvedSettings::from_settings(&Settings::default());

apps/desktop/src-tauri/src/file_system/listing/metadata.rs

@@ -68,8 +68,8 @@ pub(crate) fn get_icon_id(is_dir: bool, is_symlink: bool, name: &str) -> String
 /// Represents a file or directory entry with extended metadata.
 ///
 /// Only serialized (Rust → frontend); never sent from the frontend, so no `Deserialize`.
-/// The `Deserialize`-less derive prevents specta from splitting the type on
-/// `skip_serializing_if` fields, which would fail `validate_exported_command`.
+/// Fields that were previously omitted when `None`/empty now serialize as explicit `null`
+/// so specta's `validate_exported_command` accepts the type in Unified mode.
 #[derive(Debug, Clone, Serialize, specta::Type)]
 #[serde(rename_all = "camelCase")]
 pub struct FileEntry {
@@ -79,8 +79,6 @@ pub struct FileEntry {
     pub is_symlink: bool,
     pub size: Option<u64>,
     /// Physical size on disk in bytes (st_blocks * 512 on Unix, same as size on other platforms)
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub physical_size: Option<u64>,
     pub modified_at: Option<u64>,
     pub created_at: Option<u64>,
@@ -96,35 +94,23 @@ pub struct FileEntry {
     /// Always true for legacy list_directory(), false for list_directory_core()
     pub extended_metadata_loaded: bool,
     /// Recursive size in bytes (from drive index, None if not indexed)
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub recursive_size: Option<u64>,
     /// Recursive physical size on disk in bytes (from drive index, None if not indexed)
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub recursive_physical_size: Option<u64>,
     /// Recursive file count (from drive index, None if not indexed)
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub recursive_file_count: Option<u64>,
     /// Recursive dir count (from drive index, None if not indexed)
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub recursive_dir_count: Option<u64>,
     /// True when the subtree contains symlinks (whose content is omitted from the
     /// recursive size). Drives the "size omits symlinked content" hint in the UI.
     /// `None` when the directory isn't indexed yet.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub recursive_has_symlinks: Option<bool>,
     /// When set on a virtual entry, the frontend navigates to this path
     /// instead of treating the entry as a normal directory listing.
     /// Inert until M3 wires it for `worktrees/` and `submodules/`. Lives on
     /// the schema from M1 so M3 doesn't have to ripple a change through every
     /// consumer (frontend list views, MCP `cmdr://state`, drag-drop, copy
     /// preview, Brief/Full renderers).
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub redirect_to_path: Option<String>,
     /// Loose Size-column override for virtual git entries: rendered verbatim
     /// in the Full mode Size column instead of formatted bytes from `size`.
@@ -133,14 +119,10 @@ pub struct FileEntry {
     /// branches, files-changed for commits, item count for category roots).
     /// Cross-category Size sorting is meaningless and that's an honest
     /// tradeoff — each cell is self-explaining via tooltip + aria-label.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub display_size: Option<String>,
     /// Optional rich tooltip string for the Size cell, used when
     /// `display_size` is set. Example: "12 commits ahead, 3 commits behind
     /// `origin/main`". Doubles as the aria-label for screen readers.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[specta(optional)]
     pub display_size_tooltip: Option<String>,
 }