[PLAN 06] Ustalić konfigurację aplikacji, CLI i katalogi XDG

[KeyffMS]

Cel

Zapewnić jeden prosty mechanizm konfiguracji, uruchamiania i rozmieszczenia plików zgodny z XDG, bez ukrytych źródeł ustawień i bez rozproszonego I/O.

Decyzje bezalternatywne

• vfd-lantern bez subkomendy uruchamia TUI.
• Konfiguracja jest typowanym TOML.
• Priorytet: defaults → config użytkownika → jawne CLI.
• SettingsLoader jest jedynym miejscem łączenia źródeł.
• Wynikiem jest jedna niezmienna ValidatedSettings.
• Jedyną zmienną środowiskową aplikacji jest VFD_LANTERN_LOG.
• --enable-writes istnieje wyłącznie jako procesowa bramka CLI.

Katalogi XDG

Wyznacza je directories, a operacje plikowe wykonuje lantern-storage.

XDG config

• konfiguracja użytkownika;
• profile użytkownika;
• ProfileTrustStore;
• bezpieczne preferencje TUI.

XDG data

• backupy;
• CSV;
• finalny sidecar <csv>.session.json znajdujący się obok odpowiadającego CSV;
• wyeksportowane fault reports;
• jawnie utworzone pakiety diagnostyczne;
• inne przenośne artefakty użytkownika.

XDG state

• logi diagnostyczne;
• audit journal i head;
• session-runtime-<SessionId>-<LoggingId>.json — roboczy checkpoint konkretnej operacji logowania, odrębny od przenośnego sidecara CSV;
• panic reports;
• stan potrzebny do diagnostyki przerwanego procesu.

XDG cache

• wyłącznie dane w pełni odtwarzalne.

Finalny sidecar CSV i runtime checkpoint mają różne nazwy, schematy i cykle życia. Nie mogą być określane wspólnym terminem „session sidecar”. LoggingId rozróżnia wiele kolejnych operacji logowania w ramach jednego SessionId.

Zapis plików

• Krytyczny zapis: tempfile w tym samym katalogu, ograniczone uprawnienia, flush, fsync, rename i synchronizacja katalogu.
• Artefakty strumieniowe mają jednego właściciela i jawne flush/sync.
• create_new chroni eksporty przed nadpisaniem.
• Ścieżki waliduje lantern-storage.
• Program nie zapisuje sekretów.

CLI

• vfd-lantern;
• profile ...;
• backup inspect <file>;
• backup diff <left> <right>;
• diagnostics collect --output <DIR>;
• globalne: --config, --profile, --device, --log-level, --enable-writes, --no-color, --help, --version.

CLI nie zawiera raw write, raw PDU, motion control ani restore omijającego TUI/WriteCoordinator.

Dokument konfiguracji

Dozwolone:

• render limit 1–10 FPS;
• tryb koloru;
• limity historii i pamięci;
• pojemności ograniczonych kolejek;
• lokalizacje data/state/log;
• retencja logów diagnostycznych;
• sugestie portu/profilu/slave;
• częstotliwości klas pollingu w granicach profilu.

Niedozwolone:

• enable_writes;
• zapamiętane uzbrojenie;
• auto-connect;
• auto-restore;
• fault reset;
• motion control;
• automatyczny trust profilu;
• nieograniczone kolejki/historie.

Walidacja i start

• Nieznane pola są odrzucane.
• Maksymalny config: 1 MiB.
• Błąd zatrzymuje start przed raw mode i otwarciem portu.
• Brak pliku jest poprawny.
• Częściowo poprawny config nie jest stosowany.
• Czysty start nie otwiera portu, nie skanuje i nie uzbraja write.

Testy

• Priorytet defaults/config/CLI.
• Macierz XDG i fallbacków.
• CSV oraz finalny sidecar w data; runtime checkpoint, log i audit w state.
• Dwie operacje logowania w jednym SessionId tworzą różne checkpointy dzięki LoggingId.
• Atomowy zapis, full disk, permissions i przerwanie.
• Odrzucenie pól bezpieczeństwa.
• Brak auto-connect/write po odtworzeniu preferencji.
• Limity kolejek/historii.

Kryteria akceptacji

• Cała aplikacja otrzymuje jedną ValidatedSettings.
• CLI zawsze wygrywa z configiem, a config z defaultem.
• Żaden komponent poza SettingsLoader i lantern-storage nie interpretuje źródeł ustawień ani katalogów.
• Finalny sidecar CSV znajduje się obok CSV w XDG data.
• Runtime checkpoint ma osobny schema, zawiera LoggingId i znajduje się w XDG state.
• Uszkodzony config nie może częściowo zmienić zachowania.
• Czysty start nie wykonuje transmisji i nie tworzy niepotrzebnych artefaktów.

Zależności

• [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1
• [PLAN 02] Ustalić toolchain, wersje zależności i politykę aktualizacji #2
• [PLAN 04] Zaprojektować wersjonowany format profilu i pełną walidację #4