Jake
26c7307607
Phase 9 of the rebrand cascade. Sweep covers everything the Phase 8
frontend pass deliberately skipped: docs/, root markdown, scripts,
Cargo.toml descriptions, code comments that survived earlier
word-boundary sed, plus a handful of identifiers caught on the final
verify pass.
transcription-app changes:
- README.md, HANDOVER.md, KNOWN-ISSUES.md, run.sh — magnotia/Magnotia
-> lumotia/Lumotia.
- docs/ — sweep across all subdirs except docs/handovers/ (preserved
as immutable audit trail). Includes architecture-map references
to magnotia_core::*, magnotia_storage::*, etc. now pointing at
lumotia_*; dev-setup.md tracing output examples (lumotia_startup
target); brief/ + superpowers/ + issues/ + whisper-ecosystem/ +
audit/.
- Cargo.toml descriptions on 9 crates (core, audio, cloud-providers,
hotkey, llm, mcp, plus referenced others).
- crates/core/src/{error,hardware,recommendation,paths}.rs +
crates/audio/src/wav.rs + crates/llm/src/model_manager.rs +
crates/cloud-providers/src/keystore.rs + crates/mcp/src/lib.rs —
doc comments and a model-manager user-agent string.
- Caught on final pass: BroadcastChannel("magnotia_task_sync") -> ...
("lumotia_task_sync"); magnotia_locale i18n localStorage key
renamed + migration shim added; CSS keyframe names
magnotiaPulse / magnotiaBar / magnotiaFade renamed in the design-
system kit; magnotia_viewer_item / magnotia_viewer_mode handoff
keys renamed in HistoryPage + viewer/+page.svelte; src/assets/
wordmark.svg text.
- src-tauri/src/lib.rs comment cleanup ("magnotia era" was sed'd
to "lumotia era" earlier — restored).
Preserved (intentional):
- crates/core/src/paths.rs — keeps "magnotia" / "Magnotia" / ".magnotia"
legacy detection strings in legacy_and_target_paths() so the
migration shim can still find user data from the magnotia era.
- src/lib/stores/{page,focusTimer}.svelte.ts + src/lib/i18n/index.ts
— migration call sites reference the legacy magnotia keys
deliberately.
- docs/handovers/ — historical audit trail.
cargo build --workspace passes. npm run check: 0 errors / 0 warnings
(3958 files). cargo test --workspace: 339 pass / 0 fail.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
112 lines
7.4 KiB
Markdown
112 lines
7.4 KiB
Markdown
---
|
|
name: Diagnostics and reports
|
|
type: architecture-map-page
|
|
slice: 02-tauri-runtime
|
|
last_verified: 2026/05/09
|
|
---
|
|
|
|
# `commands::diagnostics`
|
|
|
|
> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Diagnostics
|
|
|
|
**Plain English summary.** The local-only diagnostic plumbing. Installs the Rust panic hook (writes per-panic dumps to `crashes_dir`). Captures frontend errors via a global `window.onerror` handler. Lists recent error-log rows and crash files. Bundles a markdown diagnostic report (settings, recent errors, active power assertions, crash dumps, log tail) so the user can paste it into an email or GitHub issue. Privacy posture: nothing is transmitted; the user reviews exactly what would be shared before sharing it.
|
|
|
|
## At a glance
|
|
|
|
- Path: `src-tauri/src/commands/diagnostics.rs`.
|
|
- LOC: 534.
|
|
- Tauri commands exposed (6 total):
|
|
- `log_frontend_error(state, context, message, stack: Option<String>) -> Result<(), String>`. No window guard — fires from any window's global error handler.
|
|
- `list_recent_errors_command(window, state, limit) -> Result<Vec<ErrorLogDto>, String>`. Main-window only.
|
|
- `list_crash_files(window) -> Result<Vec<CrashFile>, String>`. Main-window only.
|
|
- `generate_diagnostic_report(window, state, options: Option<ReportOptions>) -> Result<String, String>`. Main-window only.
|
|
- `save_diagnostic_report(window, app, state, options) -> Result<String, String>`. Main-window only. Returns the absolute file path it wrote.
|
|
- `get_os_info() -> OsInfo`.
|
|
- Public Rust helper used by `lib.rs::run`: `install_panic_hook()`.
|
|
- Events emitted: none.
|
|
- Depends on: `lumotia_storage::{app_data_dir, crashes_dir, list_recent_errors, log_error, logs_dir, ErrorLogRow}`, `commands::power::active_assertions_snapshot`, `commands::security::ensure_main_window`. Plus `std::fs`, `std::panic`, `std::time`.
|
|
- Called from frontend at: global `window.onerror` / `window.unhandledrejection` (`log_frontend_error`); Settings → About → Diagnostics (the bundle commands and `list_*` commands); top-of-app Cmd-vs-Ctrl labelling (`get_os_info`).
|
|
|
|
## What's in here
|
|
|
|
### Constants (`src-tauri/src/commands/diagnostics.rs:26`)
|
|
|
|
- `DEFAULT_RECENT_ERRORS = 50`.
|
|
- `MAGNOTIA_VERSION = env!("CARGO_PKG_VERSION")`.
|
|
|
|
### `install_panic_hook` (`:34`)
|
|
|
|
Creates `crashes_dir()` if missing. Replaces the default panic hook with one that writes a minimal text dump to `crashes_dir/<unix_secs>-<short_hash>.crash` and then chains to the original hook so the panic still hits stderr. Dump includes version, timestamp, thread name, panic message, OS, arch, RUST_BACKTRACE env. Backtraces require `RUST_BACKTRACE=1` and `std::backtrace` plumbing — neither set up today, so production crashes will lack stack traces.
|
|
|
|
### `log_frontend_error` (`:86`)
|
|
|
|
Truncates the stack to 2,000 chars and calls `lumotia_storage::log_error` with context `"frontend"` (or the caller-supplied context), error code `"FRONTEND_ERROR"`, the message, and the stack as metadata.
|
|
|
|
### `ErrorLogDto` (`:114`) and `list_recent_errors_command` (`:138`)
|
|
|
|
`ErrorLogDto` is a camelCase shape over `ErrorLogRow`. The list command clamps `limit` to `[1, 1000]` and defaults to 50.
|
|
|
|
### `CrashFile` and `list_crash_files` (`:152`, `:162`)
|
|
|
|
`CrashFile` exposes filename, mtime_secs, size_bytes, plus a 600-char preview. `list_crash_files_inner` reads the crashes directory, builds the structs, sorts by mtime descending.
|
|
|
|
### Report options and assembler
|
|
|
|
- `ReportOptions` has four boolean flags: `include_settings`, `include_recent_errors`, `include_crashes`, `include_log_tail` (each defaulting true).
|
|
- `redact_home(input)` replaces `home_dir().display()` substrings with `~`.
|
|
- `looks_sensitive_key(key)` flags keys containing `apikey` / `token` / `secret` / `password` / `bearer`.
|
|
- `redact_json_value(value, key_hint)` recursively walks a JSON value redacting strings under sensitive keys.
|
|
- `sanitise_preferences_json(raw)` parses, redacts, re-emits.
|
|
- `redact_line(input)` does line-level redaction for the error-message field.
|
|
|
|
### `generate_diagnostic_report_inner` (`:307`)
|
|
|
|
Builds a markdown document with sections:
|
|
|
|
1. Header (version, OS / arch, app data dir, generated timestamp, "local-only until you choose to share" notice).
|
|
2. Settings (sanitised JSON via `sanitise_preferences_json`).
|
|
3. Recent errors (50 rows, redacted).
|
|
4. Power assertions (snapshots from `commands::power::active_assertions_snapshot`).
|
|
5. Crash dumps (up to 5 most-recent, plus a count of older ones).
|
|
6. Log tail (8 KB tail of `logs_dir/lumotia.log`, home-redacted).
|
|
|
|
### `save_diagnostic_report` (`:513`)
|
|
|
|
Generates the report, then writes it to `app_data_dir/diagnostic-reports/lumotia-diagnostic-<unix_secs>.md`. Returns the absolute path.
|
|
|
|
### `OsInfo` and `get_os_info` (`:449`, `:474`)
|
|
|
|
OS family label, arch, `uses_cmd` boolean (macOS only), `is_wayland` boolean (Linux only), `custom_hotkey_backend` (Linux only — true because evdev is the primary path on Linux), and `primary_modifier_label` (`"Cmd"` on macOS, `"Ctrl"` elsewhere). Frontend reads this once at boot to set the hotkey labels and "Open file location" terminology.
|
|
|
|
## Data flow
|
|
|
|
```
|
|
panic occurs -> install_panic_hook writes crashes_dir/<ts>.crash
|
|
window.onerror fires in JS -> invoke('log_frontend_error', context, message, stack)
|
|
-> lumotia_storage::log_error
|
|
-> error_log table
|
|
|
|
Settings -> About -> Diagnostics
|
|
list_crash_files -> [CrashFile, ...]
|
|
list_recent_errors_command -> [ErrorLogDto, ...]
|
|
generate_diagnostic_report(opts) -> markdown string
|
|
user reviews, then optionally:
|
|
save_diagnostic_report(opts) -> absolute path
|
|
```
|
|
|
|
## Watch-outs
|
|
|
|
- **No backtraces in production crashes.** `RUST_BACKTRACE` is not set in the packaged binary. Either set it in a launcher script or call `std::backtrace::Backtrace::capture()` inside the panic hook.
|
|
- **`log_frontend_error` is unguarded by ACL or window-label check.** Any window can log a frontend error. That is fine, but the storage layer should enforce a row-rate limiter before this surface ever ships to users with adversarial workloads.
|
|
- **Crash file prefixes are unix-seconds-and-a-16-bit-hash.** Two panics in the same second with the same low-16-bits of seconds will collide. Vanishingly unlikely in practice. If you want bulletproof, use the same counter pattern as `commands::audio::recording_filename`.
|
|
- **Diagnostic report is markdown by design** so it can be pasted anywhere. If you ever want a structured upload format, keep this command and add a sibling that returns JSON.
|
|
- **Sensitive-key redaction is a heuristic.** It catches the obvious names (`api_key`, `apiKey`, `token`, `Bearer`) but won't catch a user-named key like `mySecretToken: "abc"` if the key string is normalised to lowercase first. Fine for "user reviews before sharing"; not fine if you ever auto-upload.
|
|
- **`ensure_main_window` is missing on `log_frontend_error` and `get_os_info`.** Intentional — both should be callable from any window. But document this so future tightening attempts know to leave them alone.
|
|
|
|
## See also
|
|
|
|
- [App lifecycle](../app-lifecycle.md) — `install_panic_hook` is called from setup.
|
|
- [Power assertions and security](power-and-security.md) — `active_assertions_snapshot` feeds the report.
|
|
- [Capabilities and ACL](../capabilities-and-acl.md) — the report is local until the user chooses to share.
|
|
- [Tests](../tests.md) — no specific test for the report itself, but the redactor helpers could use unit coverage.
|