Files
javis_bot/app/src/admin.spec.md
javis-bot 390f6f0b86 feat(app): M5 step 1, the admin backend under the management app
- datadir: the data folder layout, the location file (JARVIS_DATA_DIR wins),
  free space for the wizard.
- settings_edit: the fields the five settings screens edit; apply writes only
  non-defaults, keeps unknown keys and writes nothing unless the app's own
  check passes. A memory section reaches the worker's hello.
- secrets: config/secrets.dat, DPAPI for the Windows user; the services take
  the bot token from it before JARVIS_DISCORD_TOKEN.
- logs: the log hub behind the log screen (tabs, daily files kept 14 days,
  the recent error report, a zip under 10 MB, secrets and token-shaped text
  masked); the log macros and the worker's output feed it.

Spec: app/src/admin.spec.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 13:36:02 +09:00

6.0 KiB

Admin backend spec (v2 M5)

What the management app's screens (docs/v2/desktop-app.md) stand on: the data folder, editing the settings, the stored secrets and the logs. Plain Rust in the app crate, with no window: the Tauri shell (M5, later step) only calls these, so every rule here is tested on any OS.

Principles

  • One folder. Everything the app keeps lives in the data folder the user chose (desktop-app.md, "데이터 폴더 구조"); outside it there is only the file that remembers where it is.
  • The file stays the user's. Settings edits change only the keys they name, write only values that differ from the default, keep keys the app does not know, and never leave a half-written file.
  • Secrets never reach a log, a copy or an export.
  • Logs carry no conversation text (already the rule for every log line, discord_core.spec.md, voice_worker.spec.md); exports still mask secrets.

Data folder (app/src/datadir.rs)

The location file is %APPDATA%\JarvisBot\location.json on Windows and $XDG_CONFIG_HOME/jarvis-bot/location.json (else ~/.config/jarvis-bot/location.json) elsewhere: {"dataDir": "<absolute path>"}. JARVIS_DATA_DIR set in the environment wins over it (tests, development). No location (no file, no variable) means the first-run wizard has not finished.

DataDir::create(path) makes the layout below inside an existing or new folder and returns it; it never deletes anything. DataDir::choose(path) creates it and writes the location file (atomically).

config/  runtime/  models/llm  models/stt  models/tts  models/vad  memory/  browser/  collect/
cache/  logs/

free_bytes(path) reports the free space of the disk holding the folder (or its nearest existing parent); the wizard compares it with RECOMMENDED_FREE_BYTES (200 GB) and warns below it. A path that is not absolute, or is a file, is refused with a message.

Settings editing (app/src/settings_edit.rs)

config/settings.json keeps the format of discord_core.spec.md and conversation.spec.md.

  • fields() describes every key the screens edit: its dotted path (call.mode), screen (bot, channels, chat, memory, model), kind (bool, integer with a range, number with a range, text, text list, choice with its values, Discord ID, Discord ID list, ID to number map, chat channel list, free object), its default and a Korean label. The screens are built from this list, so a key is added in one place.
  • view(dir) returns every field's current value: the file's value, or the default when the file does not set it. A file that does not parse is reported, not overwritten.
  • apply(dir, changes) takes {path: value}. Each value is checked against its field; a value equal to the default removes the key (and a section left empty), any other value is set. Keys the app does not know are kept as they were. The whole result must pass the app's own settings check (parse_settings); only then is it written (temporary file, then rename). A refused change names the key and changes nothing.
  • memory (new section): the worker's memory settings (voice_worker.spec.md, "Memory settings": chat, others, off, since_days, recent_minutes, recent_records, matches, budget_tokens), sent in the worker hello as memory. Default {} (the worker's defaults).

Secrets (app/src/secrets.rs)

config/secrets.dat holds a JSON object of named secrets (discordToken). On Windows the bytes are encrypted with DPAPI for the current Windows user (CryptProtectData, no prompt), so the file is useless copied to another account or PC. Elsewhere (development only) the file is plain JSON with owner-only permissions (0600). Writes are atomic. get, set, remove; masked(value) shows only the last 4 characters for the screens (••••abcd).

The app's token comes from the secrets (discordToken), else from JARVIS_DISCORD_TOKEN (tests, headless runs).

Logs (app/src/logs.rs)

debug_log! and error_log! keep printing to stderr and also feed the log hub once the app installs one (logs::install). Each line has a time, a level (error, warn, info, debug), a service tab and its text. The tab comes from the line's category: app, discord (voice, receive, play, discord), chat, conversation, worker (the voice worker's own lines; its STT, LLM and TTS lines go to stt, llm, tts by their worker category), browser, capture, game (the last three from M6-M7). Unknown categories go to app.

  • Memory: the last 5,000 lines for the log screen (query: tab, lowest level, text to find, and the lines after a given sequence number, for live follow).
  • Files: logs/<tab>-<YYYY-MM-DD>.log, one line per entry; files older than 14 days are removed at start and once a day.
  • recent_error_report(): the last error with up to 30 lines before and 10 after it (all tabs, in order), the app version and a short PC summary (OS, CPU count, memory); None without an error. When it is over 2,000 characters (Discord's message limit) the screen offers a download instead.
  • export_zip(from, to, out): the log files of those days in a zip, at most 10 MB (Discord's file limit): when larger, the oldest lines are left out and a note says so.
  • Every copy and export runs through redact: each stored secret's value, and anything shaped like a Discord bot token, becomes [비밀값].

Tests

cargo test: data folder layout, location file and the environment override, a refused relative path, free space; settings view with defaults, apply writing only non-defaults, removing a key set back to its default, keeping unknown keys, refusing a bad value or a result parse_settings refuses without touching the file; secrets round trip, file permissions on Unix, masking; log tabs from categories, query filters and follow, files per day and retention, error report bounds, zip size cap, redaction of stored secrets and token-shaped text. Windows-only paths (DPAPI, %APPDATA%) are checked on the Windows VM in the Windows build step.