zapstore/spec/features/FEAT-005-diagnostic-logs.md

FEAT-005 — Local Diagnostic Logs

Goal

Capture rich, structured diagnostic logs and uncaught errors to local storage so users can export and share them through any channel of their choosing. Nothing leaves the device automatically.

Non-Goals

• No remote upload, telemetry, or analytics of any kind.
• No opt-in "send report" path. Sharing is always user-initiated via the OS share sheet.
• No structured query language; a simple text filter is enough.
• No log streaming over ADB or web sockets (developers already have flutter logs).
• No replacement for in-app user-facing error UI (toasts, error overlays). Logs are diagnostic, not UX.

Core Principles

• Local-only. Logs never leave the device unless the user explicitly exports and shares them.
• Always on. Default level in release builds is debug. There is no production "off" switch — logs are how we diagnose field issues.
• Crash-safe. Logs written before a crash MUST survive the crash and be readable on next launch.
• Non-blocking. Logging MUST NOT block the UI thread. Writes are batched and flushed on a background queue.
• Secret-safe. Sensitive values (signing keys, NWC URIs, encrypted-DM plaintext) MUST be redacted at write time, not at export time.

Capture Surface

All four error sinks below MUST be wired in main(), set up before runApp is called inside the guarded zone:

Sink	Source captured
FlutterError.onError	Sync framework errors (build, layout, paint)
PlatformDispatcher.instance.onError	Engine and uncaught Dart errors not in a guarded zone
runZonedGuarded	Async errors originating inside the app's root zone
Isolate.current.addErrorListener	Uncaught errors from the main isolate that bypass zones

Background isolates we own — at minimum the workmanager callbackDispatcher in lib/services/background_update_service.dart — MUST install the same four handlers and write to the shared log file.

The framework console dump (FlutterError.presentError / dumpErrorToConsole) MUST still run in debug builds so devs see errors in flutter run output.

Storage Model

• Path: getApplicationSupportDirectory()/logs/zapstore.log with rotation zapstore.log.1 … zapstore.log.5.
• Format: NDJSON, one record per line. Each record contains:
  • ts — ISO-8601 UTC timestamp
  • level — trace | debug | info | warn | error | fatal
  • tag — short logical area (e.g. package_manager, relay, signer)
  • msg — human-readable message
  • fields — optional flat map of structured context
  • err — error string if any
  • stack — stack trace string if any
  • isolate — main | workmanager | other named isolate
• Rotation: when zapstore.log exceeds 10 MB, rotate. Keep at most 5 historical files. Total disk budget ≤ 60 MB.
• All isolates write to the same active log file using append-mode writes plus an OS advisory file lock (flock/LOCK_EX) per batch.
• An in-memory ring buffer of the last 500 entries is maintained on the main isolate for fast in-app viewing without disk reads.

User-Visible Behavior

A new "Diagnostics" section in the profile/settings screen exposes:

• View recent logs — full-screen scrollable viewer backed by the ring buffer plus the tail of the active log file. Supports:
  • Level filter (chips: debug / info / warn / error)
  • Free-text filter
  • Copy-to-clipboard for any single entry
• Export logs — bundles all rotated log files into zapstore-logs-<UTC-timestamp>.zip in the cache directory and opens the OS share sheet via share_plus. The user picks the destination (Signal, email, Files, etc.).
• Clear logs — confirms with a dialog, then deletes all log files and clears the ring buffer.
• Log level — selector for debug (default) / info / warn. Persisted in SettingsService.

States required:

• Empty (no logs yet) — viewer shows "No logs yet"; Export shows toast "No logs to export" and does not open the share sheet.
• Large export — show file size before opening the share sheet so the user can cancel.
• Disk error during export — toast with the error; do not open share sheet.

Redaction

At write time, the logger MUST redact:

• Any string matching nsec1[ac-hj-np-z02-9]+
• Any string matching ncryptsec1[ac-hj-np-z02-9]+
• NWC connection URIs (nostr+walletconnect://...)
• Plaintext content of NIP-04 (kind 4), NIP-44 / NIP-17 (kind 13, 1059) events
• Values stored in flutter_secure_storage

Redaction replaces the value with [REDACTED:<kind>]. Public Nostr event JSON (kinds outside the list above) is not redacted — debuggability of public data is preferred.

A unit test MUST assert that none of the above patterns can appear in the log output even if passed as msg, fields, err, or stack.

Riverpod Integration

A ProviderObserver MUST be installed on the root ProviderContainer to log:

• Provider build failures (providerDidFail) at error level
• StorageError states emitted from query<T> providers at warn level

This gives automatic coverage of the standard Riverpod async-error path described in ARCHITECTURE.md.

Edge Cases

• Disk full — drop the oldest rotated file, then drop new entries; emit one warn to stderr per minute max so we don't loop.
• Corrupted log file — on read, tolerate malformed lines (skip them); on write, never fail the app.
• Logs directory missing or read-only — disable disk logging for the session, keep ring buffer working, surface a single warning entry.
• Concurrent writes from multiple isolates — serialised via file lock; entries from different isolates may interleave at line granularity but never at byte granularity.
• Crash mid-write — file is append-only with line-flushed writes; the worst case is a truncated final line, which the reader skips.
• Clock skew / device time wrong — record ts as device clock; do not attempt correction.
• Export with no logs — surface "No logs to export"; do not produce an empty zip.
• Export while writing — copy/snapshot files into the cache dir before zipping so the share is consistent.
• Very large fields value — truncate any single string field to 4 KB; replace with …(truncated).

Acceptance Criteria

• All four error sinks (FlutterError.onError, PlatformDispatcher.onError, runZonedGuarded, Isolate.addErrorListener) are wired in main() and route to LogService.
• The workmanager callbackDispatcher installs the same handlers and writes to the shared log file.
• Triggering each of: a sync UI exception, an async future error, an uncaught isolate error, and a workmanager task error each produces a fatal/error entry visible after app restart.
• Logs persist across app restart and rotate at 10 MB; at most 5 rotations are kept.
• Logging never blocks the UI thread (verified by a stress test of 1000 entries/sec for 5 s with no dropped frames).
• No log line ever contains an nsec1…, ncryptsec1…, nostr+walletconnect://…, or kind-4/13/1059 plaintext (verified by unit test).
• In-app viewer shows ring-buffer + on-disk tail, supports level and text filter, supports copy.
• Export produces a zapstore-logs-<ts>.zip and opens the OS share sheet; nothing is sent automatically.
• Clear logs removes all files and empties the ring buffer.
• App boots cleanly when logs/ is missing, read-only, or contains a corrupted file.
• Existing 7 debugPrint sites are converted to LogService calls in the same change.
• A ProviderObserver logs provider failures and StorageError states.

Notes

• Log level for release builds is debug by intent — see Goal/Core Principles. There is no network cost and the file is size-capped.
• A future feature may add a one-tap "share with developer" button, but it MUST go through the same user-initiated export flow. No background upload will ever be added under this feature.